ReferenceREST API

Sessions

Overview

A Session stores a stateful Agent transcript and its Tool-approval lifecycle. Use these endpoints to start or resume Turns, inspect history, delete the Session, or decide and join approvals; creation materializes only after a successful first Turn, and resume never creates a missing Session.

Endpoints

POST /v1/agents/:agentId/sessions

Mints a Session ID and runs the first stateful turn. The Session materializes only after a successful turn; a failed or aborted first turn leaves no Session row.

Request

Requires bearer authentication, JSON, and an ag_… agentId path parameter. Provide exactly one of message or promptId; variables is allowed only with promptId. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

LocationFieldRequiredDescription
HeaderAuthorizationyesTenant API key or dashboard Supabase JWT.
PathagentIdyesAgent ID (ag_…).
Body fieldTypeRequiredDescription
messageAI SDK UIMessagealternativeMust have id, role, and non-empty parts; file parts must be images
promptIdstringalternativeStored Prompt ID
variablesobject<string,string>noExact Prompt variables
triggerstringnoDefaults to submit-message; regeneration is invalid here
messageIdstringnoUsed only with regeneration on resume
streambooleannoDefaults to true
userIdstringnoSession and usage attribution; defaults to ""
metadataobjectnoSession and usage metadata; defaults to {}
versionintegernoPin an immutable Agent Version; omission leaves the Session unpinned

An omitted version has no schema default. An unpinned Session resolves the Agent's current Version for each Turn; an explicit pin remains fixed for later resumes.

Response

Returns 201 Created and Location: /v1/agents/:agentId/sessions/:sessionId.

With stream: true, the body is an AI SDK UI message SSE stream of UIMessageChunk events. The response includes Content-Type: text/event-stream and X-Vercel-AI-UI-Message-Stream: v1. With stream: false, it is JSON:

Response schema: chatNonStreamResponseSchema.

{
  "message": {
    "id": "msg_response",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "Hello!" }]
  }
}

Errors

400 invalid_request for malformed/mixed input, incorrect Prompt variables, or regenerate-message. 404 not_found applies to a missing Agent, Provider, Prompt, or pinned Version (AGENT_VERSION_NOT_FOUND). 409 AGENT_DISABLED or 409 SANDBOX_REQUIRED can reject execution. 429 quota_exceeded and 502 provider_error may occur. Pre-stream failures use the JSON envelope; mid-stream failures emit an AI SDK error chunk. Failed turns are metered but do not change the transcript. See REST errors.

cURL

curl --include --no-buffer --request POST \
  "$BLAZING_AGENTS_BASE_URL/v1/agents/ag_1234567890ABCDEF/sessions" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"message":{"id":"msg_client_1","role":"user","parts":[{"type":"text","text":"Hello"}]},"stream":true}'

SDK: chat. See Sessions and Turns and Build a chat endpoint.

POST /v1/agents/:agentId/sessions/:sessionId

Runs a turn using the Session's accepted history. Unknown and deleted Sessions return 404; this endpoint never creates them silently.

Request

Requires bearer authentication, JSON, an ag_… agentId, and an ss_… sessionId. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

LocationFieldRequiredDescription
HeaderAuthorizationyesTenant API key or dashboard Supabase JWT.
PathagentIdyesAgent ID (ag_…).
PathsessionIdyesSession ID (ss_…).

The body matches Create a Session turn except that version is rejected. A Session created with a pin keeps using that Version; an unpinned Session resolves the Agent's current Version on each resumed Turn. To regenerate, set trigger: "regenerate-message" and optionally messageId; the transcript is truncated from that stored message and regenerated. A literal message or stored promptId remains required.

Response

Returns 200 OK. With stream: true (default), the body is an AI SDK UI message SSE stream with Content-Type: text/event-stream and X-Vercel-AI-UI-Message-Stream: v1. With stream: false, it returns { "message": <UIMessage> }. Unlike create, resume does not return a Location header.

Non-streaming response schema: chatNonStreamResponseSchema.

Errors

400 invalid_request for invalid input, Prompt variables, version, or regeneration state. 404 not_found for an unknown/deleted Session or missing Agent/Provider/Prompt. 409 AGENT_DISABLED or 409 SANDBOX_REQUIRED can reject execution. 429 quota_exceeded and 502 provider_error may occur. Failed turns are metered but leave the accepted transcript unchanged. See REST errors.

cURL

curl --no-buffer --request POST \
  "$BLAZING_AGENTS_BASE_URL/v1/agents/ag_1234567890ABCDEF/sessions/ss_1234567890ABCDEF" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"message":{"id":"msg_client_2","role":"user","parts":[{"type":"text","text":"Tell me more."}]},"stream":true}'

SDK: chat. See Sessions and Turns and Build a chat endpoint.

GET /v1/agents/:agentId/sessions

Returns Sessions ordered by most recently updated. An unknown or foreign Agent ID produces an empty page.

Request

Requires bearer authentication and an ag_… agentId path parameter. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

LocationFieldRequiredDescription
HeaderAuthorizationyesTenant API key or dashboard Supabase JWT.
PathagentIdyesAgent ID (ag_…).
Query parameterTypeDefaultDescription
cursorstring—Opaque cursor from nextCursor
limitinteger501–200
userIdstring—Attribution filter; "" selects tenant-level Sessions

Response

Returns 200 OK with cursor pagination.

Response schema: sessionsListResponseSchema.

{
  "data": [
    {
      "id": "ss_1234567890ABCDEF",
      "agentVersion": 3,
      "messageCount": 4,
      "lastMessagePreview": "Tell me more.",
      "userId": "",
      "metadata": {},
      "createdAt": "2026-07-10T10:00:00Z",
      "updatedAt": "2026-07-10T10:05:00Z"
    }
  ],
  "nextCursor": null
}

Errors

400 invalid_request for malformed parameters or cursor. See REST errors.

cURL

curl --get \
  "$BLAZING_AGENTS_BASE_URL/v1/agents/ag_1234567890ABCDEF/sessions" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --data-urlencode "limit=50"

SDK: list. See Sessions and Turns and Build a chat endpoint.

GET /v1/agents/:agentId/sessions/:sessionId/messages

Returns stored AI SDK UIMessage objects verbatim. The newest page is returned first, with messages chronological within each page.

Request

Requires bearer authentication, an ag_… agentId, and an ss_… sessionId. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

LocationFieldRequiredDescription
HeaderAuthorizationyesTenant API key or dashboard Supabase JWT.
PathagentIdyesAgent ID (ag_…).
PathsessionIdyesSession ID (ss_…).
Query parameterTypeDefaultDescription
cursorstring—Walk backward to older messages
afterstring—Poll forward after a latestCursor
limitinteger501–200

cursor and after are mutually exclusive.

Response

Returns 200 OK.

Response schema: sessionMessagesResponseSchema.

{
  "data": [
    {
      "id": "msg_client_1",
      "role": "user",
      "parts": [{ "type": "text", "text": "Hello" }]
    },
    {
      "id": "msg_response",
      "role": "assistant",
      "parts": [{ "type": "text", "text": "Hello!" }]
    }
  ],
  "nextCursor": null,
  "latestCursor": "opaque-tail-cursor"
}

Errors

400 invalid_request for invalid IDs, cursors, limits, or both cursor directions. 404 not_found for a missing, foreign, or deleted Session. See REST errors.

cURL

curl --get \
  "$BLAZING_AGENTS_BASE_URL/v1/agents/ag_1234567890ABCDEF/sessions/ss_1234567890ABCDEF/messages" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --data-urlencode "limit=50"

SDK: messages. See Sessions and Turns and Build a chat endpoint.

DELETE /v1/agents/:agentId/sessions/:sessionId

Soft-deletes the Session. Its ID subsequently returns 404 across the Session surface.

Request

Requires bearer authentication, an ag_… agentId, and an ss_… sessionId. There are no query or body parameters. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

LocationFieldRequiredDescription
HeaderAuthorizationyesTenant API key or dashboard Supabase JWT.
PathagentIdyesAgent ID (ag_…).
PathsessionIdyesSession ID (ss_…).

Response

Returns 204 No Content with an empty body.

Errors

400 invalid_request for malformed IDs. 404 not_found for a missing, foreign, or already-deleted Session. See REST errors.

cURL

curl --request DELETE \
  "$BLAZING_AGENTS_BASE_URL/v1/agents/ag_1234567890ABCDEF/sessions/ss_1234567890ABCDEF" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"

SDK: delete. See Sessions and Turns and Build a chat endpoint.

GET /v1/agents/:agentId/sessions/:sessionId/tool-approvals

Lists pending and decided Tool approvals. The Tenant must own the Agent and Session.

Request

Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

LocationFieldRequiredDescription
HeaderAuthorizationyesTenant API key or dashboard Supabase JWT.
PathagentIdyesAgent ID (ag_…).
PathsessionIdyesSession ID (ss_…).

Response

StatusBodyLifecycle effect
200 OKToolApprovalsResponseRead-only.

Approval state belongs to this Session; listing does not claim or decide a Tool call.

Response schema: toolApprovalsResponseSchema.

Errors

404 not_found. See REST errors.

cURL

curl "$BLAZING_AGENTS_BASE_URL/v1/agents/ag_1234567890ABCDEF/sessions/ss_1234567890ABCDEF/tool-approvals" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"

SDK: tool-approvals. See Tool approvals and Build a chat endpoint.

POST /v1/agents/:agentId/sessions/:sessionId/tool-approvals/:approvalId

Approves or denies one exact pending Tool call. The Tenant must own the Agent and Session.

Request

Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

LocationFieldRequiredDescription
HeaderAuthorizationyesTenant API key or dashboard Supabase JWT.
PathagentIdyesAgent ID (ag_…).
PathsessionIdyesSession ID (ss_…).
PathapprovalIdyesTool approval ID.
LocationFieldRequiredDescription
Bodyapprovedyestrue to approve; false to deny.
BodyreasonnoDecision reason, up to 1,000 characters.
HeaderContent-Typeyesapplication/json.

Response

StatusBodyLifecycle effect
202 AcceptedToolApprovalDecisionResponsePersists the decision and exposes a continuation to join.

The decision authorizes only the named Tool call; it does not bypass Tenant or product invariants.

Response schema: toolApprovalDecisionResponseSchema.

Errors

400 invalid_request; 404 not_found; 409 when the approval is no longer pending. See REST errors.

cURL

curl --request POST "$BLAZING_AGENTS_BASE_URL/v1/agents/ag_1234567890ABCDEF/sessions/ss_1234567890ABCDEF/tool-approvals/apr_1234567890ABCDEF" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"approved":true,"reason":"Reviewed"}'

SDK: decide-tool-approval. See Tool approvals and Build a chat endpoint.

GET /v1/agents/:agentId/sessions/:sessionId/tool-approval-continuations/:continuationId

Joins the terminal SSE stream for a decided Tool approval. The Tenant must own the Agent and Session.

Request

Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

LocationFieldRequiredDescription
HeaderAuthorizationyesTenant API key or dashboard Supabase JWT.
PathagentIdyesAgent ID (ag_…).
PathsessionIdyesSession ID (ss_…).
PathcontinuationIdyesTool-approval continuation ID.

Response

StatusBodyLifecycle effect
200 OKAI SDK UI message event streamClaims or follows the durable continuation until it succeeds or fails.

The response is SSE with Content-Type: text/event-stream, X-Vercel-AI-UI-Message-Stream: v1, Cache-Control: no-cache, Connection: keep-alive, and X-Accel-Buffering: no. 409 SESSION_BUSY applies only while the continuation is waiting. Queued and running joins, replays, and followers stream persisted chunks before following live or returning terminal state.

Errors

404 not_found; 409 SESSION_BUSY; pre-stream Turn errors use the JSON error envelope and later failures use error chunks. See REST errors.

cURL

curl --no-buffer "$BLAZING_AGENTS_BASE_URL/v1/agents/ag_1234567890ABCDEF/sessions/ss_1234567890ABCDEF/tool-approval-continuations/cont_1234567890ABCDEF" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"

SDK: join-tool-approval-continuation. See Tool approvals and Build a chat endpoint.

Generation endpoint

Run stateless text or structured generation.

Artifact endpoints

List, download, and delete Agent-produced Artifacts.

On this page

SessionsOverviewEndpointsPOST /v1/agents/:agentId/sessionsRequestResponseErrorscURLSDK and related guidesPOST /v1/agents/:agentId/sessions/:sessionIdRequestResponseErrorscURLSDK and related guidesGET /v1/agents/:agentId/sessionsRequestResponseErrorscURLSDK and related guidesGET /v1/agents/:agentId/sessions/:sessionId/messagesRequestResponseErrorscURLSDK and related guidesDELETE /v1/agents/:agentId/sessions/:sessionIdRequestResponseErrorscURLSDK and related guidesGET /v1/agents/:agentId/sessions/:sessionId/tool-approvalsRequestResponseErrorscURLSDK and related guidesPOST /v1/agents/:agentId/sessions/:sessionId/tool-approvals/:approvalIdRequestResponseErrorscURLSDK and related guidesGET /v1/agents/:agentId/sessions/:sessionId/tool-approval-continuations/:continuationIdRequestResponseErrorscURLSDK and related guidesRelated