{"openapi":"3.0.3","info":{"title":"DropShapes Research & Deployment API","version":"1.0.0","description":"Business-plan API for domain research assistance with corpus RAG citations, structured outputs, SSE streaming, async jobs (202 + poll), Idempotency-Key, webhooks (research.completed + HMAC), and published deployment endpoints. Auth: Authorization Bearer ds_… or Api-Key. Quotas: 2000 requests/month and 60 RPM for Business. Companion JWT routes: GET /research/history?page=&limit= (paginated, includes total), GET /research/usage, CRUD /research/deployments. Not a substitute for qualified medical care."},"servers":[{"url":"/","description":"Current host"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"ds_","description":"DropShapes API key (Authorization: Bearer ds_… or Api-Key ds_…)"}},"schemas":{"ResearchRequest":{"type":"object","required":["domain","task"],"properties":{"domain":{"type":"string","enum":["MENTAL_HEALTH","CANCER_DISCOVERY","HEALTH_RESEARCH","CODING","EDUCATION","SPACE","NEURODIVERGENT","ENVIRONMENT"]},"task":{"type":"string"},"query":{"type":"string"},"accessibility":{"type":"boolean","default":true},"human_review":{"type":"boolean","default":true},"provider":{"type":"string","enum":["OPENAI","CLAUDE","DROPSHAPES"]},"async":{"type":"boolean","default":false},"structured":{"type":"boolean","default":true}}},"ResearchResult":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","example":"research.result"},"status":{"type":"string","enum":["QUEUED","RUNNING","SUCCEEDED","FAILED"]},"domain":{"type":"string"},"task":{"type":"string"},"output":{"type":"string"},"structured":{"type":"object","nullable":true},"citations":{"type":"array","items":{"type":"object"}},"usage":{"type":"object","properties":{"tokens":{"type":"integer"},"latency_ms":{"type":"integer"}}},"notice":{"type":"string"}}},"ApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"paths":{"/v1/research":{"post":{"summary":"Create a research request","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Optional. Replays return the same result for the same user key."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchRequest"}}}},"responses":{"200":{"description":"Sync success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchResult"}}}},"202":{"description":"Async accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchResult"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Plan required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate or quota limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/research/stream":{"post":{"summary":"Stream a research request (SSE)","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchRequest"}}}},"responses":{"200":{"description":"text/event-stream"}}}},"/v1/research/{id}":{"get":{"summary":"Retrieve a research request by id","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchResult"}}}},"404":{"description":"Not found"}}}},"/v1/deployments":{"get":{"summary":"List deployments","security":[{"ApiKeyAuth":[]}]},"post":{"summary":"Create a published research deployment","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","domain"],"properties":{"name":{"type":"string"},"slug":{"type":"string"},"domain":{"type":"string"},"task_hint":{"type":"string"},"instructions":{"type":"string"},"public":{"type":"boolean"}}}}}}}},"/v1/deployments/{slug}/run":{"post":{"summary":"Run a published deployment","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-DropShapes-Token","in":"header","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"task":{"type":"string"}}}}}}}},"/v1/webhooks":{"get":{"summary":"List research webhooks","security":[{"ApiKeyAuth":[]}]},"post":{"summary":"Register a research.completed webhook","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"secret":{"type":"string"}}}}}}}}}}