Brainfish Conversations API

openapi: 3.2.0
info:
  title: Brainfish Public Conversations 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: 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 <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'
    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:
    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
    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
  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.

        '