openapi: 3.1.0
info:
  title: Letta Admin Folders API
  version: 1.0.0
  description: REST API for Letta, the stateful agents platform. Manage agents, memory blocks, archival passages, sources, custom tools, MCP servers, multi-agent groups, runs, and streaming responses. Available as Letta Cloud (managed) at https://api.letta.com/v1 and as the self-hosted open-source server (Apache-2.0) typically run at http://localhost:8283.
  contact:
    name: Letta
    url: https://www.letta.com/
    email: support@letta.com
  license:
    name: Apache-2.0
    url: https://github.com/letta-ai/letta/blob/main/LICENSE
  x-logo:
    url: https://www.letta.com/favicon.ico
servers:
- url: https://api.letta.com
  description: Letta Cloud (managed)
- url: https://app.letta.com
  description: Letta Cloud (app)
- url: http://localhost:8283
  description: Self-hosted Letta server
security:
- bearerAuth: []
tags:
- name: Folders
  description: Organize agents and resources into folders.
paths:
  /v1/folders/count:
    get:
      tags:
      - Folders
      summary: Count Folders
      description: Count all data folders created by a user.
      operationId: count_folders
      parameters: []
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: integer
                title: Response Count Folders
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/folders/{folder_id}:
    get:
      tags:
      - Folders
      summary: Retrieve Folder
      description: Get a folder by ID
      operationId: retrieve_folder
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: string
          minLength: 43
          maxLength: 43
          pattern: ^source-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
          description: The ID of the source in the format 'source-<uuid4>'
          examples:
          - source-123e4567-e89b-42d3-8456-426614174000
          title: Folder Id
        description: The ID of the source in the format 'source-<uuid4>'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Folders
      summary: Modify Folder
      description: Update the name or documentation of an existing data folder.
      operationId: modify_folder
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: string
          minLength: 43
          maxLength: 43
          pattern: ^source-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
          description: The ID of the source in the format 'source-<uuid4>'
          examples:
          - source-123e4567-e89b-42d3-8456-426614174000
          title: Folder Id
        description: The ID of the source in the format 'source-<uuid4>'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Folders
      summary: Delete Folder
      description: Delete a data folder.
      operationId: delete_folder
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: string
          minLength: 43
          maxLength: 43
          pattern: ^source-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
          description: The ID of the source in the format 'source-<uuid4>'
          examples:
          - source-123e4567-e89b-42d3-8456-426614174000
          title: Folder Id
        description: The ID of the source in the format 'source-<uuid4>'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/folders/name/{folder_name}:
    get:
      tags:
      - Folders
      summary: Get Folder by Name
      description: '**Deprecated**: Please use the list endpoint `GET /v1/folders?name=` instead.



        Get a folder by name.'
      operationId: get_folder_by_name
      deprecated: true
      parameters:
      - name: folder_name
        in: path
        required: true
        schema:
          type: string
          title: Folder Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: string
                title: Response Get Folder By Name
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/folders/metadata:
    get:
      tags:
      - Folders
      summary: Retrieve Metadata
      description: 'Get aggregated metadata for all folders in an organization.


        Returns structured metadata including:

        - Total number of folders

        - Total number of files across all folders

        - Total size of all files

        - Per-source breakdown with file details (file_name, file_size per file) if include_detailed_per_source_metadata is True'
      operationId: retrieve_metadata
      parameters:
      - name: include_detailed_per_source_metadata
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Detailed Per Source Metadata
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationSourcesStats'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/folders/:
    get:
      tags:
      - Folders
      summary: List Folders
      description: List all data folders created by a user.
      operationId: list_folders
      parameters:
      - name: before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Folder ID cursor for pagination. Returns folders that come before this folder ID in the specified sort order
          title: Before
        description: Folder ID cursor for pagination. Returns folders that come before this folder ID in the specified sort order
      - name: after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Folder ID cursor for pagination. Returns folders that come after this folder ID in the specified sort order
          title: After
        description: Folder ID cursor for pagination. Returns folders that come after this folder ID in the specified sort order
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Maximum number of folders to return
          default: 50
          title: Limit
        description: Maximum number of folders to return
      - name: order
        in: query
        required: false
        schema:
          enum:
          - asc
          - desc
          type: string
          description: Sort order for folders by creation time. 'asc' for oldest first, 'desc' for newest first
          default: asc
          title: Order
        description: Sort order for folders by creation time. 'asc' for oldest first, 'desc' for newest first
      - name: order_by
        in: query
        required: false
        schema:
          const: created_at
          type: string
          description: Field to sort by
          default: created_at
          title: Order By
        description: Field to sort by
      - name: name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Folder name to filter by
          title: Name
        description: Folder name to filter by
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Folder'
                title: Response List Folders
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Folders
      summary: Create Folder
      description: Create a new data folder.
      operationId: create_folder
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceCreate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/folders/{folder_id}/upload:
    post:
      tags:
      - Folders
      summary: Upload File to Folder
      description: Upload a file to a data folder.
      operationId: upload_file_to_folder
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: string
          minLength: 43
          maxLength: 43
          pattern: ^source-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
          description: The ID of the source in the format 'source-<uuid4>'
          examples:
          - source-123e4567-e89b-42d3-8456-426614174000
          title: Folder Id
        description: The ID of the source in the format 'source-<uuid4>'
      - name: duplicate_handling
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/DuplicateFileHandling'
          description: How to handle duplicate filenames
          default: suffix
        description: How to handle duplicate filenames
      - name: name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional custom name to override the uploaded file's name
          title: Name
        description: Optional custom name to override the uploaded file's name
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_file_to_folder'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileMetadata'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/folders/{folder_id}/agents:
    get:
      tags:
      - Folders
      summary: List Agents for Folder
      description: Get all agent IDs that have the specified folder attached.
      operationId: list_agents_for_folder
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: string
          minLength: 43
          maxLength: 43
          pattern: ^source-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
          description: The ID of the source in the format 'source-<uuid4>'
          examples:
          - source-123e4567-e89b-42d3-8456-426614174000
          title: Folder Id
        description: The ID of the source in the format 'source-<uuid4>'
      - name: before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Agent ID cursor for pagination. Returns agents that come before this agent ID in the specified sort order
          title: Before
        description: Agent ID cursor for pagination. Returns agents that come before this agent ID in the specified sort order
      - name: after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Agent ID cursor for pagination. Returns agents that come after this agent ID in the specified sort order
          title: After
        description: Agent ID cursor for pagination. Returns agents that come after this agent ID in the specified sort order
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Maximum number of agents to return
          default: 50
          title: Limit
        description: Maximum number of agents to return
      - name: order
        in: query
        required: false
        schema:
          enum:
          - asc
          - desc
          type: string
          description: Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest first
          default: desc
          title: Order
        description: Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest first
      - name: order_by
        in: query
        required: false
        schema:
          const: created_at
          type: string
          description: Field to sort by
          default: created_at
          title: Order By
        description: Field to sort by
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                title: Response List Agents For Folder
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/folders/{folder_id}/passages:
    get:
      tags:
      - Folders
      summary: List Folder Passages
      description: List all passages associated with a data folder.
      operationId: list_folder_passages
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: string
          minLength: 43
          maxLength: 43
          pattern: ^source-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
          description: The ID of the source in the format 'source-<uuid4>'
          examples:
          - source-123e4567-e89b-42d3-8456-426614174000
          title: Folder Id
        description: The ID of the source in the format 'source-<uuid4>'
      - name: before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Passage ID cursor for pagination. Returns passages that come before this passage ID in the specified sort order
          title: Before
        description: Passage ID cursor for pagination. Returns passages that come before this passage ID in the specified sort order
      - name: after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Passage ID cursor for pagination. Returns passages that come after this passage ID in the specified sort order
          title: After
        description: Passage ID cursor for pagination. Returns passages that come after this passage ID in the specified sort order
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Maximum number of passages to return
          default: 100
          title: Limit
        description: Maximum number of passages to return
      - name: order
        in: query
        required: false
        schema:
          enum:
          - asc
          - desc
          type: string
          description: Sort order for passages by creation time. 'asc' for oldest first, 'desc' for newest first
          default: desc
          title: Order
        description: Sort order for passages by creation time. 'asc' for oldest first, 'desc' for newest first
      - name: order_by
        in: query
        required: false
        schema:
          const: created_at
          type: string
          description: Field to sort by
          default: created_at
          title: Order By
        description: Field to sort by
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Passage'
                title: Response List Folder Passages
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/folders/{folder_id}/files:
    get:
      tags:
      - Folders
      summary: List Files for Folder
      description: List paginated files associated with a data folder.
      operationId: list_files_for_folder
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: string
          minLength: 43
          maxLength: 43
          pattern: ^source-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
          description: The ID of the source in the format 'source-<uuid4>'
          examples:
          - source-123e4567-e89b-42d3-8456-426614174000
          title: Folder Id
        description: The ID of the source in the format 'source-<uuid4>'
      - name: before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: File ID cursor for pagination. Returns files that come before this file ID in the specified sort order
          title: Before
        description: File ID cursor for pagination. Returns files that come before this file ID in the specified sort order
      - name: after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: File ID cursor for pagination. Returns files that come after this file ID in the specified sort order
          title: After
        description: File ID cursor for pagination. Returns files that come after this file ID in the specified sort order
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Maximum number of files to return
          default: 1000
          title: Limit
        description: Maximum number of files to return
      - name: order
        in: query
        required: false
        schema:
          enum:
          - asc
          - desc
          type: string
          description: Sort order for files by creation time. 'asc' for oldest first, 'desc' for newest first
          default: desc
          title: Order
        description: Sort order for files by creation time. 'asc' for oldest first, 'desc' for newest first
      - name: order_by
        in: query
        required: false
        schema:
          const: created_at
          type: string
          description: Field to sort by
          default: created_at
          title: Order By
        description: Field to sort by
      - name: include_content
        in: query
        required: false
        schema:
          type: boolean
          description: Whether to include full file content
          default: false
          title: Include Content
        description: Whether to include full file content
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FileMetadata'
                title: Response List Files For Folder
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/folders/{folder_id}/files/{file_id}:
    get:
      tags:
      - Folders
      summary: Retrieve File
      description: Retrieve a file from a folder by ID.
      operationId: retrieve_file
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: string
          minLength: 43
          maxLength: 43
          pattern: ^source-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
          description: The ID of the source in the format 'source-<uuid4>'
          examples:
          - source-123e4567-e89b-42d3-8456-426614174000
          title: Folder Id
        description: The ID of the source in the format 'source-<uuid4>'
      - name: file_id
        in: path
        required: true
        schema:
          type: string
          minLength: 41
          maxLength: 41
          pattern: ^file-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
          description: The ID of the file in the format 'file-<uuid4>'
          examples:
          - file-123e4567-e89b-42d3-8456-426614174000
          title: File Id
        description: The ID of the file in the format 'file-<uuid4>'
      - name: include_content
        in: query
        required: false
        schema:
          type: boolean
          description: Whether to include full file content
          default: false
          title: Include Content
        description: Whether to include full file content
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileMetadata'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/folders/{folder_id}/{file_id}:
    delete:
      tags:
      - Folders
      summary: Delete File from Folder
      description: Delete a file from a folder.
      operationId: delete_file_from_folder
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: string
          minLength: 43
          maxLength: 43
          pattern: ^source-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
          description: The ID of the source in the format 'source-<uuid4>'
          examples:
          - source-123e4567-e89b-42d3-8456-426614174000
          title: Folder Id
        description: The ID of the source in the format 'source-<uuid4>'
      - name: file_id
        in: path
        required: true
        schema:
          type: string
          minLength: 41
          maxLength: 41
          pattern: ^file-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
          description: The ID of the file in the format 'file-<uuid4>'
          examples:
          - file-123e4567-e89b-42d3-8456-426614174000
          title: File Id
        description: The ID of the file in the format 'file-<uuid4>'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Body_upload_file_to_folder:
      properties:
        file:
          type: string
          format: binary
          title: File
      type: object
      required:
      - file
      title: Body_upload_file_to_folder
    Folder:
      properties:
        name:
          type: string
          title: Name
          description: The name of the folder.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: The description of the folder.
        instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Instructions
          description: Instructions for how to use the folder.
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Metadata associated with the folder.
        id:
          type: string
          pattern: ^source-[a-fA-F0-9]{8}
          title: Id
          description: The human-friendly ID of the Source
          examples:
          - source-123e4567-e89b-12d3-a456-426614174000
        embedding_config:
          $ref: '#/components/schemas/EmbeddingConfig'
          description: The embedding configuration used by the folder.
        created_by_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Created By Id
          description: The id of the user that made this Tool.
        last_updated_by_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Updated By Id
          description: The id of the user that made this Tool.
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
          description: The timestamp when the folder was created.
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: The timestamp when the folder was last updated.
      additionalProperties: false
      type: object
      required:
      - name
      - embedding_config
      title: Folder
      description: Representation of a folder, which is a collection of files and passages.
    SourceCreate:
      properties:
        name:
          type: string
          title: Name
          description: The name of the source.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: The description of the source.
        instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Instructions
          description: Instructions for how to use the source.
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Metadata associated with the source.
        embedding:
          anyOf:
          - type: string
          - type: 'null'
          title: Embedding
          description: The handle for the embedding config used by the source.
        embedding_chunk_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: Embedding Chunk Size
          description: The chunk size of the embedding.
        embedding_config:
          anyOf:
          - $ref: '#/components/schemas/EmbeddingConfig'
          - type: 'null'
          description: (Legacy) The embedding configuration used by the source.
      additionalProperties: false
      type: object
      required:
      - name
      title: SourceCreate
      description: Schema for creating a new Source.
    DuplicateFileHandling:
      type: string
      enum:
      - skip
      - error
      - suffix
      - replace
      title: DuplicateFileHandling
      description: How to handle duplicate filenames when uploading files
    FileMetadata:
      properties:
        source_id:
          type: string
          title: Source Id
          description: 'Deprecated: Use `folder_id` field instead. The unique identifier of the source associated with the document.'
          deprecated: true
        file_name:
          anyOf:
          - type: string
          - type: 'null'
          title: File Name
          description: The name of the file.
        original_file_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Original File Name
          description: The original name of the file as uploaded.
        file_path:
          anyOf:
          - type: string
          - type: 'null'
          title: File Path
          description: The path to the file.
        file_type:
          anyOf:
          - type: string
          - type: 'null'
          title: File Type
          description: The type of the file (MIME type).
        file_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: File Size
          description: The size of the file in bytes.
        file_creation_date:
          anyOf:
          - type: string
          - type: 'null'
          title: File Creation Date
          description: The creation date of the file.
        file_last_modified_date:
          anyOf:
          - type: string
          - type: 'null'
          title: File Last Modified Date
          description: The last modified date of the file.
        processing_status:
          $ref: '#/components/schemas/FileProcessingStatus'
          description: The current processing status of the file (e.g. pending, parsing, embedding, completed, error).
          default: pending
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
          description: Optional error message if the file failed processing.
        total_chunks:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Chunks
          description: Total number of chunks for the file.
        chunks_embedded:
          anyOf:
          - type: integer
          - type: 'null'
          title: Chunks Embedded
          description: Number of chunks that have been embedded.
        content:
          anyOf:
          - type: string
          - type: 'null'
          title: Content
          description: Optional full-text content of the file; only populated on demand due to its size.
        id:
          type: string
          pattern: ^file-[a-fA-F0-9]{8}
          title: Id
          description: The human-friendly ID of the File
          examples:
          - file-123e4567-e89b-12d3-a456-426614174000
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
          description: The creation date of the file.
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: The update date of the file.
      additionalProperties: false
      type: object
      required:
      - source_id
      title: FileMetadata
      description: Representation of a single FileMetadata
    SourceUpdate:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: The name of the source.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: The description of the source.
        instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Instructions
          description: Instructions for how to use the source.
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Metadata associated with the source.
        embedding_config:
          anyOf:
          - $ref: '#/components/schemas/EmbeddingConfig'
          - type: 'null'
          description: The embedding configuration used by the source.
      additionalProperties: false
      type: object
      title: SourceUpdate
      description: Schema for updating an existing Source.
    FileProcessingStatus:
      type: string
      enum:
      - pending
      - parsing
      - embedding
      - completed
      - error
      title: FileProcessingStatus
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    EmbeddingConfig:
      properties:
        embedding_endpoint_type:
          type: string
          enum:
          - openai
          - anthropic
          - bedrock
          - google_ai
          - google_vertex
          - azure
          - groq
          - ollama
          - webui
          - webui-legacy
          - lmstudio
          - lmstudio-legacy
          - llamacpp
          - koboldcpp
          - vllm
          - hugging-face
          - mistral
          - together
          - pinecone
          title: Embedding Endpoint Type
          description: The endpoint type for the model.
        embedding_endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Embedding Endpoint
          description: The endpoint for the model (`None` if local).
        embedding_model:
          type: string
          title: Embedding Model
          description: The model for the embedding.
        embedding_dim:
          type: integer
          title: Embedding Dim
          description: The dimension of the embedding.
        embedding_chunk_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: Embedding Chunk Size
          description: The chunk size of the embedding.
          default: 300
        handle:
          anyOf:
          - type: string
          - type: 'null'
          title: Handle
          description: The handle for this config, in the format provider/model-name.
        batch_size:
          type: integer
          title: Batch Size
          description: The maximum batch size for processing embeddings.
          default: 32
        azure_endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Azure Endpoint
          description: The Azure endpoint for the model.
        azure_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Azure Version
          description: The Azure version for the model.
        azure_deployment:
          anyOf:
          - type: string
          - type: 'null'
          title: Azure Deployment
          description: The Azure deployment for the model.
      type: object
      required:
      - embedding_endpoint_type
      - embedding_model
      - embedding_dim
      title: EmbeddingConfig
      description: Configuration for embedding model connection and processing parameters.
    FileStats:
      properties:
        file_id:
          type: string
          title: File Id
          description: Unique identifier of the file
        file_name:
          type: string
          title: File Name
          description: Name of the file
        file_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: File Size
          description: Size of the file in bytes
      additionalProperties: false
      type: object
      required:
      - file_id
      - file_name
      title: FileStats
      description: File statistics for metadata endpoint
    Passage:
      properties:
        created_by_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Created By Id
          description: The id of the user that made this object.
        last_updated_by_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Updated By Id
          description: The id of the user that made this object.
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
          description: The creation date of the passage.
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: The timestamp when the object was last updated.
        is_deleted:
          type: boolean
          title: Is Deleted
          description: Whether this passage is deleted or not.
          default: false
        archive_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Archive Id
          description: The unique identifier of the archive containing this passage.
        source_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Id
          description: 'Deprecated: Use `folder_id` field instead. The data source of the passage.'
          deprecated: true
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
          description: The unique identifier of the file associated with the passage.
        file_name:
          anyOf:
          - type: string
          - type: 'null'
          title: File Name
          description: The name of the file (only for source passages).
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: The metadata of the passage.
          default: {}
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
          description: Tags associated with this passage.
        id:
          type: string
          pattern: ^passage-[a-fA-F0-9]{8}
          title: Id
          description: The human-friendly ID of the Passage
          examples:
          - passage-123e4567-e89b-12d3-a456-426614174000
        text:
          type: string
          title: Text
          description: The text of the passage.
        embedding:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Embedding
          description: The embedding of the passage.
        embedding_config:
          anyOf:
          - $ref: '#/components/schemas/EmbeddingConfig'
          - type: 'null'
          description: The embedding configuration used by the passage.
      additionalProperties: false
      type: object
      required:
      - text
      - embedding
      - embedding_config
      title: Passage
      description: Representation of a passage, which is stored in archival memory.
    SourceStats:
      properties:
        source_id:
          type: string
          title: Source Id
          description: 'Deprecated: Use `folder_id` field instead. Unique identifier of the source'
          deprecated: true
        source_name:
          type: string
          title: Source Name
          description: 'Deprecated: Use `folder_name` field instead. Name of the source'
          deprecated: true
        file_count:
          type: integer
          title: File Count
          description: Number of files in the source
          default: 0
        total_size:
          type: integer
          title: Total Size
          description: Total size of all files in bytes
          default: 0
        files:
          items:
            $ref: '#/components/schemas/FileStats'
          type: array
          title: Files
          description: List of file statistics
      additionalProperties: false
      type: object
      required:
      - source_id
      - source_name
      title: SourceStats
      description: Aggregated metadata for a source
    OrganizationSourcesStats:
      properties:
        total_sources:
          type: integer
          title: Total Sources
          description: Total number of sources
          default: 0
        total_files:
          type: integer
          title: Total Files
          description: Total number of files across all sources
          default: 0
        total_size:
          type: integer
          title: Total Size
          description: Total size of all files in bytes
          default: 0
        sources:
          items:
            $ref: '#/components/schemas/SourceStats'
          type: array
          title: Sources
          description: List of source metadata
      additionalProperties: false
      type: object
      title: OrganizationSourcesStats
      description: Complete metadata response for organization sources
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer