Research that helps people and the planet.

1. Access & authentication

• Plan: Business (or admin). Plus/Free cannot mint keys.
• Create a key: Workspace → Settings → Research API keys, or use Create key in the try form below (while logged in). The full ds_… secret is shown only once at creation (with a Copy button). After that Settings only shows the prefix — revoke and create a new key if you lose it.
• Send the key on every /v1/* call as Authorization: Bearer ds_… or Api-Key ds_….
• JWT session endpoints (/research/history, /research/usage, /research/deployments) use your logged-in account token from Settings — not the API key.

2. Quotas & limits

• Business: 2,000 research requests / calendar month and 60 requests / minute.
• Each successful sync, stream, async completion, or deployment run counts as one research request and writes a usage event.
• Over quota or rate limit → 429 with error.type quota_exceeded or rate_limit.
• Check remaining usage in Settings or GET /research/usage (JWT).

3. Core endpoints

* Public deployments may omit the token; private ones require X-DropShapes-Token or ?token=.

4. Request body (POST /v1/research)

Optional header Idempotency-Key: repeat the same key for the same account to replay the stored result instead of billing another run.

5. Response shape

{
  "id": "clx…",
  "object": "research.result",
  "status": "SUCCEEDED",          // QUEUED | RUNNING | SUCCEEDED | FAILED
  "domain": "HEALTH_RESEARCH",
  "task": "summarize evidence",
  "query": "…",
  "accessibility": true,
  "human_review": true,
  "provider": "OPENAI",
  "model": "gpt-4o-mini",
  "output": "## Summary\n…",      // markdown (from structured when enabled)
  "structured": {                 // when structured=true
    "summary": "…",
    "findings": ["…"],
    "gaps": ["…"],
    "recommendations": ["…"],
    "needs_human_review": ["…"],
    "accessibility_notes": ["…"]
  },
  "citations": [
    { "id": "…", "title": "…", "source": "…", "url": null, "snippet": "…", "score": 0.82 }
  ],
  "usage": { "tokens": 1200, "latency_ms": 3400 },
  "notice": "…safety / education disclaimer…",
  "created_at": "2026-09-09T…",
  "completed_at": "2026-09-09T…"
}

Citations come from the DropShapes domain corpus (RAG), not live web search. Treat them as workflow aids and verify important claims against primary sources.

6. Sync, stream, and async

• Sync — POST /v1/research without async. Wait for the full JSON result.
• Stream — POST /v1/research/stream. SSE events: status, delta (JSON with a text field), done (final result object), or error.
• Async — body field async: true → HTTP 202 with status: QUEUED. Poll GET /v1/research/:id until SUCCEEDED or FAILED, or listen for the webhook.

7. Errors

{
  "error": {
    "type": "plan_required",       // or rate_limit | quota_exceeded | not_found | …
    "code": "research_plan_required",
    "message": "Human-readable explanation"
  }
}

Common statuses: 401 invalid key, 403 plan required, 404 unknown id, 429 quota/rate limit.

8. Webhooks

• Register with POST /v1/webhooks using JSON fields url (required) and optional secret.
• On completion DropShapes POSTs research.completed with headers X-DropShapes-Event and X-DropShapes-Signature: sha256=<hmac> (HMAC-SHA256 of the raw body using your secret).
• Payload includes event, created_at, and data (the research.result object).

10. Quick start (curl)

# Sync research
curl -s https://api.dropshapes.com/v1/research \
  -H "Authorization: Bearer ds_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-001" \
  -d '{
    "domain": "HEALTH_RESEARCH",
    "task": "summarize evidence",
    "query": "Explain trial results in plain language",
    "accessibility": true,
    "human_review": true
  }'

# Retrieve / poll
curl -s https://api.dropshapes.com/v1/research/RESULT_ID \
  -H "Authorization: Bearer ds_YOUR_KEY"

# Stream (SSE)
curl -N https://api.dropshapes.com/v1/research/stream \
  -H "Authorization: Bearer ds_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"CODING","task":"document errors","query":"REST API 4xx/5xx guidance"}'

# Run a deployment
curl -s https://api.dropshapes.com/v1/deployments/health-brief/run \
  -H "Content-Type: application/json" \
  -H "X-DropShapes-Token: dpt_YOUR_TOKEN" \
  -d '{"query":"What should a patient-friendly summary include?"}'