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.2 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 and cohosts: value: access_level: ORGANIZATION live_stream: access_level: PUBLIC title: Example conference created via API description: Some description of example conference created via API cohosts: - email: "admin1@yandex.ru" - email: "admin2@org.com" - email: "admin3@yandex.ru" 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/ConferencePatchData' 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 /conferences/{id}/cohosts: parameters: - name: id in: path required: true schema: type: string get: description: Read conference cohosts. Requires oauth scope `telemost-api:conferences.read` tags: - Conference Cohosts parameters: - name: offset in: query required: false schema: type: integer - name: limit in: query required: false schema: type: integer responses: 200: $ref: '#/components/responses/Cohosts' 403: $ref: '#/components/responses/ConferenceResponsesOf403' 404: $ref: '#/components/responses/ConferenceNotFound' '4XX': $ref: '#/components/responses/UndocumentedError' security: - YandexOAuth: - telemost-api:conferences.read put: description: Update conference cohosts exclusively. Requires oauth scope `telemost-api:conferences.update` tags: - Conference Cohosts requestBody: content: application/json: schema: $ref: '#/components/schemas/CohostsData' examples: Remove all cohosts in conference: value: cohosts: [] Make user@yandex.ru the sole cohost: value: cohosts: - email: "user@yandex.ru" required: true 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.update patch: description: Add conference cohosts. Requires oauth scope `telemost-api:conferences.update` tags: - Conference Cohosts requestBody: content: application/json: schema: $ref: '#/components/schemas/CohostsData' examples: Do nothing: value: cohosts: [] Add new cohosts to conference: value: cohosts: - email: "cohost1@yandex.ru" - email: "cohost2@yandex.ru" - email: "cohost3@yandex.ru" required: true 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.update delete: description: Remove conference cohosts. Requires oauth scope `telemost-api:conferences.update` tags: - Conference Cohosts parameters: - name: cohost_emails in: query required: true style: form explode: false schema: type: array items: type: string 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.update /organizations/{org_id}/settings: parameters: - name: org_id in: path required: true schema: type: number get: description: Read organization settings to be applied to new conference. Requires oauth scope `telemost-api:conferences.read` tags: - Conference settings responses: 200: $ref: '#/components/responses/OrganizationSettings' 403: $ref: '#/components/responses/ApiRestrictedToOrganizations' '4XX': $ref: '#/components/responses/UndocumentedError' security: - YandexOAuth: - telemost-api:conferences.read put: description: Update organization settings to be applied to new conference. Requires oauth scope `telemost-api:conferences.update` tags: - Conference settings requestBody: content: application/json: schema: $ref: '#/components/schemas/OrganizationSettings' examples: All organization ocnferences will be created without waiting room, only owners are allowed to start, stop, receive results of summarizations and cloud recordings: value: waiting_room_level_adhoc: value: PUBLIC waiting_room_level_calendar: value: PUBLIC cloud_recording_email_receivers: value: [ OWNER ] cloud_recording_allowed_roles: value: [ OWNER ] summarization_email_receivers: value: [ OWNER ] summarization_allowed_roles: value: [ OWNER ] required: true responses: 200: $ref: '#/components/responses/OrganizationSettings' 403: $ref: '#/components/responses/ApiRestrictedToOrganizations' '4XX': $ref: '#/components/responses/UndocumentedError' security: - YandexOAuth: - telemost-api:conferences.update 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' ConferencePatchData: description: Representation of conference data used in 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 deprecated: true enum: - PUBLIC - ORGANIZATION - UNKNOWN waiting_room_level: description: Waiting room restriction setting. Current values are PUBLIC, ORGANIZATION, ADMINS. type: string 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 ConferenceData: description: Representation of conference data used in create 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 deprecated: true enum: - PUBLIC - ORGANIZATION - UNKNOWN waiting_room_level: description: Waiting room restriction setting. Current values are PUBLIC, ORGANIZATION, ADMINS. type: string 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 cohosts: description: List of user principals of cohosts. type: array items: type: object properties: email: description: Email of cohost type: string 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 sip_uri_meeting: description: Link to call the meeting via SIP type: string required: false sip_uri_telemost: description: Link to call the Telemost voice menu via SIP type: string required: false sip_id: description: Identifier for SIP connection type: string required: false CohostsData: description: Conference cohosts type: object properties: cohosts: description: List of user principals of cohosts. type: array items: type: object properties: email: description: Email of cohost type: string Cohosts: $ref: '#/components/schemas/CohostsData' OrganizationUserRole: type: string description: > The role of the user in conference. Current values are: - OWNER - a person who has created the conference - INTERNAL_COHOST - co-organizer of the conference whose account is associated with the same organization as the conference owner’s account - INTERNAL_MEMBER - the member (not co-organizer) of the conference whose account is associated with the same organization as the conference owner’s account OrganizationSettings: description: Representation of organization settings for conferences type: object properties: waiting_room_level_adhoc: type: object properties: value: type: string required: [ value ] description: Waiting room restriction setting for adhoc created conferences. Current values are PUBLIC, ORGANIZATION, ADMINS. waiting_room_level_calendar: type: object properties: value: type: string required: [ value ] description: Waiting room restriction setting for conferences created in calendar. Current values are PUBLIC, ORGANIZATION, ADMINS. cloud_recording_email_receivers: type: object properties: value: type: array items: $ref: '#/components/schemas/OrganizationUserRole' required: [ value ] description: The set of user roles which are allowed to receive email with link to cloud recording of meetings summarization_email_receivers: type: object properties: value: type: array items: $ref: '#/components/schemas/OrganizationUserRole' required: [ value ] description: The set of user roles which are allowed to receive email with summarization of meetings cloud_recording_allowed_roles: type: object properties: value: type: array items: $ref: '#/components/schemas/OrganizationUserRole' required: [ value ] description: The set of user roles which are allowed to manage cloud recording of meetings summarization_allowed_roles: type: object properties: value: type: array items: $ref: '#/components/schemas/OrganizationUserRole' required: [ value ] description: The set of user roles which are allowed to manage summarization of meetings responses: Cohosts: description: Conference cohosts content: application/json: schema: $ref: '#/components/schemas/Cohosts' 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' OrganizationSettings: description: Organization settings for conferences content: application/json: schema: $ref: '#/components/schemas/OrganizationSettings' 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 ` 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