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 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. '