Stores, Files and Knowledge Bases - Which One Holds What

An agent platform has five places a piece of content can live, and the way to tell them apart is not what shape the content is. It is what the platform can see inside it.

Home	What the platform sees	Reached by	Right for
Store	JSON documents it indexes, filters, orders and pages	`store_query`, `store_get`, `store_put` and `store_delete` in a run; `/v1/stores`; a hosted route	Records an agent produces or an application reads: leads, listings, one row per customer
File	Bytes it does not look inside, except to read them to a run	`attachments` on a run; `/v1/files`; a published path on a hosted route	A receipt, a supplier PDF, a spreadsheet, a generated dashboard bundle
Knowledge base	Prose it chunks, embeds and searches by meaning	`search_knowledge` in any conversation or run	Manuals, policies, FAQs: things an agent looks things up in
Memory	Facts about one person, kept across conversations	Automatically, keyed on `user_identity`	What an agent should remember about who it is talking to
Sandbox disk	A scratch filesystem for one execution attempt	`run_code` in a run	Computing over data during a run. Nothing here survives the run unless it leaves as a file

Two rules follow from the table.

A store is not the file drop. If you are holding bytes - a PDF, an image, a bundle an agent generated - it is a file, even if the agent will later put what it reads into a store.

A knowledge base is not a store. A knowledge base answers “find me the passage about refunds”; a store answers “give me every order over 100 placed since Monday”. The same catalog can need both, and today that means writing it to both.

A store is a document database

If you know Firestore, you know the model: store > collection > document, schemaless JSON, where clauses on the top-level fields, one order_by, a limit, and cursor paging. Two agents can share a store without agreeing a schema first; a writer that adds a field does not break a reader that has never seen it.

What a store deliberately does not have, so that the small surface stays small:

Not in a store	Use instead
Joins across collections	Model the join into the document, or bring your own database through a webhook or MCP tool
Filters on nested fields	Lift the field to the top level; the projection indexes top-level scalars only, strings cut at 256 characters
Full-text search	A knowledge base
SQL	Your own database, reached through a webhook or MCP tool

Aggregation is the one addition still to come; after it, the surface is capped.

Putting a document in a store, and a file in the drop

The two requests look alike and are not. A document is JSON the platform will index; a file is bytes it will keep whole.

POST

/v1/stores/:store_id/collections/:collection/documents

1 curl -X POST https://api.speechify.ai/v1/stores/store_01jqr8x9zg5k2m3n4p5q6r7s8t/collections/items/documents \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "data": {}
6 }'

Try it

POST

/v1/files

1 curl -X POST https://api.speechify.ai/v1/files \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: multipart/form-data" \
4      -F file=@"[object Object]" \
5      -F kind='{
6   "type": "json"
7 }' \
8      -F path='{
9   "type": "json"
10 }' \
11      -F project_id='{
12   "type": "json"
13 }' \
14      -F user_identity='{
15   "type": "json"
16 }'

Try it

How a hosted API serves each

A hosted API route resolves to one of these, and each answers differently.

Resolver	Serves	Notes
`store_query`	A filtered, ordered page of a collection as JSON	Filters bind from the request through `{{query.x}}`, `{{path.x}}` and `{{body.x}}`
`store_document`	One document by id	Usually a path parameter
`file`	A published file’s bytes, under its own media type	Only a `kept`, workspace-wide file resolves; a file scoped to a person is never published, because a route answers whoever holds the URL
`run_latest`	The newest structured result a scheduled agent produced
`run`	An agent’s answer to this request	The customer’s backend function: anything without a fast path goes through here

A knowledge base is never served by a route directly. An agent searches it during a run, and the run’s result is what a route serves.

Three worked picks

A customer emails a receipt. A file. Upload it, name it in the run’s attachments, and the agent reads it while it works. It expires on its own unless you keep it.

A product catalog with prices and descriptions. A store for the prices and availability, so a route can filter and count; a knowledge base for the descriptions, so an agent can search them. Two homes for one catalog is a limit of today’s platform, and it is a known one.

A policy handbook. A knowledge base. Nobody filters a handbook; they ask it questions.

One thing that is not obvious

An agent can consume any hosted API - its own workspace’s, another workspace’s, or anyone else’s - through a webhook or MCP tool. The platform blocks private and loopback addresses, not public hosts, so a hosted API’s host is reachable like any other public endpoint. An agent reaching its own workspace’s store still goes through its store tools, in-process; a route is for callers outside the workspace.