ReferenceREST API

Agents

Overview

Agents are Tenant-owned configuration records. Use these endpoints to configure execution, inspect immutable Versions, attach capabilities, or operate the reversible execution kill switch; Attribution remains immutable after creation.

Endpoints

POST /v1/agents

Creates an Agent. Names are unique per tenant; a tenant can have at most 100 Agents.

Request

Requires bearer authentication and JSON. There are no path or query 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.
Body fieldTypeRequiredDefault
namestringyes—
modelstringnodeepseek/deepseek-v4-flash
providerIdstring | nullnonull
skillsstring[]no[]
toolsstring[]no[]
sandboxIdstring | nullnonull
instructionsstringno""
memoryInjectionEnabledbooleannofalse
userIdstringno""
metadataobjectno{}
mcpConnectionIdsstring[]no[]

model must contain a provider/model separator. Tool groups are file_operation_sandbox, write_todos, and memory. Selecting file_operation_sandbox requires a tenant-owned sandboxId in the effective Agent state.

Response

Returns 201 Created with an Agent object.

Response schema: agentResponseSchema.

{
  "id": "ag_1234567890ABCDEF",
  "tenantId": "ten_1234567890ABCDEF",
  "name": "Support Agent",
  "model": "openrouter/auto",
  "providerId": null,
  "skills": [],
  "tools": ["file_operation_sandbox", "write_todos"],
  "sandboxId": "sb_1234567890ABCDEF",
  "instructions": "Answer clearly.",
  "memoryInjectionEnabled": true,
  "userId": "",
  "metadata": {},
  "mcpConnectionIds": [],
  "avatarUrl": null,
  "version": 1,
  "status": "active",
  "createdAt": "2026-07-10T10:00:00Z",
  "updatedAt": "2026-07-10T10:00:00Z"
}

Errors

400 invalid_request for invalid fields, duplicate names, invalid Provider or Skill IDs, or the Agent cap. 409 SANDBOX_REQUIRED applies when sandbox-backed file operations have no valid tenant-owned attachment. 409 SANDBOX_IN_USE applies when the Sandbox is already attached to another Agent. See REST errors.

cURL

curl --request POST "$BLAZING_AGENTS_BASE_URL/v1/agents" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name":"Support Agent","model":"openrouter/auto","sandboxId":"sb_1234567890ABCDEF","tools":["file_operation_sandbox","write_todos"],"instructions":"Answer clearly.","memoryInjectionEnabled":true}'

SDK: create. See Agents and Build a chat endpoint.

GET /v1/agents

Returns Agents ordered by most recently updated. The bounded list is not paginated.

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.
Query parameterTypeRequiredDescription
userIdstringnoOmit for all Agents; use an opaque value or "" for tenant-level Agents

There is no request body.

Response

Returns 200 OK with complete Agent objects.

Response schema: agentsResponseSchema.

{
  "agents": [
    {
      "id": "ag_1234567890ABCDEF",
      "tenantId": "ten_1234567890ABCDEF",
      "name": "Support Agent",
      "model": "openrouter/auto",
      "providerId": null,
      "sandboxId": null,
      "memoryInjectionEnabled": false,
      "skills": [],
      "tools": [],
      "instructions": "Answer clearly.",
      "userId": "",
      "metadata": {},
      "mcpConnectionIds": [],
      "avatarUrl": null,
      "version": 1,
      "status": "active",
      "createdAt": "2026-07-10T10:00:00Z",
      "updatedAt": "2026-07-10T10:00:00Z"
    }
  ]
}

Errors

400 invalid_request for unknown query fields. Standard errors also apply; see REST errors.

cURL

curl --get "$BLAZING_AGENTS_BASE_URL/v1/agents" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --data-urlencode "userId="

SDK: list. See Agents and Build a chat endpoint.

GET /v1/agents/:agentId

Returns one current Agent configuration. Reading an Agent does not create a Version or otherwise change its lifecycle.

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_…).
Path parameterTypeDescription
agentIdstringAgent ID (ag_…)

There are no query or body parameters.

Response

Returns 200 OK with an Agent object, including a short-lived avatarUrl when an avatar exists.

Response schema: agentResponseSchema.

{
  "id": "ag_1234567890ABCDEF",
  "tenantId": "ten_1234567890ABCDEF",
  "name": "Support Agent",
  "model": "openrouter/auto",
  "providerId": null,
  "sandboxId": null,
  "memoryInjectionEnabled": false,
  "skills": [],
  "tools": [],
  "instructions": "Answer clearly.",
  "userId": "",
  "metadata": {},
  "mcpConnectionIds": [],
  "avatarUrl": null,
  "version": 1,
  "status": "active",
  "createdAt": "2026-07-10T10:00:00Z",
  "updatedAt": "2026-07-10T10:00:00Z"
}

Errors

400 invalid_request for a malformed ID. 404 not_found when the Agent is missing or belongs to another tenant. See REST errors.

cURL

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

SDK: get. See Agents and Build a chat endpoint.

PUT /v1/agents/:agentId

Updates the supplied Agent fields. Arrays such as skills and tools replace the full existing array. userId is immutable.

Request

Requires bearer authentication and JSON. 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_…).
ParameterTypeRequiredDescription
Body namestringno1–80 characters
Body modelstringnoProvider/model identifier
Body providerIdstring | nullnoStored Provider or platform key
Body skillsstring[]noComplete replacement Skill list
Body toolsstring[]noComplete replacement tool-group list
Body sandboxIdstring | nullnoAttach or detach a durable Sandbox
Body instructionsstringnoUp to 3,000 characters
Body memoryInjectionEnabledbooleannoToggle automatic memory context
Body metadataobjectnoReplacement metadata
Body mcpConnectionIdsstring[]noComplete replacement MCP list

At least one field is required. There are no query parameters.

Response

Returns 200 OK with the complete updated Agent object.

Response schema: agentResponseSchema.

{
  "id": "ag_1234567890ABCDEF",
  "tenantId": "ten_1234567890ABCDEF",
  "name": "Support Agent",
  "model": "openrouter/auto",
  "providerId": null,
  "skills": [],
  "tools": ["file_operation_sandbox"],
  "sandboxId": "sb_1234567890ABCDEF",
  "instructions": "Answer clearly.",
  "memoryInjectionEnabled": true,
  "userId": "",
  "metadata": { "team": "support" },
  "mcpConnectionIds": [],
  "avatarUrl": null,
  "version": 2,
  "status": "active",
  "createdAt": "2026-07-10T10:00:00Z",
  "updatedAt": "2026-07-10T10:15:00Z"
}

Errors

400 invalid_request for invalid/empty input, a duplicate name, or invalid Provider/Skill/tool selection. 404 not_found applies when the Agent is missing or foreign. 409 SANDBOX_REQUIRED applies when the effective state selects sandbox-backed file operations without an attachment; 409 SANDBOX_IN_USE applies when attaching a Sandbox used by another Agent; and 409 ADMIN_AGENT_MANAGED protects the Admin Agent. See REST errors.

cURL

curl --request PUT \
  "$BLAZING_AGENTS_BASE_URL/v1/agents/ag_1234567890ABCDEF" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"sandboxId":"sb_1234567890ABCDEF","tools":["file_operation_sandbox"],"metadata":{"team":"support"}}'

SDK: update. See Agents and Build a chat endpoint.

DELETE /v1/agents/:agentId

Hard-deletes the Agent.

Request

Requires bearer authentication. agentId is a required ag_… path parameter. 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_…).

Response

Returns 204 No Content with an empty body.

Errors

400 invalid_request for a malformed ID. 404 not_found when the Agent is missing or foreign. 409 ADMIN_AGENT_MANAGED protects the Admin Agent. See REST errors.

cURL

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

SDK: delete. See Agents and Build a chat endpoint.

POST /v1/agents/:agentId/disable

Disables an active Agent and rejects future Turns. The bearer credential's Tenant must own the Agent and every referenced resource.

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_…).

Response

StatusBodyLifecycle effect
200 OKAgentSets status to disabled; in-flight Turns finish.

Response schema: agentSchema.

Errors

404 not_found; 409 ADMIN_AGENT_MANAGED for the Admin Agent. See REST errors.

cURL

curl --request POST "$BLAZING_AGENTS_BASE_URL/v1/agents/ag_1234567890ABCDEF/disable" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"

SDK: disable. See Agents and Build a chat endpoint.

POST /v1/agents/:agentId/enable

Re-enables a disabled Agent. The bearer credential's Tenant must own the Agent and every referenced resource.

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_…).

Response

StatusBodyLifecycle effect
200 OKAgentSets status to active; skipped schedule fires are not replayed.

Response schema: agentSchema.

Errors

404 not_found; 409 ADMIN_AGENT_MANAGED. See REST errors.

cURL

curl --request POST "$BLAZING_AGENTS_BASE_URL/v1/agents/ag_1234567890ABCDEF/enable" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"

SDK: enable. See Agents and Build a chat endpoint.

POST /v1/agents/:agentId/avatar

Replaces the Agent's private avatar. API responses expose a short-lived signed avatarUrl, never the storage object key.

Request

Requires bearer authentication and multipart/form-data. 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_…).
ParameterTypeRequiredDescription
Form filefileyesPNG, JPEG, or WebP, at most 512 KiB

There are no query parameters.

Response

Returns 200 OK with the complete updated Agent object. avatarUrl is a short-lived signed URL.

Response schema: agentSchema.

Errors

400 invalid_request when file is missing. 413 invalid_request when it exceeds 512 KiB. 415 invalid_request for another media type. 404 not_found when the Agent is missing or foreign. 409 ADMIN_AGENT_MANAGED protects the Admin Agent. See REST errors.

cURL

curl --request POST \
  "$BLAZING_AGENTS_BASE_URL/v1/agents/ag_1234567890ABCDEF/avatar" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --form "file=@./avatar.webp;type=image/webp"

SDK: upload-avatar. See Agents and Build a chat endpoint.

DELETE /v1/agents/:agentId/avatar

Removes the avatar and returns the updated Agent.

Request

Requires bearer authentication. agentId is a required ag_… path parameter. 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_…).

Response

Returns 200 OK with the complete updated Agent object; avatarUrl is null.

Response schema: agentSchema.

Errors

400 invalid_request for a malformed ID. 404 not_found when the Agent is missing or foreign. 409 ADMIN_AGENT_MANAGED protects the Admin Agent. See REST errors.

cURL

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

SDK: remove-avatar. See Agents and Build a chat endpoint.

GET /v1/agents/:agentId/versions

Lists immutable Agent Versions newest first. The bearer credential's Tenant must own the Agent and every referenced resource.

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_…).
LocationFieldRequiredDescription
QuerycursornoOpaque backward-page cursor.
QuerylimitnoPage size; defaults to exactly 50.

Response

StatusBodyLifecycle effect
200 OKAgentVersionsResponseRead-only.

Use nextCursor for the next page.

Response schema: agentVersionsResponseSchema.

Errors

400 invalid_request; 404 not_found. See REST errors.

cURL

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

SDK: list-versions. See Agents and Build a chat endpoint.

GET /v1/agents/:agentId/versions/:version

Gets one immutable Agent Version. The bearer credential's Tenant must own the Agent and every referenced resource.

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_…).
PathversionyesPositive Agent Version number.

Response

StatusBodyLifecycle effect
200 OKAgentVersionRead-only; current referenced resources are not copied.

Response schema: agentVersionSchema.

Errors

400 invalid_request; 404 AGENT_VERSION_NOT_FOUND. See REST errors.

cURL

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

SDK: get-version. See Agents and Build a chat endpoint.

GET /v1/agents/:agentId/mcp-attachments

Lists the MCP Attachments selecting MCP tools for an Agent. The bearer credential's Tenant must own the Agent and every referenced resource.

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_…).

Response

StatusBodyLifecycle effect
200 OKMcpAttachmentsResponseRead-only.

Response schema: mcpAttachmentsResponseSchema.

Errors

404 not_found. See REST errors.

cURL

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

SDK: list-mcp-attachments. See Agents and Build a chat endpoint.

PATCH /v1/agents/:agentId/mcp-attachments/:mcpConnectionId

Changes end-user fields forwarded through one MCP Attachment. The bearer credential's Tenant must own the Agent and every referenced resource.

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_…).
PathmcpConnectionIdyesMCP Connection ID.
LocationFieldRequiredDescription
BodyforwardUserIdnoWhether to forward userId.
BodyforwardedMetadataKeysnoUnique metadata-key allowlist; at least one body field is required.
HeaderContent-Typeyesapplication/json.

Response

StatusBodyLifecycle effect
200 OKMcpAttachmentResponseUpdates attachment forwarding only; it does not change access control.

Response schema: mcpAttachmentResponseSchema.

Errors

400 invalid_request; 404 not_found. See REST errors.

cURL

curl --request PATCH "$BLAZING_AGENTS_BASE_URL/v1/agents/ag_1234567890ABCDEF/mcp-attachments/mcp_1234567890ABCDEF" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"forwardUserId":true,"forwardedMetadataKeys":["locale"]}'

SDK: update-mcp-attachment. See Agents and Build a chat endpoint.

Authentication

Authenticate REST requests and understand Tenant resolution.

API key endpoints

Create, list, and revoke Tenant API keys.

On this page

AgentsOverviewEndpointsPOST /v1/agentsRequestResponseErrorscURLSDK and related guidesGET /v1/agentsRequestResponseErrorscURLSDK and related guidesGET /v1/agents/:agentIdRequestResponseErrorscURLSDK and related guidesPUT /v1/agents/:agentIdRequestResponseErrorscURLSDK and related guidesDELETE /v1/agents/:agentIdRequestResponseErrorscURLSDK and related guidesPOST /v1/agents/:agentId/disableRequestResponseErrorscURLSDK and related guidesPOST /v1/agents/:agentId/enableRequestResponseErrorscURLSDK and related guidesPOST /v1/agents/:agentId/avatarRequestResponseErrorscURLSDK and related guidesDELETE /v1/agents/:agentId/avatarRequestResponseErrorscURLSDK and related guidesGET /v1/agents/:agentId/versionsRequestResponseErrorscURLSDK and related guidesGET /v1/agents/:agentId/versions/:versionRequestResponseErrorscURLSDK and related guidesGET /v1/agents/:agentId/mcp-attachmentsRequestResponseErrorscURLSDK and related guidesPATCH /v1/agents/:agentId/mcp-attachments/:mcpConnectionIdRequestResponseErrorscURLSDK and related guidesRelated