Knowledge
Knowledge bases
Request fields, response objects and current limitations.
Quickstart: official Python SDK
Use existing resource IDs in paths. Set the environment variables shown in each example.
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
| 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
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
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. |
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
| 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
curl -X GET "https://api.deepraxis.ai/knowledge/v1/vector_stores" \
-H "Authorization: Bearer $PRAXIS_API_KEY"Response
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. |
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
| 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
curl -X GET "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"Response
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. |
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
| 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
| 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
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
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. |
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
| 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
curl -X DELETE "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"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. |
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
| 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
curl -X POST "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/restore" \
-H "Authorization: Bearer $PRAXIS_API_KEY"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. |
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
| 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
curl -X POST "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/purge" \
-H "Authorization: Bearer $PRAXIS_API_KEY"Response
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. |