Skip to main content

API schema and shared components

Retained reference snapshot. This independently versioned API snapshot does not select or advance a platform or SDK release.

These are the complete components retained in the reviewed public projection. Internal references resolve against that exact document; this catalogue does not fetch remote schemas.

{
  "securitySchemes": {
    "bearerAuth": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    },
    "apiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "X-API-Key",
      "description": "Team API key. Required scopes are documented on each authenticated endpoint."
    }
  },
  "schemas": {
    "ChannelMessage": {
      "type": "object",
      "description": "WebSocket message envelope exchanged on /ws/session. Include the payload object matching the message type.",
      "required": ["type", "sessionId", "messageId", "timestamp", "direction"],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "chat",
            "browser_action",
            "action",
            "action_result",
            "audio",
            "status",
            "control",
            "reconnect",
            "ping",
            "pong",
            "error"
          ]
        },
        "sessionId": {
          "type": "string"
        },
        "messageId": {
          "type": "string",
          "format": "uuid"
        },
        "streamId": {
          "type": "string",
          "description": "Redis stream id included on replayed runtime-to-browser messages."
        },
        "timestamp": {
          "type": "number",
          "description": "Unix timestamp in milliseconds."
        },
        "direction": {
          "type": "string",
          "enum": ["to_browser", "to_ari"]
        },
        "chat": {
          "type": "object",
          "description": "Present when type is chat.",
          "additionalProperties": true
        },
        "browserAction": {
          "type": "object",
          "description": "Present when type is browser_action.",
          "additionalProperties": true
        },
        "action": {
          "type": "object",
          "description": "Present when type is action.",
          "additionalProperties": true
        },
        "actionResult": {
          "type": "object",
          "description": "Present when type is action_result.",
          "additionalProperties": true
        },
        "audio": {
          "type": "object",
          "description": "Present when type is audio.",
          "additionalProperties": true
        },
        "status": {
          "type": "object",
          "description": "Present when type is status.",
          "additionalProperties": true
        },
        "control": {
          "type": "object",
          "description": "Present when type is control; supports enable_text_chat and disable_text_chat commands.",
          "additionalProperties": true
        },
        "reconnect": {
          "type": "object",
          "description": "Present when type is reconnect.",
          "additionalProperties": true
        },
        "error": {
          "type": "object",
          "description": "Present when type is error.",
          "additionalProperties": true
        }
      }
    },
    "ErrorResponse": {
      "type": "object",
      "description": "Standard TelAPI error envelope.",
      "required": ["error"],
      "properties": {
        "error": {
          "type": "object",
          "required": ["code", "message"],
          "properties": {
            "code": {
              "type": "string",
              "description": "Stable machine-readable error code.",
              "example": "VALIDATION_ERROR"
            },
            "message": {
              "type": "string",
              "description": "Human-readable error summary.",
              "example": "Request validation failed"
            },
            "details": {
              "description": "Optional structured details, usually validation issues."
            },
            "requestId": {
              "type": "string",
              "description": "Fastify request id for log correlation when available."
            }
          }
        }
      }
    }
  }
}

Other document-level metadata​

{
  "openapi": "3.0.3",
  "info": {
    "title": "TelAPI",
    "description": "TelAPI exposes an operational health probe at /health. Browser SDK session tokens, endpoint capabilities, usage reporting and /ws/session require Browser SDK access. HTTP operations require a scoped team API key. Browser voice additionally requires WebRTC.",
    "version": "0.9.19"
  },
  "tags": [
    {
      "name": "Endpoints",
      "description": "Team endpoint discovery using team API keys"
    },
    {
      "name": "Runtime",
      "description": "Runtime capability discovery for SDK clients"
    },
    {
      "name": "Sessions",
      "description": "Session-token issuance for text, audio playback, voice, and browser-action SDK modes"
    },
    {
      "name": "Usage",
      "description": "Aggregated team-level usage reports (TTS character ingestion, etc.)"
    }
  ]
}