openapi: 3.0.3
info:
  title: Brainfish Public Agents 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: Agents
  description: AI agent operations for answer generation and streaming
paths:
  /v1/agents/answer:
    post:
      summary: Generate streaming answer
      description: "Generate streaming answers for queries using AI agents. This endpoint provides real-time\nstreaming responses for question answering with optional user personalization.\n\nSimply provide a query string and optionally a `filter.collectionIds` array to get an AI-generated answer.\nWhen `filter.collectionIds` is provided, those collections are included in the search scope, along with\nany widget-based personalization collections when applicable. Otherwise, the endpoint uses the default\nanswer flow. The response is streamed using Server-Sent Events (SSE) format, allowing clients to receive\npartial results as they are generated.\n\n## Personalization\n\nPass the optional `user` object to enable personalized answers. When provided, the external\nuser record is upserted and their attributes are used to filter knowledge base collections\nand tailor responses. At least one of `userId`, `email`, or `phone` is required within the\n`user` object.\n\n## Streaming vs Non-Streaming\n\nSet `stream` to `false` to receive the full answer as a single JSON response instead of SSE\nevents. Defaults to `true`.\n\n## Streaming Example\n\n```javascript\nconst response = await fetch('https://api.brainfi.sh/v1/agents/answer', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    'Authorization': 'Bearer bf_api_xxxxx',\n    'agent-key': 'your-agent-key'\n  },\n  body: JSON.stringify({\n    query: 'How do I reset my password?',\n    user: { email: 'jane@example.com', properties: { plan: 'enterprise' } }\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\n      switch (event.type) {\n        case 'start':\n          console.log('Answer started:', event.id);\n          break;\n        case 'progress':\n          console.log('Progress:', event.content);\n          break;\n        case 'content':\n          console.log('Content chunk:', event.content);\n          break;\n        case 'end':\n          console.log('Answer completed:', event.conversationId);\n          break;\n      }\n    }\n  }\n}\n```\n"
      operationId: generateAnswer
      tags:
      - Agents
      security:
      - BearerAuth: []
        AgentKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnswerRequest'
            examples:
              simpleQuery:
                summary: Simple question
                value:
                  query: How to reset my password?
              followupQuery:
                summary: Follow-up question with conversation context
                value:
                  query: What if I forgot my email too?
                  conversationId: 01234567890123456789012345
              withPersonalization:
                summary: Personalized answer with user attributes
                value:
                  query: What features are available on my plan?
                  user:
                    email: john@acme.com
                    properties:
                      plan: enterprise
                      region: us-east
              withCollectionFilter:
                summary: Answer scoped to selected collections
                value:
                  query: How do I reset my password?
                  filter:
                    collectionIds:
                    - collection-uuid-1
              nonStreaming:
                summary: Non-streaming response
                value:
                  query: What are the pricing plans available?
                  stream: false
      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 for password reset query
                  value: 'data: {"type":"start","id":"answer-abc123","conversationId":"01234567890123456789012345"}


                    data: {"type":"progress","content":"Searching knowledge base for password reset information..."}


                    data: {"type":"content","content":"To reset your password:\n\n1. Go to the login page at"}


                    data: {"type":"content","content":" https://app.brainfi.sh/login\n2. Click the \"Forgot Password?\" link"}


                    data: {"type":"content","content":"\n3. Enter your email address\n4. Check your email for reset instructions"}


                    data: {"type":"content","content":"\n\nIf you don''t receive the email within 5 minutes, check your spam folder or contact support."}


                    data: {"type":"end","id":"answer-abc123","conversationId":"01234567890123456789012345","complete":true}

                    '
                shortResponse:
                  summary: Example streaming response for simple query
                  value: 'data: {"type":"start","id":"answer-def456"}


                    data: {"type":"content","content":"Our pricing plans include:\n\n**Starter**: $29/month - Up to 1,000 queries\n**Professional**: $99/month - Up to 10,000 queries\n**Enterprise**: Custom pricing - Unlimited queries\n\nAll plans include 24/7 support and API access."}


                    data: {"type":"end","id":"answer-def456","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:
    AnswerRequest:
      type: object
      required:
      - query
      properties:
        query:
          type: string
          description: The query string to generate an answer for
          minLength: 1
          maxLength: 2000
          example: How to reset my password?
        conversationId:
          type: string
          description: 'Optional conversation ID for maintaining context across multiple queries.

            This should be omitted for the first request and then provided in subsequent

            requests using the conversationId returned from the previous response.

            '
          pattern: ^[0-9a-z]{25}$
          example: 01234567890123456789012345
        stream:
          type: boolean
          default: true
          description: 'Whether to stream the response via Server-Sent Events (SSE). When `true` (default),

            the response is streamed as SSE events. When `false`, the full answer is returned

            as a single JSON response.

            '
        user:
          type: object
          description: 'Optional external user identification for personalization. When provided, the user

            record is upserted and their attributes are used to filter collections and tailor

            answers. At least one of `userId`, `email`, or `phone` is required within this object.

            '
          properties:
            userId:
              type: string
              description: External user ID from your system
            email:
              type: string
              format: email
              description: User email address
            phone:
              type: string
              description: User phone number
            firstName:
              type: string
              description: User first name
            lastName:
              type: string
              description: User last name
            properties:
              type: object
              additionalProperties: true
              description: Custom key-value properties for personalization (e.g. plan, region)
        filter:
          type: object
          description: Optional collection filter for this public endpoint.
          properties:
            collectionIds:
              type: array
              items:
                type: string
                format: uuid
              description: Collection IDs to include in the answer search scope.
        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.

        '