Delete Context

client.context.delete(
    type="knowledge",
    database="acme_corp",
    collection="team_docs",
    ids=["policy_main", "runbook_deploy"],
)

await client.context.delete({
  type: "knowledge",
  database: "acme_corp",
  collection: "team_docs",
  ids: ["policy_main", "runbook_deploy"],
});

curl -X DELETE 'https://api.hydradb.com/context' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme_corp",
    "collection": "team_docs",
    "ids": ["policy_main", "runbook_deploy"],
    "type": "knowledge"
  }'

{
  "success": true,
  "data": {
    "success": true,
    "message": "Delete completed",
    "results": [
      { "id": "policy_main", "deleted": true },
      { "id": "runbook_deploy", "deleted": true }
    ],
    "deleted_count": 2
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

DELETE

context

client.context.delete(
    type="knowledge",
    database="acme_corp",
    collection="team_docs",
    ids=["policy_main", "runbook_deploy"],
)

await client.context.delete({
  type: "knowledge",
  database: "acme_corp",
  collection: "team_docs",
  ids: ["policy_main", "runbook_deploy"],
});

curl -X DELETE 'https://api.hydradb.com/context' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme_corp",
    "collection": "team_docs",
    "ids": ["policy_main", "runbook_deploy"],
    "type": "knowledge"
  }'

{
  "success": true,
  "data": {
    "success": true,
    "message": "Delete completed",
    "results": [
      { "id": "policy_main", "deleted": true },
      { "id": "runbook_deploy", "deleted": true }
    ],
    "deleted_count": 2
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

Specify the resource category with the type parameter:

type=knowledge (default) - delete knowledge sources.
type=memory - delete memories.

Pass one or more IDs in ids. Send database, collection, ids, and type as top-level fields in the request body.

Knowledge deletion

Use type: "knowledge" and pass knowledge ids in the ids array. Include the same collection you used when ingesting the knowledge; omitting it targets the default collection.

client.context.delete(
    type="knowledge",
    database="acme_corp",
    collection="team_docs",
    ids=["policy_main", "runbook_deploy"],
)

await client.context.delete({
  type: "knowledge",
  database: "acme_corp",
  collection: "team_docs",
  ids: ["policy_main", "runbook_deploy"],
});

curl -X DELETE 'https://api.hydradb.com/context' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme_corp",
    "collection": "team_docs",
    "ids": ["policy_main", "runbook_deploy"],
    "type": "knowledge"
  }'

{
  "success": true,
  "data": {
    "success": true,
    "message": "Delete completed",
    "results": [
      { "id": "policy_main", "deleted": true },
      { "id": "runbook_deploy", "deleted": true }
    ],
    "deleted_count": 2
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

Memory deletion

Use type: "memory" and pass memory ids in the ids array. Include the same collection you used when ingesting the memories; omitting it targets the default collection.

client.context.delete(
    type="memory",
    database="acme_corp",
    collection="user_alex",
    ids=["mem_user_alex_tone"],
)

await client.context.delete({
  type: "memory",
  database: "acme_corp",
  collection: "user_alex",
  ids: ["mem_user_alex_tone"],
});

curl -X DELETE 'https://api.hydradb.com/context' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme_corp",
    "collection": "user_alex",
    "ids": ["mem_user_alex_tone"],
    "type": "memory"
  }'

{
  "success": true,
  "data": {
    "success": true,
    "message": "Successfully deleted 1 memory source(s)",
    "results": [
      { "id": "mem_user_alex_tone", "deleted": true }
    ],
    "deleted_count": 1,
    "user_memory_deleted": 1
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": false,
  "data": {
    "success": false,
    "message": "No sources were deleted",
    "results": [
      {
        "id": "mem_user_alex_tone",
        "deleted": false,
        "error": "Memory not found or deletion failed"
      }
    ],
    "deleted_count": 0,
    "user_memory_deleted": 0
  },
  "error": {
    "code": "NOT_FOUND",
    "message": "No sources were deleted"
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

Status codes

By default, every outcome returns 200 - including a delete that removed nothing. The real result is in the body, so check data.deleted_count and data.results[] rather than the status code.

Default - always 200

curl -X DELETE 'https://api.hydradb.com/context' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{ "database": "acme_corp", "ids": ["policy_main"], "type": "knowledge" }'

Opt in to honest status codes

Send X-HydraDB-Delete-Status: strict and a delete that did not happen returns 404, 409, or 500 instead of 200. This is the recommended mode for new integrations - it is the only way to detect a failed delete from the status code alone.

Strict - honest status codes

curl -X DELETE 'https://api.hydradb.com/context' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  -H "X-HydraDB-Delete-Status: strict" \
  -H "Content-Type: application/json" \
  -d '{ "database": "acme_corp", "ids": ["policy_main"], "type": "knowledge" }'

In strict mode:

Status	Code	Meaning
`200`	n/a	At least one source was deleted. Check `results[]` for per-ID outcomes.
`404`	`NOT_FOUND`	None of the given `ids` matched anything to delete.
`409`	`SOURCE_PROCESSING`	A source is still indexing. Retry after ingestion completes - see the `Retry-After` header.
`500`	`INTERNAL_ERROR`	A store failed to remove the source. The delete is retryable.

Deleting a source that is still indexing is the case worth handling, and the main reason to turn strict mode on. Ingestion is asynchronous, so an ingest-then-delete sequence - what most teardown and test scripts do - can reach the source before it finishes indexing. The source is not deleted.In the default mode that comes back as a 200 with deleted_count: 0, which is exactly the silent failure that leaves data behind. In strict mode it is a 409. Retry once indexing completes, or poll Source Status first.

On 404, 409, and 500 the response data still carries the same results / deleted_count payload a 200 carries, so you can read per-ID outcomes on a failure exactly as you would on success:

409 - still indexing (strict mode)

{
  "success": false,
  "data": {
    "success": false,
    "message": "Source is still processing; retry deletion after ingestion completes",
    "results": [
      {
        "id": "policy_main",
        "deleted": false,
        "error": "Source is still processing; retry deletion after ingestion completes"
      }
    ],
    "deleted_count": 0
  },
  "error": {
    "code": "SOURCE_PROCESSING",
    "message": "Source is still processing; retry deletion after ingestion completes"
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 8.1
  }
}

Which mode you get

The header always wins. Without it, the server default applies.

Request	Behaviour
No header	The server default - currently `legacy`, so `200` for every outcome.
`X-HydraDB-Delete-Status: strict`	Honest `404` / `409` / `500`.
`X-HydraDB-Delete-Status: legacy`	`200` for every outcome, whatever the server default.

The default is expected to become strict in a future release. Adopting strict now means that change is a no-op for you.When it happens, X-HydraDB-Delete-Status: legacy keeps the unconditional 200 for any integration that is not ready. Both header values are supported and neither has a removal date - if that ever changes, we will announce it.If your integration checks response.ok or status == 200 today, it is treating blocked deletes as successful. That is the failure strict mode surfaces.

Some additional notes

Partial-success semantics: For type=knowledge, each ID is reported independently in results[]. A failure on one ID does not stop the rest. For type=memory, the response reports an aggregate user_memory_deleted reflecting all listed IDs. One exception: if any source in the request is still indexing, the whole request is refused and nothing is deleted - reported as 409 in strict mode, and as a 200 with deleted_count: 0 by default.
Retrieval drops the source immediately: Even before background cleanup finishes, deleted IDs disappear from /query and /context/list responses.
Mixed deletes need two calls: To delete both knowledge and memory items, send two requests - one with type=knowledge, one with type=memory.

Related Resources

Find IDs: List Documents
Perform a query: Query
Re-add content: Ingest Context
Bigger hammer: Delete Database - removes the entire database
Read more: Context Management - Overview

Authorizations

Authorization

string

header

required

API key sent as a Bearer token: "Bearer prefix.secret"

Headers

X-HydraDB-Delete-Status

enum<string>

Selects the status behaviour for this request. strict opts in to honest 404/409/500 codes when the delete did not happen; legacy forces the unconditional 200. Omitted, the server default applies — currently legacy.

Available options:

strict,

legacy

Body

application/json

Delete request

collection

string

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"

database

string

Database/Collection are the canonical v2 names; TenantID/SubTenantID are their deprecated aliases, reconciled by the TenantAliases middleware before binding so TenantID is always populated.

Example:

"acme_corp"

ids

string[]

IDs of the sources or memories to delete.

Example:

["HydraDoc1234", "HydraDoc4567"]

sub_tenant_id

string

deprecated

deprecated: use collection

Example:

"sub_tenant_4567"

tenant_id

string

deprecated

deprecated: use database

Example:

"tenant_1234"

type

enum<string>

Bucket to delete from: knowledge (default) or memory.

Available options:

knowledge,

memory

Example:

"knowledge"

Response

data

object

Show child attributes

Example:

{
  "deleted_count": 1,
  "message": "Success",
  "results": [
    {
      "deleted": true,
      "error": "",
      "id": "HydraDoc1234"
    }
  ],
  "success": true,
  "user_memory_deleted": 1
}

error

object

Error message, empty string on success.

Show child attributes

Example:

{
  "code": "DATABASE_NOT_FOUND",
  "message": "Database not found"
}

API Documentation

Databases

Context

Query

Connectors

Webhooks

Miscellaneous

Knowledge deletion

Memory deletion

Status codes

Opt in to honest status codes

Which mode you get

Some additional notes

Authorizations

Headers

Body

Response

​Knowledge deletion

​Memory deletion

​Status codes

​Opt in to honest status codes

​Which mode you get

​Some additional notes

Authorizations

Headers

Body

Response

Knowledge deletion

Memory deletion

Status codes

Opt in to honest status codes

Which mode you get

Some additional notes