Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.brainstormer.io/llms.txt

Use this file to discover all available pages before exploring further.

The Brainstormer API uses standard HTTP status codes. When a request fails, the response body contains a JSON object with the following shape: 
{
  "error": "Unauthorized",
  "message": "Invalid or revoked API key",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
FieldTypeDescription
errorstringShort error category (e.g. "Unauthorized")
messagestringHuman-readable explanation of what went wrong
timestampstringISO 8601 timestamp of when the error occurred

​
Error codes

The request was malformed. This usually means a required field is missing or a field value is invalid.What to check:
  • All required fields are present in the request body (agent_id and message for /v1/chat; kb_id and query for /v1/kb/search).
  • Field values are the correct type (e.g. top_k must be a number, not a string).
Example response:
{
  "error": "Bad Request",
  "message": "Missing required field: agent_id",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
The request was not authenticated. This means the Authorization header is missing, is not in the expected Bearer brs_live_... format, or the key has been revoked.What to check:
  • Your request includes an Authorization header.
  • The header value starts with Bearer brs_live_.
  • The key has not been revoked in the Developer Portal.
Example response:
{
  "error": "Unauthorized",
  "message": "Invalid or revoked API key",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
Your API key was authenticated but does not have permission to access the requested resource.What to check:
  • The agent or knowledge base you are trying to access belongs to the same organization as the API key.
  • The application type you selected when creating the key is appropriate for the operation you are performing.
Example response:
{
  "error": "Forbidden",
  "message": "You do not have access to this resource",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
The resource identified by the ID in the request does not exist within your organization.What to check:
  • The agent_id or kb_id you are using is correct and was not deleted.
  • The resource belongs to the same organization as the API key you are using.
Example response:
{
  "error": "Not Found",
  "message": "Agent not found",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
A backend service is temporarily unavailable. This is typically a transient condition.What to do: Retry the request using exponential backoff. Start with a 1-second delay and double it on each subsequent attempt, up to a maximum of around 30 seconds.Example response:
{
  "error": "Service Unavailable",
  "message": "Chat service is currently unavailable",
  "timestamp": "2024-01-01T00:00:00.000Z"
}