Anam.ai Knowledge API

openapi: 3.2.0
info:
  title: Anam AI Knowledge API
  version: '1.0'
servers:
- url: https://api.anam.ai
  description: Anam API
security:
- BearerAuth: []
tags:
- name: Knowledge
paths:
  /v1/knowledge/groups:
    get:
      description: Returns a list of all knowledge groups for the organization
      responses:
        '200':
          description: Successfully retrieved knowledge groups
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KnowledgeGroup'
              examples:
                default:
                  $ref: '#/components/examples/KnowledgeGroupArrayResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - API key lacks the required permission
        '500':
          description: Server error
      tags:
      - Knowledge
      operationId: listKnowledgeGroups
      summary: list knowledge groups
      x-mint:
        metadata:
          title: list knowledge groups
        mcp:
          enabled: true
          name: list-knowledge-groups
          description: Returns a list of all knowledge groups for the organization
    post:
      description: Create a new knowledge group
      requestBody:
        description: Name and optional description for the new knowledge group. The group starts empty — upload documents separately via `POST /v1/knowledge/groups/{id}/documents`.
        required: true
        content:
          application/json:
            examples:
              default:
                $ref: '#/components/examples/KnowledgeGroupCreate'
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                description:
                  type: string
                chunkSize:
                  type:
                  - integer
                  - 'null'
                  minimum: 100
                  maximum: 2000
                  description: Default maximum tokens per chunk for documents processed in this group. When not set or null, the group stores the default of 350.
                chunkOverlap:
                  type:
                  - integer
                  - 'null'
                  minimum: 0
                  maximum: 1000
                  description: Default token overlap for documents processed in this group. Must be at most half of chunkSize, or at most 175 when chunkSize is not set. When not set or null, the group stores the default of 0.
      responses:
        '201':
          description: Successfully created knowledge group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeGroup'
              examples:
                default:
                  $ref: '#/components/examples/KnowledgeGroupResponse'
        '400':
          description: Bad request - Invalid data
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - API key lacks the required permission
        '500':
          description: Server error
      tags:
      - Knowledge
      operationId: createKnowledgeGroup
      summary: create knowledge group
      x-mint:
        metadata:
          title: create knowledge group
        mcp:
          enabled: true
          name: create-knowledge-group
          description: Create a new knowledge group
  /v1/knowledge/groups/{id}:
    get:
      description: Get a single RAG group by ID
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: Unique identifier of the knowledge group
      responses:
        '200':
          description: Successfully retrieved RAG group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeGroup'
              examples:
                default:
                  $ref: '#/components/examples/KnowledgeGroupResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - API key lacks the required permission
        '404':
          description: RAG group not found
        '500':
          description: Server error
      tags:
      - Knowledge
      operationId: getKnowledgeGroup
      summary: get knowledge group
      x-mint:
        metadata:
          title: get knowledge group
        mcp:
          enabled: true
          name: get-knowledge-group
          description: Get a single RAG group by ID
    put:
      description: Update a RAG group
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: Unique identifier of the knowledge group
      requestBody:
        description: Fields to update on the knowledge group. Omit a field to leave it unchanged.
        required: true
        content:
          application/json:
            examples:
              default:
                $ref: '#/components/examples/KnowledgeGroupUpdate'
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                chunkSize:
                  type:
                  - integer
                  - 'null'
                  minimum: 100
                  maximum: 2000
                  description: Default maximum tokens per chunk for documents processed in this group. Send null to reset it to the default of 350. Changing a default does not re-chunk existing documents; it applies the next time each document without its own override is processed or revectorised.
                chunkOverlap:
                  type:
                  - integer
                  - 'null'
                  minimum: 0
                  maximum: 1000
                  description: Default token overlap for documents processed in this group. Must be at most half of chunkSize, or at most 175 when chunkSize is not set. Send null to reset it to the default of 0. Changing a default does not re-chunk existing documents; it applies the next time each document without its own override is processed or revectorised.
      responses:
        '200':
          description: Successfully updated RAG group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeGroup'
              examples:
                default:
                  $ref: '#/components/examples/KnowledgeGroupResponse'
        '400':
          description: Bad request - Invalid data
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - API key lacks the required permission
        '404':
          description: RAG group not found
        '409':
          description: Conflict - the group's chunk settings changed while this update was being applied. Retry the request.
        '500':
          description: Server error
      tags:
      - Knowledge
      operationId: updateKnowledgeGroup
      summary: update knowledge group
      x-mint:
        metadata:
          title: update knowledge group
        mcp:
          enabled: true
          name: update-knowledge-group
          description: Update a RAG group
    delete:
      description: Delete a RAG group
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: Unique identifier of the knowledge group
      responses:
        '204':
          description: Successfully deleted RAG group
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - API key lacks the required permission
        '404':
          description: RAG group not found
        '500':
          description: Server error
      tags:
      - Knowledge
      operationId: deleteKnowledgeGroup
      summary: delete knowledge group
      x-mint:
        metadata:
          title: delete knowledge group
        mcp:
          enabled: true
          name: delete-knowledge-group
          description: Delete a RAG group. Use with caution as this action cannot be undone.
  /v1/knowledge/groups/{id}/search:
    post:
      description: Search for similar content in a RAG group using vector similarity
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: Unique identifier of the knowledge group
      requestBody:
        description: Query string to search the group's documents, plus an optional cap on how many chunks to return. Only `READY` documents are included in the results.
        required: true
        content:
          application/json:
            examples:
              default:
                $ref: '#/components/examples/KnowledgeGroupSearch'
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                limit:
                  type: integer
                  minimum: 1
                  maximum: 20
                  default: 5
      responses:
        '200':
          description: Successfully retrieved search results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KnowledgeSearchResult'
              examples:
                default:
                  $ref: '#/components/examples/KnowledgeSearchArrayResponse'
        '400':
          description: Bad request - Invalid search query
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - API key lacks the required permission
        '404':
          description: RAG group not found
        '500':
          description: Server error
      tags:
      - Knowledge
      operationId: searchKnowledgeGroup
      summary: search knowledge group
      x-mint:
        metadata:
          title: search knowledge group
        mcp:
          enabled: true
          name: search-knowledge-group
          description: Search for similar content in a RAG group using vector similarity
  /v1/knowledge/groups/{id}/documents:
    get:
      description: Get all documents in a RAG group
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: Unique identifier of the knowledge group
      responses:
        '200':
          description: Successfully retrieved documents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KnowledgeDocument'
              examples:
                default:
                  $ref: '#/components/examples/KnowledgeDocumentArrayResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - API key lacks the required permission
        '404':
          description: RAG group not found
        '500':
          description: Server error
      tags:
      - Knowledge
      operationId: listKnowledgeGroupDocuments
      summary: list knowledge group documents
      x-mint:
        metadata:
          title: list knowledge group documents
        mcp:
          enabled: true
          name: list-knowledge-group-documents
          description: Get all documents in a RAG group
    post:
      description: Upload a document to a RAG group (Supports PDF, TXT, MD, DOCX, CSV, JSON up to 50MB). Authentication can be via API key (Bearer token) OR upload token (X-Upload-Token header).
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: Unique identifier of the knowledge group
      requestBody:
        description: Document file to upload into the knowledge group. Supported formats are PDF, TXT, MD, DOCX, CSV, and JSON, up to 50MB. Must be sent as `multipart/form-data`. Documents are processed asynchronously — the returned record starts in `PROCESSING` state and becomes searchable once it reaches `READY`.
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Document file (PDF, TXT, MD, DOCX, CSV, or JSON, max 50MB).
                chunkSize:
                  type: integer
                  minimum: 100
                  maximum: 2000
                  description: Maximum tokens per chunk for this document. Defaults to the group's chunkSize, or the default of 350 when the group has none. Setting chunkSize or chunkOverlap overrides the group's settings for this document. JSON files ignore chunk settings; they are kept whole up to 2000 tokens, and larger files are split at 1000 tokens with 50 overlap.
                chunkOverlap:
                  type: integer
                  minimum: 0
                  maximum: 1000
                  description: Token overlap between chunks for this document. Must be at most half of chunkSize, or at most 175 when chunkSize is not set. Defaults to the group's chunkOverlap, or the default of 0 when the group has none. If you set only chunkSize, overlap is the default of 0 rather than the group's value.
      responses:
        '201':
          description: Successfully uploaded document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeDocument'
              examples:
                default:
                  $ref: '#/components/examples/KnowledgeDocumentResponse'
        '400':
          description: Bad request - Invalid file or parameters
        '401':
          description: Unauthorized - Invalid or missing API key/upload token
        '403':
          description: Forbidden - API key lacks the required permission
        '404':
          description: RAG group not found
        '500':
          description: Server error
      tags:
      - Knowledge
      operationId: uploadKnowledgeGroupDocument
      summary: upload knowledge group document
      x-mint:
        metadata:
          title: upload knowledge group document
        mcp:
          enabled: true
          name: upload-knowledge-group-document
          description: Upload a document to a RAG group (Supports PDF, TXT, MD, DOCX, CSV, JSON up to 50MB). Authentication can be via API key (Bearer token) OR upload token (X-Upload-Token header).
  /v1/knowledge/documents/{id}:
    get:
      description: Get a single document by ID
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: Unique identifier of the knowledge document
      responses:
        '200':
          description: Successfully retrieved document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeDocument'
              examples:
                default:
                  $ref: '#/components/examples/KnowledgeDocumentResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - API key lacks the required permission
        '404':
          description: Document not found
        '500':
          description: Server error
      tags:
      - Knowledge
      operationId: getKnowledgeDocument
      summary: get knowledge document
      x-mint:
        metadata:
          title: get knowledge document
        mcp:
          enabled: true
          name: get-knowledge-document
          description: Get a single document by ID
    put:
      description: Update a document (rename)
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: Unique identifier of the knowledge document
      requestBody:
        description: Rename the document. Only `filename` is editable; the stored file and its extracted chunks are unchanged. Chunk settings can only be set at upload, so a non-null `chunkSize` or `chunkOverlap` returns 400.
        required: true
        content:
          application/json:
            examples:
              default:
                $ref: '#/components/examples/KnowledgeDocumentRename'
            schema:
              type: object
              properties:
                filename:
                  type: string
                  description: New filename for the document
      responses:
        '200':
          description: Successfully updated document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeDocument'
              examples:
                default:
                  $ref: '#/components/examples/KnowledgeDocumentResponse'
        '400':
          description: Bad request - Invalid data
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - API key lacks the required permission
        '404':
          description: Document not found
        '500':
          description: Server error
      tags:
      - Knowledge
      operationId: updateKnowledgeDocument
      summary: update knowledge document
      x-mint:
        metadata:
          title: update knowledge document
        mcp:
          enabled: true
          name: update-knowledge-document
          description: Update a document (rename)
    delete:
      description: Delete a document from a RAG group
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: Unique identifier of the knowledge document
      responses:
        '204':
          description: Successfully deleted document
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - API key lacks the required permission
        '404':
          description: Document not found
        '500':
          description: Server error
      tags:
      - Knowledge
      operationId: deleteKnowledgeDocument
      summary: delete knowledge document
      x-mint:
        metadata:
          title: delete knowledge document
        mcp:
          enabled: true
          name: delete-knowledge-document
          description: Delete a document from a RAG group. Use with caution as this action cannot be undone.
  /v1/knowledge/documents/{id}/download:
    get:
      description: Get a presigned download URL for a knowledge document
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: Unique identifier of the knowledge document
      responses:
        '200':
          description: Successfully generated download URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  downloadUrl:
                    type: string
                  filename:
                    type: string
              examples:
                default:
                  $ref: '#/components/examples/KnowledgeDocumentDownloadResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - API key lacks the required permission
        '404':
          description: Document not found
        '500':
          description: Server error
      tags:
      - Knowledge
      operationId: getKnowledgeDocumentDownload
      summary: get knowledge document download
      x-mint:
        metadata:
          title: get knowledge document download
        mcp:
          enabled: true
          name: get-knowledge-document-download
          description: Get a presigned download URL for a knowledge document
components:
  examples:
    KnowledgeDocumentArrayResponse:
      summary: All documents in a knowledge group (bare array)
      value:
      - id: 00000000-0000-0000-0000-000000000000
        knowledgeFolderId: 00000000-0000-0000-0000-000000000000
        filename: getting-started.pdf
        fileType: application/pdf
        fileSize: 248320
        fileUrl: https://cdn.anam.ai/knowledge/getting-started.pdf
        status: READY
        errorMessage: null
        chunkSize: null
        chunkOverlap: null
        appliedChunking:
          strategy: paragraph
          chunkSize: 800
          chunkOverlap: 100
          source: folder
          appliedAt: '2026-04-20T10:01:12.000Z'
        createdAt: '2026-04-20T10:00:00.000Z'
        updatedAt: '2026-04-20T10:01:12.000Z'
    KnowledgeSearchArrayResponse:
      summary: Search results (bare array, ranked by score)
      value:
      - documentId: 00000000-0000-0000-0000-000000000000
        filename: getting-started.pdf
        content: To reset your password, visit the account settings page and click "Reset password".
        score: 0.87
        chunkIndex: 3
        metadata:
          section: Account
    KnowledgeGroupSearch:
      summary: Find the top 5 chunks matching a query
      value:
        query: How do I reset my password?
        limit: 5
    KnowledgeDocumentResponse:
      summary: A single knowledge document
      value:
        id: 00000000-0000-0000-0000-000000000000
        knowledgeFolderId: 00000000-0000-0000-0000-000000000000
        filename: getting-started.pdf
        fileType: application/pdf
        fileSize: 248320
        fileUrl: https://cdn.anam.ai/knowledge/getting-started.pdf
        status: READY
        errorMessage: null
        chunkSize: null
        chunkOverlap: null
        appliedChunking:
          strategy: paragraph
          chunkSize: 800
          chunkOverlap: 100
          source: folder
          appliedAt: '2026-04-20T10:01:12.000Z'
        createdAt: '2026-04-20T10:00:00.000Z'
        updatedAt: '2026-04-20T10:01:12.000Z'
    KnowledgeDocumentDownloadResponse:
      summary: A short-lived URL for downloading a knowledge document
      value:
        downloadUrl: https://cdn.anam.ai/knowledge/00000000-0000-0000-0000-000000000000.pdf?X-Amz-Signature=…
        filename: getting-started.pdf
    KnowledgeGroupUpdate:
      summary: Rename a knowledge group
      value:
        name: Customer support
    KnowledgeGroupCreate:
      summary: Create an empty knowledge group with default chunk settings
      value:
        name: Product docs
        description: Help-centre articles and API reference.
        chunkSize: 800
        chunkOverlap: 100
    KnowledgeGroupArrayResponse:
      summary: All knowledge groups for the organization (bare array)
      value:
      - id: 00000000-0000-0000-0000-000000000000
        name: Product docs
        description: Help-centre articles and API reference.
        documentCount: 12
        chunkSize: 800
        chunkOverlap: 100
        createdAt: '2026-04-20T10:00:00.000Z'
        updatedAt: '2026-04-20T10:00:00.000Z'
    KnowledgeGroupResponse:
      summary: A single knowledge group
      value:
        id: 00000000-0000-0000-0000-000000000000
        name: Product docs
        description: Help-centre articles and API reference.
        documentCount: 12
        chunkSize: 800
        chunkOverlap: 100
        createdAt: '2026-04-20T10:00:00.000Z'
        updatedAt: '2026-04-20T10:00:00.000Z'
    KnowledgeDocumentRename:
      summary: Rename a document
      value:
        filename: updated-filename.pdf
  schemas:
    KnowledgeDocument:
      type: object
      description: A single file uploaded into a knowledge group. Retrieved chunks reference it by ID.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the document.
        knowledgeFolderId:
          type: string
          format: uuid
          description: ID of the knowledge group this document belongs to.
        filename:
          type: string
          description: Original filename as uploaded.
        fileType:
          type: string
          description: MIME type or extension-derived file type.
        fileSize:
          type: integer
          description: Size of the file in bytes.
        fileUrl:
          type: string
          format: uri
          description: Internal URL at which the file is stored.
        status:
          type: string
          enum:
          - UPLOADED
          - PROCESSING
          - READY
          - FAILED
          description: Current processing state. Only `READY` documents are searchable.
        errorMessage:
          type:
          - string
          - 'null'
          description: Failure reason when `status` is `FAILED`, otherwise `null`.
        chunkSize:
          type:
          - integer
          - 'null'
          description: Chunk size override set at upload, in tokens; null when not overridden. When both chunkSize and chunkOverlap are null, the document uses its group's settings. When only chunkOverlap is set, a null chunkSize means the default of 350.
        chunkOverlap:
          type:
          - integer
          - 'null'
          description: Chunk overlap override set at upload, in tokens; null when not overridden. When both chunkSize and chunkOverlap are null, the document uses its group's settings. When only chunkSize is set, a null chunkOverlap means the default of 0.
        appliedChunking:
          type:
          - object
          - 'null'
          description: Settings the last successful processing used. Null until the document has been processed.
          properties:
            strategy:
              type: string
            chunkSize:
              type:
              - integer
              - 'null'
            chunkOverlap:
              type:
              - integer
              - 'null'
            source:
              type: string
              enum:
              - document
              - folder
              - default
            appliedAt:
              type: string
              format: date-time
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the document was uploaded.
        updatedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when the document record was last updated.
    KnowledgeSearchResult:
      type: object
      description: One matching chunk returned by a knowledge-group search.
      properties:
        documentId:
          type: string
          format: uuid
          description: ID of the document the chunk was extracted from.
        filename:
          type: string
          description: Filename of the source document.
        content:
          type: string
          description: Text content of the matching chunk.
        score:
          type: number
          description: Similarity score for this chunk against the query, higher is more similar.
        chunkIndex:
          type: integer
          description: Zero-based index of the chunk within the source document.
        metadata:
          type: object
          description: Free-form metadata attached to the chunk at ingest time.
    KnowledgeGroup:
      type: object
      description: A folder of documents that a persona can search via RAG tools.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the knowledge group.
        name:
          type: string
          description: Human-readable name for the group.
        description:
          type:
          - string
          - 'null'
          description: Free-form description of what the group contains.
        documentCount:
          type: integer
          description: Number of non-deleted documents currently in the group.
        chunkSize:
          type:
          - integer
          - 'null'
          description: Default maximum tokens per chunk for documents in this group. Null means documents use the default of 350.
        chunkOverlap:
          type:
          - integer
          - 'null'
          description: Default token overlap for documents in this group. Null means documents use the default of 0.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the group was created.
        updatedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when the group was last updated.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
x-mint:
  mcp:
    enabled: true
x-provenance:
  method: harvested
  publisher: Anam.ai
  source: https://api.anam.ai/swagger.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)