Knowledge
Batches
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 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. |