Knowledge

Knowledge lets a model search your own documents. You make a knowledge base, add documents to it, and name it in a request: the model calls the hosted search tool when it needs to, HIPS searches the base and hands the model numbered passages with their sources, and the answer records which passages the model was given. It works with every model whose tool calls are validated, and it follows OpenAI's vector store API and its file_search tool, so the OpenAI SDKs call it with the HIPS key and base URL.

Note

Knowledge is built and not switched on in production yet. Until it is, every /v1/vector_stores path answers 404 route_not_found, a Messages or Responses request naming hips:knowledge_search or file_search answers 400 unsupported_value at tools ("not served on this platform yet"), chat completions refuse the tool entry as a field they do not know, and the Console's Knowledge screens are hidden.

Fig. 1, sheet 16Knowledge

A knowledge base

A base is a vector_store whose id is its kb_ id. It belongs to one workspace and is never shared with another.
It has one embedding model, chosen at creation and fixed for its life, and its own requirements: a pool (Auto by default, or certified) and a region (eu alone at first; another is refused with 400 region_unavailable until a regional store exists).
Its requirements bind its ingestion and every request that searches it: a request whose own requirements cannot meet the base's is a 400 requirement_conflict naming both, never placed where the base does not allow.

Adding documents

Upload a file with POST /v1/files and purpose: "user_data" (assistants is taken as its alias), then add it to the base. Each document is read in isolation, normalized, cut into chunks along its structure and embedded on GPUs, with a stage you can watch.

Formats

Format	Read
Plain text, Markdown	As it is
HTML	Its main content, as Markdown
PDF with a text layer	The text layer, page by page, so a passage knows its pages
`.docx`, `.pptx`, `.xlsx`	Headings, paragraphs, lists and tables; slides in order with their notes; each sheet a table
CSV, JSON	A table, and indented text
Scanned PDFs, images	Not yet: they need a recognition model served on GPUs, and fail with `empty_text` until then

Stages

Stage (`hips.stage`)	`status`	What happens
`queued`	`in_progress`	Waiting for a slot, oldest first
`extracting`	`in_progress`	The file's text is read and normalized
`chunking`	`in_progress`	Cut along its structure
`embedding`	`in_progress`	Embedded; `hips.progress` counts the chunks. A model HIPS cannot reach keeps it here with `hips.delayed: true`, never failed for HIPS's outage
`completed`	`completed`	Searchable
`failed`	`failed`	`last_error` with its code and sentence
`cancelled`	`cancelled`	A file batch canceled before the document was read

Failures

Code	When	What to do
`unsupported_file`	Not a format above	Send another format
`file_unreadable`	Protected, encrypted or broken	Send a readable copy
`empty_text`	No text read (a scan, an image)	Send a file with a text layer
`too_large`, `too_many_pages`	Over the bounds per file Not decided yet	Split it
`limit_reached`	The workspace's chunk limit Not decided yet	Retry once there is room
`embedding_failed`	The embedding model refused its input	Retry

A failed document stays listed with its reason until it is deleted, and counts toward no total, limit or storage.

Searching from a model

Name the hosted tool and the base in tools; the model decides when to search and writes the query. One base a search for now.

Route	The tool entry	What the answer records
`POST /v1/chat/completions`	`{"type": "hips:knowledge_search", "parameters": {"knowledge_base_ids": ["kb_..."], "max_num_results": 5}}`	The calls in a top-level `hips.tool_calls` of the answer, each with its `results`; `message.tool_calls` holds only your own functions' calls
`POST /v1/messages`	`{"type": "hips:knowledge_search", "name": "knowledge_search", "knowledge_base_ids": ["kb_..."]}`	A `server_tool_use` block and its `hips_tool_result` block, one Anthropic `search_result` block per passage
`POST /v1/responses`	`{"type": "file_search", "vector_store_ids": ["kb_..."]}`	A `file_search_call` item with its `queries`, and its `results` when `include` holds `file_search_call.results`; `file_citation` annotations where the model cites a passage

The model must have validated tool calls in the pool the request resolves to (hips.tool_calls on Models); otherwise a 400 unsupported_parameter.
The tool is offered once its price per call is published: until then a 400 tool_not_available, and nothing is charged.
usage.server_tool_use.knowledge_search_requests counts the searches that ran; the token counts are every pass's, summed.
On Messages and Responses, stream: true with the tool is a 400 unsupported_value for now: it is served on whole answers. On chat completions a streamed request is answered once the search loop is done.
A base that is not the workspace's, or is being deleted, is a 404 knowledge_base_not_found before the model runs.

Searching from your code

POST /v1/vector_stores/{id}/search runs the same search without a model and answers OpenAI's search results page (Vector stores).

Citations

The record in the answer is the citation that always holds: which passages the model was given, from which document and where (file, heading path, byte offsets, pages). Where the model wrote a marker [n] naming a passage of the request, the Responses route adds a file_citation annotation at the marker and leaves the text as the model wrote it. Whether a model writes markers is the model's: the record is the guarantee, the annotations best effort.

Who reads your documents

Base pool	Who reads the documents
Auto	At ingestion, every chunk is an embedding input on a GPU of whichever pool serves it, a provider's device included; at a search, the passages reach the device or server that serves the request's next pass, under its sandbox and data handling, as any prompt does
Certified	Only the Certified pool's GPUs read the chunks and the passages

The store, the chunks and the search run on the platform in the European Union (Ireland); a search from another region is one round trip there. The passages are data for the model, never instructions.

Limits

Limit	Value
Knowledge bases a workspace, documents a base, a file's size and pages, chunks a workspace	Not decided yet
Documents a workspace keeps as `user_data` files	Not decided yet; past it, 400 `limit_reached`
Ingestion at once and per hour	Not decided yet; past it, 429 `rate_limit_exceeded` with `param: "knowledge_ingest"`
Searches	Counted as requests of your limits; 429 with `param: "knowledge_search"`
Bases a search, results, passages from one document	One base for now; the rest Not decided yet

Deletion and export

Removing a document from a base removes its text, chunks and vectors at once; the File stays until you delete it.
Deleting a base marks it so nothing reads it, then purges it.
A base set to expire with expires_after is purged after that many days unused; HIPS sets no expiry of its own.
Reads, exports and deletes answer whatever the workspace's state, so you can always take your documents out: GET /v1/vector_stores/{id}/files/{file_id}/content gives a document's text.

Billing

What	How it is billed
Ingestion	The embedding compute it uses, per started second at the base's embedding model's own rate (H109), on your usage as `knowledge_ingest`
Storage	A base's stored bytes, and a document's File while kept, at the storage price of $0.10 per GB-month (decided 2026-11-07)
A search	Per call, at a price not published yet Not decided yet, the query's embedding included; a rerank on top per started second
A failed call, an outage	Not charged

In the Console

Knowledge in the side menu, once it is switched on: the bases, a base with its documents and their stages, uploads, a search to try, and the storage and its cost. The screens are built and hidden while the platform does not serve Knowledge.

Sheet: 16 of 19
Updated: 2026-11-11

Format

Read

Plain text, Markdown

As it is

HTML

Its main content, as Markdown

PDF with a text layer

The text layer, page by page, so a passage knows its pages

.docx, .pptx, .xlsx

Headings, paragraphs, lists and tables; slides in order with their notes; each sheet a table

CSV, JSON

A table, and indented text

Scanned PDFs, images

Not yet: they need a recognition model served on GPUs, and fail with empty_text until then

Stage (`hips.stage`)

`status`

What happens

queued

in_progress

Waiting for a slot, oldest first

extracting

in_progress

The file's text is read and normalized

chunking

in_progress

Cut along its structure

embedding

in_progress

Embedded; hips.progress counts the chunks. A model HIPS cannot reach keeps it here with hips.delayed: true, never failed for HIPS's outage

completed

Searchable

failed

last_error with its code and sentence

cancelled

A file batch canceled before the document was read

Code

When

What to do

unsupported_file

Not a format above

Send another format

file_unreadable

Protected, encrypted or broken

Send a readable copy

empty_text

No text read (a scan, an image)

Send a file with a text layer

too_large, too_many_pages

Over the bounds per file Not decided yet

Split it

limit_reached

The workspace's chunk limit Not decided yet

Retry once there is room

embedding_failed

The embedding model refused its input

Retry

Route

The tool entry

What the answer records

POST /v1/chat/completions

{"type": "hips:knowledge_search", "parameters": {"knowledge_base_ids": ["kb_..."], "max_num_results": 5}}

The calls in a top-level hips.tool_calls of the answer, each with its results; message.tool_calls holds only your own functions' calls

POST /v1/messages

{"type": "hips:knowledge_search", "name": "knowledge_search", "knowledge_base_ids": ["kb_..."]}

A server_tool_use block and its hips_tool_result block, one Anthropic search_result block per passage

POST /v1/responses

{"type": "file_search", "vector_store_ids": ["kb_..."]}

A file_search_call item with its queries, and its results when include holds file_search_call.results; file_citation annotations where the model cites a passage

Base pool

Who reads the documents

Auto

At ingestion, every chunk is an embedding input on a GPU of whichever pool serves it, a provider's device included; at a search, the passages reach the device or server that serves the request's next pass, under its sandbox and data handling, as any prompt does

Certified

Only the Certified pool's GPUs read the chunks and the passages

Limit

Value

Knowledge bases a workspace, documents a base, a file's size and pages, chunks a workspace

Not decided yet

Documents a workspace keeps as user_data files

Not decided yet; past it, 400 limit_reached

Ingestion at once and per hour

Not decided yet; past it, 429 rate_limit_exceeded with param: "knowledge_ingest"

Searches

Counted as requests of your limits; 429 with param: "knowledge_search"

Bases a search, results, passages from one document

One base for now; the rest Not decided yet

What

How it is billed

Ingestion

The embedding compute it uses, per started second at the base's embedding model's own rate (H109), on your usage as knowledge_ingest

Storage

A base's stored bytes, and a document's File while kept, at the storage price of $0.10 per GB-month (decided 2026-11-07)

A search

Per call, at a price not published yet Not decided yet, the query's embedding included; a rerank on top per started second

A failed call, an outage

Not charged

A knowledge base

Adding documents

Searching from a model

Searching from your code

Citations

Who reads your documents

Limits

Deletion and export

Billing

In the Console

Related sheets

A knowledge base

Adding documents

Searching from a model

Searching from your code

Citations

Who reads your documents

Limits

Deletion and export

Billing

In the Console

Related sheets