Delete session

Overview

A session is a conversation Blazing Agents keeps for you, so each new turn sees everything said before. Use these endpoints to start a conversation, continue it, read its history, delete it, and handle tool approvals. A session is saved as soon as its first turn is accepted, before the model runs. Continuing a session never creates one that is missing.

Policy-driven approvals

Sessions follow the agent's approvalInChat policy. Whether a tool call waits for a person or is escalated by automatic review, you handle it the same way: list the pending approvals, decide one, then join its continuation. See review availability.

Approval records also carry tool, assistantMessageId, createdAt, and decidedAt. Some of these fields are optional, so do not require them; see tool approval metadata.

Endpoints

List sessionsGET/v1/agents/:agentId/sessions

List an agent's sessions.

Lists an agent's sessions, most recently updated first, one page at a time. Each session shows its message count and a preview of its last message. An agent that does not exist in your tenant returns an empty page.

Request

Requires bearer authentication.

Returns 200 OK as application/json. A page of the agent's sessions.

Response schema: SessionList.

{
  "data": [
    {
      "id": "ss_6Rt2Mw8KqZ4Nc1Hp",
      "agentVersion": null,
      "messageCount": 4,
      "lastMessagePreview": "Open Settings, choose Security, and select Reset password.",
      "userId": "user_42",
      "metadata": {
        "plan": "pro"
      },
      "createdAt": "2026-07-10T10:00:00.000Z",
      "updatedAt": "2026-07-10T10:05:00.000Z"
    }
  ],
  "nextCursor": null
}

Errors

See REST errors for the error envelope and shared codes.

cURL

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

Create session turnPOST/v1/agents/:agentId/sessions

Create a session and run the first turn.

Starts a session and runs its first turn. The new session's URL is in the Location header. A rejected request creates no session; a turn that fails while running still leaves a session you can continue. Send version to pin the session to that agent version for every turn, or leave it out to use the agent's current version each time. trigger: "regenerate-message" is not allowed here. Send exactly one of message or promptId; variables is allowed only with promptId. The answer streams back as an AI SDK UI message stream. A failure before the stream starts returns a JSON error. Once the stream has started, a failure arrives as an error chunk; the turn still counts toward usage, and the conversation is left as it was.

Request

Requires bearer authentication and a JSON body.

Returns 201 Created as text/event-stream. Server-sent events, each carrying one AI SDK UI message chunk. Sets Location: URL of the new session.

Errors

See REST errors for the error envelope and shared codes.

cURL

curl --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":"How do I reset my password?"}]},"userId":"user_42","metadata":{"plan":"pro"}}'

List latest sessionsGET/v1/sessions/latest

List latest sessions.

Lists your tenant's sessions across all agents, most recently updated first, skipping sessions with no messages. Set byAgent=true to get only each agent's latest session, which is handy for an inbox of agents. Each item also shows the agent's current model, thinkingLevel, and status, and disabled agents are included.

Request

Requires bearer authentication.

Returns 200 OK as application/json. A page of your latest sessions.

Response schema: LatestSessionList.

{
  "data": [
    {
      "id": "ss_6Rt2Mw8KqZ4Nc1Hp",
      "agentVersion": null,
      "messageCount": 4,
      "lastMessagePreview": "Open Settings, choose Security, and select Reset password.",
      "userId": "user_42",
      "metadata": {
        "plan": "pro"
      },
      "createdAt": "2026-07-10T10:00:00.000Z",
      "updatedAt": "2026-07-10T10:05:00.000Z",
      "agentId": "ag_4kP9sT2vXq7LmN3a",
      "model": "openai/gpt-6-luna",
      "thinkingLevel": null,
      "status": "active"
    }
  ],
  "nextCursor": null
}

Errors

See REST errors for the error envelope and shared codes.

cURL

curl "$BLAZING_AGENTS_BASE_URL/v1/sessions/latest" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"

List session messagesGET/v1/agents/:agentId/sessions/:sessionId/messages

List session messages.

Lists a session's messages as AI SDK UIMessage objects. The first page holds the newest messages, and messages within a page are in chronological order. Use cursor to walk back to older messages, or save latestCursor and pass it as after later to fetch only new messages. Send at most one of cursor or after.

Request

Requires bearer authentication.

Returns 200 OK as application/json. A page of the session's messages.

Response schema: SessionMessageList.

{
  "data": [
    {
      "id": "msg_client_1",
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "How do I reset my password?"
        }
      ]
    },
    {
      "id": "msg_9Kd3Vx7PqT2bLn5W",
      "role": "assistant",
      "parts": [
        {
          "type": "text",
          "text": "Open Settings, choose Security, and select Reset password."
        }
      ]
    }
  ],
  "nextCursor": null,
  "latestCursor": "eyJzZXEiOjJ9"
}

Errors

See REST errors for the error envelope and shared codes.

cURL

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

Resume session turnPOST/v1/agents/:agentId/sessions/:sessionId

Resume a session with the next turn.

Continues a session with a new turn. A session that does not exist or was deleted returns 404; it is never created. version is not allowed: a pinned session keeps its version, and an unpinned one uses the agent's current version. To generate an answer again, set trigger: "regenerate-message" and optionally messageId; the conversation is cut back to that message (by default, the last answer) and the answer is generated again, and a failed regeneration keeps the previous answer. Returns 409 session_busy while another turn is running or a tool approval is waiting for a decision. Send exactly one of message or promptId; variables is allowed only with promptId. The answer streams back as an AI SDK UI message stream. A failure before the stream starts returns a JSON error. Once the stream has started, a failure arrives as an error chunk; the turn still counts toward usage, and the conversation is left as it was.

Request

Requires bearer authentication and a JSON body.

Returns 200 OK as text/event-stream. Server-sent events, each carrying one AI SDK UI message chunk.

Errors

See REST errors for the error envelope and shared codes.

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":"What if I no longer have my email?"}]}}'

Delete sessionDELETE/v1/agents/:agentId/sessions/:sessionId

Delete a session.

Deletes a session. Afterwards it can no longer be read or continued, and every request for it returns 404. Set deleteArtifacts to choose whether its artifacts are deleted too. While a tool approval is waiting for a decision, or the turn it resumes is still running, the session cannot be deleted.

Request

Requires bearer authentication.

Returns 204 No Content. The session was deleted.

Errors

See REST errors for the error envelope and shared codes.

cURL

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

List tool approvalsGET/v1/agents/:agentId/sessions/:sessionId/tool-approvals

List tool approvals.

Lists the session's pending and decided tool approvals, with the continuation that resumes the turn once they are decided, if there is one. Listing does not decide or claim any tool call.

Request

Requires bearer authentication.

Returns 200 OK as application/json. The session's tool approvals.

Response schema: ToolApprovalList.

{
  "data": [
    {
      "approvalId": "apr_3Fp9Lx2WqD6sNc8J",
      "decision": "pending",
      "tool": {
        "type": "builtin",
        "name": "bash"
      },
      "toolName": "bash",
      "toolCallId": "call_8Hn4Tb1ZrM5kQv2X",
      "input": {
        "command": "rm reports/2025-q4.csv"
      },
      "reason": null,
      "assistantMessageId": "msg_9Kd3Vx7PqT2bLn5W",
      "createdAt": "2026-07-10T10:05:00.000Z",
      "decidedAt": null
    }
  ],
  "continuation": {
    "id": "tac_5Wq8Hn2KxR7mTb4C",
    "state": "waiting"
  }
}

Errors

See REST errors for the error envelope and shared codes.

cURL

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

Decide tool approvalPOST/v1/agents/:agentId/sessions/:sessionId/tool-approvals/:approvalId

Decide a tool approval.

Approves or denies one pending tool call. The decision applies only to that exact call, and every other rule still applies. While other approvals from the same turn are still pending, the continuation stays waiting. Once the last one is decided it becomes queued and the agent carries on; join the continuation to stream the rest of the turn.

Request

Requires bearer authentication and a JSON body.

Returns 202 Accepted as application/json. The continuation that resumes the turn, and its state.

Response schema: ToolApprovalDecision.

{
  "continuationId": "tac_5Wq8Hn2KxR7mTb4C",
  "state": "queued"
}

Errors

See REST errors for the error envelope and shared codes.

cURL

curl --request POST "$BLAZING_AGENTS_BASE_URL/v1/agents/ag_1234567890ABCDEF/sessions/ss_1234567890ABCDEF/tool-approvals/$APPROVAL_ID" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"approved":true,"reason":"Reviewed the file; it is safe to delete."}'

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

Join a tool-approval continuation.

Streams the rest of the turn after its tool approvals are decided, as an AI SDK UI message stream. Output saved so far replays first, then live output follows until the turn ends, so you can join again at any time. Returns 409 session_busy while an approval is still waiting for a decision. A failure before the stream starts returns a JSON error; later failures arrive as error chunks in the stream.

Request

Requires bearer authentication.

Returns 200 OK as text/event-stream. Server-sent events, each carrying one AI SDK UI message chunk.

Errors

See REST errors for the error envelope and shared codes.

cURL

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

Next

• Sessions and turns to continue, stop, and reload conversations.
• Streaming protocol to read the SSE stream.
• Tool approvals to choose which calls need review.