openapi: 3.0.3
info:
  title: Brainfish Public Agents Documents 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: Documents
  description: Document management operations including create, read, update, list, and delete
paths:
  /v1/documents:
    get:
      summary: List documents
      description: 'List documents with optional filtering and pagination. Returns documents the authenticated user has access to.

        '
      operationId: listDocuments
      tags:
      - Documents
      security:
      - BearerAuth: []
      parameters:
      - name: collectionId
        in: query
        description: Filter by collection ID
        schema:
          type: string
          format: uuid
      - name: parentDocumentId
        in: query
        description: Filter by parent document ID. Use 'null' to get root-level documents.
        schema:
          type: string
          format: uuid
          nullable: true
      - name: template
        in: query
        description: Filter by template status
        schema:
          type: boolean
      - name: sort
        in: query
        description: Field to sort by
        schema:
          type: string
          enum:
          - createdAt
          - updatedAt
          - publishedAt
          - title
          default: updatedAt
      - name: direction
        in: query
        description: Sort direction
        schema:
          type: string
          enum:
          - ASC
          - DESC
          default: DESC
      - name: limit
        in: query
        description: Maximum number of results to return (1-100)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: offset
        in: query
        description: Offset for pagination
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: List of documents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentListResponse'
              example:
                data:
                - id: 30ba6c51-5f9d-4d8d-be10-783f7af1c9af
                  url: /doc/getting-started-guide-fKhbRGBXj6
                  urlId: fKhbRGBXj6
                  title: Getting Started Guide
                  summary: This guide helps you get started with the platform...
                  tasks:
                    completed: 0
                    total: 0
                  index: P0
                  createdAt: '2024-01-10T08:00:00Z'
                  createdBy: user-123
                  updatedAt: '2024-01-15T10:30:00Z'
                  updatedBy: user-123
                  publishedAt: '2024-01-15T10:30:00Z'
                  archivedAt: null
                  deletedAt: null
                  teamId: team-456
                  collectionId: col-456
                  revision: 5
                  isPublic: true
                  hasPendingSuggestion: false
                pagination:
                  offset: 0
                  limit: 25
                  total: 42
                timestamp: '2024-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Create document
      description: 'Create a new document. You can create a published document or a draft by setting the `publish` flag.

        '
      operationId: createDocument
      tags:
      - Documents
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDocumentRequest'
            examples:
              simpleDocument:
                summary: Create a simple document
                value:
                  title: My New Document
                  text: '# Introduction


                    This is the content of my document.'
                  collectionId: col-456
                  publish: true
              draftDocument:
                summary: Create a draft
                value:
                  title: Work in Progress
                  text: Draft content here...
                  collectionId: col-456
                  publish: false
              nestedDocument:
                summary: Create a nested document
                value:
                  title: Sub-article
                  text: Content for the sub-article...
                  collectionId: col-456
                  parentDocumentId: doc-parent-123
                  publish: true
      responses:
        '200':
          description: Document created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
              example:
                data:
                  id: doc-new-123
                  title: My New Document
                  url: /doc/my-new-document-xyz789
                  text: '# Introduction


                    This is the content of my document.'
                  collectionId: col-456
                  publishedAt: '2024-01-15T10:30:00Z'
                  createdAt: '2024-01-15T10:30:00Z'
                  updatedAt: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/documents/{id}:
    get:
      summary: Get document
      description: 'Retrieve a document by its ID or URL ID.

        '
      operationId: getDocument
      tags:
      - Documents
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: 'Document identifier. Accepts either:

          - UUID format: `123e4567-e89b-12d3-a456-426614174000`

          - URL slug format: `bookings-and-meet-greets-tqQoYObGRP`

          '
        schema:
          type: string
        examples:
          uuid:
            value: 123e4567-e89b-12d3-a456-426614174000
            summary: UUID format
          urlSlug:
            value: bookings-and-meet-greets-tqQoYObGRP
            summary: URL slug format
      responses:
        '200':
          description: Document details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
              example:
                data:
                  id: doc-123
                  title: Getting Started Guide
                  url: /doc/getting-started-guide-abc123
                  text: '# Welcome


                    This guide helps you get started...'
                  collectionId: col-456
                  publishedAt: '2024-01-15T10:30:00Z'
                  createdAt: '2024-01-10T08:00:00Z'
                  updatedAt: '2024-01-15T10:30:00Z'
                timestamp: '2024-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      summary: Update document
      description: 'Update an existing document. Only provided fields will be updated.

        '
      operationId: updateDocument
      tags:
      - Documents
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: 'Document identifier. Accepts either:

          - UUID format: `123e4567-e89b-12d3-a456-426614174000`

          - URL slug format: `bookings-and-meet-greets-tqQoYObGRP`

          '
        schema:
          type: string
        examples:
          uuid:
            value: 123e4567-e89b-12d3-a456-426614174000
            summary: UUID format
          urlSlug:
            value: bookings-and-meet-greets-tqQoYObGRP
            summary: URL slug format
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDocumentRequest'
            examples:
              updateTitle:
                summary: Update document title
                value:
                  title: Updated Title
              updateContent:
                summary: Update document content
                value:
                  text: '# New Content


                    This is the updated content.'
              publishDocument:
                summary: Publish a draft
                value:
                  publish: true
      responses:
        '200':
          description: Document updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      summary: Delete document
      description: 'Delete a document. By default, the document is soft-deleted and can be restored. Use `permanent=true` to permanently delete the document.

        '
      operationId: deleteDocument
      tags:
      - Documents
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: 'Document identifier. Accepts either:

          - UUID format: `123e4567-e89b-12d3-a456-426614174000`

          - URL slug format: `bookings-and-meet-greets-tqQoYObGRP`

          '
        schema:
          type: string
        examples:
          uuid:
            value: 123e4567-e89b-12d3-a456-426614174000
            summary: UUID format
          urlSlug:
            value: bookings-and-meet-greets-tqQoYObGRP
            summary: URL slug format
      - name: permanent
        in: query
        description: Whether to permanently delete the document
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Document deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteDocumentResponse'
              example:
                success: true
                timestamp: '2024-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/documents/{id}/move:
    post:
      summary: Move document
      description: 'Move a document to a different collection or parent document. The document and all of its

        children will be moved to the target collection. Any existing pins from the source collection

        are automatically removed.

        '
      operationId: moveDocument
      tags:
      - Documents
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Document ID (UUID)
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveDocumentRequest'
            examples:
              moveToCollection:
                summary: Move document to another collection
                value:
                  collectionId: 123e4567-e89b-12d3-a456-426614174000
              moveUnderParent:
                summary: Move document under a parent document
                value:
                  collectionId: 123e4567-e89b-12d3-a456-426614174000
                  parentDocumentId: 987fcdeb-51a2-43e7-b890-123456789abc
              moveWithIndex:
                summary: Move document to a specific position
                value:
                  collectionId: 123e4567-e89b-12d3-a456-426614174000
                  index: 0
      responses:
        '200':
          description: Document moved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MoveDocumentResponse'
              example:
                data:
                  documents:
                  - id: doc-123
                    title: Getting Started Guide
                    url: /doc/getting-started-guide-abc123
                    collectionId: 123e4567-e89b-12d3-a456-426614174000
                  collections:
                  - id: 123e4567-e89b-12d3-a456-426614174000
                    name: Help Articles
                timestamp: '2024-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/documents/search:
    post:
      summary: Search documents
      description: 'Search documents using semantic search. Returns relevant documents matching the query with relevance scores.

        '
      operationId: searchDocuments
      tags:
      - Documents
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchDocumentsRequest'
            examples:
              simpleSearch:
                summary: Simple search query
                value:
                  query: How do I reset my password?
              filteredSearch:
                summary: Search within a specific collection
                value:
                  query: API authentication
                  collectionId: 123e4567-e89b-12d3-a456-426614174000
              limitedSearch:
                summary: Search with result limit
                value:
                  query: getting started
                  limit: 10
              cmsOnlySearch:
                summary: Search CMS documents only (exclude external catalogs)
                value:
                  query: product features
                  cmsOnly: true
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchDocumentsResponse'
              example:
                data:
                - id: doc-123
                  title: Password Reset Guide
                  score: 0.95
                  percent: 95
                  chunk: To reset your password, navigate to the login page and click 'Forgot Password'...
                  url: /doc/password-reset-guide-abc123
                  collectionId: col-456
                  isPublic: true
                - id: doc-456
                  title: Account Security
                  score: 0.82
                  percent: 82
                  chunk: Keeping your account secure includes regularly updating your password...
                  url: /doc/account-security-def789
                  collectionId: col-456
                  isPublic: true
                pagination:
                  limit: 10
                  total: 15
                query: How do I reset my password?
                timestamp: '2024-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/documents/suggestion:
    post:
      summary: Generate article suggestions
      description: "Triggers the Brainfish Knowledge Discovery Agent to analyze article content and generate \nsuggestions for improving the content. Processing happens asynchronously.\n\nThe agent will analyze the provided content and create suggestions for human review. \nResults will be synced back to the platform when processing is complete:\n- **New document drafts**: If `new_article` is true, the agent will create new article drafts\n- **Article suggestions**: If `new_article` is false, the agent will suggest updates to existing documents\n\nAll suggestions require human review before being published.\n\n**Duplicate Request Prevention**: Requests with identical `content` are \ncached for 5 minutes to prevent duplicate processing. If you submit the same content \nwithin this window, a 409 Conflict response will be returned.\n\nUse the returned `task_id` to track the processing status.\n"
      operationId: generateArticleSuggestion
      tags:
      - Documents
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateArticleSuggestionRequest'
            examples:
              basic:
                summary: Basic article suggestion request
                value:
                  content: '# Introduction


                    Welcome to our platform. This guide will help you get started...'
                  collection_id: 123e4567-e89b-12d3-a456-426614174000
                  new_article: false
      responses:
        '200':
          description: Suggestion generation triggered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateArticleSuggestionResponse'
              example:
                data:
                  task_id: task-abc123
                  status: processing
                message: Article suggestion generation has been triggered. Results will be synced when processing is complete.
                timestamp: '2024-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Duplicate request - same content is already being processed (cached for 5 minutes)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: conflict
                message: A similar suggestion request is already being processed. Please wait and try again.
                timestamp: '2024-01-15T10:30:00Z'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    MoveDocumentRequest:
      type: object
      required:
      - collectionId
      properties:
        collectionId:
          type: string
          format: uuid
          description: Target collection ID to move the document into
        parentDocumentId:
          type: string
          format: uuid
          nullable: true
          description: Optional parent document ID within the target collection
        index:
          type: integer
          minimum: 0
          description: Position index among siblings (0-based). If omitted, the document is placed at the end.
    DocumentResponse:
      type: object
      required:
      - data
      - timestamp
      properties:
        data:
          $ref: '#/components/schemas/DocumentDetail'
        timestamp:
          type: string
          format: date-time
          description: Response timestamp
    UpdateDocumentRequest:
      type: object
      properties:
        title:
          type: string
          description: Document title
          example: Updated Title
        text:
          type: string
          description: Document content in Markdown format
          example: '# Updated Content


            New content here...'
        publish:
          type: boolean
          description: Whether to publish the document
        fullWidth:
          type: boolean
          description: Whether the document should display in full width
        collectionId:
          type: string
          format: uuid
          description: Collection ID to move the document to
        siteEnabled:
          type: boolean
          description: Whether the document should be public on the site
    UserSummary:
      type: object
      properties:
        id:
          type: string
          description: User ID
        name:
          type: string
          description: User's full name
        avatarUrl:
          type: string
          description: User's avatar URL
    MoveDocumentResponse:
      type: object
      required:
      - data
      - timestamp
      properties:
        data:
          type: object
          required:
          - documents
          - collections
          properties:
            documents:
              type: array
              items:
                $ref: '#/components/schemas/Document'
              description: The moved document and any child documents whose collection changed
            collections:
              type: array
              items:
                $ref: '#/components/schemas/CollectionListItem'
              description: The source and/or target collections affected by the move
        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
    GenerateArticleSuggestionResponse:
      type: object
      required:
      - data
      - message
      - timestamp
      properties:
        data:
          type: object
          properties:
            task_id:
              type: string
              description: Unique identifier for the processing task
              example: task-abc123
            status:
              type: string
              description: Current status of the task
              example: processing
        message:
          type: string
          description: Human-readable status message
          example: Article suggestion generation has been triggered. Results will be synced when processing is complete.
        timestamp:
          type: string
          format: date-time
          description: Response timestamp
    SearchDocumentsResponse:
      type: object
      required:
      - data
      - pagination
      - query
      - timestamp
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SearchResult'
        pagination:
          type: object
          description: Pagination info (note - semantic search does not support offset-based pagination)
          required:
          - limit
          - total
          properties:
            limit:
              type: integer
              description: Maximum results per page
              example: 10
            total:
              type: integer
              description: Total number of results
              example: 15
        query:
          type: string
          description: The processed search query (may be rewritten for better results)
          example: How do I reset my password?
        timestamp:
          type: string
          format: date-time
          description: Response timestamp
    DocumentListItem:
      type: object
      description: Simplified document representation for list endpoints
      required:
      - id
      - url
      - urlId
      - title
      properties:
        id:
          type: string
          format: uuid
          description: Unique document identifier
          example: 30ba6c51-5f9d-4d8d-be10-783f7af1c9af
        url:
          type: string
          description: Document URL path
          example: /doc/getting-started-guide-fKhbRGBXj6
        urlId:
          type: string
          description: URL-friendly document identifier (10 characters)
          example: fKhbRGBXj6
        title:
          type: string
          description: Document title
          example: Getting Started Guide
        summary:
          type: string
          description: Auto-generated summary of the document
          example: This guide helps you get started...
        tasks:
          type: object
          properties:
            completed:
              type: integer
              description: Number of completed tasks
              example: 0
            total:
              type: integer
              description: Total number of tasks
              example: 0
        index:
          type: string
          description: Document sort index
          example: P0
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        createdBy:
          type: string
          nullable: true
          description: ID of the user who created the document
          example: user-123
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
        updatedBy:
          type: string
          nullable: true
          description: ID of the user who last updated the document
          example: user-123
        publishedAt:
          type: string
          format: date-time
          nullable: true
          description: Publication timestamp
        archivedAt:
          type: string
          format: date-time
          nullable: true
          description: Archive timestamp
        deletedAt:
          type: string
          format: date-time
          nullable: true
          description: Deletion timestamp
        teamId:
          type: string
          format: uuid
          description: Team ID the document belongs to
        collectionId:
          type: string
          format: uuid
          description: Collection ID the document belongs to
        revision:
          type: integer
          description: Document revision count
          example: 5
        isPublic:
          type: boolean
          description: Whether the document is publicly accessible on the site
          example: true
        hasPendingSuggestion:
          type: boolean
          description: Whether the document has a pending suggestion awaiting review
          example: false
    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
    DocumentListResponse:
      type: object
      required:
      - data
      - pagination
      - timestamp
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DocumentListItem'
        pagination:
          type: object
          required:
          - offset
          - limit
          - total
          properties:
            offset:
              type: integer
              description: Current offset
              example: 0
            limit:
              type: integer
              description: Maximum results per page
              example: 25
            total:
              type: integer
              description: Total number of results
              example: 42
        timestamp:
          type: string
          format: date-time
          description: Response timestamp
    DocumentDetail:
      type: object
      description: Full document representation with text content
      required:
      - id
      - url
      - urlId
      - title
      - text
      properties:
        id:
          type: string
          format: uuid
          description: Unique document identifier
          example: 30ba6c51-5f9d-4d8d-be10-783f7af1c9af
        url:
          type: string
          description: Document URL path
          example: /doc/getting-started-guide-fKhbRGBXj6
        urlId:
          type: string
          description: URL-friendly document identifier (10 characters)
          example: fKhbRGBXj6
        title:
          type: string
          description: Document title
          example: Getting Started Guide
        text:
          type: string
          description: Document content in Markdown format
          example: '# Getting Started


            Welcome to our platform...'
        summary:
          type: string
          description: Auto-generated summary of the document
          example: This guide helps you get started...
        tasks:
          type: object
          properties:
            completed:
              type: integer
              description: Number of completed tasks
              example: 0
            total:
              type: integer
              description: Total number of tasks
              example: 0
        index:
          type: string
          description: Document sort index
          example: P0
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        createdBy:
          type: string
          nullable: true
          description: ID of the user who created the document
          example: user-123
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
        updatedBy:
          type: string
          nullable: true
          description: ID of the user who last updated the document
          example: user-123
        publishedAt:
          type: string
          format: date-time
          nullable: true
          description: Publication timestamp
        archivedAt:
          type: string
          format: date-time
          nullable: true
          description: Archive timestamp
        deletedAt:
          type: string
          format: date-time
          nullable: true
          description: Deletion timestamp
        teamId:
          type: string
          format: uuid
          description: Team ID the document belongs to
        collectionId:
          type: string
          format: uuid
          description: Collection ID the document belongs to
        parentDocumentId:
          type: string
          format: uuid
          nullable: true
          description: Parent document ID if nested
        revision:
          type: integer
          description: Document revision count
          example: 5
        isPublic:
          type: boolean
          description: Whether the document is publicly accessible on the site
          example: true
        hasPendingSuggestion:
          type: boolean
          description: Whether the document has a pending suggestion awaiting review
          example: false
    Document:
      type: object
      required:
      - id
      - title
      - url
      properties:
        id:
          type: string
          description: Unique document identifier
          example: doc-123
        url:
          type: string
          description: Document URL path
          example: /doc/getting-started-guide-abc123
        urlId:
          type: string
          description: URL-friendly document identifier
          example: abc123
        title:
          type: string
          description: Document title
          example: Getting Started Guide
        text:
          type: string
          description: Document content in Markdown format
          example: '# Welcome


            This guide helps you get started...'
        summary:
          type: string
          description: Auto-generated summary of the document
          example: Welcome. This guide helps you get started...
        revision:
          type: integer
          description: Document revision count
          example: 5
        collectionId:
          type: string
          format: uuid
          description: Collection ID the document belongs to
        parentDocumentId:
          type: string
          format: uuid
          nullable: true
          description: Parent document ID if nested
        template:
          type: boolean
          description: Whether this is a template document
        templateId:
          type: string
          format: uuid
          nullable: true
          description: Template ID used to create this document
        fullWidth:
          type: boolean
          description: Whether the document displays in full width
        siteEnabled:
          type: boolean
          description: Whether the document is public on the site
        teamId:
          type: string
          format: uuid
          description: Team ID the document belongs to
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
        publishedAt:
          type: string
          format: date-time
          nullable: true
          description: Publication timestamp
        archivedAt:
          type: string
          format: date-time
          nullable: true
          description: Archive timestamp
        deletedAt:
          type: string
          format: date-time
          nullable: true
          description: Deletion timestamp
        createdBy:
          $ref: '#/components/schemas/UserSummary'
        updatedBy:
          $ref: '#/components/schemas/UserSummary'
    SearchDocumentsRequest:
      type: object
      required:
      - query
      properties:
        query:
          type: string
          description: Search query string
          minLength: 1
          example: How do I reset my password?
        collectionId:
          type: string
          format: uuid
          description: Filter by collection ID
        collectionIds:
          type: array
          items:
            type: string
            format: uuid
          description: Filter by multiple collection IDs
        dateFilter:
          type: string
          enum:
          - day
          - week
          - month
          - year
          description: Filter by date range
        limit:
          type: integer
          minimum: 1
          maximum: 25
          default: 10
          description: Maximum number of results to return (semantic search does not support offset-based pagination)
        cmsOnly:
          type: boolean
          default: false
          description: Only include CMS documents (exclude external catalog content like Confluence, Notion, etc.)
    CreateDocumentRequest:
      type: object
      properties:
        title:
          type: string
          description: Document title
          default: ''
          example: Getting Started Guide
        text:
          type: string
          description: Document content in Markdown format
          default: ''
          example: '# Introduction


            Welcome to our platform...'
        collectionId:
          type: string
          format: uuid
          description: Collection ID to create the document in
          example: 123e4567-e89b-12d3-a456-426614174000
        parentDocumentId:
          type: string
          format: uuid
          nullable: true
          description: Parent document ID for nested documents
        publish:
          type: boolean
          description: Whether to publish the document immediately
          example: true
        template:
          type: boolean
          description: Whether this document is a template
          example: false
        templateId:
          type: string
          format: uuid
          description: Template ID to use for creating the document
    DeleteDocumentResponse:
      type: object
      required:
      - success
      - timestamp
      properties:
        success:
          type: boolean
          description: Whether the deletion was successful
          example: true
        timestamp:
          type: string
          format: date-time
          description: Response timestamp
    GenerateArticleSuggestionRequest:
      type: object
      required:
      - content
      properties:
        content:
          type: string
          minLength: 1
          description: Full article content in Markdown format
          example: '# Introduction


            Welcome to our platform. This guide will help you get started...'
        collection_id:
          type: string
          format: uuid
          description: Optional collection ID where new documents will be created
          example: 123e4567-e89b-12d3-a456-426614174000
        new_article:
          type: boolean
          default: false
          description: Whether to create a new article (true) or suggest updates to existing documents (false)
          example: false
    SearchResult:
      type: object
      properties:
        id:
          type: string
          description: Document ID
          example: doc-123
        title:
          type: string
          description: Document title
          example: Password Reset Guide
        score:
          type: number
          description: Relevance score (0-1)
          example: 0.95
        percent:
          type: integer
          description: Relevance score as percentage (0-100)
          example: 95
        chunk:
          type: string
          description: Relevant text snippet from the document
          example: To reset your password, navigate to the login page...
        url:
          type: string
          description: Document URL path
          example: /doc/password-reset-guide-abc123
        collectionId:
          type: string
          format: uuid
          description: Collection ID the document belongs to
        isPublic:
          type: boolean
          description: Whether the document is publicly accessible
        lastUpdated:
          type: string
          format: date-time
          description: Last update timestamp
  responses:
    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'
    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
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: not_found
            message: Document not found
            timestamp: '2024-01-15T10:30:00Z'
            requestId: req-notfound123
    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.

        '