Quickstart
Create a key, make your first attested Gateway call, upload a document, query it, and read the proof certificate.
Four short steps take you from nothing to a signed answer grounded in your own document. Every example works as written once SUBSIDIA_API_KEY is set. You need a Subsidia account with an active plan or trial; the questions you ask here count against it (see Rate limits and quotas).
1. Create an API key
Open the Gateway page of the Subsidia console at https://subsidia.protypa.fr/console/gateway and create a key. For this guide give it the engine scope (Gateway and proofs) and the knowledge scope (documents and queries). The full key, starting with sk_live_, is shown once: copy it immediately.
A key that carries any of these capability scopes can reach only the route families it names, which is what you want for anything that leaves your laptop. Scopes, ceilings and read-only keys are covered in Authentication.
export SUBSIDIA_API_KEY="sk_live_..."2. Make your first Gateway call
The Gateway is OpenAI compatible, so the simplest call is a chat completion. pulse-auto lets Synapse choose the model for the task. The response carries an x-pulse-proof header: the id of the signed certificate for this exact exchange. Keep it.
curl -i https://api.subsidia.protypa.fr/v1/chat/completions \ -H "Authorization: Bearer $SUBSIDIA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "pulse-auto", "messages": [ {"role": "user", "content": "In one sentence, what is a hash chain?"} ] }'3. Upload a document and query it
Cortex is the knowledge side of the engine. Upload a file (PDF, DOCX, XLSX, PPTX, CSV, EML, or an image for OCR, up to 25 MB) as multipart/form-data. Ingestion is asynchronous: the upload returns a source id and a status, and the document is searchable once the status is ready. Uploading the same content twice returns duplicate instead of ingesting it again. Details in Knowledge sources.
curl https://api.subsidia.protypa.fr/v1/knowledge-sources/upload \ -H "Authorization: Bearer $SUBSIDIA_API_KEY" \ -F "file=@./bail-commercial.pdf" \ -F "name=Bail commercial 2024"curl https://api.subsidia.protypa.fr/v1/knowledge-sources/$SOURCE_ID \ -H "Authorization: Bearer $SUBSIDIA_API_KEY"# repeat every few seconds until "status" is "ready" ("failed" means ingestion did not complete)Now ask a question. POST /v1/knowledge/query runs the full retrieval pipeline and returns matches (the passages) and a trace that explains why each one matched. It does not generate prose: it is the retrieval half, for you to feed into your own prompt or to display as citations. See Knowledge query.
curl https://api.subsidia.protypa.fr/v1/knowledge/query \ -H "Authorization: Bearer $SUBSIDIA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "What is the notice period to terminate the lease?", "topK": 5}'To get a generated, grounded answer with a certificate instead of raw passages, add +cortex to the model address. The Gateway retrieves the passages, writes the answer, and hashes the exact passages used into the certificate.
curl -i https://api.subsidia.protypa.fr/v1/chat/completions \ -H "Authorization: Bearer $SUBSIDIA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "pulse-auto+cortex", "messages": [{"role": "user", "content": "What is the notice period to terminate the lease?"}] }'4. Read and verify the proof
The certificate commits, by SHA-256, to your request, to what actually left toward the model provider after masking, and to the response. For a +cortex call it also lists the passages the answer drew on, in a grounding array. It never contains the content itself. Fetch it with the id from x-pulse-proof, then ask the server to verify the signature and the chain link.
# the certificatecurl https://api.subsidia.protypa.fr/v1/proofs/$PROOF_ID \ -H "Authorization: Bearer $SUBSIDIA_API_KEY"
# server-side verification: signature_valid, chain_valid, validcurl https://api.subsidia.protypa.fr/v1/proofs/$PROOF_ID/verify \ -H "Authorization: Bearer $SUBSIDIA_API_KEY"