Vector stores

The official openai Python SDK can use vector stores, files and batches directly. Both URLs access the same data.

https://api.deepraxis.ai/openai/v1

Current differences

Search returns chunks, so a file may appear more than once; max_num_results counts chunks. rewrite_query: true first rewrites the query with a small model (billed by model usage; falls back to the original query on failure); the model it uses can only be set through models on the native API, and passing models here returns 400. Search has_more is always false and next_page always null. description is accepted but discarded. expand=files and expand[]=files are Praxis extensions; unknown values are ignored.

Deleted stores are retained for 7 days. Retrieval can still return 200 completed, while writes and search return 409. Use the native API for restore, retry, segments, events and hybrid-search weights. Compatible responses omit praxis, chunk_id, page and span. usage_bytes counts extracted chunk text bytes. Unknown request fields are currently ignored.

Native API · Errors

Method	Path	Operation
POST	/openai/v1/vector_stores	Create knowledge base
GET	/openai/v1/vector_stores	List knowledge bases
GET	/openai/v1/vector_stores/{vector_store_id}	Retrieve knowledge base
POST	/openai/v1/vector_stores/{vector_store_id}	Update knowledge base
DELETE	/openai/v1/vector_stores/{vector_store_id}	Delete knowledge base
POST	/openai/v1/vector_stores/{vector_store_id}/search	Search knowledge base
POST	/openai/v1/vector_stores/{vector_store_id}/files	Add file
GET	/openai/v1/vector_stores/{vector_store_id}/files	List files
GET	/openai/v1/vector_stores/{vector_store_id}/files/{file_id}	Retrieve file
POST	/openai/v1/vector_stores/{vector_store_id}/files/{file_id}	Update file attributes
DELETE	/openai/v1/vector_stores/{vector_store_id}/files/{file_id}	Remove file
GET	/openai/v1/vector_stores/{vector_store_id}/files/{file_id}/content	Read extracted content
POST	/openai/v1/vector_stores/{vector_store_id}/file_batches	Create file batch
GET	/openai/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}	Retrieve file batch
POST	/openai/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel	Cancel file batch
GET	/openai/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/files	List batch files

Create knowledge base

POST /openai/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.

Request example

curl -X POST "https://api.deepraxis.ai/openai/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"	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.
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

Error codes and objects

List knowledge bases

GET /openai/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
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/openai/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"	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.
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
first_id	string / null	required; ID of the first item on this page; null for an empty page.
last_id	string / null	required; ID of the last item on this page; use as after to continue. Null for an empty page.
has_more	boolean	required; Whether additional items remain after this page within the selected cursor range.

Error codes and objects

Retrieve knowledge base

GET /openai/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. Deleted stores return 404.

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/openai/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"	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.
(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
(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.first_id	string / null	required; ID of the first item on this page; null for an empty page.
(2).files.last_id	string / null	required; ID of the last item on this page; use as after to continue. Null for an empty page.
(2).files.has_more	boolean	required; Whether additional items remain after this page within the selected cursor range.

Error codes and objects

Update knowledge base

POST /openai/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

Request example

curl -X POST "https://api.deepraxis.ai/openai/v1/vector_stores/${VECTOR_STORE_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"Support 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"	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.
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

Error codes and objects

Delete knowledge base

DELETE /openai/v1/vector_stores/{vector_store_id}

Deletes the store. Subsequent retrieve and repeat DELETE return 404 not_found_error; lists exclude deleted stores. Native restore remains available for 7 days.

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/openai/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.deleted"	required; Object discriminator; vector_store.deleted identifies this deletion receipt.
deleted	true	required; Confirms deletion on the compatible surface; subsequent access returns not found.

Error codes and objects

Search knowledge base

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

Search ingested files, grouping matched chunks by file with chunks sorted by score in content. max_num_results counts files; up to 50 candidate chunks are grouped. Unlike OpenAI vector stores, this compatible URL rejects ranking_options.hybrid_search with 400 INVALID_PARAMS and does not paginate; has_more reports truncated files but next_page remains null. Use /knowledge/v1 for hybrid weights and per-chunk results. Only ranker default-2024-11-15 requests reranking; auto, none and omission use the initial ranking.

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 unique files after grouping the retrieved chunks (up to 50 candidate chunks).; 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; unsupported: Rejected with 400 INVALID_PARAMS on /openai/v1. Use /knowledge/v1 for weights.; 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; ignored: Compatibility responses remove praxis, including explanations.
praxis.explain	boolean	optional; Requests explanations internally; the compatible response omits them.

Request example

curl -X POST "https://api.deepraxis.ai/openai/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}"

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 unique file; content contains its matched chunks.
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; Highest matched chunk score for this file.; min: 0; max: 1
data[].attributes	object / null	required; Current file attributes used for filtering; null when unset.
data[].content	object[]	required; Matched chunks in descending chunk-score order.
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.
has_more	boolean	required; True when filtered files exceed max_num_results; next_page remains null.; supported:
next_page	null	required; ignored: Always null; no next search page.

Error codes and objects

Add file

POST /openai/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/openai/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.

Error codes and objects

List files

GET /openai/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/openai/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.
first_id	string / null	required; ID of the first item on this page; null for an empty page.
last_id	string / null	required; ID of the last item on this page; use as after to continue. Null for an empty page.
has_more	boolean	required; Whether additional items remain after this page within the selected cursor range.

Error codes and objects

Retrieve file

GET /openai/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/openai/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.

Error codes and objects

Update file attributes

POST /openai/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/openai/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.

Error codes and objects

Remove file

DELETE /openai/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/openai/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.

Error codes and objects

Read extracted content

GET /openai/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/openai/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.

Error codes and objects

Create file batch

POST /openai/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/openai/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.

Error codes and objects

Retrieve file batch

GET /openai/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/openai/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.

Error codes and objects

Cancel file batch

POST /openai/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/openai/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.

Error codes and objects

List batch files

GET /openai/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/openai/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.
first_id	string / null	required; ID of the first item on this page; null for an empty page.
last_id	string / null	required; ID of the last item on this page; use as after to continue. Null for an empty page.
has_more	boolean	required; Whether additional items remain after this page within the selected cursor range.

Error codes and objects

Vector stores

On this page