Knowledge API

Resource	Use
Knowledge bases	Create, retrieve, update, delete and restore
Files	Attach, retrieve, edit attributes, remove and retry
Batches	Add files in batches, retrieve status and cancel
Search	Find relevant text chunks
Segments	Read chunks, positions and terms
Events	Read store and ingestion events

Error codes · Limits and file formats · OpenAI vector stores

Knowledge bases

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.

Files

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

Add file

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

Attach an uploaded File for asynchronous ingestion, then poll this attachment until status is completed, failed or cancelled before searching. Unlike OpenAI vector stores, the file limit is 100000000 bytes; chunk sizes use estimated tokens rather than a model tokenizer. Text, Markdown, CSV, JSON, HTML, PDF, DOCX, PPTX, XLSX and PNG/JPEG/GIF/WebP images can be extracted; audio and video uploads are not knowledge documents. Images may yield generated descriptions rather than verbatim OCR. auto chunking resolves to static 800/400; explicit sizes are 100–4096 with overlap at most half the size. Each store holds at most 10000 attached files. Reattaching the same file returns its existing record without applying new attributes or chunking; inspect last_error after failure.

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
file_id	string	required; Existing source File ID returned by file upload; the file must be visible to the caller.; min characters: 1
attributes	object / null	optional; Search-filter attributes for a newly attached file; omission or null leaves attributes unset. Reattaching an existing file does not change them.
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

Request example

curl -X POST "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/files" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"file_id\":\"${FILE_ID}\"}"

Response

HTTP 200

Field	Type	Description
id	string	required; Same ID as the source File.; min characters: 1
object	"vector_store.file"	required; Object discriminator; vector_store.file identifies a file attached to a knowledge base.
vector_store_id	string	required; Resource ID.; min characters: 1
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.
last_error	object / null	required; Ingestion failure details; null before a failure and after a successful ingestion or retry.
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.
last_error (1).message	string	required; Explanation of the ingestion failure associated with code.
usage_bytes	integer	required; Original source file size in bytes after completion; zero while pending, failed or cancelled.; min: 0
created_at	integer	required; Unix timestamp in seconds.
chunking_strategy	object / object	required; Stored chunking strategy for this attachment; auto input is returned as static settings.
chunking_strategy (1).type	"static"	required; static selects explicit chunk-size and overlap settings.
chunking_strategy (1).static	object	required; Chunk-size and overlap limits in estimated tokens.
chunking_strategy (1).static.max_chunk_size_tokens	integer	required; Estimated tokens per chunk.; min: 100; max: 4096
chunking_strategy (1).static.chunk_overlap_tokens	integer	required; Must not exceed half of max_chunk_size_tokens.; min: 0; max: 2048
chunking_strategy (2).type	"other"	required; other identifies a stored strategy whose chunk-size settings are unavailable.
attributes	object / null	required; File attributes used for search filtering; null means no attributes are set.
praxis	object	optional; Native ingestion progress and source-file measurements.
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.
praxis.deadline_at	integer / null	required; Ingestion deadline in Unix seconds; unfinished ingestion fails when this time is reached.
praxis.filename	string	required; Original source filename returned by the File service.
praxis.bytes	integer	required; Original file size in bytes.; min: 0
praxis.pages	integer / null	required; Number of parsed pages after successful ingestion; null before a successful parse is committed.
praxis.chunk_count	integer	required; Number of ingested chunks; zero until completion and after failure or cancellation.; min: 0

List files

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

Lists attached files and their ingestion status, newest attachment first by default. Use last_id as after to continue; ?filter=failed selects files that can be retried.

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
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"
filter	query: "in_progress" / "completed" / "failed" / "cancelled"	in_progress means ingestion is pending or running; completed means searchable; failed means ingestion failed; cancelled means ingestion was stopped by batch cancellation. Omit to include all statuses.

Request example

curl -X GET "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/files" \
  -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 attached files in the requested order.
data[].id	string	required; Same ID as the source File.; min characters: 1
data[].object	"vector_store.file"	required; Object discriminator; vector_store.file identifies a file attached to a knowledge base.
data[].vector_store_id	string	required; Resource ID.; min characters: 1
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.
data[].last_error	object / null	required; Ingestion failure details; null before a failure and after a successful ingestion or retry.
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.
data[].last_error (1).message	string	required; Explanation of the ingestion failure associated with code.
data[].usage_bytes	integer	required; Original source file size in bytes after completion; zero while pending, failed or cancelled.; min: 0
data[].created_at	integer	required; Unix timestamp in seconds.
data[].chunking_strategy	object / object	required; Stored chunking strategy for this attachment; auto input is returned as static settings.
data[].chunking_strategy (1).type	"static"	required; static selects explicit chunk-size and overlap settings.
data[].chunking_strategy (1).static	object	required; Chunk-size and overlap limits in estimated tokens.
data[].chunking_strategy (1).static.max_chunk_size_tokens	integer	required; Estimated tokens per chunk.; min: 100; max: 4096
data[].chunking_strategy (1).static.chunk_overlap_tokens	integer	required; Must not exceed half of max_chunk_size_tokens.; min: 0; max: 2048
data[].chunking_strategy (2).type	"other"	required; other identifies a stored strategy whose chunk-size settings are unavailable.
data[].attributes	object / null	required; File attributes used for search filtering; null means no attributes are set.
data[].praxis	object	optional; Native ingestion progress and source-file measurements.
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.
data[].praxis.deadline_at	integer / null	required; Ingestion deadline in Unix seconds; unfinished ingestion fails when this time is reached.
data[].praxis.filename	string	required; Original source filename returned by the File service.
data[].praxis.bytes	integer	required; Original file size in bytes.; min: 0
data[].praxis.pages	integer / null	required; Number of parsed pages after successful ingestion; null before a successful parse is committed.
data[].praxis.chunk_count	integer	required; Number of ingested chunks; zero until completion and after failure or cancellation.; min: 0
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 file

GET /knowledge/v1/vector_stores/{vector_store_id}/files/{file_id}

Retrieves an attached file using the id returned by attachment or file listing. Poll this operation until status leaves in_progress to observe the ingestion outcome.

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
file_id	path: string	Required; Source File ID of an attachment, returned by file attachment or listing. min characters: 1

Request example

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

Response

HTTP 200

Field	Type	Description
id	string	required; Same ID as the source File.; min characters: 1
object	"vector_store.file"	required; Object discriminator; vector_store.file identifies a file attached to a knowledge base.
vector_store_id	string	required; Resource ID.; min characters: 1
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.
last_error	object / null	required; Ingestion failure details; null before a failure and after a successful ingestion or retry.
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.
last_error (1).message	string	required; Explanation of the ingestion failure associated with code.
usage_bytes	integer	required; Original source file size in bytes after completion; zero while pending, failed or cancelled.; min: 0
created_at	integer	required; Unix timestamp in seconds.
chunking_strategy	object / object	required; Stored chunking strategy for this attachment; auto input is returned as static settings.
chunking_strategy (1).type	"static"	required; static selects explicit chunk-size and overlap settings.
chunking_strategy (1).static	object	required; Chunk-size and overlap limits in estimated tokens.
chunking_strategy (1).static.max_chunk_size_tokens	integer	required; Estimated tokens per chunk.; min: 100; max: 4096
chunking_strategy (1).static.chunk_overlap_tokens	integer	required; Must not exceed half of max_chunk_size_tokens.; min: 0; max: 2048
chunking_strategy (2).type	"other"	required; other identifies a stored strategy whose chunk-size settings are unavailable.
attributes	object / null	required; File attributes used for search filtering; null means no attributes are set.
praxis	object	optional; Native ingestion progress and source-file measurements.
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.
praxis.deadline_at	integer / null	required; Ingestion deadline in Unix seconds; unfinished ingestion fails when this time is reached.
praxis.filename	string	required; Original source filename returned by the File service.
praxis.bytes	integer	required; Original file size in bytes.; min: 0
praxis.pages	integer / null	required; Number of parsed pages after successful ingestion; null before a successful parse is committed.
praxis.chunk_count	integer	required; Number of ingested chunks; zero until completion and after failure or cancellation.; min: 0

Update file attributes

POST /knowledge/v1/vector_stores/{vector_store_id}/files/{file_id}

Replaces search-filter attributes of an existing attachment without reingesting its content. Use an attached file id. Example body: {"attributes":{"category":"refund"}}; null clears the attributes.

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
file_id	path: string	Required; Source File ID of an attachment, returned by file attachment or listing. min characters: 1

Request body

Field	Type	Description
attributes	object / null	optional; Replaces all search-filter attributes; null clears them.

Request example

curl -X POST "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/files/${FILE_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"attributes\":{\"category\":\"refund\"}}"

Response

HTTP 200

Field	Type	Description
id	string	required; Same ID as the source File.; min characters: 1
object	"vector_store.file"	required; Object discriminator; vector_store.file identifies a file attached to a knowledge base.
vector_store_id	string	required; Resource ID.; min characters: 1
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.
last_error	object / null	required; Ingestion failure details; null before a failure and after a successful ingestion or retry.
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.
last_error (1).message	string	required; Explanation of the ingestion failure associated with code.
usage_bytes	integer	required; Original source file size in bytes after completion; zero while pending, failed or cancelled.; min: 0
created_at	integer	required; Unix timestamp in seconds.
chunking_strategy	object / object	required; Stored chunking strategy for this attachment; auto input is returned as static settings.
chunking_strategy (1).type	"static"	required; static selects explicit chunk-size and overlap settings.
chunking_strategy (1).static	object	required; Chunk-size and overlap limits in estimated tokens.
chunking_strategy (1).static.max_chunk_size_tokens	integer	required; Estimated tokens per chunk.; min: 100; max: 4096
chunking_strategy (1).static.chunk_overlap_tokens	integer	required; Must not exceed half of max_chunk_size_tokens.; min: 0; max: 2048
chunking_strategy (2).type	"other"	required; other identifies a stored strategy whose chunk-size settings are unavailable.
attributes	object / null	required; File attributes used for search filtering; null means no attributes are set.
praxis	object	optional; Native ingestion progress and source-file measurements.
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.
praxis.deadline_at	integer / null	required; Ingestion deadline in Unix seconds; unfinished ingestion fails when this time is reached.
praxis.filename	string	required; Original source filename returned by the File service.
praxis.bytes	integer	required; Original file size in bytes.; min: 0
praxis.pages	integer / null	required; Number of parsed pages after successful ingestion; null before a successful parse is committed.
praxis.chunk_count	integer	required; Number of ingested chunks; zero until completion and after failure or cancellation.; min: 0

Remove file

DELETE /knowledge/v1/vector_stores/{vector_store_id}/files/{file_id}

Removes the file from search immediately; does not delete the original File.

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
file_id	path: string	Required; Source File ID of an attachment, returned by file attachment or listing. min characters: 1

Request example

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

Response

HTTP 200

Field	Type	Description
id	string	required; Resource ID.; min characters: 1
object	"vector_store.file.deleted"	required; Object discriminator; vector_store.file.deleted identifies this deletion receipt.
deleted	true	required; Confirms removal from this knowledge base; the source File is not deleted.

Read extracted content

GET /knowledge/v1/vector_stores/{vector_store_id}/files/{file_id}/content

Extracted text chunks may overlap. Image content can be a generated description rather than verbatim OCR.

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
file_id	path: string	Required; Source File ID of an attachment, returned by file attachment or listing. min characters: 1

Request example

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

Response

HTTP 200

Field	Type	Description
object	"vector_store.file_content.page"	required; Object discriminator; vector_store.file_content.page identifies extracted file content.
data	object[]	required; All currently stored text chunks in segment-index order; neighboring chunks may overlap.
data[].type	"text"	required; text identifies an extracted text chunk.
data[].text	string	required; Extracted text of this chunk; may overlap neighboring chunks.
has_more	false	required; Always false; all currently stored chunks are returned in this response.
next_page	null	required; Always null because extracted content is not paginated.

Retry failed file

POST /knowledge/v1/vector_stores/{vector_store_id}/files/{file_id}/retry

Retries only failed files; other states return 409 FILE_INVALID_STATE. Retry after failure has not yet been observed in the documented run.

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
file_id	path: string	Required; Source File ID of an attachment, returned by file attachment or listing. min characters: 1

Request example

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

Response

HTTP 200

Field	Type	Description
id	string	required; Same ID as the source File.; min characters: 1
object	"vector_store.file"	required; Object discriminator; vector_store.file identifies a file attached to a knowledge base.
vector_store_id	string	required; Resource ID.; min characters: 1
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.
last_error	object / null	required; Ingestion failure details; null before a failure and after a successful ingestion or retry.
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.
last_error (1).message	string	required; Explanation of the ingestion failure associated with code.
usage_bytes	integer	required; Original source file size in bytes after completion; zero while pending, failed or cancelled.; min: 0
created_at	integer	required; Unix timestamp in seconds.
chunking_strategy	object / object	required; Stored chunking strategy for this attachment; auto input is returned as static settings.
chunking_strategy (1).type	"static"	required; static selects explicit chunk-size and overlap settings.
chunking_strategy (1).static	object	required; Chunk-size and overlap limits in estimated tokens.
chunking_strategy (1).static.max_chunk_size_tokens	integer	required; Estimated tokens per chunk.; min: 100; max: 4096
chunking_strategy (1).static.chunk_overlap_tokens	integer	required; Must not exceed half of max_chunk_size_tokens.; min: 0; max: 2048
chunking_strategy (2).type	"other"	required; other identifies a stored strategy whose chunk-size settings are unavailable.
attributes	object / null	required; File attributes used for search filtering; null means no attributes are set.
praxis	object	optional; Native ingestion progress and source-file measurements.
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.
praxis.deadline_at	integer / null	required; Ingestion deadline in Unix seconds; unfinished ingestion fails when this time is reached.
praxis.filename	string	required; Original source filename returned by the File service.
praxis.bytes	integer	required; Original file size in bytes.; min: 0
praxis.pages	integer / null	required; Number of parsed pages after successful ingestion; null before a successful parse is committed.
praxis.chunk_count	integer	required; Number of ingested chunks; zero until completion and after failure or cancellation.; min: 0

Batches

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

Create file batch

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

Attaches existing Files as a batch for asynchronous ingestion. Supply exactly one of file_ids or files; files allows per-file settings. Existing attachments are reused. Read the returned batch id to monitor status.

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

Provide exactly one of file_ids or files. Already attached files are reused without changing their attributes or chunking.

Field	Type	Description
(1).file_ids	string[]	required; Existing File IDs to attach with shared attributes and chunking settings. Supply file_ids or files, never both.; min items: 1; max items: 500
(1).attributes	object / null	optional; Search-filter attributes applied to each newly attached file; omission or null leaves them unset.
(1).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"}
(1).chunking_strategy (1).type	"auto"	required; auto uses the default static chunk size of 800 estimated tokens with 400 overlap tokens.
(1).chunking_strategy (2).type	"static"	required; static selects explicit chunk-size and overlap settings.
(1).chunking_strategy (2).static	object	required; Chunk-size and overlap limits in estimated tokens.
(1).chunking_strategy (2).static.max_chunk_size_tokens	integer	required; Estimated tokens per chunk.; min: 100; max: 4096
(1).chunking_strategy (2).static.chunk_overlap_tokens	integer	required; Must not exceed half of max_chunk_size_tokens.; min: 0; max: 2048
(2).files	object[]	required; Files to attach with individual attributes and chunking settings; top-level attributes and chunking_strategy are ignored.; min items: 1; max items: 500
(2).files[].file_id	string	required; Existing source File ID returned by file upload; the file must be visible to the caller.; min characters: 1
(2).files[].attributes	object	optional; File attributes used by search filters. Up to 16 keys of 64 characters; string values up to 512 characters.; max keys: 16; Key length ≤ 64; Values: string / number / boolean
(2).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"}
(2).files[].chunking_strategy (1).type	"auto"	required; auto uses the default static chunk size of 800 estimated tokens with 400 overlap tokens.
(2).files[].chunking_strategy (2).type	"static"	required; static selects explicit chunk-size and overlap settings.
(2).files[].chunking_strategy (2).static	object	required; Chunk-size and overlap limits in estimated tokens.
(2).files[].chunking_strategy (2).static.max_chunk_size_tokens	integer	required; Estimated tokens per chunk.; min: 100; max: 4096
(2).files[].chunking_strategy (2).static.chunk_overlap_tokens	integer	required; Must not exceed half of max_chunk_size_tokens.; min: 0; max: 2048
(2).attributes	JSON	optional; ignored: Ignored when files is supplied.
(2).chunking_strategy	JSON	optional; ignored: Ignored when files is supplied.

Request example

curl -X POST "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/file_batches" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"file_ids\":[\"${FILE_ID}\"]}"

Response

HTTP 200

Field	Type	Description
id	string	required; Resource ID.; min characters: 1
object	"vector_store.files_batch"	required; Object discriminator; vector_store.files_batch identifies a batch of attached files.
vector_store_id	string	required; Resource ID.; min characters: 1
status	"in_progress" / "completed" / "cancelled" / "failed"	required; cancelled means the batch was cancelled; otherwise in_progress means a member is still ingesting, failed means ingestion ended with failed members, and completed means no pending or failed members remain. Cancelling a terminal batch leaves it unchanged.
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.

Retrieve file batch

GET /knowledge/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}

Retrieves a batch created in this knowledge base, including current status and file counts. Use the batch id returned by batch creation to monitor ingestion.

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
batch_id	path: string	Required; File-batch ID returned by batch creation in this knowledge base. min characters: 1

Request example

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

Response

HTTP 200

Field	Type	Description
id	string	required; Resource ID.; min characters: 1
object	"vector_store.files_batch"	required; Object discriminator; vector_store.files_batch identifies a batch of attached files.
vector_store_id	string	required; Resource ID.; min characters: 1
status	"in_progress" / "completed" / "cancelled" / "failed"	required; cancelled means the batch was cancelled; otherwise in_progress means a member is still ingesting, failed means ingestion ended with failed members, and completed means no pending or failed members remain. Cancelling a terminal batch leaves it unchanged.
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.

Cancel file batch

POST /knowledge/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel

Cancels only in-progress batches and pending files. Completed, failed and cancelled batches return unchanged (200, idempotent).

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
batch_id	path: string	Required; File-batch ID returned by batch creation in this knowledge base. min characters: 1

Request example

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

Response

HTTP 200

Field	Type	Description
id	string	required; Resource ID.; min characters: 1
object	"vector_store.files_batch"	required; Object discriminator; vector_store.files_batch identifies a batch of attached files.
vector_store_id	string	required; Resource ID.; min characters: 1
status	"in_progress" / "completed" / "cancelled" / "failed"	required; cancelled means the batch was cancelled; otherwise in_progress means a member is still ingesting, failed means ingestion ended with failed members, and completed means no pending or failed members remain. Cancelling a terminal batch leaves it unchanged.
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.

List batch files

GET /knowledge/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/files

Lists files still attached from the identified batch, newest attachment first by default. Use the batch creation id and ?filter=failed to inspect failures; last_id is the next after cursor.

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
batch_id	path: string	Required; File-batch ID returned by batch creation in this knowledge base. min characters: 1
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"
filter	query: "in_progress" / "completed" / "failed" / "cancelled"	in_progress means ingestion is pending or running; completed means searchable; failed means ingestion failed; cancelled means ingestion was stopped by batch cancellation. Omit to include all statuses.

Request example

curl -X GET "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/file_batches/${BATCH_ID}/files" \
  -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 attached files in the requested order.
data[].id	string	required; Same ID as the source File.; min characters: 1
data[].object	"vector_store.file"	required; Object discriminator; vector_store.file identifies a file attached to a knowledge base.
data[].vector_store_id	string	required; Resource ID.; min characters: 1
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.
data[].last_error	object / null	required; Ingestion failure details; null before a failure and after a successful ingestion or retry.
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.
data[].last_error (1).message	string	required; Explanation of the ingestion failure associated with code.
data[].usage_bytes	integer	required; Original source file size in bytes after completion; zero while pending, failed or cancelled.; min: 0
data[].created_at	integer	required; Unix timestamp in seconds.
data[].chunking_strategy	object / object	required; Stored chunking strategy for this attachment; auto input is returned as static settings.
data[].chunking_strategy (1).type	"static"	required; static selects explicit chunk-size and overlap settings.
data[].chunking_strategy (1).static	object	required; Chunk-size and overlap limits in estimated tokens.
data[].chunking_strategy (1).static.max_chunk_size_tokens	integer	required; Estimated tokens per chunk.; min: 100; max: 4096
data[].chunking_strategy (1).static.chunk_overlap_tokens	integer	required; Must not exceed half of max_chunk_size_tokens.; min: 0; max: 2048
data[].chunking_strategy (2).type	"other"	required; other identifies a stored strategy whose chunk-size settings are unavailable.
data[].attributes	object / null	required; File attributes used for search filtering; null means no attributes are set.
data[].praxis	object	optional; Native ingestion progress and source-file measurements.
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.
data[].praxis.deadline_at	integer / null	required; Ingestion deadline in Unix seconds; unfinished ingestion fails when this time is reached.
data[].praxis.filename	string	required; Original source filename returned by the File service.
data[].praxis.bytes	integer	required; Original file size in bytes.; min: 0
data[].praxis.pages	integer / null	required; Number of parsed pages after successful ingestion; null before a successful parse is committed.
data[].praxis.chunk_count	integer	required; Number of ingested chunks; zero until completion and after failure or cancellation.; min: 0
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.

Search

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

Search knowledge base

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

Search ingested text to answer a question or find supporting passages. Native results contain one chunk each, so file_id can repeat; max_num_results counts chunks (1–50, default 10), while the compatible URL groups results by file. Unlike OpenAI vector stores, next_page is always null even when has_more is true. Only completed attachments are searchable. For keyword-only retrieval set ranking_options.hybrid_search to {"embedding_weight":0,"text_weight":1}; omit rewrite_query or set it to false to avoid query rewriting. Unlike OpenAI, ranker auto does not rerank; only default-2024-11-15 requests reranking. Set praxis.explain=true to inspect scores and use returned content[].chunk_id to retrieve a segment.

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
query	string / string[]	required; Nonblank text. Multiple queries are joined with newlines for one search.
filters	object / object / object	optional; Type-strict file attribute filters. At most 20 nested levels below the root.
filters (1).type	"eq" / "ne" / "gt" / "gte" / "lt" / "lte"	required; eq means equal, ne not equal, gt greater, gte greater or equal, lt less, and lte less or equal. The attribute must exist and have the same value type.
filters (1).key	string	required; Literal file-attribute key to compare, including any punctuation in the key.; min characters: 1
filters (1).value	string / number / boolean	required; Scalar value compared without type coercion.
filters (2).type	"in" / "nin"	required; in matches an attribute equal to an array member; nin matches an attribute unequal to every member. Missing attributes never match.
filters (2).key	string	required; Literal file-attribute key to compare, including any punctuation in the key.; min characters: 1
filters (2).value	string / number[]	required; String or number values tested for membership without type coercion.
filters (3).type	"and" / "or"	required; and requires every child filter to match; or requires at least one child filter to match.
filters (3).filters	object / object / object[]	required; Nonempty child-filter list combined using the selected and/or operator.; min items: 1
filters (3).filters[]	object / object / object	Repeat the same filter structure; nesting limit is 20.
max_num_results	integer	optional; Maximum chunks, not distinct files.; min: 1; max: 50; default: 10
rewrite_query	boolean	optional; supported: When true, the store's query_rewrite model first rewrites each query into a concise search query; retrieval uses the rewrite and search_query returns it. Each rewrite is one small model call billed by model usage. If a rewrite fails, times out (5 s) or is empty, that query falls back to the original text and the search still succeeds. Omitted or false makes no model call.
next_page	string	optional; ignored: Unlike OpenAI vector stores, search has no next page; supplying this cursor has no effect. Narrow the query or filters to inspect other matches.
ranking_options	object	optional; Controls result ranking and the minimum score required for inclusion.
ranking_options.ranker	"none" / "auto" / "default-2024-11-15"	optional; Unlike OpenAI, auto does not select a reranker. Only default-2024-11-15 requests reranking; none, auto and omission use the initial ranking. Reranking effect has not been measured separately.
ranking_options.score_threshold	number	optional; Minimum score. Scores are not relevance probabilities; threshold effect has not been measured separately.; min: 0; max: 1; default: 0
ranking_options.hybrid_search	object	optional; Praxis extension. Supply both nonnegative weights with a positive sum. Defaults when omitted: 0.7 / 0.3.; Praxis extension
ranking_options.hybrid_search.embedding_weight	number	required; Relative weight of semantic retrieval; zero disables semantic retrieval.; min: 0; default: 0.7
ranking_options.hybrid_search.text_weight	number	required; Relative weight of keyword retrieval; zero disables keyword retrieval.; min: 0; default: 0.3
praxis	object	optional; Set explain=true to include score and term explanations.; Praxis extension
praxis.explain	boolean	optional; Requests per-result score, rank and term explanations when true.; default: false

Request example

curl -X POST "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/search" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"query\":\"When will I receive my refund?\",\"max_num_results\":5,\"praxis\":{\"explain\":true}}"

Response

HTTP 200

Field	Type	Description
object	"vector_store.search_results.page"	required; Object discriminator; vector_store.search_results.page identifies a search result page.
search_query	string[]	required; The queries used for retrieval, one per input query; rewritten when rewrite_query is true, otherwise the input as sent.
data	object[]	required; One result per matched chunk; the same file_id can occur more than once.
data[].file_id	string	required; Resource ID.; min characters: 1
data[].filename	string	required; Original source filename for the matched file.
data[].score	number	required; Relevance ranking score for this chunk, clamped to the range 0 to 1; not a probability.; min: 0; max: 1
data[].attributes	object / null	required; Current file attributes used for filtering; null when unset.
data[].content	object[]	required; Matched chunk text and its source coordinates; one chunk per native result.
data[].content[].type	"text"	required; text identifies an extracted text chunk.
data[].content[].text	string	required; Extracted text of the matched chunk, which may overlap neighboring chunks.
data[].content[].chunk_id	string	optional; Resource ID.; min characters: 1
data[].content[].page	integer / null	optional; One-based source page containing the start of this chunk; null when no page mapping is available.
data[].content[].span	integer[]	optional; Start and end offsets in UTF-16 code units.; min items: 2; max items: 2
data[].praxis	object	optional; Native search explanation, included only when praxis.explain is requested.
data[].praxis.explain	object	required; Per-chunk retrieval scores, ranks and matched query terms.
data[].praxis.explain.semantic_score	number / null	required; Semantic retrieval score for this chunk; null when absent from semantic candidates.
data[].praxis.explain.keyword_score	number / null	required; Keyword retrieval score for this chunk; null when absent from keyword candidates.
data[].praxis.explain.rerank_score	number / null	required; Score from the reranking model; null when reranking was not applied.
data[].praxis.explain.semantic_rank	integer / null	required; One-based position in semantic candidates; null when not recalled by that route.
data[].praxis.explain.keyword_rank	integer / null	required; One-based position in keyword candidates; null when not recalled by that route.
data[].praxis.explain.rank_before_rerank	integer	required; One-based fused rank before reranking; without reranking, the position among returned filtered results.; min: 1
data[].praxis.explain.query_terms	string[]	required; Normalized query terms used in the explanation, including adjacent Han-character pairs.
data[].praxis.explain.matched_terms	string[]	required; Query terms found in the normalized chunk text.
has_more	boolean	required; True when filtered chunks exceed max_num_results; next_page remains null.; supported:
next_page	null	required; ignored: Always null; no next search page.

Segments

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

List file segments

GET /knowledge/v1/vector_stores/{vector_store_id}/files/{file_id}/segments

Lists the stored chunks of an attached file, ordered by increasing segment index by default. Use the attachment id and last_id as after to continue; returned chunk ids can be retrieved individually.

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
file_id	path: string	Required; Source File ID of an attachment, returned by file attachment or listing. min characters: 1
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: "asc"

Request example

curl -X GET "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/files/${FILE_ID}/segments" \
  -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 segments in the requested order.
data[].id	string	required; Resource ID.; min characters: 1
data[].file_id	string	required; Resource ID.; min characters: 1
data[].index	integer	required; Zero-based position of this chunk in the source document.; min: 0
data[].text	string	required; Extracted text covered by this chunk; neighboring chunks may overlap.
data[].tokens	integer	required; Estimated token count of this chunk, not a model tokenizer count.; min: 0
data[].page	integer / null	required; One-based source page containing the chunk start; null when no page mapping is available.
data[].span	integer[]	required; Start and end offsets in UTF-16 code units.; min items: 2; max items: 2
data[].overlap_prev_tokens	integer	required; Estimated tokens shared with the previous chunk; zero for the first chunk.; min: 0
data[].overlap_next_tokens	integer	required; Estimated tokens shared with the next chunk; zero for the last chunk.; min: 0
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 segment

GET /knowledge/v1/vector_stores/{vector_store_id}/segments/{chunk_id}

Retrieves one chunk and its term statistics. Take chunk_id from segment listing or native search content; the chunk must belong to this knowledge base.

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
chunk_id	path: string	Required; Chunk ID returned by segment listing or native search content. min characters: 1

Request example

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

Response

HTTP 200

Field	Type	Description
id	string	required; Resource ID.; min characters: 1
file_id	string	required; Resource ID.; min characters: 1
index	integer	required; Zero-based position of this chunk in the source document.; min: 0
text	string	required; Extracted text covered by this chunk; neighboring chunks may overlap.
tokens	integer	required; Estimated token count of this chunk, not a model tokenizer count.; min: 0
page	integer / null	required; One-based source page containing the chunk start; null when no page mapping is available.
span	integer[]	required; Start and end offsets in UTF-16 code units.; min items: 2; max items: 2
overlap_prev_tokens	integer	required; Estimated tokens shared with the previous chunk; zero for the first chunk.; min: 0
overlap_next_tokens	integer	required; Estimated tokens shared with the next chunk; zero for the last chunk.; min: 0
terms	object[]	required; Terms occurring in this chunk with local frequency and store-wide chunk counts.
terms[].term	string	required; Lowercase text token; consecutive Han characters also produce adjacent two-character terms.
terms[].count	integer	required; Number of occurrences of this term in this chunk.; min: 0
terms[].chunks_in_store	integer	required; Number of indexed chunks in this store containing the term.; min: 0

Events

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

List events

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

Reads events for this knowledge base in increasing sequence order, including while soft-deleted. Pass next_seq as after_seq to continue; null next_seq marks the current end. Example: ?after_seq=0&limit=20.

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
after_seq	query: integer	Return events with larger seq. Use next_seq to continue; invalid text is currently ignored. default: 0
limit	query: integer	Page size. min: 1; max: 100; default: 20

Request example

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

Response

HTTP 200

Field	Type	Description
data	object[]	required; Events with seq greater than after_seq, ordered by increasing seq.
data[].seq	integer	required; Store-local increasing event sequence; pass the returned next_seq as after_seq to continue.; min: 1
data[].id	string	required; Server-generated UUID identifying this event.
data[].type	"vector_store.created" / "vector_store.updated" / "vector_store.expired" / "vector_store.deleted" / "vector_store.restored" / "file.attached" / "file.stage_changed" / "file.completed" / "file.failed" / "file.cancelled" / "file.removed" / "batch.created" / "batch.completed" / "batch.cancelled"	required; Kind of store, file-ingestion or batch event recorded in this knowledge base.
data[].processed_at	integer	required; Unix timestamp in seconds.
data[].vector_store_id	string	required; Resource ID.; min characters: 1
data[].file_id	string / null	required; Associated source File ID; null for events without a file.
data[].batch_id	string / null	required; Associated file-batch ID; null for events without a batch.
data[].data	object	required; Event-specific details; stage changes include stage, ingestion failures include code, and other events may use an empty object.
next_seq	integer / null	required; Pass as after_seq for the next page; null means the end.