Apps, workspaces, resources

The three objects everything else is built on.

Three objects, nested strictly. Almost every design question with this API comes down to how you map your own domain onto the middle one.

Apps

An app is your integration. It owns one API key and every workspace beneath it, and you create it in the console rather than through this API — there is no endpoint for apps here, because the key already tells the server which one you mean.

Use more than one app when you have genuinely separate integrations that should not share a credential — a staging environment, or a second product. Everything within one app is reachable by one key.

Workspaces

A workspace is a set of documents that get answered together, and it is the only boundary retrieval respects. A question asked in one workspace can never surface a passage from another, whatever the wording.

That guarantee is the reason to model separation as workspaces rather than as a filter you apply yourself. There is no way to ask across two workspaces in one request, and no way to accidentally leak between them.

Resources

A resource is one uploaded document inside a workspace. It carries the original file, the text extracted from it, a model-written summary, and the indexed passages retrieval actually searches.

A resource only becomes answerable when its status reaches ready. Until then it exists, is listed, and contributes nothing.

Choosing your workspace shape

Three shapes cover almost every integration. Pick by asking who must never see whose documents:

One workspace per end customer — A patient, a client, a student. Strongest isolation, and the shape the product was designed around. Costs one create call per customer.
One workspace per team or topic — Engineering handbook, HR policy, product docs. Fewer workspaces, and every member of that team sees the same answers.
One shared workspace — A public help centre where every reader may see every document. Simplest, and only correct when there is genuinely nothing to separate.

You cannot merge or split workspaces later, and moving a document means re-uploading and re-ingesting it. Choose the shape before you load documents at scale.