Agenta Folders API

openapi: 3.2.0
info:
  title: Agenta Folders API
  description: Agenta API
  contact:
    name: Agenta
    url: https://agenta.ai/
    email: team@agenta.ai
  version: 0.1.0
servers:
- url: /api
- url: https://eu.cloud.agenta.ai/api
security:
- APIKeyHeader: []
tags:
- name: Folders
  description: Organize applications and other resources into folder hierarchies.
paths:
  /folders/:
    post:
      tags:
      - Folders
      summary: Create Folder
      description: 'Create a folder.


        The folder name must match `[\w -]+` (letters, digits, underscore,

        space, hyphen); other characters return `400`. The resulting path

        (the slug joined to the parent''s path with a dot) must be unique

        within the project, otherwise the call returns `409`. Passing a

        `parent_id` that does not exist returns `404`. Paths are capped at

        10 levels of nesting and slugs at 64 characters.'
      operationId: create_folder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FolderCreateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /folders/{folder_id}:
    get:
      tags:
      - Folders
      summary: Fetch Folder
      description: 'Fetch one folder by id.


        Returns a single `folder` envelope. If the folder does not exist in

        the caller''s project, `count` is `0` and `folder` is omitted.'
      operationId: fetch_folder
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Folder Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Folders
      summary: Edit Folder
      description: 'Rename or move a folder.


        Use this endpoint to change a folder''s `slug`, `name`, or

        `parent_id`. The `id` in the request body must match the path

        parameter or the call returns `400`. Name and path-uniqueness rules

        from create apply: invalid names return `400`, a path collision

        returns `409`, and a missing `parent_id` returns `404`.'
      operationId: edit_folder
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Folder Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FolderEditRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Folders
      summary: Delete Folder
      description: 'Delete a folder and every descendant.


        Removes the folder identified by `folder_id` together with every

        folder beneath it, in a single transaction. Deletion is

        unconditional; there is no archive or unarchive step. Resources

        that were assigned to any of the removed folders continue to

        exist and are no longer reachable through the deleted folder.'
      operationId: delete_folder
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Folder Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderIdResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /folders/query:
    post:
      tags:
      - Folders
      summary: Query Folders
      description: 'Filter folders inside the caller''s project.


        Follows the general response envelope described in the

        Query Pattern guide, but

        does not accept `windowing` or `include_archived` — folders are

        hard-deleted and the response always returns the full filtered

        set. Filters include `id`/`ids`, `slug`/`slugs`, `kind`/`kinds`,

        `parent_id`/`parent_ids` (use `parent_id: null` for root folders),

        `path`/`paths`, and `prefix`/`prefixes` for subtree lookup.'
      operationId: query_folders
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FolderQueryRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoldersResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    FolderEdit:
      properties:
        flags:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/LabelJson-Input'
            type: object
          - type: 'null'
          title: Flags
        tags:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/LabelJson-Input'
            type: object
          - type: 'null'
          title: Tags
        meta:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/FullJson-Input'
            type: object
          - type: 'null'
          title: Meta
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        slug:
          anyOf:
          - type: string
          - type: 'null'
          title: Slug
        id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Id
        kind:
          anyOf:
          - $ref: '#/components/schemas/FolderKind'
          - type: 'null'
          description: Resource family. Must match the current folder's kind; defaults to `applications`.
        parent_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Parent Id
          description: New parent folder id. Include the key with a `null` value to move the folder to the root; omit the key to keep the existing parent.
      type: object
      title: FolderEdit
    FolderCreate:
      properties:
        flags:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/LabelJson-Input'
            type: object
          - type: 'null'
          title: Flags
        tags:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/LabelJson-Input'
            type: object
          - type: 'null'
          title: Tags
        meta:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/FullJson-Input'
            type: object
          - type: 'null'
          title: Meta
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        slug:
          anyOf:
          - type: string
          - type: 'null'
          title: Slug
        kind:
          anyOf:
          - $ref: '#/components/schemas/FolderKind'
          - type: 'null'
          description: Resource family the folder organizes. Defaults to `applications` when omitted.
        parent_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Parent Id
          description: Id of the parent folder. Omit or set to `null` to create a root folder.
      type: object
      title: FolderCreate
    LabelJson-Input:
      anyOf:
      - type: boolean
      - type: string
      - additionalProperties:
          $ref: '#/components/schemas/LabelJson-Input'
        type: object
    FolderQuery:
      properties:
        flags:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/LabelJson-Input'
            type: object
          - type: 'null'
          title: Flags
        tags:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/LabelJson-Input'
            type: object
          - type: 'null'
          title: Tags
        meta:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/FullJson-Input'
            type: object
          - type: 'null'
          title: Meta
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Id
          description: Match a single folder id.
        ids:
          anyOf:
          - items:
              type: string
              format: uuid
            type: array
          - type: 'null'
          title: Ids
          description: Match any of the given folder ids.
        slug:
          anyOf:
          - type: string
          - type: 'null'
          title: Slug
          description: Match a folder by slug, regardless of its position in the tree.
        slugs:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Slugs
          description: Match folders whose slug is in the given list.
        kind:
          anyOf:
          - $ref: '#/components/schemas/FolderKind'
          - type: 'null'
          description: Match folders of a single resource family.
        kinds:
          anyOf:
          - type: boolean
          - items:
              $ref: '#/components/schemas/FolderKind'
            type: array
          - type: 'null'
          title: Kinds
          description: Filter by presence of a kind. `false` returns folders with no kind, `true` returns folders where `kind` is set, and an array restricts to the given kinds.
        parent_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Parent Id
          description: Match folders whose parent is this id. Send `null` to return only root folders.
        parent_ids:
          anyOf:
          - items:
              type: string
              format: uuid
            type: array
          - type: 'null'
          title: Parent Ids
          description: Match folders whose parent is any of the given ids.
        path:
          anyOf:
          - type: string
          - type: 'null'
          title: Path
          description: Exact match on the materialized `path` (e.g. `support.prod`).
        paths:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Paths
          description: Exact match on any of the given paths.
        prefix:
          anyOf:
          - type: string
          - type: 'null'
          title: Prefix
          description: 'Subtree lookup: returns the folder at this path and every descendant.'
        prefixes:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Prefixes
          description: Subtree lookup across multiple prefixes, OR-ed together.
      type: object
      title: FolderQuery
    FolderResponse:
      properties:
        count:
          type: integer
          title: Count
          description: Number of folders returned (`0` or `1`).
          default: 0
        folder:
          anyOf:
          - $ref: '#/components/schemas/Folder'
          - type: 'null'
          description: The folder, when found. Omitted when `count` is `0`.
      type: object
      title: FolderResponse
    FullJson-Input:
      anyOf:
      - type: string
      - type: integer
      - type: number
      - type: boolean
      - additionalProperties:
          $ref: '#/components/schemas/FullJson-Input'
        type: object
      - items:
          $ref: '#/components/schemas/FullJson-Input'
        type: array
      - type: 'null'
    FolderIdResponse:
      properties:
        count:
          type: integer
          title: Count
          description: '`1` if a folder was deleted, `0` if no folder matched.'
          default: 0
        id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Id
          description: Id of the deleted folder. Omitted when nothing was deleted.
      type: object
      title: FolderIdResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LabelJson-Output:
      anyOf:
      - type: boolean
      - type: string
      - additionalProperties:
          $ref: '#/components/schemas/LabelJson-Output'
        type: object
    FolderKind:
      type: string
      enum:
      - applications
      title: FolderKind
    Folder:
      properties:
        flags:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/LabelJson-Output'
            type: object
          - type: 'null'
          title: Flags
        tags:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/LabelJson-Output'
            type: object
          - type: 'null'
          title: Tags
        meta:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/FullJson-Output'
            type: object
          - type: 'null'
          title: Meta
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
        deleted_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Deleted At
        created_by_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Created By Id
        updated_by_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Updated By Id
        deleted_by_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Deleted By Id
        slug:
          anyOf:
          - type: string
          - type: 'null'
          title: Slug
        id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Id
        kind:
          anyOf:
          - $ref: '#/components/schemas/FolderKind'
          - type: 'null'
          description: Resource family this folder organizes. Only `applications` is defined today, and it also covers workflows, evaluators, and testsets (they share the artifact table).
        path:
          anyOf:
          - type: string
          - type: 'null'
          title: Path
          description: Dot-separated materialized path built from the folder's slug and its ancestors' slugs. Read-only; derived by the server.
        parent_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Parent Id
          description: Id of the parent folder, or `null` for a root folder.
      type: object
      title: Folder
    FullJson-Output:
      anyOf:
      - type: string
      - type: integer
      - type: number
      - type: boolean
      - additionalProperties:
          $ref: '#/components/schemas/FullJson-Output'
        type: object
      - items:
          $ref: '#/components/schemas/FullJson-Output'
        type: array
      - type: 'null'
    FolderCreateRequest:
      properties:
        folder:
          $ref: '#/components/schemas/FolderCreate'
          description: Folder to create. `slug` is required; `parent_id` nests the new folder under an existing one.
      type: object
      required:
      - folder
      title: FolderCreateRequest
    FolderQueryRequest:
      properties:
        folder:
          $ref: '#/components/schemas/FolderQuery'
          description: Filter object. Any combination of `id`/`ids`, `slug`/`slugs`, `kind`/`kinds`, `parent_id`/`parent_ids`, `path`/`paths`, and `prefix`/`prefixes` narrows the result.
      type: object
      required:
      - folder
      title: FolderQueryRequest
    FoldersResponse:
      properties:
        count:
          type: integer
          title: Count
          description: Number of folders in `folders`.
          default: 0
        folders:
          items:
            $ref: '#/components/schemas/Folder'
          type: array
          title: Folders
          description: Matching folders for the query. Ordering is not guaranteed.
      type: object
      title: FoldersResponse
    FolderEditRequest:
      properties:
        folder:
          $ref: '#/components/schemas/FolderEdit'
          description: Folder edit payload. `id` must match the path parameter. Only fields present in the payload are changed.
      type: object
      required:
      - folder
      title: FolderEditRequest
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      name: Authorization
      in: header