Brainfish Documents API

openapi: 3.2.0
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
          - 'null'
          format: uuid
      - 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:
    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
    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
          - 'null'
          format: uuid
          description: Parent document ID if nested
        template:
          type: boolean
          description: Whether this is a template document
        templateId:
          type:
          - string
          - 'null'
          format: uuid
          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
          - 'null'
          format: date-time
          description: Publication timestamp
        archivedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Archive timestamp
        deletedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Deletion timestamp
        createdBy:
          $ref: '#/components/schemas/UserSummary'
        updatedBy:
          $ref: '#/components/schemas/UserSummary'
    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
          - 'null'
          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
          - 'null'
          description: ID of the user who last updated the document
          example: user-123
        publishedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Publication timestamp
        archivedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Archive timestamp
        deletedAt:
          type:
          - string
          - 'null'
          format: date-time
          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
    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
    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.)
    ValidationError:
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        properties:
          validationErrors:
            type: array
            items:
              type: o

# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/brainfish/refs/heads/main/openapi/brainfish-documents-api-openapi.yml