Brainfish Users API

openapi: 3.2.0
info:
  title: Brainfish Public Users 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: 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

        and optional collection filters to scope which knowledge base collections are searched.


        Use the optional `collectionIds` array to restrict answers to specific collections the

        caller has access to. When omitted, all available collections are searched.


        The response is streamed using Server-Sent Events (SSE) format, identical to the

        `/v1/agents/answer` endpoint.


        For user personalization (attribute-based collection filtering, external user tracking),

        use the `/v1/agents/answer` endpoint with the `user` field instead.


        ## Authentication


        Requires a Bearer API token. The token determines the team context and permissions.


        ## Streaming Example


        ```javascript

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

        method: ''POST'',

        headers: {

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

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

        },

        body: JSON.stringify({

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

        collectionIds: [''collection-uuid-1'', ''collection-uuid-2'']

        })

        });


        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 ''content'':

        process.stdout.write(event.content);

        break;

        case ''end'':

        console.log(''\nDone. conversationId:'', event.conversationId);

        break;

        }

        }

        }

        }

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

        '