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

# Delete Collection

> Permanently remove one collection and all of its data from a database.

export const Field = ({name, type, required, recommended}) => {
  const label = required ? 'required' : recommended ? 'recommended' : null;
  const typeLabel = typeof type === 'string' ? type : null;
  const ariaParts = [name, typeLabel && `${typeLabel}`, label].filter(Boolean);
  return <span aria-label={ariaParts.join(', ')} className={label ? 'field-wrap has-field-tip' : 'field-wrap'} style={{
    position: 'relative',
    cursor: label ? 'default' : undefined
  }} tabIndex={label ? 0 : undefined}>
      <span className="field-name-row">
        <code>{name}</code>
        {required && <span className="field-req"> *</span>}
        {recommended && <span className="field-rec"> ●</span>}
      </span>
      {type && <span className="field-type">{type}</span>}
      {label && <span className="field-tip" role="tooltip">
          {label}
        </span>}
    </span>;
};

This action is irreversible. Deleting a collection removes all knowledge, memories, embeddings, and graph data stored under that collection. The parent database and its other collections are not affected. There is no soft-delete and no recovery window.

<RequestExample>
  ```python Python SDK theme={"dark"}
  response = client.databases.delete_collection(
      database="my_first_database",
      collection="engineering",
  )
  ```

  ```typescript TypeScript SDK theme={"dark"}
  const response = await client.databases.deleteCollection({
    database: "my_first_database",
    collection: "engineering",
  });
  ```

  ```bash cURL theme={"dark"}
  curl -X DELETE 'https://api.hydradb.com/databases/collections?database=my_first_database&collection=engineering' \
    -H "Authorization: Bearer <your_api_key>" \
    -H "API-Version: 2"
  ```
</RequestExample>

## Query parameters

| Name                                               | Description                                                                                                                                                                                                                          |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <Field name="database" type="string" required />   | Identifier of the database that owns the collection. Formerly `tenant_id`; the API still accepts the `tenant_id` alias in its place (deprecated), though the SDKs and OpenAPI spec model only the canonical name.                    |
| <Field name="collection" type="string" required /> | Identifier of the collection to delete. Formerly `sub_tenant_id`; the API still accepts the `sub_tenant_id` alias in its place (deprecated). Unlike the read endpoints this has no default: a delete has no safe default collection. |

<ResponseExample>
  ```json Success theme={"dark"}
  {
    "success": true,
    "data": {
      "database": "my_first_database",
      "collection": "engineering",
      "status": "deletion_scheduled",
      "message": "Collection deregistered. Background cleanup is in progress."
    },
    "error": null,
    "meta": {
      "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
      "latency_ms": 12.3
    }
  }
  ```

  ```json Failure theme={"dark"}
  {
    "success": false,
    "data": null,
    "error": {
      "code": "DATABASE_NOT_FOUND",
      "message": "Database not found"
    },
    "meta": {
      "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
      "latency_ms": 4.8
    }
  }
  ```
</ResponseExample>

## While cleanup is running

Deletion is asynchronous: a `200` means cleanup was accepted, not that it finished. From the moment the API accepts the call, the collection is fenced:

* Every ingest, query, and read addressed to it returns `404`, so nothing can write into a collection that is being purged. Sibling collections in the same database, and the database itself, are unaffected and keep serving normally.
* Ingestion already in flight for this collection is cancelled before any store is purged, so a job that started before the delete cannot repopulate it afterwards.
* The collection disappears from [List Collections](/api-reference/v2/endpoint/list-sub-tenants) once its records are dropped, which happens before the slower vector, graph, and object-store cleanup completes.

There is no collection-level completion endpoint, and a repeated `DELETE` returning `200` is not a completion signal either.

You do not need one to reuse the name safely. Ingestion creates a missing collection implicitly, so a successful write is not evidence that cleanup finished; what makes it safe is the fence. While cleanup is running the API rejects the write with `404`, and the fence is lifted only once every store has been purged. So write when you are ready: a `404` means cleanup is still going and you should try again later, and a success means it was already done. Do not treat a successful write as a *probe*, because it also creates the collection.

## Behavior notes

<Warning>
  **Irreversible action.** Ingested documents, memories, embeddings, graph nodes, and storage objects for this collection are permanently removed. Other collections in the same database are not touched. There is no recovery window.
</Warning>

* **Async cleanup:** The endpoint returns immediately after accepting the request. Cleanup of vector stores, graphs, and storage objects runs in the background.
* **Repeat calls are the retry path:** Deleting the same collection again is idempotent. A duplicate call while cleanup is still running joins the delete in progress rather than starting a second one. If a cleanup fails part-way, the collection stays fenced and re-issuing the same `DELETE` re-runs it.
* **Stopping work first is still kinder:** The API cancels this collection's in-flight ingestion for you, but a job cancelled mid-run is reported as failed to whatever started it. Draining your own writers first avoids that noise.
* **Dashboard:** Owners can also expand a database on the Databases page and delete a collection from the inline list.

## Errors

Common codes: `400 VALIDATION_ERROR`, `404 DATABASE_NOT_FOUND`, `401 UNAUTHORIZED`. See [Error Responses](/api-reference/v2/error-responses) for the full list.

<div className="api-before-related-resources" />

<Tip>
  **Related Resources**

  * **Before this:** [List Collections](/api-reference/v2/endpoint/list-sub-tenants) - find the collection ID
  * **Alternative:** [Delete Context](/api-reference/v2/endpoint/delete-source) - remove specific knowledge or memories without deleting the collection
  * **Larger scope:** [Delete Database](/api-reference/v2/endpoint/delete-tenant) - remove the entire database
  * **Read more:** [Concepts → Multi tenancy](/essentials/v2/multi-tenant)
</Tip>


## OpenAPI

````yaml api-reference/v2/openapi.json DELETE /databases/collections
openapi: 3.1.0
info:
  contact:
    email: support@hydradb.com
    name: HydraDB Support
  description: >-
    HydraDB Application API — knowledge ingestion, search, and memory
    management.
  license:
    name: Proprietary
  title: HydraDB Application API
  version: 0.1.0
servers:
  - description: Production server
    url: https://api.hydradb.com
security: []
externalDocs:
  description: ''
  url: ''
paths:
  /databases/collections:
    delete:
      tags:
        - database-management
      summary: Delete a collection
      description: >-
        Permanently remove one collection and all of its data from a database.
        The database itself is left intact and its other collections are
        untouched. `database` and `collection` are both required. The API still
        accepts the deprecated `tenant_id` and `sub_tenant_id` aliases in their
        place, but generated clients should send the canonical names.
      parameters:
        - description: >-
            Database identifier. The API also accepts the deprecated `tenant_id`
            alias in its place; this operation models only the canonical name,
            as every other operation in this spec does.
          in: query
          name: database
          required: true
          schema:
            example: acme_corp
            type: string
        - description: >-
            Collection identifier. Unlike the read endpoints this does not
            default to the database's own collection, because a delete has no
            safe default. The API also accepts the deprecated `sub_tenant_id`
            alias in its place; this operation models only the canonical name.
          in: query
          name: collection
          required: true
          schema:
            example: engineering
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/handler.Envelope-tenants_SubTenantDeleteResponse
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
        - BearerAuth: []
components:
  schemas:
    handler.Envelope-tenants_SubTenantDeleteResponse:
      properties:
        data:
          $ref: '#/components/schemas/tenants.SubTenantDeleteResponse'
          example:
            collection: engineering
            database: acme_corp
            message: Collection deregistered. Background cleanup is in progress.
            status: deletion_scheduled
        error:
          $ref: '#/components/schemas/handler.apiError'
          description: Error message, empty string on success.
          example:
            code: DATABASE_NOT_FOUND
            message: Database not found
        meta:
          $ref: '#/components/schemas/handler.responseMeta'
          example:
            latency_ms: 12.3
            request_id: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d
        success:
          description: Whether the request succeeded.
          example: true
          type: boolean
      type: object
    handler.ErrorResponse:
      properties:
        data: {}
        detail:
          $ref: '#/components/schemas/handler.ErrorDetail'
          description: Structured error detail with code, message, and deprecation hints.
          example:
            deprecated: true
            deprecated_field: tenant_id
            error_code: VALIDATION_ERROR
            message: Request validation failed
            preferred_field: database
        error:
          $ref: '#/components/schemas/handler.apiError'
          description: Error message, empty string on success.
          example:
            code: DATABASE_NOT_FOUND
            message: Database not found
        meta:
          $ref: '#/components/schemas/handler.ErrorMeta'
          example:
            latency_ms: 12.3
            request_id: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d
        success:
          description: Whether the request succeeded.
          example: true
          type: boolean
      type: object
    tenants.SubTenantDeleteResponse:
      properties:
        collection:
          description: Collection that was deleted. Formerly `sub_tenant_id`.
          example: engineering
          type: string
        database:
          description: Owning database. Formerly `tenant_id`.
          example: acme_corp
          type: string
        message:
          description: Human-readable result message.
          example: Collection deregistered. Background cleanup is in progress.
          type: string
        status:
          description: Current lifecycle or processing state.
          example: deletion_scheduled
          type: string
        sub_tenant_id:
          deprecated: true
          example: engineering
          type: string
          x-deprecated: 'true'
        tenant_id:
          deprecated: true
          example: acme_corp
          type: string
          x-deprecated: 'true'
      type: object
    handler.apiError:
      properties:
        code:
          description: Machine-readable error code (e.g. `DATABASE_NOT_FOUND`).
          example: DATABASE_NOT_FOUND
          type: string
        message:
          description: Human-readable description of the error.
          example: Database not found
          type: string
      type: object
    handler.responseMeta:
      properties:
        api_version:
          description: >-
            APIVersion echoes the version of the API that served the request
            (PRO-1209),

            sourced from reqmeta.APIVersion — the same value carried by OpenAPI

            info.version and /health — so a client always knows which API
            version

            produced a response. Always present (no omitempty).
          type: string
        collection:
          description: >-
            Collection scope. Defaults to the default collection when omitted.
            Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still
            accepted (deprecated).
          example: team_docs
          type: string
        database:
          description: >-
            Owning database. Formerly `tenant_id`; the `tenant_id` alias is
            still accepted (deprecated).
          example: acme_corp
          type: string
        deprecation:
          description: >-
            Deprecation lists any migration nudges that apply to this request —
            the

            caller used a legacy /tenants route, a legacy
            tenant_id/sub_tenant_id field,

            or the deprecated sub_tenant_ids selector. It is a non-breaking
            signal (the

            status code is unchanged); omitempty keeps it absent for
            fully-migrated

            requests. A list so independent deprecations coexist without
            clobbering.
          items:
            $ref: '#/components/schemas/handler.deprecationNotice'
          type: array
          uniqueItems: false
        latency_ms:
          description: Server-side processing time in milliseconds.
          example: 12.3
          type: number
        request_id:
          description: Unique identifier for this request, useful for support and tracing.
          example: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d
          type: string
        source_type:
          description: Type of the parent source (e.g. `file`, `slack`, `notion`).
          example: file
          type: string
        sub_tenant_id:
          deprecated: true
          example: sub_tenant_4567
          type: string
          x-deprecated: 'true'
        tenant_id:
          deprecated: true
          example: tenant_1234
          type: string
          x-deprecated: 'true'
      type: object
    handler.ErrorDetail:
      properties:
        deprecated:
          description: Whether this response concerns a deprecated field or route.
          example: true
          type: boolean
        deprecated_field:
          description: The deprecated field name.
          example: tenant_id
          type: string
        error_code:
          description: Machine-readable error classification code.
          example: VALIDATION_ERROR
          type: string
        message:
          description: Human-readable description of the error.
          example: Request validation failed
          type: string
        preferred_field:
          description: The canonical replacement for the deprecated field.
          example: database
          type: string
        success:
          deprecated: true
          description: >-
            Deprecated for API clients: always false on this path, so it carries
            no

            information. To detect a failure read the HTTP status code; for what

            went wrong read the envelope's error.code and error.message, and

            meta.request_id when reporting it. The whole `detail` object is

            deprecated legacy — tagging the field individually so SDK users see
            it

            on the property, not just the container (PRO-1208).
          example: true
          type: boolean
          x-deprecated: 'true'
      type: object
    handler.ErrorMeta:
      properties:
        api_version:
          type: string
        latency_ms:
          example: 12.3
          type: number
        request_id:
          description: Unique identifier for this request, useful for support and tracing.
          example: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d
          type: string
      type: object
    handler.deprecationNotice:
      properties:
        deprecated:
          description: Whether this response concerns a deprecated field or route.
          example: true
          type: boolean
        deprecated_field:
          description: The deprecated field name.
          example: tenant_id
          type: string
        deprecated_since:
          description: API version when the field was deprecated.
          example: 2.0.1
          type: string
        message:
          description: Migration guidance message.
          example: tenant_id is deprecated; use database instead.
          type: string
        preferred_field:
          description: The canonical replacement for the deprecated field.
          example: database
          type: string
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: API key
      description: 'API key sent as a Bearer token: "Bearer prefix.secret"'
      scheme: bearer
      type: http

````