openapi: 3.0.0
info:
  title: Cloudflare Calls API
  version: '1.0'
externalDocs:
  description: Find out more about Cloudflare Calls
  url: https://developers.cloudflare.com/calls/
servers:
  - url: https://rtc.live.cloudflare.com/v1
paths:
  /apps/{appId}/sessions/new:
    post:
      tags:
        - New Session
      summary: Create a new PeerConnection
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/NewSessionRequest'
                - example:
                    sessionDescription:
                      type: offer
                      sdp: |
                        v=0
                        o=- 0 0 IN IP4 127.0.0.1
                        s=-
                        c=IN IP4 127.0.0.1
                        t=0 0
                        m=audio 4000 RTP/AVP 111
                        a=rtpmap:111 OPUS/48000/2
                        m=video 4002 RTP/AVP 96
                        a=rtpmap:96 VP8/90000
                        ...
      security:
        - secret: []
      parameters:
        - in: path
          name: appId
          schema:
            type: string
          required: true
          description: WebRTC application ID
      responses:
        '201':
          description: Created
          headers:
            vary:
              schema:
                type: string
                example: Origin
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/NewSessionResponse'
                  - example:
                      sessionDescription:
                      sdp: |
                        v=0
                        o=- 0 0 IN IP4 127.0.0.1
                        s=-
                        c=IN IP4 127.0.0.1
                        t=0 0
                        m=audio 4000 RTP/AVP 111
                        a=rtpmap:111 OPUS/48000/2
                        m=video 4002 RTP/AVP 96
                        a=rtpmap:96 VP8/90000
                        ...
                      type: answer
                      sessionId: e017a2629c754fedc1f7d8587e06d126
  /apps/{appId}/sessions/{sessionId}/tracks/new:
    post:
      tags:
        - Add a track
      summary: Solve the given track object(s) and add the track(s) to the WebRTC session
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TracksRequest'
            examples:
              local_tracks:
                description: Share a track to be played by remote peers
                value:
                  sessionDescription:
                    sdp: |
                      v=0
                      o=- 0 0 IN IP4 127.0.0.1
                      s=-
                      c=IN IP4 127.0.0.1
                      t=0 0
                      m=audio 4000 RTP/AVP 111
                      a=rtpmap:111 OPUS/48000/2
                      m=video 4002 RTP/AVP 96
                      a=rtpmap:96 VP8/90000
                      ...
                    type: offer
                  tracks:
                    - location: local
                      mid: '4'
                      trackName: 1a037563-c35c-4bf6-a9ee-2b474cbb9a51
              remote_tracks:
                description: Play a track from a remote peer
                value:
                  tracks:
                    - location: remote
                      sessionId: 2a45361d5fd7cc14eface0587c276c94
                      trackName: 2e037563-a35d-4bf6-a9ee-2d474cbb9a58
      security:
        - secret: []
      parameters:
        - in: path
          name: appId
          schema:
            type: string
          required: true
          description: WebRTC application ID
        - in: path
          name: sessionId
          schema:
            type: string
          required: true
          description: Current PeerConnection session ID
      responses:
        '200':
          description: OK
          headers:
            vary:
              schema:
                type: string
                example: Origin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TracksResponse'
              examples:
                local_tracks:
                  value:
                    requiresImmediateRenegotiation: false
                    tracks:
                        - trackName: 1a037563-c35c-4bf6-a9ee-2b474cbb9a51
                          mid: '4'
                    sessionDescription:
                      sdp: |
                        v=0
                        o=- 0 0 IN IP4 127.0.0.1
                        s=-
                        c=IN IP4 127.0.0.1
                        t=0 0
                        m=audio 4000 RTP/AVP 111
                        a=rtpmap:111 OPUS/48000/2
                        m=video 4002 RTP/AVP 96
                        a=rtpmap:96 VP8/90000
                        ...
                      type: answer
                remote_tracks:
                  value:
                    requiresImmediateRenegotiation: true
                    tracks:
                      - sessionId: 2a45361d5fd7cc14eface0587c276c94
                        trackName: 2e037563-a35d-4bf6-a9ee-2d474cbb9a58
                        mid: '7'
                    sessionDescription:
                      sdp: |
                        v=0
                        o=- 0 0 IN IP4 127.0.0.1
                        s=-
                        c=IN IP4 127.0.0.1
                        t=0 0
                        m=audio 4000 RTP/AVP 111
                        a=rtpmap:111 OPUS/48000/2
                        m=video 4002 RTP/AVP 96
                        a=rtpmap:96 VP8/90000
                        ...
                      type: offer
  /apps/{appId}/sessions/{sessionId}/renegotiate:
    put:
      tags:
        - Renegotiate WebRTC session
      summary: When a previous response has requiresImmediateRenegotiation, you must renegotiate
      requestBody:
        content:
          application/json:
            schema:
              properties:
                sessionDescription:
                  $ref: '#/components/schemas/SessionDescription'
            example:
              sessionDescription:
                sdp: |
                  v=0
                  o=- 0 0 IN IP4 127.0.0.1
                  s=-
                  c=IN IP4 127.0.0.1
                  t=0 0
                  m=audio 4000 RTP/AVP 111
                  a=rtpmap:111 OPUS/48000/2
                  m=video 4002 RTP/AVP 96
                  a=rtpmap:96 VP8/90000
                  ...
                  type: answer
      security:
        - secret: []
      parameters:
        - in: path
          name: appId
          schema:
            type: string
          required: true
          description: WebRTC application ID
        - in: path
          name: sessionId
          schema:
            type: string
          required: true
      responses:
        '200':
          description: OK
          headers:
            vary:
              schema:
                type: string
                example: Origin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionDescription'
              example: {}
  /apps/{appId}/sessions/{sessionId}/tracks/close:
    put:
      tags:
        - Close a track
      summary: Close a local or remote track
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CloseTracksRequest'
                - example:
                    tracks:
                      - mid: '7'
                    sessionDescription:
                      sdp: |
                        v=0
                        o=- 0 0 IN IP4 127.0.0.1
                        s=-
                        c=IN IP4 127.0.0.1
                        t=0 0
                        m=audio 4000 RTP/AVP 111
                        a=rtpmap:111 OPUS/48000/2
                        m=video 4002 RTP/AVP 96
                        a=rtpmap:96 VP8/90000
                        ...
                      type: offer
                    force: false
      security:
        - secret: []
      parameters:
        - in: path
          name: appId
          schema:
            type: string
          required: true
          description: WebRTC application ID
        - in: path
          name: sessionId
          schema:
            type: string
          required: true
      responses:
        '200':
          description: OK
          headers:
            vary:
              schema:
                type: string
                example: Origin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloseTracksResponse'
              example:
                sessionDescription:
                  sdp: |
                    v=0
                    o=- 0 0 IN IP4 127.0.0.1
                    s=-
                    c=IN IP4 127.0.0.1
                    t=0 0
                    m=audio 4000 RTP/AVP 111
                    a=rtpmap:111 OPUS/48000/2
                    m=video 4002 RTP/AVP 96
                    a=rtpmap:96 VP8/90000
                    ...
                  type: answer
                requiresImmediateRenegotiation: false
                tracks:
                  - mid: '7'
  /apps/{appId}/sessions/{sessionId}:
    get:
      tags:
        - Get session state
      summary: Return the list of tracks associated to the session
      security:
        - secret: []
      parameters:
        - in: path
          name: appId
          schema:
            type: string
          required: true
          description: WebRTC application ID
        - in: path
          name: sessionId
          schema:
            type: string
          required: true
      responses:
        '200':
          description: OK
          headers:
            vary:
              schema:
                type: string
                example: Origin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSessionStateResponse'
              example:
                tracks:
                  - location: local
                    mid: '2'
                    trackName: 1a037563-c35c-4bf6-a9ee-2b474cbb9a51
                    status: active
                  - location: remote
                    mid: '7'
                    sessionId: 2a45361d5fd7cc14eface0587c276c94
                    trackName: 2e037563-a35d-4bf6-a9ee-2d474cbb9a58
                    status: active
                    
components:
  securitySchemes:
    secret:
      type: http
      scheme: bearer
  schemas:
    SessionDescription:
      type: object
      properties:
        sdp:
          type: string
        type:
          type: string
          enum:
            - answer
            - offer
    TrackObject:
      type: object
      properties:
        location:
          type: string
          enum:
            - local
            - remote
          description: If you want to share a track, it should be local. If you want to play a track shared by a remote agent, it should be remote
        mid:
          type: string
          description: mid associated to track's transceiver. It should be set with local tracks only
        sessionId:
          type: string
          description: Session ID of the track owner. It should be set for remote tracks only
        trackName:
          type: string
          description: Given name for the track
    CloseTrackObject:
      type: object
      properties:
        mid:
          type: string
          description: mid associated to the track's transceiver to close
    TracksRequest:
        type: object
        properties:
          sessionDescription:
            $ref: "#/components/schemas/SessionDescription"
          tracks:
            type: array
            items:
              $ref: "#/components/schemas/TrackObject"
    TracksResponse:
      type: object
      properties:
        requiresImmediateRenegotiation:
          type: boolean
        sessionDescription:
          $ref: "#/components/schemas/SessionDescription"
        tracks:
          type: array
          items:
            allOf:
              - $ref: "#/components/schemas/TrackObject"
              - properties:
                  error:
                    type: object
                    properties:
                      errorCode:
                        type: string
                      errorDescription:
                        type: string
    NewSessionRequest:
      type: object
      properties:
        sessionDescription:
          $ref: "#/components/schemas/SessionDescription"
    NewSessionResponse:
      type: object
      properties:
        sessionDescription:
          type: object
          properties:
            sdp:
              type: string
            type:
              type: string
              enum:
                - answer
                - offer
        sessionId:
          type: string
    CloseTracksRequest:
      type: object
      properties:
        sessionDescription:
          $ref: "#/components/schemas/SessionDescription"
        tracks:
          type: array
          items:
            $ref: "#/components/schemas/CloseTrackObject"
        force:
          type: boolean
          description: True if you want to stop just the data flow for the tracks, no WebRTC renegotiation
    CloseTracksResponse:
      type: object
      properties:
        sessionDescription:
          $ref: "#/components/schemas/SessionDescription"
        tracks:
          type: array
          items:
            allOf:
              - $ref: "#/components/schemas/CloseTrackObject"
              - properties:
                  error:
                    type: object
                    properties:
                      errorCode:
                        type: string
                      errorDescription:
                        type: string
        requiresImmediateRenegotiation:
          type: boolean
    GetSessionStateResponse:
      type: object
      properties:
        tracks:
          type: array
          items:
            allOf:
              - $ref: "#/components/schemas/TrackObject"
              - properties:
                  status:
                    type: string
                    enum:
                      - active
                      - inactive
                      - waiting