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.

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 least one knowledge base is required when publishing (isDraft: false).

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

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.

number

default:"0"

Number of agents to skip for pagination.

Response (200)

object[]

Array of agent objects.

object

Show Pagination

number

Requested limit.

number

Requested offset.

number

Total count of agents.

curl

curl https://your-domain.com/api/bots?limit=20&offset=0 \
  -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).

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.

Response (200)

Returns the updated agent object.

Errors

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.

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