Build document Q&A

At the end of this guide, your server can answer a question such as "How many vacation days do new employees get?" from your own handbook, and show which file the answer came from. The flow is:

1. 1A user JWT prepares a project and a project API key (once).
2. 2Your server uploads documents and indexes them in a vector store.
3. 3For each question, your server calls Responses with the project key, and Mahvash retrieves relevant passages and answers with citations.

Each step below links to the exact API actions and shows a request and an illustrative response.

Create (or choose) a project for this knowledge base using a user JWT, then issue a project API key for your server. Keeping documents in their own project means their files, stores and key cannot be mixed up with other workloads.

Store the key in your secret manager. Every following call uses it, and everything it creates belongs to this project.

Upload each document with POST /v1/files as multipart/form-data and keep the returned file-... ID in your own database next to your document record.

• Use purpose=user_data for documents you want to search.
• For large files, use a resumable upload session instead; it produces the same kind of file object.
• Do not send files as base64 JSON.

Create a vector store in the same project and attach the file to it. Attaching starts indexing; poll the vector store file until its status is completed.

• failed means the document could not be processed — check last_error, fix the source and try again.
• A store can hold many files. Group documents that should be searched together, and use separate stores when different users may read different documents.

You have two options for using the store:

• Explicit search: name the store in each request's file_search tool (step 5). Best when different users may search different stores.
• Project data source: attach the store to the project. With project auto-search enabled, every request that does not set its own tools searches the project's data sources automatically. Best when everyone using the project may search the same knowledge.

Attaching a data source is different from attaching a file to a store: it does not upload or index anything. Requests can still opt out with tools: [] or tool_choice: "none".

Send a Responses request with the project key. The request and illustrative response at the end of this step use an explicit file_search tool.

The response contains a file_search_call item followed by the assistant message. Citations are annotations on the output_text, not text inside the answer:

• file_citation annotations carry the Mahvash file_id and filename the passage came from.
• Map file_id to your own document record and render a link to your own viewer, protected by your own permissions.
• If the answer has no citation, show it as unsupported rather than presenting it as sourced.

Documents change, so plan how they leave the system as carefully as how they enter it:

• Replace a document: upload the new version, attach it to the store, wait for completed, then remove the old file from the store.
• Stop project-wide retrieval: detach the data source. Existing responses keep their citations.
• Remove content: removing a file from a store deletes its index entries but keeps the file; delete the file separately, then delete the store when it is empty.