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