openapi: 3.0.3
info:
title: Brainfish Public Agents Users API
description: "The Brainfish API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\nUse the Brainfish API to programmatically manage your knowledge base, generate AI-powered answers, and integrate Brainfish capabilities into your applications.\n\n---\n\n## Just Getting Started?\n\nCheck out our [Help documentation](https://help.brainfi.sh) for guides and tutorials.\n\n---\n\n## Base URL\n\n```\nhttps://api.brainfi.sh\n```\n\nAll API requests must be made over HTTPS. Calls made over plain HTTP will fail.\n\n---\n\n## Authentication\n\nThe Brainfish API uses API tokens to authenticate requests. You can view and manage your API tokens in your [Brainfish Dashboard](https://app.brainfi.sh) under **Settings → API Tokens**.\n\nAPI tokens have the prefix `bf_api_`. Your API tokens carry many privileges, so be sure to keep them secure! Do not share your API tokens in publicly accessible areas such as GitHub, client-side code, and so forth.\n\nAll API requests must include authentication. Requests without authentication will fail.\n\n| Header | Description |\n|--------|-------------|\n| `Authorization` | Bearer token authentication: `Bearer bf_api_xxxxx` |\n| `agent-key` | Required for AI Agent endpoints only. Find this in your Agents page. |\n\n**Example: Authenticated Request**\n\n```bash\ncurl https://api.brainfi.sh/v1/auth/validate \\\n -X POST \\\n -H \"Authorization: Bearer bf_api_xxxxx\" \\\n -H \"Content-Type: application/json\"\n```\n\n---\n\n## Errors\n\nBrainfish uses conventional HTTP response codes to indicate the success or failure of an API request.\n\n| Code | Description |\n|------|-------------|\n| `2xx` | Success — The request was successful. |\n| `4xx` | Client Error — The request failed due to client-side issues (e.g., missing required parameter, invalid authentication, resource not found). |\n| `5xx` | Server Error — Something went wrong on Brainfish's servers (these are rare). |\n\n**Error Response Format**\n\n```json\n{\n \"error\": \"validation_failed\",\n \"message\": \"Request validation failed\",\n \"validationErrors\": [\n {\n \"field\": \"query\",\n \"message\": \"Query cannot be empty\",\n \"code\": \"invalid_string\"\n }\n ],\n \"timestamp\": \"2024-01-15T10:30:00Z\",\n \"requestId\": \"req-abc123\"\n}\n```\n\nThe `requestId` can be provided to Brainfish support when troubleshooting issues.\n\n---\n\n## Rate Limiting\n\nThe API implements rate limiting to ensure fair usage and system stability.\n\n| Endpoint Type | Limit |\n|---------------|-------|\n| Most endpoints | 25 requests per minute |\n| Token revocation | 10 requests per hour |\n\nWhen you exceed the rate limit, the API returns a `429 Too Many Requests` response with headers indicating when you can retry:\n\n- `X-RateLimit-Limit`: Maximum requests allowed in the window\n- `X-RateLimit-Remaining`: Remaining requests in current window\n- `X-RateLimit-Reset`: Unix timestamp when the rate limit resets\n\n---\n\n## Available Resources\n\n| Resource | Description |\n|----------|-------------|\n| **Authentication** | Validate and revoke API tokens |\n| **AI Agents** | Generate streaming AI-powered answers from your knowledge base |\n| **Analytics** | Query conversation thread analytics with filtering and pagination |\n| **Conversations** | Generate follow-up questions for conversations |\n| **Collections** | Organize documents into collections |\n| **Catalogs** | Create catalogs and sync content via API |\n| **Documents** | Create, read, update, and delete documents |\n\n---\n\n## Quick Start\n\n**1. Create an API token** in your Brainfish dashboard under Settings → API Tokens.\n\n**2. Validate your token** to ensure it's working:\n\n```bash\ncurl https://api.brainfi.sh/v1/auth/validate \\\n -X POST \\\n -H \"Authorization: Bearer bf_api_xxxxx\" \\\n -H \"Content-Type: application/json\"\n```\n\n**3. For AI endpoints**, get your agent key from the Agents page.\n\n**4. Generate an AI answer**:\n\n```bash\ncurl https://api.brainfi.sh/v1/agents/answer \\\n -X POST \\\n -H \"Authorization: Bearer bf_api_xxxxx\" \\\n -H \"agent-key: your-agent-key\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\": \"How do I reset my password?\"}'\n```\n\n---\n\n## Pagination\n\nList endpoints support pagination using `limit` and `offset` parameters:\n\n| Parameter | Description | Default |\n|-----------|-------------|---------|\n| `limit` | Maximum number of results to return (1-100) | 25 |\n| `offset` | Number of results to skip | 0 |\n\nPaginated responses include a `pagination` object:\n\n```json\n{\n \"data\": [...],\n \"pagination\": {\n \"offset\": 0,\n \"limit\": 25,\n \"total\": 42\n }\n}\n```\n"
version: 1.0.0
contact:
name: Brainfish API Support
email: support@brainfish.ai
url: https://help.brainfi.sh/articles/api-reference-7mjzVCAmeM
license:
name: Proprietary
servers:
- url: https://api.brainfi.sh
description: Production server
tags:
- name: Users
description: User-scoped operations. Generate answers personalized to a specific external/platform user with automatic attribute-based collection filtering.
paths:
/v1/users/answer:
post:
summary: Generate streaming answer
description: "Generate streaming answers for queries. This is a simplified endpoint that accepts a query\nand optional collection filters to scope which knowledge base collections are searched.\n\nUse the optional `collectionIds` array to restrict answers to specific collections the\ncaller has access to. When omitted, all available collections are searched.\n\nThe response is streamed using Server-Sent Events (SSE) format, identical to the\n`/v1/agents/answer` endpoint.\n\nFor user personalization (attribute-based collection filtering, external user tracking),\nuse the `/v1/agents/answer` endpoint with the `user` field instead.\n\n## Authentication\n\nRequires a Bearer API token. The token determines the team context and permissions.\n\n## Streaming Example\n\n```javascript\nconst response = await fetch('https://api.brainfi.sh/v1/users/answer', {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n 'Authorization': 'Bearer bf_api_xxxxx'\n },\n body: JSON.stringify({\n query: 'How do I reset my password?',\n collectionIds: ['collection-uuid-1', 'collection-uuid-2']\n })\n});\n\nconst reader = response.body.getReader();\nconst decoder = new TextDecoder();\n\nwhile (true) {\n const { done, value } = await reader.read();\n if (done) break;\n\n const chunk = decoder.decode(value);\n const lines = chunk.split('\\n');\n\n for (const line of lines) {\n if (line.startsWith('data: ')) {\n const event = JSON.parse(line.slice(6));\n switch (event.type) {\n case 'start':\n console.log('Answer started:', event.id);\n break;\n case 'content':\n process.stdout.write(event.content);\n break;\n case 'end':\n console.log('\\nDone. conversationId:', event.conversationId);\n break;\n }\n }\n }\n}\n```\n"
operationId: generateUserAnswer
tags:
- Users
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserAnswerRequest'
examples:
simpleQuery:
summary: Simple question
value:
query: How do I reset my password?
withCollectionFilter:
summary: Query scoped to specific collections
value:
query: How do I configure SSO?
collectionIds:
- 550e8400-e29b-41d4-a716-446655440000
- 6ba7b810-9dad-11d1-80b4-00c04fd430c8
followUpQuery:
summary: Follow-up in an existing conversation
value:
query: What if I forgot my email too?
conversationId: 01234567890123456789012345
responses:
'200':
description: Streaming response with answer generation events
content:
text/event-stream:
schema:
type: string
description: Server-sent events stream containing answer generation progress
examples:
streamingResponse:
summary: Example streaming response
value: 'data: {"type":"start","id":"answer-abc123","conversationId":"01234567890123456789012345"}
data: {"type":"progress","content":"Searching knowledge base..."}
data: {"type":"content","content":"To reset your password:\n\n1. Go to the login page"}
data: {"type":"content","content":"\n2. Click \"Forgot Password?\"\n3. Enter your email address"}
data: {"type":"end","id":"answer-abc123","conversationId":"01234567890123456789012345","complete":true}
'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
components:
responses:
Unauthorized:
description: Authentication required or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missingToken:
summary: Missing authentication token
value:
error: authentication_required
message: 'Authentication required. Use Authorization: Bearer <token> header'
timestamp: '2024-01-15T10:30:00Z'
requestId: req-abc123
missingAgentKey:
summary: Missing agent key
value:
error: authentication_required
message: Agent key is required
timestamp: '2024-01-15T10:30:00Z'
requestId: req-def456
invalidCredentials:
summary: Invalid credentials
value:
error: authentication_required
message: Invalid or missing authentication credentials
timestamp: '2024-01-15T10:30:00Z'
requestId: req-ghi789
TooManyRequests:
description: Rate limit exceeded
headers:
X-RateLimit-Limit:
schema:
type: integer
description: Request limit per time window
X-RateLimit-Remaining:
schema:
type: integer
description: Remaining requests in current window
X-RateLimit-Reset:
schema:
type: integer
description: Time when rate limit resets (Unix timestamp)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: rate_limit_exceeded
message: 'Too many requests. Rate limit: 25 requests per minute'
timestamp: '2024-01-15T10:30:00Z'
UnprocessableEntity:
description: Invalid request format or unknown message type
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
examples:
emptyQuery:
summary: Empty query validation error
value:
error: validation_failed
message: Request validation failed
validationErrors:
- field: query
message: Query cannot be empty
code: invalid_string
timestamp: '2024-01-15T10:30:00Z'
requestId: req-val123
invalidConversationId:
summary: Invalid conversation ID format
value:
error: validation_failed
message: Request validation failed
validationErrors:
- field: conversationId
message: Invalid conversation ID format
code: invalid_string
timestamp: '2024-01-15T10:30:00Z'
requestId: req-val456
queryTooLong:
summary: Query exceeds maximum length
value:
error: validation_failed
message: Request validation failed
validationErrors:
- field: query
message: Query must be 2000 characters or less
code: too_big
timestamp: '2024-01-15T10:30:00Z'
requestId: req-val789
InternalServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: internal_error
message: An unexpected error occurred
requestId: req-abc123
timestamp: '2024-01-15T10:30:00Z'
schemas:
UserAnswerRequest:
type: object
required:
- query
properties:
query:
type: string
description: The query string to generate an answer for
minLength: 1
example: How do I reset my password?
conversationId:
type: string
description: 'Optional conversation ID for maintaining context across multiple queries.
Omit for the first request; use the conversationId from the previous response for follow-ups.
'
pattern: ^[0-9a-z]{25}$
stream:
type: boolean
default: true
description: Whether to stream the response via SSE
collectionIds:
type: array
items:
type: string
format: uuid
description: 'Optional array of collection IDs to restrict which knowledge base collections are
searched. When omitted, all available collections are searched.
'
channelType:
type: string
enum:
- email
- whatsapp
- slack
- msteams
description: Optional channel type for context
attachments:
type: array
maxItems: 10
items:
type: object
required:
- type
- url
properties:
type:
type: string
enum:
- image
url:
type: string
format: uri
description: Optional image attachments (max 10)
Error:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error type or code
message:
type: string
description: Human-readable error message
details:
type: object
additionalProperties: true
description: Additional error details
timestamp:
type: string
format: date-time
description: Error timestamp
requestId:
type: string
description: Unique request identifier for debugging
ValidationError:
allOf:
- $ref: '#/components/schemas/Error'
- type: object
properties:
validationErrors:
type: array
items:
type: object
properties:
field:
type: string
description: Field that failed validation
message:
type: string
description: Validation error message
code:
type: string
description: Validation error code
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API Token
description: 'Bearer token authentication. Include your API token in the Authorization header.
Example: `Authorization: Bearer bf_api_xxxxx`
Create tokens in your Brainfish dashboard under Settings → API Tokens.
'
AccessToken:
type: apiKey
in: header
name: access-token
description: '**Deprecated**: Use Bearer authentication instead.
Legacy access token header for backward compatibility. Must start with `bf_api_`.
Create tokens in your Brainfish dashboard under Settings → API Tokens.
'
AgentKey:
type: apiKey
in: header
name: agent-key
description: 'Agent key identifier that specifies which AI agent/widget to use for the request.
Find agent keys in your Brainfish dashboard under Agents. Click on any agent key to copy it.
'