Agents

Agents (also called bots) are the core resource in Brainstormer. Each agent has a name, AI model, system prompt, linked knowledge bases, and configuration for streaming, voice, file uploads, and multimodal support.

All API requests require a valid JWT token in the Authorization: Bearer <token> header. The API Gateway decodes the JWT and forwards auth context (user-id, organization-id, user-email, x-platform-role, x-org-role) as headers to downstream services.

Create Agent

Create a new agent in your organization. Requires the member organization role or higher (platform superadmins always pass); a viewer gets 403.

Request Body

string

required

Agent name. 1-255 characters.

string

Agent description. Max 2000 characters.

string

AI model ID (e.g. openai/gpt-4o). If omitted, uses the platform default.

string

System prompt for the agent. Max 50,000 characters.

string[]

required

Array of knowledge base UUIDs to link to this agent, at most 100. At least one knowledge base is required when publishing (isDraft: false).Every id is validated before anything is written: the knowledge base must exist, belong to the agent’s organization, and be one you can edit (organization owners, admins and members can edit every knowledge base in their organization; a viewer needs an edit grant on it). If any id fails, the request is refused with 400 invalid_knowledge_base_ids and no agent is created.

boolean

default:"false"

If true, creates the agent as a draft. Draft agents do not need a linked knowledge base.

boolean

default:"true"

Enable streaming responses for chat.

boolean

default:"false"

Allow file uploads in chat.

boolean

default:"false"

Enable voice capabilities.

object

Voice configuration.

Show Voice settings

string

required

Voice ID.

number

Speed multiplier (0.1-2.0).

object

Multimodal input configuration.

Show Multimodal config

boolean

required

Enable multimodal inputs.

string[]

Array of: image, document, audio, video, text.

object[]

Tool configurations for the agent.

Show Tool config

string

required

Tool definition ID.

boolean

required

Whether the tool is active.

object

Tool-specific configuration.

object[]

Template variables for the system prompt.

Response (201)

boolean

Always true on success.

object

The created agent object.

Show Agent object

string

Agent UUID.

string

Agent name.

string

Agent description.

string

AI model ID.

string

Owning organization UUID.

boolean

Whether this is a draft.

boolean

Streaming enabled.

boolean

File uploads enabled.

string

ISO 8601 timestamp.

string

ISO 8601 timestamp.

Errors

error

One or more knowledgeBaseIds cannot be linked. A knowledge base that does not exist and one in another organization get the identical response, so this cannot be used to confirm that another organization’s knowledge base exists. Nothing was written.

Show Error body

string

invalid_knowledge_base_ids

string

invalid_knowledge_base_ids

string

A human-readable explanation, suitable to show as-is.

string[]

The offending ids, in request order.

error

The caller’s organization role is below member. Body: { "error": "Forbidden", "message": "Requires member role or higher" }.

error

The knowledge base access check could not be completed. Nothing was written; retry the request. Body carries error, code (both knowledge_base_check_unavailable) and message.

error

Returned when isDraft is false and the agent has no linked knowledge bases, or none of the linked knowledge bases have indexed documents. The response includes:

Show Error body

string

Knowledge base not ready

string

At least one knowledge base must be linked and have indexed documents before this agent can go live.

curl -X POST https://your-domain.com/api/bots \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "description": "Answers customer questions using the help center KB",
    "model": "openai/gpt-4o",
    "knowledgeBaseIds": ["kb-uuid-here"],
    "streamingEnabled": true
  }'

const response = await fetch("https://your-domain.com/api/bots", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Customer Support Agent",
    description: "Answers customer questions using the help center KB",
    model: "openai/gpt-4o",
    knowledgeBaseIds: ["kb-uuid-here"],
    streamingEnabled: true,
  }),
});

const { bot } = await response.json();

List Agents

List all agents in your organization.

Query Parameters

number

default:"50"

Maximum number of agents to return. 1-100.

string

Opaque keyset cursor. Pass the nextCursor from the previous page’s response to fetch the following page; omit it for the first page. A malformed cursor returns 400.This endpoint does not take an offset. Agents are ordered by creation time, which is not unique, and an offset addresses a page boundary by row count — so a tie, or an agent created or deleted while a client is paging, can silently skip a row or return one twice.

string

Filter by lifecycle status: draft or published. Omit to return every status, including archived.

string

Case-insensitive substring match on agent name or description. 1-200 chars.

Response (200)

object[]

Array of agent objects.

object

Show Pagination

number

Requested limit.

number

Number of agents in this page — not a total. There is no total count on this endpoint.

string | null

Cursor for the next page, or null when this is the last page. A short page is not the end of the list — only a null cursor is.

curl

# First page
curl "https://your-domain.com/api/bots?limit=20" \
  -H "Authorization: Bearer $TOKEN"

# Next page — pass back the nextCursor from the previous response
curl "https://your-domain.com/api/bots?limit=20&cursor=eyJjIjoiMjAyNi0wOS0wMSAxMDowMDowMCIsImlkIjoi4oCmIn0" \
  -H "Authorization: Bearer $TOKEN"

Get Agent

Get a single agent by ID, including linked knowledge bases.

Path Parameters

string

required

Agent UUID.

Response (200)

Returns the full agent object plus:

object[]

Array of linked knowledge base objects with full details (name, description, document counts).

boolean

Whether the builtin:voice_input tool is on. Gates the microphone button in the chat UI.

boolean

Whether the builtin:file_upload tool is on. Gates the file-attach control.

string[] | null

What the agent’s model accepts as input, resolved from the model catalog: a subset of text, image, file, audio, video, in that order.Chat surfaces use it to withhold attachment types the model cannot read — a model without image is not offered images, and one with neither image nor file is not offered attachments at all.null means unknown, not “accepts nothing”. It is returned when the model has no catalog row or its capabilities could not be read, and a client must then restrict nothing: refusing an upload on the strength of absent data disables a feature that works.

curl

curl https://your-domain.com/api/bots/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $TOKEN"

Update Agent

Update an existing agent. All fields are optional — only provided fields are updated.

Path Parameters

string

required

Agent UUID.

Request Body

Same fields as Create Agent, but all are optional.

If you include knowledgeBaseIds, the entire set of linked KBs is replaced. Sending an empty array [] will unlink all knowledge bases.

knowledgeBaseIds is validated against the agent’s organization before anything is written. Every id must exist and belong to that organization. A link you add or remove must be to a knowledge base you can edit; a link that is already there and stays is not re-checked, so re-saving an agent’s existing knowledge needs no edit access to each knowledge base.

Response (200)

Returns the updated agent object.

Errors

error

Same body as on Create Agent. The agent and its links are left unchanged.

error

The knowledge base access check could not be completed. Nothing was written.

error

Returned when isDraft is set to false and the agent has no linked knowledge bases, or none of the linked knowledge bases have indexed documents yet.

curl

curl -X PUT https://your-domain.com/api/bots/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Agent Name",
    "model": "anthropic/claude-sonnet-4"
  }'

Delete Agent

Soft-delete an agent (sets deleted_at; conversations are retained). The agent stops appearing in active listings. Requires delete on the agent. Writes an agent.delete audit entry under the agent’s own organization. Linked knowledge bases are not deleted — see Agent Delete Impact for what a delete stops and how the dashboard deletes chosen knowledge bases with it.

Path Parameters

string

required

Agent UUID.

Response (204)

No content on success.

curl

curl -X DELETE https://your-domain.com/api/bots/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $TOKEN"

Get Agent Usage

Get usage statistics for an agent (conversations, messages, token usage, costs).

Path Parameters

string

required

Agent UUID.

Response (200)

Returns usage statistics including conversation counts, message counts, total tokens, and estimated cost.

Version History

Get version history for an agent. Every update creates a new version snapshot.

Path Parameters

string

required

Agent UUID.

Response (200)

object[]

Array of version snapshots, newest first.

Show Version object

number

Version number.

object

Snapshot of the agent config at this version.

string

Version notes (user-provided or auto-generated).

string

ISO 8601 timestamp.

string

User ID who created this version.

number

Total number of versions.

Revert to Version

Revert an agent’s configuration to a specific version. This creates a new version (does not rewrite history).

Path Parameters

string

required

Agent UUID.

number

required

Version number to revert to.

Response (200)

boolean

Always true.

object

Updated agent object.

string

Confirmation message.

Get Draft Status

Get the current publish/draft status of an agent, including any pending review.

Path Parameters

string

required

Agent UUID.

Publishing Lifecycle

Agents follow a publish lifecycle: draft -> submitted for review -> approved/rejected -> published.

Submit for Review

Submit a draft agent for review.

Approve Agent

Approve a submitted agent (requires appropriate role).

Reject Agent

Reject a submitted agent with feedback.

Publish Agent

Publish an approved agent, making it available to end users.

Errors

error

Returned when the agent has no linked knowledge bases, or none of the linked knowledge bases have indexed documents yet.

Get Agent Indexing Status

Returns the indexing status of all knowledge bases linked to this agent. Use this to check whether the agent is ready to be published.

Path Parameters

string

required

Agent UUID.

Response (200)

number

Number of knowledge bases linked to the agent.

number

Total documents across all linked knowledge bases.

number

Documents with processing_status = completed.

number

Documents that failed processing.

number

Documents still pending or processing.

boolean

true when at least one knowledge base is linked and at least one document is indexed.

curl

curl https://your-domain.com/api/bots/550e8400-e29b-41d4-a716-446655440000/indexing-status \
  -H "Authorization: Bearer $TOKEN"

RBAC Permissions

All agent endpoints enforce role-based access control:

Action	Required Permission
Get agent	`use`
List agents	(org membership)
Create agent	(org membership)
Update agent	`edit`
Delete agent	`delete`
View usage	`view_analytics`

​Agents

​Create Agent

​Request Body

​Response (201)

​Errors

​List Agents

​Query Parameters

​Response (200)

​Get Agent

​Path Parameters

​Response (200)

​Update Agent

​Path Parameters

​Request Body

​Response (200)

​Errors

​Delete Agent

​Path Parameters

​Response (204)

​Get Agent Usage

​Path Parameters

​Response (200)

​Version History

​Path Parameters

​Response (200)

​Revert to Version

​Path Parameters

​Response (200)

​Get Draft Status

​Path Parameters

​Publishing Lifecycle

​Submit for Review

​Approve Agent

​Reject Agent

​Publish Agent

​Errors

​Get Agent Indexing Status

​Path Parameters

​Response (200)

​RBAC Permissions

Agents

Create Agent

Request Body

Response (201)

Errors

List Agents

Query Parameters

Response (200)

Get Agent

Path Parameters

Response (200)

Update Agent

Path Parameters

Request Body

Response (200)

Errors

Delete Agent

Path Parameters

Response (204)

Get Agent Usage

Path Parameters

Response (200)

Version History

Path Parameters

Response (200)

Revert to Version

Path Parameters

Response (200)

Get Draft Status

Path Parameters

Publishing Lifecycle

Submit for Review

Approve Agent

Reject Agent

Publish Agent

Errors

Get Agent Indexing Status

Path Parameters

Response (200)

RBAC Permissions