Skip to main content

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

POST /api/v1/sessions/token

Request a session token

Issues a runtime session id and a short-lived WebSocket token for the requested SDK mode. After this call, connect the browser SDK to: /ws/session?sessionId={sessionId}&token={wsToken} WebSocket wire format: - Messages use the ChannelMessage envelope (see components.schemas.ChannelMessage). - The server sends an initial status message with state=connected. WebSocket close codes: - 4001 — missing sessionId or token - 4003 — invalid token or expired session - 4000 — superseded by a newer connection - 4500 — internal server error Authentication: requires a team API key with CREATE_CALL_TOKEN scope. Browser voice is not enabled in this profile.

Request, response and operation contract​

{
  "summary": "Request a session token",
  "tags": ["Sessions"],
  "description": "Issues a runtime session id and a short-lived WebSocket token for the requested SDK mode.\n\nAfter this call, connect the browser SDK to:\n  /ws/session?sessionId={sessionId}&token={wsToken}\n\nWebSocket wire format:\n- Messages use the ChannelMessage envelope (see components.schemas.ChannelMessage).\n- The server sends an initial status message with state=connected.\n\nWebSocket close codes:\n- 4001 — missing sessionId or token\n- 4003 — invalid token or expired session\n- 4000 — superseded by a newer connection\n- 4500 — internal server error\n\nAuthentication: requires a team API key with CREATE_CALL_TOKEN scope.\n\nBrowser voice is not enabled in this profile.",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": ["endpointId", "mode"],
          "properties": {
            "endpointId": {
              "type": "string",
              "format": "uuid",
              "description": "Endpoint to open a session against. It must belong to the API key team.",
              "example": "0f6c3d4e-8b8f-4c59-9d0e-7e5e3b1f7f0f"
            },
            "mode": {
              "type": "string",
              "enum": ["text", "audio_playback", "browser_actions", "listen"],
              "description": "Session mode to provision: text chat, browser TTS playback, browser action dispatch, or interpretation listening."
            }
          }
        },
        "examples": {
          "request_text_capability": {
            "summary": "Request a text session",
            "value": {
              "endpointId": "0f6c3d4e-8b8f-4c59-9d0e-7e5e3b1f7f0f",
              "mode": "text"
            }
          },
          "request_audio_playback_capability": {
            "summary": "Request an audio playback session",
            "value": {
              "endpointId": "0f6c3d4e-8b8f-4c59-9d0e-7e5e3b1f7f0f",
              "mode": "audio_playback"
            }
          },
          "request_browser_actions_capability": {
            "summary": "Request a browser actions session",
            "value": {
              "endpointId": "0f6c3d4e-8b8f-4c59-9d0e-7e5e3b1f7f0f",
              "mode": "browser_actions"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ],
  "responses": {
    "200": {
      "description": "Default Response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": ["sessionId", "wsToken", "wsTokenExpiresIn", "expiresIn"],
            "properties": {
              "sessionId": {
                "type": "string",
                "description": "The runtime session id (also the X-Call-ID for voice)"
              },
              "wsToken": {
                "type": "string",
                "description": "WebSocket token for /ws/session authentication"
              },
              "wsTokenExpiresIn": {
                "type": "number",
                "description": "WS token validity in seconds (5 min)"
              },
              "expiresIn": {
                "type": "number",
                "description": "Session token validity in seconds"
              }
            }
          },
          "examples": {
            "example_text_capability": {
              "summary": "Text session token",
              "value": {
                "sessionId": "call-loc5q7g0-k7p3f9x2",
                "wsToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
                "wsTokenExpiresIn": 300,
                "expiresIn": 3600
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Request validation failed",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "description": "Request validation failed",
            "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."
                  }
                }
              }
            }
          },
          "example": {
            "error": {
              "code": "VALIDATION_ERROR",
              "message": "Request validation failed"
            }
          }
        }
      }
    },
    "401": {
      "description": "API key is missing or invalid",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "description": "API key is missing or invalid",
            "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."
                  }
                }
              }
            }
          },
          "example": {
            "error": {
              "code": "AUTHENTICATION_ERROR",
              "message": "API key is missing or invalid"
            }
          }
        }
      }
    },
    "403": {
      "description": "Forbidden: wrong team, origin/IP rejected, missing scope, or subscription limit reached",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "description": "Forbidden: wrong team, origin/IP rejected, missing scope, or subscription limit reached",
            "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."
                  }
                }
              }
            }
          },
          "example": {
            "error": {
              "code": "FORBIDDEN",
              "message": "Forbidden: wrong team, origin/IP rejected, missing scope, or subscription limit reached"
            }
          }
        }
      }
    },
    "404": {
      "description": "Endpoint not found",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "description": "Endpoint not found",
            "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."
                  }
                }
              }
            }
          },
          "example": {
            "error": {
              "code": "NOT_FOUND",
              "message": "Endpoint not found"
            }
          }
        }
      }
    },
    "409": {
      "description": "Endpoint flow is not configured or not synced for the requested mode",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "description": "Endpoint flow is not configured or not synced for the requested mode",
            "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."
                  }
                }
              }
            }
          },
          "example": {
            "error": {
              "code": "FLOW_NOT_CONFIGURED",
              "message": "Endpoint flow is not configured or not synced for the requested mode"
            }
          }
        }
      }
    },
    "429": {
      "description": "Too many requests",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "description": "Too many requests",
            "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."
                  }
                }
              }
            }
          },
          "example": {
            "error": {
              "code": "RATE_LIMIT_EXCEEDED",
              "message": "Too many requests"
            }
          }
        }
      }
    },
    "500": {
      "description": "Unexpected server error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "description": "Unexpected server error",
            "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."
                  }
                }
              }
            }
          },
          "example": {
            "error": {
              "code": "INTERNAL_ERROR",
              "message": "Unexpected server error"
            }
          }
        }
      }
    }
  }
}

Shared path-item configuration​

{}

Effective document defaults​

{
  "servers": [],
  "security": []
}

Resolve local schema references in the component catalogue or the exact OpenAPI download. Operation and path-item overrides retain their OpenAPI meaning; omitted security is not a declaration that authentication is unnecessary.