AngelCam speakers API

openapi: 3.0.0
info:
  version: 2026.06.11
  title: Angelcam active-service speakers API
  contact:
    email: support@angelcam.com
  x-logo:
    url: ./assets/logo-angelcam.svg
  description: 'Angelcam RESTful API — HTTPS only, JSON, all URLs require a trailing slash. See the [developer docs](/) for quickstart, authentication, and key concepts.

    '
servers:
- url: https://api.angelcam.com/v1
tags:
- name: speakers
  x-displayName: Speakers
  description: 'Manage speakers and trigger audio playback. See the [Speakers guide](/guides/speakers/) for setup instructions, including how to configure an AngelBox as a speaker.

    '
paths:
  /speakers/:
    get:
      operationId: speaker-list
      summary: Retrieve speaker list
      tags:
      - speakers
      parameters:
      - name: limit
        in: query
        required: false
        description: 'Limit result set. Example: `1`.'
        schema:
          type: integer
          minimum: 1
      - name: offset
        in: query
        required: false
        description: 'Return results starting at `offset`. Example: `10`.'
        schema:
          type: integer
          minimum: 1
      security:
      - OAuth2:
        - speaker_access
      - PersonalAccessToken: []
      responses:
        '200':
          description: List of speakers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeakerListResponse'
        '400':
          $ref: '#/components/responses/Error400InvalidParams'
        '401':
          $ref: '#/components/responses/Error401Unauthorized'
        '403':
          $ref: '#/components/responses/Error403PermissionDenied'
    post:
      operationId: connect-speakers
      summary: Connect new speaker
      tags:
      - speakers
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpeakerObject'
      security:
      - OAuth2:
        - speaker_manage
      - PersonalAccessToken: []
      responses:
        '201':
          description: Newly created speaker object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeakerObject'
        '400':
          $ref: '#/components/responses/Error400InvalidBody'
        '401':
          $ref: '#/components/responses/Error401Unauthorized'
        '403':
          $ref: '#/components/responses/Error403PermissionDenied'
  /speakers/{speaker_id}/:
    parameters:
    - $ref: '#/components/parameters/speakerId'
    get:
      operationId: speaker-detail
      summary: Retrieve speaker detail
      tags:
      - speakers
      security:
      - OAuth2:
        - speaker_access
      - PersonalAccessToken: []
      responses:
        '200':
          description: Speaker.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeakerObject'
        '401':
          $ref: '#/components/responses/Error401Unauthorized'
        '403':
          $ref: '#/components/responses/Error403PermissionDenied'
        '404':
          $ref: '#/components/responses/Error404NotFound'
    put:
      operationId: update-speaker
      summary: Update existing speaker
      tags:
      - speakers
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpeakerObject'
      security:
      - OAuth2:
        - speaker_manage
      - PersonalAccessToken: []
      responses:
        '200':
          description: Updated speaker object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeakerObject'
        '400':
          $ref: '#/components/responses/Error400InvalidBody'
        '401':
          $ref: '#/components/responses/Error401Unauthorized'
        '403':
          $ref: '#/components/responses/Error403PermissionDenied'
        '404':
          $ref: '#/components/responses/Error404NotFound'
  /speakers/{speaker_id}/play/:
    parameters:
    - $ref: '#/components/parameters/speakerId'
    post:
      operationId: audio-playback-start
      summary: Start audio playback
      tags:
      - speakers
      security:
      - OAuth2:
        - audio_messages_play
      - PersonalAccessToken: []
      description: 'Play a given audio message or return a WebRTC signaling URL if no message ID is given.


        ### Live audio playback using WebRTC


        Every [WebRTC signaling](#section/Angelcam-API/WebRTC-signaling) session for live audio playback starts by sending an SDP offer from the client to the corresponding Angelcam server followed by one or more local ICE candidates. The server then responds with an SDP answer followed by one or more of its local ICE candidates. The candidate exchange should conclude by sending a `null` candidate by each side to the other peer to signal that there are no more local ICE candidates. There is no lock-step mechanism for sending the ICE candidates. All available local candidates should be sent to the other peer immediately after sending the SDP offer/answer.


        #### STUN/TURN servers


        No external STUN or TURN servers are required as all Angelcam servers have a public IP address and, therefore, the `host` ICE candidates on the server side are always reachable. The client''s server-reflexive candidates, if needed, are then discovered once the client contacts the server via the server''s `host` candidates.

        '
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: integer
                  nullable: true
                  description: audio message ID
                repeat:
                  type: boolean
                  default: false
                  description: repeat the audio message
                stop_after:
                  type: integer
                  nullable: true
                  description: Duration in seconds after which the playback will automatically stop. This is required when repeat is `true` to prevent infinite playback.
      responses:
        '200':
          description: WebRTC signaling URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webrtc_signaling_url:
                    type: string
                    format: url
                    description: WebRTC signaling URL
                    example: wss://m1-eu1.angelcam.com/speakers/123/web-rtc/
                required:
                - webrtc_signaling_url
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '401':
          $ref: '#/components/responses/Error401Unauthorized'
        '403':
          $ref: '#/components/responses/Error403PermissionDenied'
        '404':
          $ref: '#/components/responses/Error404NotFound'
        '503':
          $ref: '#/components/responses/Error503ServiceUnavailable'
  /speakers/{speaker_id}/stop/:
    parameters:
    - $ref: '#/components/parameters/speakerId'
    post:
      operationId: audio-playback-stop
      summary: Stop audio playback
      tags:
      - speakers
      security:
      - OAuth2:
        - audio_messages_play
      - PersonalAccessToken: []
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '401':
          $ref: '#/components/responses/Error401Unauthorized'
        '403':
          $ref: '#/components/responses/Error403PermissionDenied'
        '404':
          $ref: '#/components/responses/Error404NotFound'
  /speakers/{speaker_id}/test/:
    parameters:
    - $ref: '#/components/parameters/speakerId'
    get:
      operationId: speaker-test
      summary: Test speaker connection
      description: 'On success, the endpoint returns HTTP 204; otherwise, HTTP 400 with a detail about the connection issue is returned.


        _Note that this is just a connectivity test. Successful connectivity test does not mean that the speaker itself works (i.e. that it''s able to play audio)._

        '
      tags:
      - speakers
      security:
      - OAuth2:
        - speaker_access
      - PersonalAccessToken: []
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/Error400InvalidParams'
        '401':
          $ref: '#/components/responses/Error401Unauthorized'
        '403':
          $ref: '#/components/responses/Error403PermissionDenied'
        '404':
          $ref: '#/components/responses/Error404NotFound'
components:
  parameters:
    speakerId:
      name: speaker_id
      in: path
      required: true
      description: Speaker ID
      example: 1
      schema:
        type: integer
        minimum: 1
  schemas:
    ErrorGeneric:
      type: object
      title: Error object
      properties:
        title:
          type: string
        detail:
          type: string
        status:
          type: integer
      required:
      - title
      - detail
      - status
    Error400InvalidParams:
      type: object
      title: Error 400 Invalid Parameters
      properties:
        title:
          type: string
        detail:
          type: object
        status:
          type: integer
      required:
      - title
      - detail
      - status
      example:
        title: invalid
        detail:
        - refresh_rate:
          - valid number is required.
          - Ensure this value is greater than 0.
        - max_width:
          - valid number is required.
          - Ensure this value is greater than or equal to 1.
        status: 400
    Error403PermissionDenied:
      allOf:
      - $ref: '#/components/schemas/ErrorGeneric'
      title: Error 403 Permission Denied
      example:
        title: permission_denied
        detail: You do not have permission to perform this action.
        status: 403
    Error401Unauthorized:
      allOf:
      - $ref: '#/components/schemas/ErrorGeneric'
      title: Error 401 Unauthorized
      example:
        title: not_authenticated
        detail: Authentication credentials were not provided
        status: 401
    Error503ServiceUnavailable:
      allOf:
      - $ref: '#/components/schemas/ErrorGeneric'
      title: Error 502 Bad Gateway
      example:
        title: bad_gateway
        detail: Bad Gateway
        status: 502
    SpeakerObject:
      type: object
      title: Speaker object
      properties:
        id:
          type: integer
          minimum: 1
          description: Speaker ID
          readOnly: true
        name:
          type: string
          description: Speaker name
        setup:
          type: string
          enum:
          - arrow
          description: Speaker connection type
        protocol:
          type: string
          enum:
          - basic
          description: Audio protocol
        arrow_client:
          type: string
          format: uuid
          description: UUID of arrow client client used for speaker connection, required when setup=arrow
          nullable: true
        arrow_service_id:
          type: string
          description: hexadecimal id of arrow service, can contain leading zeros, required when setup=arrow
          nullable: true
        endpoint:
          type: string
          format: uri
          description: Endpoint URL for the speaker
          example: /api/v1/audio/play
        username:
          type: string
        password:
          type: string
          writeOnly: true
      required:
      - id
      - name
      - setup
      - protocol
      - endpoint
      example:
        id: 157
        name: Angelbox Speaker
        setup: arrow
        protocol: basic
        arrow_client: 75b62326-eca3-4424-ab68-48e7da47e847
        arrow_service_id: 00af
        endpoint: /api/v1/audio/play
    Error404NotFound:
      allOf:
      - $ref: '#/components/schemas/ErrorGeneric'
      title: Error 404 Not Found
      example:
        title: not_found
        detail: Not Found
        status: 404
    SpeakerListResponse:
      type: object
      title: Speaker list
      properties:
        count:
          type: integer
          description: Count of speakers
        next:
          format: uri
          description: Next page from pagination
          nullable: true
          type: string
        previous:
          format: uri
          description: Previous page from pagination
          nullable: true
          type: string
        results:
          type: array
          description: List of speakers
          items:
            $ref: '#/components/schemas/SpeakerObject'
      required:
      - count
      - next
      - previous
      - results
  responses:
    Error400InvalidParams:
      description: Query params are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error400InvalidParams'
    EmptyResponse:
      description: Empty response.
    Error400InvalidBody:
      description: Body payload is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error400InvalidParams'
    Error403PermissionDenied:
      description: Missing permission.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error403PermissionDenied'
    Error404NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error404NotFound'
    Error401Unauthorized:
      description: Missing or invalid authorization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error401Unauthorized'
    Error503ServiceUnavailable:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error503ServiceUnavailable'
  securitySchemes:
    OAuth2:
      type: oauth2
      description: 'See the Authentication section above for full documentation.

        '
      flows:
        authorizationCode:
          authorizationUrl: https://my.angelcam.com/oauth/authorize/
          tokenUrl: https://my.angelcam.com/oauth/token/
          scopes:
            user_access: Permission to access user information
            user_delete: Permission to delete the current user account
            camera_access: Permission to list cameras and to get details of a specific camera
            camera_create: Permission to create cameras
            camera_manage: Permission to update cameras
            camera_delete: Permission to delete cameras
            camera_guest_access: Permission to access camera guest
            camera_guest_manage: Permission to manage camera guest
            public_cameras_access: Permission to access public cameras
            arrow_client_access: Permission to access Arrow clients
            arrow_client_manage: Permission to manage Arrow clients
            event_access: Permission to access events
            recording_access: Permission to access camera recordings
            recording_start_stop: Permission to start and stop recording on camera
            recording_clips_access: Permission to access recording clips
            recording_clips_create: Permission to create recording clips
            recording_clips_share: Permission to share recording clips
            sensor_access: Permission to list sensors and to get details of a specific sensor
            sensor_manage: Permission to create, update and delete sensors
            broadcasting_access: Permission to see general broadcasting information and access broadcasting streams
            broadcasting_start_stop: Permission to start and stop public broadcasting on camera
            client_access: Permission to list resellers clients and get details of a specific client
            client_create: Permission to create client account
            client_manage: Permission to update clients detail
            streams_detect: Permission to detect camera streams
            sites_access: Permission to access sites
            sites_manage: Permission to create, update and delete sites
            services_access: Permission to access available services
            trials_access: Permission to access available trials
            trials_activate: Permission to activate a trial
            active_services_access: Permission to access active services
            active_services_manage: Permission to manage active services
            orders_access: Permission to access orders
            messages_access: Permission to access RTS messages
            messages_manage: Permission to manage RTS messages
            incidents_access: Permission to access Incidents
            space_access: Permission to list and activate spaces
            space_permissions_access: Permission to view space permissions
        password:
          tokenUrl: https://api.angelcam.com/oauth/token/
          scopes:
            user_access: Permission to access user information
            user_delete: Permission to delete the current user account
            camera_access: Permission to list cameras and to get details of a specific camera
            camera_create: Permission to create cameras
            camera_manage: Permission to update cameras
            camera_delete: Permission to delete cameras
            camera_guest_access: Permission to access camera guest
            camera_guest_manage: Permission to manage camera guest
            arrow_client_access: Permission to access Arrow clients
            arrow_client_manage: Permission to manage Arrow clients
            event_access: Permission to access events
            recording_access: Permission to access camera recordings
            recording_start_stop: Permission to start and stop recording on camera
            recording_clips_access: Permission to access recording clips
            recording_clips_create: Permission to create recording clips
            recording_clips_share: Permission to share recording clips
            sensor_access: Permission to list sensors and to get details of a specific sensor
            sensor_manage: Permission to create, update and delete sensors
            broadcasting_access: Permission to see general broadcasting information and access broadcasting streams
            broadcasting_start_stop: Permission to start and stop public broadcasting on camera
            client_access: Permission to list resellers clients and get details of a specific client
            client_create: Permission to create client account
            client_manage: Permission to update clients detail
            streams_detect: Permission to detect camera streams
            sites_access: Permission to access sites
            sites_manage: Permission to create, update and delete sites
            services_access: Permission to access available services
            trials_access: Permission to access available trials
            trials_activate: Permission to activate a trial
            active_services_access: Permission to access active services
            active_services_manage: Permission to manage active services
            orders_access: Permission to access orders
            messages_access: Permission to access RTS messages
            messages_manage: Permission to manage RTS messages
            rts_settings_access: Permission to access RTS settings
            rts_settings_manage: Permission to manage RTS settings
            rts_arming_manage: Permission to arm and disarm RTS
            incidents_access: Permission to access Incidents
            space_access: Permission to list and activate spaces
            space_permissions_access: Permission to view space permissions
    PersonalAccessToken:
      type: apiKey
      in: header
      name: Authorization
      description: 'Enter your token as: `PersonalAccessToken {your-token}`

        '
x-tagGroups:
- name: General
  tags:
  - user
  - space
  - location
- name: Camera management
  tags:
  - camera
  - shared-camera
  - camera-guest
  - camera-stream-detection
  - arrow-clients
  - angelcameras
- name: Recording
  tags:
  - recording
  - stream-controls
  - shared-camera-recording
  - clip
  - shared-camera-clip
- name: Broadcasting
  tags:
  - broadcasting
  - public-camera
- name: Events & Sensors
  tags:
  - event
  - sensor
- name: Speaker management
  tags:
  - speakers
  - audio-message
- name: RTS
  tags:
  - incidents
  - rts_settings
  - rts_messages
  - rts_notification_methods
  - rts_notification_rules
- name: Billing
  tags:
  - service
  - active-service
  - order
- name: Clients
  tags:
  - client