response = client.databases.delete_collection(
database="my_first_database",
collection="engineering",
)
const response = await client.databases.deleteCollection({
database: "my_first_database",
collection: "engineering",
});
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"
{
"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
}
}
{
"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
}
}
Databases
Delete Collection
Permanently remove one collection and all of its data from a database.
DELETE
/
databases
/
collections
response = client.databases.delete_collection(
database="my_first_database",
collection="engineering",
)
const response = await client.databases.deleteCollection({
database: "my_first_database",
collection: "engineering",
});
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"
{
"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
}
}
{
"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
}
}
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.
response = client.databases.delete_collection(
database="my_first_database",
collection="engineering",
)
const response = await client.databases.deleteCollection({
database: "my_first_database",
collection: "engineering",
});
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"
Query parameters
| Name | Description |
|---|---|
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. | |
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. |
{
"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
}
}
{
"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
}
}
While cleanup is running
Deletion is asynchronous: a200 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 once its records are dropped, which happens before the slower vector, graph, and object-store cleanup completes.
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
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.
- 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
DELETEre-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 for the full list.
Related Resources
- Before this: List Collections - find the collection ID
- Alternative: Delete Context - remove specific knowledge or memories without deleting the collection
- Larger scope: Delete Database - remove the entire database
- Read more: Concepts → Multi tenancy
Authorizations
API key sent as a Bearer token: "Bearer prefix.secret"
Query Parameters
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.
Example:
"acme_corp"
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.
Example:
"engineering"
Response
OK
Show child attributes
Show child attributes
Example:
{
"collection": "engineering",
"database": "acme_corp",
"message": "Collection deregistered. Background cleanup is in progress.",
"status": "deletion_scheduled"
}
Error message, empty string on success.
Show child attributes
Show child attributes
Example:
{
"code": "DATABASE_NOT_FOUND",
"message": "Database not found"
}
Show child attributes
Show child attributes
Example:
{
"latency_ms": 12.3,
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d"
}
Whether the request succeeded.
Example:
true
Was this page helpful?