> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Folder

> Update a [knowledge base](/line/knowledge-base) folder's name, parent, documents, or agents



## OpenAPI

````yaml /latest.yml PATCH /agents/folders/{id}
openapi: 3.0.1
info:
  title: Cartesia API
  version: 0.0.1
servers:
  - url: https://api.cartesia.ai
    description: Production
security: []
paths:
  /agents/folders/{id}:
    patch:
      tags:
        - Folders
      summary: Update Folder
      description: >-
        Update a [knowledge base](/line/knowledge-base) folder's name, parent,
        documents, or agents
      operationId: folders_update
      parameters:
        - $ref: '#/components/parameters/CartesiaVersionHeader'
        - name: id
          in: path
          description: The ID of the folder.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFolderBody'
      responses:
        '200':
          description: Folder updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderResponse'
        '400':
          description: >-
            Bad request. Possible reasons: a folder with the same name already
            exists in the target location (`error_code:
            kb_folder_duplicate_name`); nesting would exceed the three-level
            limit (`error_code: kb_folder_max_depth`); attempting to move a
            folder under itself or one of its descendants (`error_code:
            kb_folder_circular_reference`); one or more `documents[].id` values
            do not exist or are not owned by you (`error_code:
            kb_document_not_owned`); or one or more `agents[].id` values do not
            exist or are not owned by you (`error_code: kb_agent_not_found`).
        '404':
          description: >-
            Folder not found (`error_code: kb_folder_not_found`) or parent
            folder not found (`error_code: kb_folder_parent_not_found`).
      security:
        - APIKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: Attach to agents
          source: |
            curl -X PATCH "https://api.cartesia.ai/agents/folders/folder_abc" \
              -H "X-API-Key: your-api-key" \
              -H "Cartesia-Version: 2025-04-16" \
              -H "Content-Type: application/json" \
              -d '{"agents": [{"id": "agent_abc"}, {"id": "agent_def"}]}'
components:
  parameters:
    CartesiaVersionHeader:
      name: Cartesia-Version
      in: header
      description: API version header.
      required: true
      schema:
        type: string
        format: date
        example: '2026-03-01'
        enum:
          - '2026-03-01'
  schemas:
    UpdateFolderBody:
      title: UpdateFolderBody
      type: object
      description: >-
        Fields to update on a folder. All fields are optional. Passing
        `documents` or `agents` replaces the full set — send an empty array to
        detach all documents or agents.
      properties:
        name:
          type: string
          minLength: 1
          description: A new name for the folder. Must be unique among siblings.
        parent_id:
          type: string
          nullable: true
          description: >-
            Move the folder under a new parent, or `null` to move it to the top
            level. Cannot create a circular reference.
        documents:
          type: array
          description: >-
            The complete set of documents that should be in this folder.
            Documents not in the list are deleted. Pass an empty array to delete
            all documents in the folder.
          items:
            type: object
            properties:
              id:
                type: string
            required:
              - id
        agents:
          type: array
          description: >-
            The complete set of agents that have access to this folder. Agents
            not in the list have their access revoked. Pass an empty array to
            revoke access for all agents.
          items:
            type: object
            properties:
              id:
                type: string
            required:
              - id
    FolderResponse:
      title: FolderResponse
      type: object
      properties:
        id:
          type: string
          description: The ID of the folder.
        parent_id:
          type: string
          nullable: true
          description: The ID of the parent folder, or `null` for top-level folders.
        name:
          type: string
          description: The folder's name.
        created_at:
          type: string
          format: date-time
          description: When the folder was created.
        agents:
          type: array
          items:
            $ref: '#/components/schemas/FolderAgentSummary'
          description: Agents that have access to this folder.
        documents:
          type: array
          items:
            $ref: '#/components/schemas/FolderDocumentSummary'
          description: Documents inside this folder.
      required:
        - id
        - parent_id
        - name
        - created_at
        - agents
        - documents
    FolderAgentSummary:
      title: FolderAgentSummary
      type: object
      description: An agent that has access to this folder.
      properties:
        id:
          type: string
          description: The ID of the agent.
        name:
          type: string
          description: The name of the agent.
      required:
        - id
        - name
    FolderDocumentSummary:
      title: FolderDocumentSummary
      type: object
      description: >-
        A document summary as returned inside a folder. Does not include the
        document `content`.
      properties:
        id:
          type: string
          description: The ID of the document.
        name:
          type: string
          nullable: true
          description: The document's display name, or `null` if unnamed.
        created_at:
          type: string
          format: date-time
          description: When the document was uploaded.
        metadata:
          type: object
          additionalProperties:
            type: string
          description: User-defined string-keyed metadata.
      required:
        - id
        - name
        - created_at
        - metadata
  securitySchemes:
    APIKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Cartesia API key (`sk_car_...`). Get one at
        [play.cartesia.ai/keys](https://play.cartesia.ai/keys).

````