Enable agent

Overview

An agent holds the configuration Blazing Agents uses to run a turn: its provider and model, instructions, tools, workspace, and attachments. Use these endpoints to create and change agents, read their saved versions, attach MCP servers, and turn an agent off and on again. userId is fixed once the agent is created.

Automatic context compaction

POST and PUT accept autoCompaction (default true on create) and compactionReserveTokens (default 16384 on create, a nonnegative safe integer). Leave them out of an update to keep the saved values. Agents and agent versions both return them. See context compaction for how summaries work, what they cost, and what happens when they fail.

Thinking configuration

POST and PUT accept thinkingLevel: string | null. It defaults to null on create. Leave it out of an update to keep it, or send null to clear it. A non-null value must be non-empty and needs a configured provider and model. Agent and version responses include it. A level the model is known not to support returns validation_failed with the valid choices, and nothing is saved. On the admin agent you can change the thinking level along with its provider and model, but nothing else.

Tool approval configuration

POST and PUT accept approvalInChat and approvalInTasks, each an ApprovalPolicy. Agent and version responses include both. Each defaults to {"default":"full","overrides":[]} on create. Leave a policy out of an update to keep it; send one to replace it, and a missing or empty overrides clears the list. Neither accepts null. Built-in tools you name must be available. New or changed MCP tools must be found on an MCP connection attached to the agent in your tenant. Naming the same tool twice is invalid, and later configuration or attachment changes must keep every rule valid. See policy examples and validation.

Endpoints

List agentsGET`/v1/agents`

List agents.

Lists your agents, most recently updated first. Filter by end user or by workspace.

Request

Requires bearer authentication.

Field	Type	Location	Required	Description
`userId`	string	query		Return only agents for this end user. Send an empty string for tenant-level agents, or leave it out for all agents.
`workspaceId`	string	query		Return only agents that use this workspace.

Response

The updated agent.

Agentobjectrequired

The updated agent.

Returns 200 OK as application/json. The tenant's agents.

Response schema: AgentList.

{
  "agents": [
    {
      "approvalInChat": {
        "default": "full",
        "overrides": []
      },
      "approvalInTasks": {
        "default": "full",
        "overrides": []
      },
      "id": "ag_4kP9sT2vXq7LmN3a",
      "tenantId": "ten_8Hq2Zr5WcY1bJt6D",
      "name": "Support Agent",
      "model": "openai/gpt-6-luna",
      "thinkingLevel": null,
      "providerId": "prv_7Tn4Kd9QwE2sLx5R",
      "workspaceId": "ws_3Vb8Ny6HpU1cGf4M",
      "autoCompaction": true,
      "compactionReserveTokens": 16384,
      "memoryInjectionEnabled": false,
      "tools": [
        "workspace",
        "write_todos"
      ],
      "instructions": "Answer billing questions clearly and briefly.",
      "userId": "",
      "metadata": {
        "team": "support"
      },
      "mcpConnectionIds": [],
      "avatarUrl": null,
      "createdAt": "2026-07-10T10:00:00.000Z",
      "updatedAt": "2026-07-10T10:00:00.000Z",
      "version": 1,
      "status": "active"
    }
  ]
}

Errors

Status	Codes	Description
`400`	`validation_failed`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required

See REST errors for the error envelope and shared codes.

cURL

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

Create agentPOST`/v1/agents`

Create an agent.

Creates an agent. Names are unique within your tenant. providerId and model go together: send both to give the agent a model, or leave both out. Leave out workspaceId to create a new workspace for the agent.

Request

Requires bearer authentication and a JSON body.

Field	Type	Location	Required	Description
`approvalInChat`	object	body		Which tool calls need approval in sessions and stateless generation. Defaults to `{"default":"full","overrides":[]}`.
`approvalInTasks`	object	body		Which tool calls need approval in task runs. Defaults to `{"default":"full","overrides":[]}`.
`name`	string	body	required	Display name, unique within your tenant. 1–80 characters.
`model`	string \| null	body		The provider's own model ID, such as `openai/gpt-6-luna`. Send it together with `providerId`. Defaults to `null`.
`thinkingLevel`	string \| null	body		How much reasoning to request from the model, such as `high`. Needs a provider and model, and must be a level the model supports. Defaults to `null`.
`providerId`	string \| null	body		ID of the provider whose key runs the model. Send it together with `model`. Defaults to `null`.
`workspaceId`	string	body		ID of the workspace the agent reads and writes files in. Leave it out to create a new workspace for the agent, or send an existing one to share it.
`autoCompaction`	boolean	body		Summarize older context automatically when a conversation nears the model's context limit. Defaults to `true`.
`compactionReserveTokens`	integer	body		Tokens to keep free for the model's reply when deciding whether to compact. Minimum 0. Defaults to `16384`.
`memoryInjectionEnabled`	boolean	body		Add the agent's saved memories to every turn automatically. Defaults to `false`.
`tools`	string[]	body		Built-in tool groups the agent can use: `workspace`, `write_todos`, and `memory`. Defaults to `[]`.
`instructions`	string	body		Instructions the agent follows on every turn. Up to 3000 characters. Defaults to `""`.
`userId`	string	body		Your end user's ID, used for attribution. An empty string means a tenant-level agent. It cannot change after creation. Defaults to `""`.
`metadata`	object	body		Your own key-value data, returned unchanged. Defaults to `{}`.
`mcpConnectionIds`	string[]	body		IDs of the MCP connections attached to the agent. Defaults to `[]`.

Response

The updated agent.

Agentobjectrequired

The updated agent.

Returns 201 Created as application/json. The created agent.

Response schema: Agent.

{
  "approvalInChat": {
    "default": "full",
    "overrides": []
  },
  "approvalInTasks": {
    "default": "full",
    "overrides": []
  },
  "id": "ag_4kP9sT2vXq7LmN3a",
  "tenantId": "ten_8Hq2Zr5WcY1bJt6D",
  "name": "Support Agent",
  "model": "openai/gpt-6-luna",
  "thinkingLevel": null,
  "providerId": "prv_7Tn4Kd9QwE2sLx5R",
  "workspaceId": "ws_3Vb8Ny6HpU1cGf4M",
  "autoCompaction": true,
  "compactionReserveTokens": 16384,
  "memoryInjectionEnabled": false,
  "tools": [
    "workspace",
    "write_todos"
  ],
  "instructions": "Answer billing questions clearly and briefly.",
  "userId": "",
  "metadata": {
    "team": "support"
  },
  "mcpConnectionIds": [],
  "avatarUrl": null,
  "createdAt": "2026-07-10T10:00:00.000Z",
  "updatedAt": "2026-07-10T10:00:00.000Z",
  "version": 1,
  "status": "active"
}

Errors

Status	Codes	Description
`400`	`validation_failed`, `invalid_request`, `model_not_found`, `agent_mcp_connection_not_found`, `agent_mcp_connections_invalid`, `mcp_connection_discovery_failed`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required
`404`	`provider_not_found`, `workspace_not_found`	The resource was not found
`409`	`agent_name_conflict`	The request conflicts with the resource's current state
`429`	`rate_limited`	Too many requests
`503`	`model_validation_unavailable`, `service_unavailable`	The service is temporarily unavailable

See REST errors for the error envelope and shared codes.

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","providerId":"prv_7Tn4Kd9QwE2sLx5R","model":"openai/gpt-6-luna","tools":["workspace","write_todos"],"instructions":"Answer billing questions clearly and briefly.","metadata":{"team":"support"}}'

List agent MCP attachmentsGET`/v1/agents/:agentId/mcp-attachments`

List agent MCP attachments.

Lists the MCP connections attached to an agent and what the agent forwards to each one.

Request

Requires bearer authentication.

Field	Type	Location	Required	Description
`agentId`	string	path	required	ID of the agent.

Response

The updated agent.

Agentobjectrequired

The updated agent.

Returns 200 OK as application/json. The agent's MCP attachments.

Response schema: McpAttachmentList.

{
  "mcpAttachments": [
    {
      "mcpConnectionId": "mcp_2Rk7Wm4XsQ9dHv1B",
      "forwardUserId": true,
      "forwardedMetadataKeys": [
        "plan"
      ],
      "createdAt": "2026-07-10T10:00:00.000Z",
      "updatedAt": "2026-07-10T10:05:00.000Z"
    }
  ]
}

Errors

Status	Codes	Description
`400`	`validation_failed`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required
`404`	`not_found`	The resource was not found

See REST errors for the error envelope and shared codes.

cURL

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

Update agent MCP attachmentPATCH`/v1/agents/:agentId/mcp-attachments/:mcpConnectionId`

Update an agent MCP attachment.

Changes what an agent forwards to one of its attached MCP connections. Send at least one field.

Request

Requires bearer authentication and a JSON body.

Field	Type	Location	Required	Description
`agentId`	string	path	required	ID of the agent.
`mcpConnectionId`	string	path	required	ID of an MCP connection attached to the agent.
`forwardUserId`	boolean	body		Send the session's `userId` to the MCP server with every tool call.
`forwardedMetadataKeys`	string[]	body		Session metadata keys whose values are sent to the MCP server with every tool call. Replaces the current list.

Response

The updated agent.

Agentobjectrequired

The updated agent.

Returns 200 OK as application/json. The updated MCP attachment.

Response schema: McpAttachment.

{
  "mcpConnectionId": "mcp_2Rk7Wm4XsQ9dHv1B",
  "forwardUserId": true,
  "forwardedMetadataKeys": [
    "plan"
  ],
  "createdAt": "2026-07-10T10:00:00.000Z",
  "updatedAt": "2026-07-10T10:05:00.000Z"
}

Errors

Status	Codes	Description
`400`	`validation_failed`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required
`404`	`not_found`	The resource was not found

See REST errors for the error envelope and shared codes.

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":["plan"]}'

List agent versionsGET`/v1/agents/:agentId/versions`

List agent versions.

Lists an agent's saved versions, newest first. Each version is a complete snapshot of the configuration and never changes. Pass nextCursor as cursor to get the next page.

Request

Requires bearer authentication.

Field	Type	Location	Required	Description
`agentId`	string	path	required	ID of the agent.
`cursor`	string	query		`nextCursor` from the previous page. Leave it out for the first page.
`limit`	integer	query		Maximum number of versions to return. 1–200. Defaults to `50`.

Response

The updated agent.

Agentobjectrequired

The updated agent.

Returns 200 OK as application/json. A page of agent versions.

Response schema: AgentVersionList.

{
  "data": [
    {
      "approvalInChat": {
        "default": "full",
        "overrides": []
      },
      "approvalInTasks": {
        "default": "full",
        "overrides": []
      },
      "agentId": "ag_4kP9sT2vXq7LmN3a",
      "tenantId": "ten_8Hq2Zr5WcY1bJt6D",
      "version": 1,
      "name": "Support Agent",
      "model": "openai/gpt-6-luna",
      "thinkingLevel": null,
      "providerId": "prv_7Tn4Kd9QwE2sLx5R",
      "autoCompaction": true,
      "compactionReserveTokens": 16384,
      "memoryInjectionEnabled": false,
      "tools": [
        "workspace",
        "write_todos"
      ],
      "instructions": "Answer billing questions clearly and briefly.",
      "metadata": {
        "team": "support"
      },
      "mcpConnectionIds": [],
      "createdAt": "2026-07-10T10:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Errors

Status	Codes	Description
`400`	`validation_failed`, `invalid_cursor`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required
`404`	`not_found`	The resource was not found

See REST errors for the error envelope and shared codes.

cURL

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

Get agent versionGET`/v1/agents/:agentId/versions/:version`

Get an agent version.

Returns one saved version of an agent, a complete snapshot of its configuration at that point.

Request

Requires bearer authentication.

Field	Type	Location	Required	Description
`agentId`	string	path	required	ID of the agent.
`version`	number	path	required	Version number, starting at 1.

Response

The updated agent.

Agentobjectrequired

The updated agent.

Returns 200 OK as application/json. The agent version.

Response schema: AgentVersion.

{
  "approvalInChat": {
    "default": "full",
    "overrides": []
  },
  "approvalInTasks": {
    "default": "full",
    "overrides": []
  },
  "agentId": "ag_4kP9sT2vXq7LmN3a",
  "tenantId": "ten_8Hq2Zr5WcY1bJt6D",
  "version": 1,
  "name": "Support Agent",
  "model": "openai/gpt-6-luna",
  "thinkingLevel": null,
  "providerId": "prv_7Tn4Kd9QwE2sLx5R",
  "autoCompaction": true,
  "compactionReserveTokens": 16384,
  "memoryInjectionEnabled": false,
  "tools": [
    "workspace",
    "write_todos"
  ],
  "instructions": "Answer billing questions clearly and briefly.",
  "metadata": {
    "team": "support"
  },
  "mcpConnectionIds": [],
  "createdAt": "2026-07-10T10:00:00.000Z"
}

Errors

Status	Codes	Description
`400`	`validation_failed`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required
`404`	`not_found`	The resource was not found

See REST errors for the error envelope and shared codes.

cURL

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

Get agentGET`/v1/agents/:agentId`

Get an agent.

Returns an agent's current configuration, including a short-lived avatarUrl when the agent has an avatar.

Request

Requires bearer authentication.

Field	Type	Location	Required	Description
`agentId`	string	path	required	ID of the agent.

Response

The updated agent.

Agentobjectrequired

The updated agent.

Returns 200 OK as application/json. The agent.

Response schema: Agent.

{
  "approvalInChat": {
    "default": "full",
    "overrides": []
  },
  "approvalInTasks": {
    "default": "full",
    "overrides": []
  },
  "id": "ag_4kP9sT2vXq7LmN3a",
  "tenantId": "ten_8Hq2Zr5WcY1bJt6D",
  "name": "Support Agent",
  "model": "openai/gpt-6-luna",
  "thinkingLevel": null,
  "providerId": "prv_7Tn4Kd9QwE2sLx5R",
  "workspaceId": "ws_3Vb8Ny6HpU1cGf4M",
  "autoCompaction": true,
  "compactionReserveTokens": 16384,
  "memoryInjectionEnabled": false,
  "tools": [
    "workspace",
    "write_todos"
  ],
  "instructions": "Answer billing questions clearly and briefly.",
  "userId": "",
  "metadata": {
    "team": "support"
  },
  "mcpConnectionIds": [],
  "avatarUrl": null,
  "createdAt": "2026-07-10T10:00:00.000Z",
  "updatedAt": "2026-07-10T10:00:00.000Z",
  "version": 1,
  "status": "active"
}

Errors

Status	Codes	Description
`400`	`validation_failed`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required
`404`	`not_found`	The resource was not found

See REST errors for the error envelope and shared codes.

cURL

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

Update agentPUT`/v1/agents/:agentId`

Update an agent.

Updates an agent and saves the result as a new version. Send at least one field. Fields you leave out keep their values, and arrays replace the current list. Changing providerId requires model in the same request, and sending both as null clears them. On the platform-managed ba assist agent, only providerId, model, and thinkingLevel can change.

Request

Requires bearer authentication and a JSON body.

Field	Type	Location	Required	Description
`agentId`	string	path	required	ID of the agent.
`approvalInChat`	object	body		Which tool calls need approval in sessions and stateless generation.
`approvalInTasks`	object	body		Which tool calls need approval in task runs.
`name`	string	body		Display name, unique within your tenant. 1–80 characters.
`model`	string \| null	body		The provider's own model ID, such as `openai/gpt-6-luna`. Send it together with `providerId`.
`thinkingLevel`	string \| null	body		How much reasoning to request from the model, such as `high`. Needs a provider and model, and must be a level the model supports.
`providerId`	string \| null	body		ID of the provider whose key runs the model. Send it together with `model`.
`workspaceId`	string	body		ID of the workspace the agent reads and writes files in.
`autoCompaction`	boolean	body		Summarize older context automatically when a conversation nears the model's context limit.
`compactionReserveTokens`	integer	body		Tokens to keep free for the model's reply when deciding whether to compact. Minimum 0.
`memoryInjectionEnabled`	boolean	body		Add the agent's saved memories to every turn automatically.
`tools`	string[]	body		Built-in tool groups the agent can use: `workspace`, `write_todos`, and `memory`.
`instructions`	string	body		Instructions the agent follows on every turn. Up to 3000 characters.
`metadata`	object	body		Your own key-value data, returned unchanged.
`mcpConnectionIds`	string[]	body		IDs of the MCP connections attached to the agent.

Response

The updated agent.

Agentobjectrequired

The updated agent.

Returns 200 OK as application/json. The updated agent.

Response schema: Agent.

{
  "approvalInChat": {
    "default": "full",
    "overrides": []
  },
  "approvalInTasks": {
    "default": "full",
    "overrides": []
  },
  "id": "ag_4kP9sT2vXq7LmN3a",
  "tenantId": "ten_8Hq2Zr5WcY1bJt6D",
  "name": "Support Agent",
  "model": "openai/gpt-6-luna",
  "thinkingLevel": null,
  "providerId": "prv_7Tn4Kd9QwE2sLx5R",
  "workspaceId": "ws_3Vb8Ny6HpU1cGf4M",
  "autoCompaction": true,
  "compactionReserveTokens": 16384,
  "memoryInjectionEnabled": false,
  "tools": [
    "workspace"
  ],
  "instructions": "Answer billing and refund questions clearly and briefly.",
  "userId": "",
  "metadata": {
    "team": "support"
  },
  "mcpConnectionIds": [],
  "avatarUrl": null,
  "createdAt": "2026-07-10T10:00:00.000Z",
  "updatedAt": "2026-07-10T10:15:00.000Z",
  "version": 2,
  "status": "active"
}

Errors

Status	Codes	Description
`400`	`validation_failed`, `invalid_request`, `model_not_found`, `agent_mcp_connection_not_found`, `agent_mcp_connections_invalid`, `mcp_connection_discovery_failed`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required
`404`	`not_found`, `provider_not_found`, `workspace_not_found`	The resource was not found
`409`	`agent_name_conflict`, `admin_agent_managed`	The request conflicts with the resource's current state
`503`	`model_validation_unavailable`	The service is temporarily unavailable

See REST errors for the error envelope and shared codes.

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 '{"instructions":"Answer billing and refund questions clearly and briefly.","tools":["workspace"]}'

Delete agentDELETE`/v1/agents/:agentId`

Delete an agent.

Permanently deletes an agent. Its workspace is kept. Set includeArtifacts to choose whether its artifacts are deleted too. The platform-managed ba assist agent cannot be deleted.

Request

Requires bearer authentication.

Field	Type	Location	Required	Description
`agentId`	string	path	required	ID of the agent.
`includeArtifacts`	string	query	required	`true` also deletes the agent's artifacts; `false` keeps them. One of `true`, `false`.

Response

The updated agent.

Agentobjectrequired

The updated agent.

Returns 204 No Content. The agent was deleted.

Errors

Status	Codes	Description
`400`	`validation_failed`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required
`404`	`not_found`	The resource was not found
`409`	`admin_agent_managed`	The request conflicts with the resource's current state

See REST errors for the error envelope and shared codes.

cURL

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

Disable agentPOST`/v1/agents/:agentId/disable`

Disable an agent.

Turns an agent off. New turns for a disabled agent fail with agent_disabled until you enable it again. The platform-managed ba assist agent cannot be disabled.

Request

Requires bearer authentication.

Field	Type	Location	Required	Description
`agentId`	string	path	required	ID of the agent.

Response

The updated agent.

Agentobjectrequired

The updated agent.

Returns 200 OK as application/json. The updated agent.

Response schema: Agent.

{
  "approvalInChat": {
    "default": "full",
    "overrides": []
  },
  "approvalInTasks": {
    "default": "full",
    "overrides": []
  },
  "id": "ag_4kP9sT2vXq7LmN3a",
  "tenantId": "ten_8Hq2Zr5WcY1bJt6D",
  "name": "Support Agent",
  "model": "openai/gpt-6-luna",
  "thinkingLevel": null,
  "providerId": "prv_7Tn4Kd9QwE2sLx5R",
  "workspaceId": "ws_3Vb8Ny6HpU1cGf4M",
  "autoCompaction": true,
  "compactionReserveTokens": 16384,
  "memoryInjectionEnabled": false,
  "tools": [
    "workspace",
    "write_todos"
  ],
  "instructions": "Answer billing questions clearly and briefly.",
  "userId": "",
  "metadata": {
    "team": "support"
  },
  "mcpConnectionIds": [],
  "avatarUrl": null,
  "createdAt": "2026-07-10T10:00:00.000Z",
  "updatedAt": "2026-07-10T10:00:00.000Z",
  "version": 1,
  "status": "disabled"
}

Errors

Status	Codes	Description
`400`	`validation_failed`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required
`404`	`not_found`	The resource was not found
`409`	`admin_agent_managed`	The request conflicts with the resource's current state

See REST errors for the error envelope and shared codes.

cURL

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

Enable agentPOST`/v1/agents/:agentId/enable`

Enable an agent.

Turns a disabled agent back on.

Request

Requires bearer authentication.

Field	Type	Location	Required	Description
`agentId`	string	path	required	ID of the agent.

Response

The updated agent.

Agentobjectrequired

The updated agent.

Returns 200 OK as application/json. The updated agent.

Response schema: Agent.

{
  "approvalInChat": {
    "default": "full",
    "overrides": []
  },
  "approvalInTasks": {
    "default": "full",
    "overrides": []
  },
  "id": "ag_4kP9sT2vXq7LmN3a",
  "tenantId": "ten_8Hq2Zr5WcY1bJt6D",
  "name": "Support Agent",
  "model": "openai/gpt-6-luna",
  "thinkingLevel": null,
  "providerId": "prv_7Tn4Kd9QwE2sLx5R",
  "workspaceId": "ws_3Vb8Ny6HpU1cGf4M",
  "autoCompaction": true,
  "compactionReserveTokens": 16384,
  "memoryInjectionEnabled": false,
  "tools": [
    "workspace",
    "write_todos"
  ],
  "instructions": "Answer billing questions clearly and briefly.",
  "userId": "",
  "metadata": {
    "team": "support"
  },
  "mcpConnectionIds": [],
  "avatarUrl": null,
  "createdAt": "2026-07-10T10:00:00.000Z",
  "updatedAt": "2026-07-10T10:00:00.000Z",
  "version": 1,
  "status": "active"
}

Errors

Status	Codes	Description
`400`	`validation_failed`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required
`404`	`not_found`	The resource was not found
`409`	`admin_agent_managed`	The request conflicts with the resource's current state

See REST errors for the error envelope and shared codes.

cURL

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

Upload agent avatarPOST`/v1/agents/:agentId/avatar`

Upload an agent avatar.

Sets the agent's avatar, replacing any current one. Send the image as the file field of a multipart form. The platform-managed ba assist agent's avatar cannot change.

Request

Requires bearer authentication and a multipart form body.

Field	Type	Location	Required	Description
`agentId`	string	path	required	ID of the agent.
`file`	file	form	required	PNG, JPEG, or WebP image of 512 KiB or smaller. Its file extension must match its type.

Response

The updated agent.

Agentobjectrequired

The updated agent.

Returns 200 OK as application/json. The updated agent.

Response schema: Agent.

{
  "approvalInChat": {
    "default": "full",
    "overrides": []
  },
  "approvalInTasks": {
    "default": "full",
    "overrides": []
  },
  "id": "ag_4kP9sT2vXq7LmN3a",
  "tenantId": "ten_8Hq2Zr5WcY1bJt6D",
  "name": "Support Agent",
  "model": "openai/gpt-6-luna",
  "thinkingLevel": null,
  "providerId": "prv_7Tn4Kd9QwE2sLx5R",
  "workspaceId": "ws_3Vb8Ny6HpU1cGf4M",
  "autoCompaction": true,
  "compactionReserveTokens": 16384,
  "memoryInjectionEnabled": false,
  "tools": [
    "workspace",
    "write_todos"
  ],
  "instructions": "Answer billing questions clearly and briefly.",
  "userId": "",
  "metadata": {
    "team": "support"
  },
  "mcpConnectionIds": [],
  "avatarUrl": "https://files.example.com/avatars/ag_4kP9sT2vXq7LmN3a.webp",
  "createdAt": "2026-07-10T10:00:00.000Z",
  "updatedAt": "2026-07-10T10:00:00.000Z",
  "version": 1,
  "status": "active"
}

Errors

Status	Codes	Description
`400`	`validation_failed`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required
`404`	`not_found`	The resource was not found
`409`	`admin_agent_managed`	The request conflicts with the resource's current state
`415`	`invalid_request`	The request body has an unsupported media type

See REST errors for the error envelope and shared codes.

cURL

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

Delete agent avatarDELETE`/v1/agents/:agentId/avatar`

Delete an agent avatar.

Removes the agent's avatar and returns the updated agent. The platform-managed ba assist agent's avatar cannot change.

Request

Requires bearer authentication.

Field	Type	Location	Required	Description
`agentId`	string	path	required	ID of the agent.

Response

The updated agent.

Agentobjectrequired

The updated agent.

Returns 200 OK as application/json. The updated agent.

Response schema: Agent.

{
  "approvalInChat": {
    "default": "full",
    "overrides": []
  },
  "approvalInTasks": {
    "default": "full",
    "overrides": []
  },
  "id": "ag_4kP9sT2vXq7LmN3a",
  "tenantId": "ten_8Hq2Zr5WcY1bJt6D",
  "name": "Support Agent",
  "model": "openai/gpt-6-luna",
  "thinkingLevel": null,
  "providerId": "prv_7Tn4Kd9QwE2sLx5R",
  "workspaceId": "ws_3Vb8Ny6HpU1cGf4M",
  "autoCompaction": true,
  "compactionReserveTokens": 16384,
  "memoryInjectionEnabled": false,
  "tools": [
    "workspace",
    "write_todos"
  ],
  "instructions": "Answer billing questions clearly and briefly.",
  "userId": "",
  "metadata": {
    "team": "support"
  },
  "mcpConnectionIds": [],
  "avatarUrl": null,
  "createdAt": "2026-07-10T10:00:00.000Z",
  "updatedAt": "2026-07-10T10:00:00.000Z",
  "version": 1,
  "status": "active"
}

Errors

Status	Codes	Description
`400`	`validation_failed`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required
`404`	`not_found`	The resource was not found
`409`	`admin_agent_managed`	The request conflicts with the resource's current state

See REST errors for the error envelope and shared codes.

cURL

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

Agents to decide what each setting does.
Versions and lifecycle to pin and restore versions.
Sessions API to start a conversation with the agent.

Overview

Automatic context compaction

Thinking configuration

Tool approval configuration

Endpoints

List agentsGET/v1/agents

Request

Errors

cURL

Create agentPOST/v1/agents

Request

Errors

cURL

List agent MCP attachmentsGET/v1/agents/:agentId/mcp-attachments

Request

Errors

cURL

Update agent MCP attachmentPATCH/v1/agents/:agentId/mcp-attachments/:mcpConnectionId

Request

Errors

cURL

List agent versionsGET/v1/agents/:agentId/versions

Request

Errors

cURL

Get agent versionGET/v1/agents/:agentId/versions/:version

Request

Errors

cURL

Get agentGET/v1/agents/:agentId

Request

Errors

cURL

Update agentPUT/v1/agents/:agentId

Request

Errors

cURL

Delete agentDELETE/v1/agents/:agentId

Request

Errors

cURL

Disable agentPOST/v1/agents/:agentId/disable

Request

Errors

cURL

Enable agentPOST/v1/agents/:agentId/enable

Request

Errors

cURL

Upload agent avatarPOST/v1/agents/:agentId/avatar

Request

Errors

cURL

Delete agent avatarDELETE/v1/agents/:agentId/avatar

Request

Errors

cURL

Next

List agentsGET`/v1/agents`

Create agentPOST`/v1/agents`

List agent MCP attachmentsGET`/v1/agents/:agentId/mcp-attachments`

Update agent MCP attachmentPATCH`/v1/agents/:agentId/mcp-attachments/:mcpConnectionId`

List agent versionsGET`/v1/agents/:agentId/versions`

Get agent versionGET`/v1/agents/:agentId/versions/:version`

Get agentGET`/v1/agents/:agentId`

Update agentPUT`/v1/agents/:agentId`

Delete agentDELETE`/v1/agents/:agentId`

Disable agentPOST`/v1/agents/:agentId/disable`

Enable agentPOST`/v1/agents/:agentId/enable`

Upload agent avatarPOST`/v1/agents/:agentId/avatar`

Delete agent avatarDELETE`/v1/agents/:agentId/avatar`