# Knowledge bases (/en/docs/api/native/knowledge/stores)



[Quickstart: official Python SDK](/en/docs/developers/services/knowledge/quickstart)

[Base URL and authentication](/en/docs/api/native/knowledge)

Use existing resource IDs in paths. Set the environment variables shown in each example.

## Create knowledge base [#create-knowledge-base]

`POST /knowledge/v1/vector_stores`

Create a knowledge base, optionally starting ingestion of uploaded file\_ids in the same call; no separate attachment or batch is needed for those files. Use the returned id with vectorStores.files.retrieve to poll each attachment until completed, failed or cancelled; store status=completed alone does not mean every file succeeded. Unlike OpenAI vector stores, each file is limited to 100000000 bytes and each account to 100 active/nondeleted stores. Minimal body: \{"name":"Refund policies"}.

### Request body [#request-body]

| Field | Type | Description |
| --- | --- | --- |
| name | string | optional; Omitted name becomes an empty string; null is rejected.; max characters: 256; default: "" |
| metadata | object / null | optional; User-defined string metadata for the store; omission or null creates an empty map.; default: {} |
| expires_after | object / null | optional; Expiry policy from last activity; omission or null disables automatic expiry.; default: null |
| expires_after (1).anchor | "last_active_at" | required; last_active_at measures expiry from the most recent activity timestamp. |
| expires_after (1).days | integer | required; Days since last activity; attaching files and searching refresh activity.; min: 1; max: 365 |
| file_ids | string[] | optional; Existing File IDs to attach; the store allows up to 10,000 files. |
| chunking_strategy | object / object | optional; auto resolves to static with 800 estimated tokens and 400 overlap tokens. Unlike OpenAI vector stores, token counts are estimates; each Han character counts as one, and other whitespace-delimited words count as their UTF-16 length divided by four, rounded up.; default: {"type":"auto"} |
| chunking_strategy (1).type | "auto" | required; auto uses the default static chunk size of 800 estimated tokens with 400 overlap tokens. |
| chunking_strategy (2).type | "static" | required; static selects explicit chunk-size and overlap settings. |
| chunking_strategy (2).static | object | required; Chunk-size and overlap limits in estimated tokens. |
| chunking_strategy (2).static.max_chunk_size_tokens | integer | required; Estimated tokens per chunk.; min: 100; max: 4096 |
| chunking_strategy (2).static.chunk_overlap_tokens | integer | required; Must not exceed half of max_chunk_size_tokens.; min: 0; max: 2048 |
| description | string | optional; ignored: Accepted but not saved or returned; its type is not validated. |
| models | object / null | optional; Model roles to set. The model must exist in the model catalog and serve the role (embedding → openai.embeddings, rerank → cohere.rerank, query_rewrite → openai.chat.completions). The embedding model must output 1024-dimension vectors. Omitted roles stay unchanged; null restores all defaults. Unknown roles or empty IDs return 400 INVALID_PARAMS. The OpenAI-compatible API rejects this field with 400.; Praxis extension |
| models (1).embedding | string / null | optional; Embeds file chunks and queries. Fixed once the store has files. null restores the default (bge-m3). |
| models (1).rerank | string / null | optional; Reorders results when ranking_options.ranker is default-2024-11-15. null restores the default (bge-reranker-base). |
| models (1).query_rewrite | string / null | optional; Rewrites queries when a search sets rewrite_query. null restores the default (qwen3.8-flash). |

### Request example [#request-example]

```bash
curl -X POST "https://api.deepraxis.ai/knowledge/v1/vector_stores" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"Refund policies\"}"
```

### Response [#response]

HTTP 200

| Field | Type | Description |
| --- | --- | --- |
| id | string | required; Resource ID.; min characters: 1 |
| object | "vector_store" | required; Object discriminator; vector_store identifies a knowledge base. |
| name | string | required; Display name of the knowledge base; an empty string means no name was set.; max characters: 256 |
| status | "in_progress" / "completed" / "expired" / "deleting" | required; in_progress means at least one file is ingesting; completed means no file is ingesting, even if some failed; expired means the expiry policy has taken effect. deleting means soft-deleted and awaiting permanent removal. |
| usage_bytes | integer | required; Sum of completed source file sizes in bytes.; min: 0 |
| file_counts | object | required; Counts of files still attached to the store or batch, grouped by ingestion status. |
| file_counts.in_progress | integer | required; Number of files waiting for or undergoing ingestion.; min: 0 |
| file_counts.completed | integer | required; Number of files whose ingestion completed.; min: 0 |
| file_counts.failed | integer | required; Number of files whose ingestion failed.; min: 0 |
| file_counts.cancelled | integer | required; Number of files stopped by batch cancellation.; min: 0 |
| file_counts.total | integer | required; Total attached files across all ingestion statuses.; min: 0 |
| created_at | integer | required; Unix timestamp in seconds. |
| last_active_at | integer / null | required; Most recent creation, file attachment or search time in Unix seconds; null when unavailable. |
| expires_after | object / null | required; Expiry policy measured from last activity; null disables automatic expiry. |
| expires_after (1).anchor | "last_active_at" | required; last_active_at measures expiry from the most recent activity timestamp. |
| expires_after (1).days | integer | required; Days since last activity; attaching files and searching refresh activity.; min: 1; max: 365 |
| expires_at | integer / null | required; Scheduled expiry time in Unix seconds; null when no expiry policy is set. |
| metadata | object | required; Up to 16 keys; keys up to 64 characters; string values up to 512 characters.; max keys: 16; Key length ≤ 64; Values: string |
| purge_at | string / null | optional; Recovery deadline as an ISO 8601 date-time; null when not soft-deleted. |
| models | object | optional; Effective model per role (Router model IDs). Unset roles use the defaults.; Praxis extension |
| models.embedding | string | required; Embeds file chunks and queries. Fixed once the store has files. Default: bge-m3.; min characters: 1 |
| models.rerank | string | required; Reorders results when ranking_options.ranker is default-2024-11-15. Default: bge-reranker-base.; min characters: 1 |
| models.query_rewrite | string | required; Rewrites queries when a search sets rewrite_query. Default: qwen3.8-flash.; min characters: 1 |
| praxis | object | optional; Native lifecycle and recovery information for this knowledge base. |
| praxis.lifecycle | "provisioning" / "active" / "expired" / "deleted" / "failed" | required; provisioning means initialization is pending; active permits file operations and search; expired means the expiry policy took effect; deleted means soft-deleted; failed means initialization failed. |
| praxis.deleted_at | integer / null | required; Soft-deletion time in Unix seconds; null when not soft-deleted. |
| praxis.purge_at | integer / null | required; Recovery deadline in Unix seconds; null when not soft-deleted. |

[Error codes and objects](/en/docs/api/native/knowledge/errors)

## List knowledge bases [#list-knowledge-bases]

`GET /knowledge/v1/vector_stores`

Lists knowledge bases visible to the caller, newest first by default. Use last\_id as after to read the next page; for example, ?limit=20.

### Parameters [#parameters]

| Name   | Location and type            | Description                                                                                                               |
| ------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| status | query: "active" / "deleting" | active selects active stores; deleting selects soft-deleted stores awaiting purge. Omission excludes soft-deleted stores. |
| after  | query: string                | Cursor ID from the previous page. min characters: 1                                                                       |
| before | query: string                | Return items before this ID. min characters: 1                                                                            |
| limit  | query: integer               | Page size. min: 1; max: 100; default: 20                                                                                  |
| order  | query: "asc" / "desc"        | Order by creation time; defaults to desc for stores/files and asc by index for segments. default: "desc"                  |

### Request example [#request-example-1]

```bash
curl -X GET "https://api.deepraxis.ai/knowledge/v1/vector_stores" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

### Response [#response-1]

HTTP 200

| Field | Type | Description |
| --- | --- | --- |
| object | "list" | required; Object discriminator; list identifies a cursor-paginated collection. |
| data | object[] | required; Current page of knowledge bases in the requested order. |
| data[].id | string | required; Resource ID.; min characters: 1 |
| data[].object | "vector_store" | required; Object discriminator; vector_store identifies a knowledge base. |
| data[].name | string | required; Display name of the knowledge base; an empty string means no name was set.; max characters: 256 |
| data[].status | "in_progress" / "completed" / "expired" / "deleting" | required; in_progress means at least one file is ingesting; completed means no file is ingesting, even if some failed; expired means the expiry policy has taken effect. deleting means soft-deleted and awaiting permanent removal. |
| data[].usage_bytes | integer | required; Sum of completed source file sizes in bytes.; min: 0 |
| data[].file_counts | object | required; Counts of files still attached to the store or batch, grouped by ingestion status. |
| data[].file_counts.in_progress | integer | required; Number of files waiting for or undergoing ingestion.; min: 0 |
| data[].file_counts.completed | integer | required; Number of files whose ingestion completed.; min: 0 |
| data[].file_counts.failed | integer | required; Number of files whose ingestion failed.; min: 0 |
| data[].file_counts.cancelled | integer | required; Number of files stopped by batch cancellation.; min: 0 |
| data[].file_counts.total | integer | required; Total attached files across all ingestion statuses.; min: 0 |
| data[].created_at | integer | required; Unix timestamp in seconds. |
| data[].last_active_at | integer / null | required; Most recent creation, file attachment or search time in Unix seconds; null when unavailable. |
| data[].expires_after | object / null | required; Expiry policy measured from last activity; null disables automatic expiry. |
| data[].expires_after (1).anchor | "last_active_at" | required; last_active_at measures expiry from the most recent activity timestamp. |
| data[].expires_after (1).days | integer | required; Days since last activity; attaching files and searching refresh activity.; min: 1; max: 365 |
| data[].expires_at | integer / null | required; Scheduled expiry time in Unix seconds; null when no expiry policy is set. |
| data[].metadata | object | required; Up to 16 keys; keys up to 64 characters; string values up to 512 characters.; max keys: 16; Key length ≤ 64; Values: string |
| data[].purge_at | string / null | optional; Recovery deadline as an ISO 8601 date-time; null when not soft-deleted. |
| data[].models | object | optional; Effective model per role (Router model IDs). Unset roles use the defaults.; Praxis extension |
| data[].models.embedding | string | required; Embeds file chunks and queries. Fixed once the store has files. Default: bge-m3.; min characters: 1 |
| data[].models.rerank | string | required; Reorders results when ranking_options.ranker is default-2024-11-15. Default: bge-reranker-base.; min characters: 1 |
| data[].models.query_rewrite | string | required; Rewrites queries when a search sets rewrite_query. Default: qwen3.8-flash.; min characters: 1 |
| data[].praxis | object | optional; Native lifecycle and recovery information for this knowledge base. |
| data[].praxis.lifecycle | "provisioning" / "active" / "expired" / "deleted" / "failed" | required; provisioning means initialization is pending; active permits file operations and search; expired means the expiry policy took effect; deleted means soft-deleted; failed means initialization failed. |
| data[].praxis.deleted_at | integer / null | required; Soft-deletion time in Unix seconds; null when not soft-deleted. |
| data[].praxis.purge_at | integer / null | required; Recovery deadline in Unix seconds; null when not soft-deleted. |
| first_id | string / null | required; ID of the first item on this page; null for an empty page. |
| last_id | string / null | required; ID of the last item on this page; use as after to continue. Null for an empty page. |
| has_more | boolean | required; Whether additional items remain after this page within the selected cursor range. |

[Error codes and objects](/en/docs/api/native/knowledge/errors)

## Retrieve knowledge base [#retrieve-knowledge-base]

`GET /knowledge/v1/vector_stores/{vector_store_id}`

Retrieves a knowledge base using an id returned by create or list. Add ?expand=files to include the first page of attached files. Soft-deleted stores remain readable with status=deleting until purged.

### Parameters [#parameters-1]

| Name              | Location and type | Description                                                                                                        |
| ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| vector\_store\_id | path: string      | Required; Knowledge-base ID returned by create or list; use the ID rather than its display name. min characters: 1 |
| expand            | query: "files"\[] | Praxis extension on both URLs: files includes the first file page. Unknown values are ignored.                     |
| expand\[]         | query: "files"\[] | Praxis extension on both URLs: files includes the first file page. Unknown values are ignored.                     |

### Request example [#request-example-2]

```bash
curl -X GET "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

### Response [#response-2]

HTTP 200

| Field | Type | Description |
| --- | --- | --- |
| (1).id | string | required; Resource ID.; min characters: 1 |
| (1).object | "vector_store" | required; Object discriminator; vector_store identifies a knowledge base. |
| (1).name | string | required; Display name of the knowledge base; an empty string means no name was set.; max characters: 256 |
| (1).status | "in_progress" / "completed" / "expired" / "deleting" | required; in_progress means at least one file is ingesting; completed means no file is ingesting, even if some failed; expired means the expiry policy has taken effect. deleting means soft-deleted and awaiting permanent removal. |
| (1).usage_bytes | integer | required; Sum of completed source file sizes in bytes.; min: 0 |
| (1).file_counts | object | required; Counts of files still attached to the store or batch, grouped by ingestion status. |
| (1).file_counts.in_progress | integer | required; Number of files waiting for or undergoing ingestion.; min: 0 |
| (1).file_counts.completed | integer | required; Number of files whose ingestion completed.; min: 0 |
| (1).file_counts.failed | integer | required; Number of files whose ingestion failed.; min: 0 |
| (1).file_counts.cancelled | integer | required; Number of files stopped by batch cancellation.; min: 0 |
| (1).file_counts.total | integer | required; Total attached files across all ingestion statuses.; min: 0 |
| (1).created_at | integer | required; Unix timestamp in seconds. |
| (1).last_active_at | integer / null | required; Most recent creation, file attachment or search time in Unix seconds; null when unavailable. |
| (1).expires_after | object / null | required; Expiry policy measured from last activity; null disables automatic expiry. |
| (1).expires_after (1).anchor | "last_active_at" | required; last_active_at measures expiry from the most recent activity timestamp. |
| (1).expires_after (1).days | integer | required; Days since last activity; attaching files and searching refresh activity.; min: 1; max: 365 |
| (1).expires_at | integer / null | required; Scheduled expiry time in Unix seconds; null when no expiry policy is set. |
| (1).metadata | object | required; Up to 16 keys; keys up to 64 characters; string values up to 512 characters.; max keys: 16; Key length ≤ 64; Values: string |
| (1).purge_at | string / null | optional; Recovery deadline as an ISO 8601 date-time; null when not soft-deleted. |
| (1).models | object | optional; Effective model per role (Router model IDs). Unset roles use the defaults.; Praxis extension |
| (1).models.embedding | string | required; Embeds file chunks and queries. Fixed once the store has files. Default: bge-m3.; min characters: 1 |
| (1).models.rerank | string | required; Reorders results when ranking_options.ranker is default-2024-11-15. Default: bge-reranker-base.; min characters: 1 |
| (1).models.query_rewrite | string | required; Rewrites queries when a search sets rewrite_query. Default: qwen3.8-flash.; min characters: 1 |
| (1).praxis | object | optional; Native lifecycle and recovery information for this knowledge base. |
| (1).praxis.lifecycle | "provisioning" / "active" / "expired" / "deleted" / "failed" | required; provisioning means initialization is pending; active permits file operations and search; expired means the expiry policy took effect; deleted means soft-deleted; failed means initialization failed. |
| (1).praxis.deleted_at | integer / null | required; Soft-deletion time in Unix seconds; null when not soft-deleted. |
| (1).praxis.purge_at | integer / null | required; Recovery deadline in Unix seconds; null when not soft-deleted. |
| (2).files | object | optional; First page of files, only when expand=files. |
| (2).files.object | "list" | required; Object discriminator; list identifies a cursor-paginated collection. |
| (2).files.data | object[] | required; Current page of attached files in the requested order. |
| (2).files.data[].id | string | required; Same ID as the source File.; min characters: 1 |
| (2).files.data[].object | "vector_store.file" | required; Object discriminator; vector_store.file identifies a file attached to a knowledge base. |
| (2).files.data[].vector_store_id | string | required; Resource ID.; min characters: 1 |
| (2).files.data[].status | "in_progress" / "completed" / "cancelled" / "failed" | required; in_progress means ingestion is pending or running; completed means searchable; failed means ingestion failed; cancelled means ingestion was stopped by batch cancellation. |
| (2).files.data[].last_error | object / null | required; Ingestion failure details; null before a failure and after a successful ingestion or retry. |
| (2).files.data[].last_error (1).code | "server_error" / "unsupported_file" / "invalid_file" | required; unsupported_file means the file type is unsupported; invalid_file means encrypted, empty or over the parsed-token limit; server_error covers other ingestion failures and deadline expiry. |
| (2).files.data[].last_error (1).message | string | required; Explanation of the ingestion failure associated with code. |
| (2).files.data[].usage_bytes | integer | required; Original source file size in bytes after completion; zero while pending, failed or cancelled.; min: 0 |
| (2).files.data[].created_at | integer | required; Unix timestamp in seconds. |
| (2).files.data[].chunking_strategy | object / object | required; Stored chunking strategy for this attachment; auto input is returned as static settings. |
| (2).files.data[].chunking_strategy (1).type | "static" | required; static selects explicit chunk-size and overlap settings. |
| (2).files.data[].chunking_strategy (1).static | object | required; Chunk-size and overlap limits in estimated tokens. |
| (2).files.data[].chunking_strategy (1).static.max_chunk_size_tokens | integer | required; Estimated tokens per chunk.; min: 100; max: 4096 |
| (2).files.data[].chunking_strategy (1).static.chunk_overlap_tokens | integer | required; Must not exceed half of max_chunk_size_tokens.; min: 0; max: 2048 |
| (2).files.data[].chunking_strategy (2).type | "other" | required; other identifies a stored strategy whose chunk-size settings are unavailable. |
| (2).files.data[].attributes | object / null | required; File attributes used for search filtering; null means no attributes are set. |
| (2).files.data[].praxis | object | optional; Native ingestion progress and source-file measurements. |
| (2).files.data[].praxis.stage | "queued" / "parse" / "chunk" / "embed" / "index" / null | required; queued means waiting; parse extracts text; chunk splits text; embed creates vectors; index makes chunks searchable. Null means ingestion is no longer running. |
| (2).files.data[].praxis.deadline_at | integer / null | required; Ingestion deadline in Unix seconds; unfinished ingestion fails when this time is reached. |
| (2).files.data[].praxis.filename | string | required; Original source filename returned by the File service. |
| (2).files.data[].praxis.bytes | integer | required; Original file size in bytes.; min: 0 |
| (2).files.data[].praxis.pages | integer / null | required; Number of parsed pages after successful ingestion; null before a successful parse is committed. |
| (2).files.data[].praxis.chunk_count | integer | required; Number of ingested chunks; zero until completion and after failure or cancellation.; min: 0 |
| (2).files.first_id | string / null | required; ID of the first item on this page; null for an empty page. |
| (2).files.last_id | string / null | required; ID of the last item on this page; use as after to continue. Null for an empty page. |
| (2).files.has_more | boolean | required; Whether additional items remain after this page within the selected cursor range. |

[Error codes and objects](/en/docs/api/native/knowledge/errors)

## Update knowledge base [#update-knowledge-base]

`POST /knowledge/v1/vector_stores/{vector_store_id}`

Updates an active knowledge base using its returned id. Omitted fields stay unchanged; metadata replaces the whole map. Example body: \{"name":"Refund policies"}.

### Parameters [#parameters-2]

| Name              | Location and type | Description                                                                                                        |
| ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| vector\_store\_id | path: string      | Required; Knowledge-base ID returned by create or list; use the ID rather than its display name. min characters: 1 |

### Request body [#request-body-1]

| Field | Type | Description |
| --- | --- | --- |
| name | string / null | optional; null clears the name to an empty string. Omitted fields stay unchanged. |
| metadata | object / null | optional; Replaces all metadata; null clears it to an empty object. |
| expires_after | object / null | optional; null removes automatic expiry. |
| expires_after (1).anchor | "last_active_at" | required; last_active_at measures expiry from the most recent activity timestamp. |
| expires_after (1).days | integer | required; Days since last activity; attaching files and searching refresh activity.; min: 1; max: 365 |
| models | object / null | optional; Model roles to set. The model must exist in the model catalog and serve the role (embedding → openai.embeddings, rerank → cohere.rerank, query_rewrite → openai.chat.completions). The embedding model must output 1024-dimension vectors. Omitted roles stay unchanged; null restores all defaults. Unknown roles or empty IDs return 400 INVALID_PARAMS. The OpenAI-compatible API rejects this field with 400.; Praxis extension |
| models (1).embedding | string / null | optional; Embeds file chunks and queries. Fixed once the store has files. null restores the default (bge-m3). |
| models (1).rerank | string / null | optional; Reorders results when ranking_options.ranker is default-2024-11-15. null restores the default (bge-reranker-base). |
| models (1).query_rewrite | string / null | optional; Rewrites queries when a search sets rewrite_query. null restores the default (qwen3.8-flash). |

### Request example [#request-example-3]

```bash
curl -X POST "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"models\":{\"query_rewrite\":\"qwen3.8-flash\"}}"
```

### Response [#response-3]

HTTP 200

| Field | Type | Description |
| --- | --- | --- |
| id | string | required; Resource ID.; min characters: 1 |
| object | "vector_store" | required; Object discriminator; vector_store identifies a knowledge base. |
| name | string | required; Display name of the knowledge base; an empty string means no name was set.; max characters: 256 |
| status | "in_progress" / "completed" / "expired" / "deleting" | required; in_progress means at least one file is ingesting; completed means no file is ingesting, even if some failed; expired means the expiry policy has taken effect. deleting means soft-deleted and awaiting permanent removal. |
| usage_bytes | integer | required; Sum of completed source file sizes in bytes.; min: 0 |
| file_counts | object | required; Counts of files still attached to the store or batch, grouped by ingestion status. |
| file_counts.in_progress | integer | required; Number of files waiting for or undergoing ingestion.; min: 0 |
| file_counts.completed | integer | required; Number of files whose ingestion completed.; min: 0 |
| file_counts.failed | integer | required; Number of files whose ingestion failed.; min: 0 |
| file_counts.cancelled | integer | required; Number of files stopped by batch cancellation.; min: 0 |
| file_counts.total | integer | required; Total attached files across all ingestion statuses.; min: 0 |
| created_at | integer | required; Unix timestamp in seconds. |
| last_active_at | integer / null | required; Most recent creation, file attachment or search time in Unix seconds; null when unavailable. |
| expires_after | object / null | required; Expiry policy measured from last activity; null disables automatic expiry. |
| expires_after (1).anchor | "last_active_at" | required; last_active_at measures expiry from the most recent activity timestamp. |
| expires_after (1).days | integer | required; Days since last activity; attaching files and searching refresh activity.; min: 1; max: 365 |
| expires_at | integer / null | required; Scheduled expiry time in Unix seconds; null when no expiry policy is set. |
| metadata | object | required; Up to 16 keys; keys up to 64 characters; string values up to 512 characters.; max keys: 16; Key length ≤ 64; Values: string |
| purge_at | string / null | optional; Recovery deadline as an ISO 8601 date-time; null when not soft-deleted. |
| models | object | optional; Effective model per role (Router model IDs). Unset roles use the defaults.; Praxis extension |
| models.embedding | string | required; Embeds file chunks and queries. Fixed once the store has files. Default: bge-m3.; min characters: 1 |
| models.rerank | string | required; Reorders results when ranking_options.ranker is default-2024-11-15. Default: bge-reranker-base.; min characters: 1 |
| models.query_rewrite | string | required; Rewrites queries when a search sets rewrite_query. Default: qwen3.8-flash.; min characters: 1 |
| praxis | object | optional; Native lifecycle and recovery information for this knowledge base. |
| praxis.lifecycle | "provisioning" / "active" / "expired" / "deleted" / "failed" | required; provisioning means initialization is pending; active permits file operations and search; expired means the expiry policy took effect; deleted means soft-deleted; failed means initialization failed. |
| praxis.deleted_at | integer / null | required; Soft-deletion time in Unix seconds; null when not soft-deleted. |
| praxis.purge_at | integer / null | required; Recovery deadline in Unix seconds; null when not soft-deleted. |

[Error codes and objects](/en/docs/api/native/knowledge/errors)

## Delete knowledge base [#delete-knowledge-base]

`DELETE /knowledge/v1/vector_stores/{vector_store_id}`

Remove a knowledge base from active use while keeping a recovery window. Unlike OpenAI vector stores, native DELETE returns the store with status=deleting and ISO purge\_at, retains it for 7 days and is idempotent on repeat. Retrieve remains 200; object operations return 409. Use restore before purge\_at to recover it, or purge to remove it irreversibly.

### Parameters [#parameters-3]

| Name              | Location and type | Description                                                                                                        |
| ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| vector\_store\_id | path: string      | Required; Knowledge-base ID returned by create or list; use the ID rather than its display name. min characters: 1 |

### Request example [#request-example-4]

```bash
curl -X DELETE "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

### Response [#response-4]

HTTP 200

| Field | Type | Description |
| --- | --- | --- |
| id | string | required; Resource ID.; min characters: 1 |
| object | "vector_store" | required; Object discriminator; vector_store identifies a knowledge base. |
| name | string | required; Display name of the knowledge base; an empty string means no name was set.; max characters: 256 |
| status | "in_progress" / "completed" / "expired" / "deleting" | required; in_progress means at least one file is ingesting; completed means no file is ingesting, even if some failed; expired means the expiry policy has taken effect. deleting means soft-deleted and awaiting permanent removal. |
| usage_bytes | integer | required; Sum of completed source file sizes in bytes.; min: 0 |
| file_counts | object | required; Counts of files still attached to the store or batch, grouped by ingestion status. |
| file_counts.in_progress | integer | required; Number of files waiting for or undergoing ingestion.; min: 0 |
| file_counts.completed | integer | required; Number of files whose ingestion completed.; min: 0 |
| file_counts.failed | integer | required; Number of files whose ingestion failed.; min: 0 |
| file_counts.cancelled | integer | required; Number of files stopped by batch cancellation.; min: 0 |
| file_counts.total | integer | required; Total attached files across all ingestion statuses.; min: 0 |
| created_at | integer | required; Unix timestamp in seconds. |
| last_active_at | integer / null | required; Most recent creation, file attachment or search time in Unix seconds; null when unavailable. |
| expires_after | object / null | required; Expiry policy measured from last activity; null disables automatic expiry. |
| expires_after (1).anchor | "last_active_at" | required; last_active_at measures expiry from the most recent activity timestamp. |
| expires_after (1).days | integer | required; Days since last activity; attaching files and searching refresh activity.; min: 1; max: 365 |
| expires_at | integer / null | required; Scheduled expiry time in Unix seconds; null when no expiry policy is set. |
| metadata | object | required; Up to 16 keys; keys up to 64 characters; string values up to 512 characters.; max keys: 16; Key length ≤ 64; Values: string |
| purge_at | string / null | optional; Recovery deadline as an ISO 8601 date-time; null when not soft-deleted. |
| models | object | optional; Effective model per role (Router model IDs). Unset roles use the defaults.; Praxis extension |
| models.embedding | string | required; Embeds file chunks and queries. Fixed once the store has files. Default: bge-m3.; min characters: 1 |
| models.rerank | string | required; Reorders results when ranking_options.ranker is default-2024-11-15. Default: bge-reranker-base.; min characters: 1 |
| models.query_rewrite | string | required; Rewrites queries when a search sets rewrite_query. Default: qwen3.8-flash.; min characters: 1 |
| praxis | object | optional; Native lifecycle and recovery information for this knowledge base. |
| praxis.lifecycle | "provisioning" / "active" / "expired" / "deleted" / "failed" | required; provisioning means initialization is pending; active permits file operations and search; expired means the expiry policy took effect; deleted means soft-deleted; failed means initialization failed. |
| praxis.deleted_at | integer / null | required; Soft-deletion time in Unix seconds; null when not soft-deleted. |
| praxis.purge_at | integer / null | required; Recovery deadline in Unix seconds; null when not soft-deleted. |

[Error codes and objects](/en/docs/api/native/knowledge/errors)

## Restore knowledge base [#restore-knowledge-base]

`POST /knowledge/v1/vector_stores/{vector_store_id}/restore`

Restores a deleting store within 7 days. Active stores return 409 VECTOR\_STORE\_INVALID\_STATE; absent stores return 404. Empty body is allowed.

### Parameters [#parameters-4]

| Name              | Location and type | Description                                                                                                        |
| ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| vector\_store\_id | path: string      | Required; Knowledge-base ID returned by create or list; use the ID rather than its display name. min characters: 1 |

### Request example [#request-example-5]

```bash
curl -X POST "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/restore" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

### Response [#response-5]

HTTP 200

| Field | Type | Description |
| --- | --- | --- |
| id | string | required; Resource ID.; min characters: 1 |
| object | "vector_store" | required; Object discriminator; vector_store identifies a knowledge base. |
| name | string | required; Display name of the knowledge base; an empty string means no name was set.; max characters: 256 |
| status | "in_progress" / "completed" / "expired" / "deleting" | required; in_progress means at least one file is ingesting; completed means no file is ingesting, even if some failed; expired means the expiry policy has taken effect. deleting means soft-deleted and awaiting permanent removal. |
| usage_bytes | integer | required; Sum of completed source file sizes in bytes.; min: 0 |
| file_counts | object | required; Counts of files still attached to the store or batch, grouped by ingestion status. |
| file_counts.in_progress | integer | required; Number of files waiting for or undergoing ingestion.; min: 0 |
| file_counts.completed | integer | required; Number of files whose ingestion completed.; min: 0 |
| file_counts.failed | integer | required; Number of files whose ingestion failed.; min: 0 |
| file_counts.cancelled | integer | required; Number of files stopped by batch cancellation.; min: 0 |
| file_counts.total | integer | required; Total attached files across all ingestion statuses.; min: 0 |
| created_at | integer | required; Unix timestamp in seconds. |
| last_active_at | integer / null | required; Most recent creation, file attachment or search time in Unix seconds; null when unavailable. |
| expires_after | object / null | required; Expiry policy measured from last activity; null disables automatic expiry. |
| expires_after (1).anchor | "last_active_at" | required; last_active_at measures expiry from the most recent activity timestamp. |
| expires_after (1).days | integer | required; Days since last activity; attaching files and searching refresh activity.; min: 1; max: 365 |
| expires_at | integer / null | required; Scheduled expiry time in Unix seconds; null when no expiry policy is set. |
| metadata | object | required; Up to 16 keys; keys up to 64 characters; string values up to 512 characters.; max keys: 16; Key length ≤ 64; Values: string |
| purge_at | string / null | optional; Recovery deadline as an ISO 8601 date-time; null when not soft-deleted. |
| models | object | optional; Effective model per role (Router model IDs). Unset roles use the defaults.; Praxis extension |
| models.embedding | string | required; Embeds file chunks and queries. Fixed once the store has files. Default: bge-m3.; min characters: 1 |
| models.rerank | string | required; Reorders results when ranking_options.ranker is default-2024-11-15. Default: bge-reranker-base.; min characters: 1 |
| models.query_rewrite | string | required; Rewrites queries when a search sets rewrite_query. Default: qwen3.8-flash.; min characters: 1 |
| praxis | object | optional; Native lifecycle and recovery information for this knowledge base. |
| praxis.lifecycle | "provisioning" / "active" / "expired" / "deleted" / "failed" | required; provisioning means initialization is pending; active permits file operations and search; expired means the expiry policy took effect; deleted means soft-deleted; failed means initialization failed. |
| praxis.deleted_at | integer / null | required; Soft-deletion time in Unix seconds; null when not soft-deleted. |
| praxis.purge_at | integer / null | required; Recovery deadline in Unix seconds; null when not soft-deleted. |

[Error codes and objects](/en/docs/api/native/knowledge/errors)

## Permanently purge knowledge base [#permanently-purge-knowledge-base]

`POST /knowledge/v1/vector_stores/{vector_store_id}/purge`

Immediately and irreversibly clears a deleting store using the retention cleanup path. Active stores return 409; absent stores return 404. Empty body is allowed.

### Parameters [#parameters-5]

| Name              | Location and type | Description                                                                                                        |
| ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| vector\_store\_id | path: string      | Required; Knowledge-base ID returned by create or list; use the ID rather than its display name. min characters: 1 |

### Request example [#request-example-6]

```bash
curl -X POST "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/purge" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

### Response [#response-6]

HTTP 200

| Field | Type | Description |
| --- | --- | --- |
| id | string | required; ID of the knowledge base that was permanently removed. |
| object | "vector_store" | required; Object discriminator; vector_store identifies this purge receipt. |
| purged | true | required; Confirms irreversible removal of the knowledge base and its indexed content. |

[Error codes and objects](/en/docs/api/native/knowledge/errors)