openapi: 3.0.3
info:
  title: Telemost API v1
  description: API to create and manage video meetings and live streams in Yandex.Telemost
  version: 1.0.1
servers:
  - url: 'https://cloud-api.yandex.net/v1/telemost-api'
paths:
  /conferences:
    post:
      description: Create video meeting with optional live stream. Requires oauth scope `telemost-api:conferences.create`
      tags:
        - Conferences
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConferenceData'
            examples:
              Restricted with public live stream:
                value:
                  access_level: ORGANIZATION
                  live_stream:
                    access_level: PUBLIC
                    title: Example conference created via API
                    description: Some description of example conference created via API
              Public video meeting without live stream:
                value:
                  access_level: PUBLIC
        required: true
      responses:
        201:
          $ref: '#/components/responses/ConferenceShort'
        402:
          $ref: '#/components/responses/PaymentRequiredToUseLiveStreams'
        403:
          $ref: '#/components/responses/ApiRestrictedToOrganizations'
        '4XX':
          $ref: '#/components/responses/UndocumentedError'
      security:
        - YandexOAuth:
            - telemost-api:conferences.create
  /conferences/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      description: Read conference data. Requires oauth scope `telemost-api:conferences.read`
      tags:
        - Conferences
      responses:
        200:
          $ref: '#/components/responses/Conference'
        403:
          $ref: '#/components/responses/ConferenceResponsesOf403'
        404:
          $ref: '#/components/responses/ConferenceNotFound'
        '4XX':
          $ref: '#/components/responses/UndocumentedError'
      security:
        - YandexOAuth:
            - telemost-api:conferences.read
    patch:
      description: Update conference or live stream. Requires oauth scope `telemost-api:conferences.update`
      tags:
        - Conferences
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConferenceData'
            examples:
              Add or update live stream:
                value:
                  live_stream:
                    access_level: PUBLIC
                    title: Example conference created via API
                    description: Some description of example conference created via API
              Restrict conference and live stream:
                value:
                  access_level: ORGANIZATION
                  live_stream:
                    access_level: ORGANIZATION
              Restrict conference without touching live stream:
                value:
                  access_level: ORGANIZATION
        required: true
      responses:
        200:
          $ref: '#/components/responses/ConferenceShort'
        402:
          $ref: '#/components/responses/PaymentRequiredToUseLiveStreams'
        403:
          $ref: '#/components/responses/ConferenceResponsesOf403'
        404:
          $ref: '#/components/responses/ConferenceNotFound'
        '4XX':
          $ref: '#/components/responses/UndocumentedError'
      security:
        - YandexOAuth:
            - telemost-api:conferences.update
    delete:
      description: Delete conference. Requires oauth scope `telemost-api:conferences.delete`
      tags:
        - Conferences
      responses:
        204:
          $ref: '#/components/responses/NoContent'
        403:
          $ref: '#/components/responses/ConferenceResponsesOf403'
        404:
          $ref: '#/components/responses/ConferenceNotFound'
        '4XX':
          $ref: '#/components/responses/UndocumentedError'
      security:
        - YandexOAuth:
            - telemost-api:conferences.delete
components:
  schemas:
    Error:
      description: General format of error response
      type: object
      properties:
        error:
          description: Code of error
          type: string
        message:
          description: Human readable message
          type: string
        description:
          description: Technical description
          type: string
    Conference:
      description: Representation of conference
      allOf:
        - type: object
          properties:
            id:
              type: string
            join_url:
              type: string
        - $ref: '#/components/schemas/ConferenceData'
        - $ref: '#/components/schemas/ConferenceShort'
    ConferenceData:
      description: Representation of conference data used in create and patch requests
      type: object
      properties:
        access_level:
          description: Access restriction setting. Future added values
            will be treated as UNKNOWN for clients for backward compatibility
          type: string
          enum:
            - PUBLIC
            - ORGANIZATION
            - UNKNOWN
        live_stream:
          description: Live stream data. When missing no live stream is to be added or patched
          type: object
          properties:
            access_level:
              description: Access restriction setting. Future added values
                will be treated as UNKNOWN for clients for backward compatibility
              type: string
              enum:
                - PUBLIC
                - ORGANIZATION
                - UNKNOWN
            title:
              description: Title of live stream used on viewers page
              type: string
              maxLength: 1024
            description:
              description: Description of live stream used on viewers page
              type: string
              maxLength: 2048
    ConferenceShort:
      description: Short representation of conference
      type: object
      properties:
        id:
          description: Identifier of conference
          type: string
        join_url:
          description: Link for participants to join conference
          type: string
        live_stream:
          description: Live stream data. Missing when conference has no live stream
          type: object
          properties:
            watch_url:
              description: Link for viewers to watch stream
              type: string
  responses:
    ConferenceShort:
      description: Short conference info
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConferenceShort'
          examples:
            With live stream:
              value:
                id: '12345678901234'
                join_url: https://telemost.yandex.ru/j/12345678901234
                live_stream:
                  watch_url: https://telemost.yandex.ru/live/123456789abcdef0123456789abcdef0
            Without live stream:
              value:
                id: '12345678901234'
                join_url: https://telemost.yandex.ru/j/12345678901234
      headers:
        Yandex-Cloud-Request-ID:
          $ref: '#/components/headers/Yandex-Cloud-Request-ID'
    Conference:
      description: Conference response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Conference'
          examples:
            With live stream:
              value:
                id: '12345678901234'
                join_url: https://telemost.yandex.ru/j/12345678901234
                access_level: ORGANIZATION
                live_stream:
                  watch_url: https://telemost.yandex.ru/live/123456789abcdef0123456789abcdef0
                  access_level: PUBLIC
                  title: Example conference created via API
                  description: Some description of example conference created via API
            Without live stream:
              value:
                id: '12345678901234'
                join_url: https://telemost.yandex.ru/j/12345678901234
                access_level: UNKNOWN
      headers:
        Yandex-Cloud-Request-ID:
          $ref: '#/components/headers/Yandex-Cloud-Request-ID'
    NoContent:
      description: No content
      headers:
        Yandex-Cloud-Request-ID:
          $ref: '#/components/headers/Yandex-Cloud-Request-ID'
    ApiRestrictedToOrganizations:
      description: Only users of Yandex 360 for business allowed to use this api
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: ApiRestrictedToOrganizations
      headers:
        Yandex-Cloud-Request-ID:
          $ref: '#/components/headers/Yandex-Cloud-Request-ID'
    PaymentRequiredToUseLiveStreams:
      description: Live streams are not available in your tariff plan
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: PaymentRequiredToUseLiveStreams
      headers:
        Yandex-Cloud-Request-ID:
          $ref: '#/components/headers/Yandex-Cloud-Request-ID'
    ConferenceNotFound:
      description: Requested conference not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: ConferenceNotFound
      headers:
        Yandex-Cloud-Request-ID:
          $ref: '#/components/headers/Yandex-Cloud-Request-ID'
    ConferenceAccessForbidden:
      description: Requested conference access forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: ConferenceAccessForbidden
      headers:
        Yandex-Cloud-Request-ID:
          $ref: '#/components/headers/Yandex-Cloud-Request-ID'
    ConferenceResponsesOf403:
      description: Responses with 403 status code
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            Requested conference access forbidden:
              value:
                error: ConferenceAccessForbidden
            Only users of Yandex 360 for business allowed to use this api:
              value:
                error: ApiRestrictedToOrganizations
      headers:
        Yandex-Cloud-Request-ID:
          $ref: '#/components/headers/Yandex-Cloud-Request-ID'
    UndocumentedError:
      description: Undocumented error like bad request, too many requests, authorization problem
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Yandex-Cloud-Request-ID:
          $ref: '#/components/headers/Yandex-Cloud-Request-ID'
  headers:
    Yandex-Cloud-Request-ID:
      description: Server generated request id to contact support
      schema:
        type: string
  securitySchemes:
    YandexOAuth:
      description: Fill field below with `OAuth <Token>` value.
        To obtain token [create](https://oauth.yandex.ru/client/new) and [use](https://yandex.ru/dev/id/doc/en/access)
        your own application with required data access scopes prefixed by `telemost-api:`
        or just get DEBUG token [here](https://oauth.yandex.ru/authorize?response_type=token&client_id=65e062c9a30c4b8f86651dd464c17572).
      type: apiKey
      name: Authorization
      in: header