openapi: 3.0.3 info: title: Brainfish Public Agents Conversations 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: Conversations description: Conversation operations including follow-up question generation paths: /v1/conversations/{conversationId}/follow-ups: post: summary: Generate follow-up questions description: 'Generate follow-up questions for a conversation based on the most recent answer and its source documents. This endpoint analyzes the conversation context (the original question, the AI-generated answer, and the source documents) to suggest relevant follow-up questions the user might want to ask next. The `conversationId` must reference an existing conversation that has a completed answer. If the conversation has no answer yet, a 422 error is returned. ' operationId: generateFollowUpQuestions tags: - Conversations security: - BearerAuth: [] AgentKey: [] parameters: - name: conversationId in: path required: true description: Conversation ID from a previous answer generation session schema: type: string requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/FollowUpQuestionsRequest' examples: default: summary: Use default limit (3 questions) value: {} customLimit: summary: Request more follow-up questions value: limit: 5 responses: '200': description: Follow-up questions generated successfully content: application/json: schema: $ref: '#/components/schemas/FollowUpQuestionsResponse' example: data: followUps: - What are the security requirements for password resets? - Can I enable two-factor authentication? - How do I update my email address? timestamp: '2024-01-15T10:30:00Z' '401': $ref: '#/components/responses/Unauthorized' '404': description: Conversation not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: not_found message: Conversation not found timestamp: '2024-01-15T10:30:00Z' '422': description: Conversation answer is not yet available content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unprocessable_entity message: Conversation answer is not yet available timestamp: '2024-01-15T10:30:00Z' '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' 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: FollowUpQuestionsResponse: type: object required: - data - timestamp properties: data: type: object required: - followUps properties: followUps: type: array items: type: string description: List of suggested follow-up questions example: - What are the security requirements for password resets? - Can I enable two-factor authentication? - How do I update my email address? timestamp: type: string format: date-time description: Response timestamp 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 FollowUpQuestionsRequest: type: object properties: limit: type: integer minimum: 1 maximum: 10 default: 3 description: Maximum number of follow-up questions to generate 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. '