Brainfish Agents API

openapi: 3.2.0
info:
  title: Brainfish Public Agents API
  description: The Brainfish API is organized around REST.
  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

        streaming responses for question answering with optional user personalization.


        Simply provide a query string and optionally a `filter.collectionIds` array to get an AI-generated answer.

        When `filter.collectionIds` is provided, those collections are included in the search scope, along with

        any widget-based personalization collections when applicable. Otherwise, the endpoint uses the default

        answer flow. The response is streamed using Server-Sent Events (SSE) format, allowing clients to receive

        partial results as they are generated.


        ## Personalization


        Pass the optional `user` object to enable personalized answers. When provided, the external

        user record is upserted and their attributes are used to filter knowledge base collections

        and tailor responses. At least one of `userId`, `email`, or `phone` is required within the

        `user` object.


        ## Streaming vs Non-Streaming


        Set `stream` to `false` to receive the full answer as a single JSON response instead of SSE

        events. Defaults to `true`.


        ## Streaming Example


        ```javascript

        const response = await fetch(''https://api.brainfi.sh/v1/agents/answer'', {

        method: ''POST'',

        headers: {

        ''Content-Type'': ''application/json'',

        ''Authorization'': ''Bearer bf_api_xxxxx'',

        ''agent-key'': ''your-agent-key''

        },

        body: JSON.stringify({

        query: ''How do I reset my password?'',

        user: { email: ''jane@example.com'', properties: { plan: ''enterprise'' } }

        })

        });


        const reader = response.body.getReader();

        const decoder = new TextDecoder();


        while (true) {

        const { done, value } = await reader.read();

        if (done) break;


        const chunk = decoder.decode(value);

        const lines = chunk.split(''\n'');


        for (const line of lines) {

        if (line.startsWith(''data: '')) {

        const event = JSON.parse(line.slice(6));


        switch (event.type) {

        case ''start'':

        console.log(''Answer started:'', event.id);

        break;

        case ''progress'':

        console.log(''Progress:'', event.content);

        break;

        case ''content'':

        console.log(''Content chunk:'', event.content);

        break;

        case ''end'':

        console.log(''Answer completed:'', event.conversationId);

        break;

        }

        }

        }

        }

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

        '