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

# Delete a catalog (detach or cascade)

> `mode=detach` (default) clears `catalog` on every member so it appears under Uncataloged, through a versioned write per member. `mode=cascade` deletes every member tap and pipeline, including each pipeline's destination data, and requires `confirm` equal to `name`. Both remove every placeholder of the catalog (matched by its `catalog` field, or by name suffix when that field is empty). A member already moved out of `name` by a concurrent change is listed under `failed`. Not transactional: failed members are listed under `failed` (207). Catalog operations (rename, detach, cascade) are serialized server-side, so concurrent requests run one after another and the later one sees the earlier one's result. Requires `pipeline:delete`; each member is also checked against the key's owner and catalog scopes, and the placeholder is left untouched if any member is refused. In cascade mode, if any tap delete fails, the catalog's pipelines are not deleted and are reported under `failed`.




## OpenAPI

````yaml /openapi.yaml delete /api/v1/catalog/{name}
openapi: 3.0.3
info:
  title: Datris API
  description: >
    REST API for the Datris AI Data Platform. Ingest, validate, transform,
    store, and retrieve data.


    For AI agent integration, use the [MCP
    Server](https://docs.datris.ai/mcp-server) instead.
  version: 1.28.0
  contact:
    name: Datris
    url: https://datris.ai
  license:
    name: Apache 2.0
servers:
  - url: http://localhost:8080
    description: Local development
security:
  - ApiKeyAuth: []
paths:
  /api/v1/catalog/{name}:
    delete:
      tags:
        - Pipelines
      summary: Delete a catalog (detach or cascade)
      description: >
        `mode=detach` (default) clears `catalog` on every member so it appears
        under Uncataloged, through a versioned write per member. `mode=cascade`
        deletes every member tap and pipeline, including each pipeline's
        destination data, and requires `confirm` equal to `name`. Both remove
        every placeholder of the catalog (matched by its `catalog` field, or by
        name suffix when that field is empty). A member already moved out of
        `name` by a concurrent change is listed under `failed`. Not
        transactional: failed members are listed under `failed` (207). Catalog
        operations (rename, detach, cascade) are serialized server-side, so
        concurrent requests run one after another and the later one sees the
        earlier one's result. Requires `pipeline:delete`; each member is also
        checked against the key's owner and catalog scopes, and the placeholder
        is left untouched if any member is refused. In cascade mode, if any tap
        delete fails, the catalog's pipelines are not deleted and are reported
        under `failed`.
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: Catalog name. `Uncataloged` (any case) is refused.
        - name: mode
          in: query
          required: false
          schema:
            type: string
            enum:
              - detach
              - cascade
            default: detach
        - name: confirm
          in: query
          required: false
          schema:
            type: string
          description: Required for `mode=cascade`; must equal the catalog name.
      responses:
        '200':
          description: Every member detached or deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogDeleteResult'
        '207':
          description: Some members failed; see `failed`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogDeleteResult'
        '400':
          description: >-
            Reserved or blank catalog name, unknown mode, or cascade without a
            matching `confirm`
        '403':
          description: >-
            The catalog holds only its placeholder and the key's scope does not
            cover it. Body: `{"error": "capability denied", "errorKind":
            "capability_denied", "message": ...}`
        '404':
          description: No tap, pipeline or placeholder carries this catalog
        '500':
          description: Error
components:
  schemas:
    CatalogDeleteResult:
      type: object
      description: >-
        Carries `detached` (mode=detach) or `deleted` (mode=cascade), plus
        `failed`.
      properties:
        detached:
          type: array
          items:
            type: string
        deleted:
          type: array
          items:
            type: string
        failed:
          type: array
          items:
            $ref: '#/components/schemas/CatalogFailure'
    CatalogFailure:
      type: object
      properties:
        name:
          type: string
          description: Member (or `__catalog__` placeholder) name
        error:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Optional API key for authentication (enabled via application.yaml)

````