Brix Twilio API

openapi: 3.2.0
info:
  title: Brix Twilio API
  version: '1'
  summary: 'Control plane for Brix digital signage: screens, content, playlists, schedules, casts and emergencies.'
  description: 'Generated from the route table the API actually mounts

    (`apps/api/routes.snapshot.json`), the description each route is required to

    carry (`tests/contracts/route-registry.json`), and request/response schemas

    (`apps/api/src/openapi/`). CI enforces all three, so this document cannot list a

    route that does not exist or omit one that does.


    **Schemas.** 447 operations carry request and response schemas

    (`x-brix-schema: verified`). Each is checked in CI against the response the

    real handler returns — a missing, mistyped or undeclared field fails the build.

    The remaining operations are route-level only (`x-brix-schema: none`): their

    path, method, permission and purpose are exact, but the shape of `data` is not

    yet modelled, and we would rather say so than publish a schema that validates

    against nothing. Objects are open: a new field is not a breaking change.


    **Envelope.** Success bodies are `{ "data": … }`. Failures are

    `{ "error": "", "message": "…" }`, plus `requestId` on a 5xx.

    Many list routes page opt-in (see each operation): pass `?limit=` and

    follow `nextCursor` via `?cursor=` until it is null.


    **Authentication.** `Authorization: Bearer ` with an API key

    (`ak_…`, created in the console under Settings → API & MCP) or a user session. An

    API key carries a creator-chosen set of `resource.verb` permissions and may be

    pinned to one location''s subtree; a key can never be granted a permission its

    creator does not hold. The permission an operation needs is in

    `x-brix-permission` and in its security requirement.


    **Tenancy.** Every request resolves to one workspace. A resource belonging to

    another tenant returns 404, never 403, so a response never confirms that an

    account exists.


    **Rate limits.** A 429 carries `Retry-After`; a 503 `database_busy` means retry

    after the `Retry-After` interval.'
servers:
- url: https://api.brixsignage.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Twilio
paths:
  /v1/twilio/recording:
    post:
      operationId: createTwilioRecording
      tags:
      - Twilio
      summary: Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full…
      description: 'Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full URL + params, TWILIO_AUTH_TOKEN), 403 otherwise; 503 phone_not_configured until the Twilio secrets and a work number are set. Recording status callback: copies the audio into R2 (crm-recordings/ layout), writes it on the call and the lead''s activity, transcribes a voicemail; deletes the Twilio copy only after a verified copy and only when the flag is on.'
      x-brix-schema: none
      responses:
        2XX:
          description: 'Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation.'
        4XX:
          description: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/twilio/voice/bridge/accept:
    post:
      operationId: acceptTwilioVoiceBridge
      tags:
      - Twilio
      summary: Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full…
      description: 'Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full URL + params, TWILIO_AUTH_TOKEN), 403 otherwise; 503 phone_not_configured until the Twilio secrets and a work number are set. Click-to-call: on a 1, dials the lead from the work number (recording notice on the lead''s side); anything else ends it.'
      x-brix-schema: none
      responses:
        2XX:
          description: 'Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation.'
        4XX:
          description: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/twilio/voice/bridge/after:
    post:
      operationId: createTwilioVoiceBridgeAfter
      tags:
      - Twilio
      summary: Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full…
      description: 'Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full URL + params, TWILIO_AUTH_TOKEN), 403 otherwise; 503 phone_not_configured until the Twilio secrets and a work number are set. The lead leg of a click-to-call or dial-through ended: final status, talk time, closes the lead''s Call back tasks when answered.'
      x-brix-schema: none
      responses:
        2XX:
          description: 'Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation.'
        4XX:
          description: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/twilio/voice/bridge/answer:
    post:
      operationId: createTwilioVoiceBridgeAnswer
      tags:
      - Twilio
      summary: Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full…
      description: 'Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full URL + params, TWILIO_AUTH_TOKEN), 403 otherwise; 503 phone_not_configured until the Twilio secrets and a work number are set. Click-to-call: Ben answered his cell — ''Brix call to {name}. Press 1 to connect.'''
      x-brix-schema: none
      responses:
        2XX:
          description: 'Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation.'
        4XX:
          description: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/twilio/voice/consent:
    post:
      operationId: createTwilioVoiceConsent
      tags:
      - Twilio
      summary: Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full…
      description: 'Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full URL + params, TWILIO_AUTH_TOKEN), 403 otherwise; 503 phone_not_configured until the Twilio secrets and a work number are set. Runs on the dialled party''s phone before the legs join: ''This call may be recorded.'''
      x-brix-schema: none
      responses:
        2XX:
          description: 'Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation.'
        4XX:
          description: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/twilio/voice/dial-through/number:
    post:
      operationId: createTwilioVoiceDialThroughNumber
      tags:
      - Twilio
      summary: Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full…
      description: 'Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full URL + params, TWILIO_AUTH_TOKEN), 403 otherwise; 503 phone_not_configured until the Twilio secrets and a work number are set. Dial-through: only after a correct PIN, dials the keyed number from the work number.'
      x-brix-schema: none
      responses:
        2XX:
          description: 'Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation.'
        4XX:
          description: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/twilio/voice/dial-through/pin:
    post:
      operationId: createTwilioVoiceDialThroughPin
      tags:
      - Twilio
      summary: Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full…
      description: 'Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full URL + params, TWILIO_AUTH_TOKEN), 403 otherwise; 503 phone_not_configured until the Twilio secrets and a work number are set. Dial-through PIN check (PBKDF2): right → ask for the number; 3 wrong → hang up, audit row crm-phone.pin-lockout and an email.'
      x-brix-schema: none
      responses:
        2XX:
          description: 'Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation.'
        4XX:
          description: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/twilio/voice/inbound:
    post:
      operationId: createTwilioVoiceInbound
      tags:
      - Twilio
      summary: Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full…
      description: 'Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full URL + params, TWILIO_AUTH_TOKEN), 403 otherwise; 503 phone_not_configured until the Twilio secrets and a work number are set. The number''s ''A call comes in'' URL: rings the forward-to cell with the caller''s number as caller id and a press-1 whisper; from the cell itself, starts dial-through (PIN).'
      x-brix-schema: none
      responses:
        2XX:
          description: 'Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation.'
        4XX:
          description: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/twilio/voice/inbound/after:
    post:
      operationId: createTwilioVoiceInboundAfter
      tags:
      - Twilio
      summary: Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full…
      description: 'Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full URL + params, TWILIO_AUTH_TOKEN), 403 otherwise; 503 phone_not_configured until the Twilio secrets and a work number are set. The inbound ring ended: done if Ben took it, otherwise the voicemail greeting and .'
      x-brix-schema: none
      responses:
        2XX:
          description: 'Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation.'
        4XX:
          description: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/twilio/voice/status:
    post:
      operationId: createTwilioVoiceStatus
      tags:
      - Twilio
      summary: Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full…
      description: 'Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full URL + params, TWILIO_AUTH_TOKEN), 403 otherwise; 503 phone_not_configured until the Twilio secrets and a work number are set. Call status callback (the number''s ''Call status changes'' URL and every leg we start): moves the call row and the lead''s call activity; a missed inbound call gets its Call back task and email.'
      x-brix-schema: none
      responses:
        2XX:
          description: 'Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation.'
        4XX:
          description: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/twilio/voice/voicemail/done:
    post:
      operationId: createTwilioVoiceVoicemailDone
      tags:
      - Twilio
      summary: Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full…
      description: 'Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full URL + params, TWILIO_AUTH_TOKEN), 403 otherwise; 503 phone_not_configured until the Twilio secrets and a work number are set. The voicemail ended: notes the recording sid and length on the call row.'
      x-brix-schema: none
      responses:
        2XX:
          description: 'Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation.'
        4XX:
          description: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/twilio/voice/whisper:
    post:
      operationId: createTwilioVoiceWhisper
      tags:
      - Twilio
      summary: Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full…
      description: 'Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full URL + params, TWILIO_AUTH_TOKEN), 403 otherwise; 503 phone_not_configured until the Twilio secrets and a work number are set. Runs on Ben''s cell before an inbound caller is joined: ''Brix call from {name}. Press 1 to answer.'''
      x-brix-schema: none
      responses:
        2XX:
          description: 'Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation.'
        4XX:
          description: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/twilio/voice/whisper/accept:
    post:
      operationId: acceptTwilioVoiceWhisper
      tags:
      - Twilio
      summary: Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full…
      description: 'Twilio Voice webhook for the CRM phone line — verifies X-Twilio-Signature (full URL + params, TWILIO_AUTH_TOKEN), 403 otherwise; 503 phone_not_configured until the Twilio secrets and a work number are set. The whisper''s keypress: 1 joins the call, anything else hangs up the cell leg (the caller goes to voicemail).'
      x-brix-schema: none
      responses:
        2XX:
          description: 'Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation.'
        4XX:
          description: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: 'Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, …'
        message:
          description: Human-readable explanation. Safe to show an operator.
          type: string
        requestId:
          description: 'Present on 5xx: quote it to support.'
          type: string
      required:
      - error
      additionalProperties: {}
      description: Error envelope returned by every failing request.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key (`ak_…`) or a user session token. API keys carry `resource.verb` permissions.