Getting started

Quickstart

Send your first question, check its status and read the completed answer.

This walkthrough covers one complete request: authenticate, submit a question, check its status and read the result. Each step has a copyable example in the code panel.

Before you start

An API key for your workspace. Keys are issued from the Synquery app. If you don't have access yet, request API access.
A terminal with curl, or any HTTP client.

1. Authenticate

Every call sends your key in the x-api-key header. Check that your key works by calling GET /usage, which returns your balance and limits at once.

2. Submit a question

Send the question, who should answer it and the fields each expert fills in. The call returns at once with a request_id and status: "pending". Add an Idempotency-Key header so a retried call never creates a second request.

3. Check the status

Poll GET /questions/{request_id}, or set a callback_url to receive webhooks instead. While the request is pending, responses holds every confirmed answer so far, so you can read answers as they arrive.

4. Read the completed answer

When status is complete, the response adds the synthesis: a short answer, a summary per field, agreement, confidence and any warnings. Each entry in responses is one expert's answer, with their profile, their own words and what the answer is based on.

How long it takes

Real requests are answered by people, so they take hours, not seconds. Most requests with 3–5 experts complete within 24 hours, and the eta field tells you when to expect the result. Set a deadline if you need the answer by a set time. A sandbox that returns realistic fake answers in seconds is on the roadmap.

Authentication →

curl -X POST https://api.synquery.com/v0/questions \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: robotic-knee-share-001" \ -d '{ "question": "What share of total knee replacements at US hospitals now use robotic assistance, and what is driving adoption?", "expert_requirements": { "sides": ["surgeon", "or_director"], "experience_with": "Robotic-assisted knee replacement", "num_experts": 3 }, "answer_fields": [ {"name": "robotic_share", "type": "range", "unit": "%", "description": "Share of total knee replacements done with robotic assistance"}, {"name": "adoption_drivers", "type": "list", "description": "What is driving adoption"} ] }'

{ "request_id": "q_8f2k1x", "status": "complete", "partial": false, "experts_delivered": 3, "answer": "All three experts put robotic assistance at 20–30% of total knee replacements at the hospitals they know.", "summary": { "robotic_share": {"low": 20, "high": 30, "basis": "first_hand", "n": 3, "received": 3}, "adoption_drivers": {"top": ["Surgeon training and recruitment", "Patient demand"], "n": 3} }, "agreement": {"agreeing": 3, "total": 3, "on": "robotic_share"}, "confidence": "high", "responses": ["…one entry per expert…"] }