{"openapi":"3.1.0","info":{"title":"Elicit API","version":"0.0.1","description":"The Elicit API provides programmatic access to Elicit's research capabilities, including semantic search over 125 million+ academic papers and automated report generation.\n\n## Authentication\n\nAll API requests require a Bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer elk_live_your_key_here\n```\n\nAPI keys can be created and managed from your [Elicit account settings](https://elicit.com/settings).\n\n## Billing\n\nAPI access requires a Pro plan or above. There is no extra charge for API access beyond your subscription. Reports created via the API count against your workflow quota, the same as reports created through the web interface. Search requests are rate-limited based on your plan tier — see the Search endpoint for details.\n\nManage your plan in [account settings](https://elicit.com/settings).\n\n## Code Examples\n\nWorking examples in curl, Python, and JavaScript, plus integrations (CLI tool, Slack bot, Claude Code skill):\n\n**[github.com/elicit/api-examples](https://github.com/elicit/api-examples)**\n\n## Error Handling\n\nAll errors return a consistent JSON structure with an `error` object containing a machine-readable `code` and a human-readable `message`.","contact":{"name":"Elicit","url":"https://elicit.com"}},"externalDocs":{"description":"Code examples and integrations","url":"https://github.com/elicit/api-examples"},"servers":[{"url":"https://elicit.com","description":"Elicit"}],"paths":{"/api/v1/search":{"post":{"tags":["Search"],"summary":"Search for academic papers","description":"Search Elicit's database of over 125 million academic papers using natural language queries.\n\nSemantic search uses natural language understanding to find relevant papers even when the exact terms don't match.\n\n### Rate Limits\n\n| Plan | Papers per request | Requests per day |\n|------|-------------------|-----------------|\n| Basic | No access | No access |\n| Plus | No access | No access |\n| Pro | 100 | 100 |\n| Team | 200 | 200 |\n| Enterprise | 5,000 | No limit |\n\nUpgrade your plan in [account settings](https://elicit.com/settings) for higher limits.\n\n### Example\n\n```bash\ncurl -X POST https://elicit.com/api/v1/search \\\n  -H \"Authorization: Bearer elk_live_your_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"effects of sleep deprivation on cognitive performance\"}'\n```","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"description":"Search parameters","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":2000,"description":"The search query string","example":"GLP-1 receptor agonists for weight loss"},"filters":{"$ref":"#/components/schemas/SearchFilters","description":"Filters to narrow search results"},"maxResults":{"type":"integer","minimum":1,"maximum":5000,"default":10,"description":"Maximum number of results to return (1-5000)"}},"required":["query"]},"examples":{"basic":{"summary":"Basic search","value":{"query":"effects of sleep deprivation on cognitive performance"}},"filtered":{"summary":"Filtered search with keywords and date range","value":{"query":"GLP-1 receptor agonists for weight loss","filters":{"minEpochS":1672531200,"maxEpochS":1773721943,"includeKeywords":["semaglutide","liraglutide"],"excludeKeywords":["rodent","mouse model"],"typeTags":["RCT","Meta-Analysis"],"hasPdf":true},"maxResults":20}}}}}},"responses":{"200":{"description":"Search results returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"},"examples":{"success":{"summary":"Successful search","value":{"papers":[{"elicitId":"abc123def456","title":"Effects of Sleep Deprivation on Cognitive Performance: A Meta-Analysis","authors":["Smith, J.","Jones, A.","Williams, R."],"year":2023,"abstract":"This meta-analysis examines the relationship between sleep deprivation and various measures of cognitive performance...","doi":"10.1234/sleep.2023.001","pmid":"37123456","venue":"Sleep Medicine Reviews","citedByCount":42,"urls":["https://example.com/paper.pdf"]}]}}}}}},"400":{"description":"Invalid request. The request body failed validation — check that `query` is present and `maxResults` is between 1 and 5000.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"query is required"}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missing":{"summary":"Missing Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}},"invalid":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"revoked":{"summary":"Revoked API key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}}}}}},"403":{"description":"API access is not available on your current plan. Upgrade to Pro or above to use the API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"api_access_denied","message":"API access is not available on your current plan. Please upgrade to Pro or above."}}}}},"429":{"description":"Rate limit exceeded for this plan tier. Limits are enforced over a rolling 24-hour window. Check `X-RateLimit-Reset` for when the oldest request in your window expires.","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed per rolling 24-hour window for your plan tier","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Number of requests remaining in the current 24-hour window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix epoch timestamp (seconds) when the oldest request in your window expires and a slot opens up","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limit_exceeded","message":"Rate limit of 20 requests per 24 hours exceeded. Try again later."}}}}},"500":{"description":"An unexpected error occurred. Retry after a short delay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"Internal server error"}}}}}}}},"/api/v1/reports":{"post":{"tags":["Reports"],"summary":"Create a new report","description":"Start an asynchronous report generation job. Elicit will search for relevant papers, screen them for relevance, extract structured data, and produce a full research report.\n\nReports are long-running operations (typically 5–15 minutes). The response includes a `reportId` that you use to poll for status via `GET /api/v1/reports/:reportId`.\n\nThe report is also visible at the `url` returned in the response, where you can watch it progress in real time.\n\n### Workflow\n\n1. **POST /api/v1/reports** — submit your research question (returns immediately with `reportId`)\n2. **GET /api/v1/reports/:reportId** — poll until `status` is `completed` or `failed`\n3. Use the `pdfUrl` and `docxUrl` fields on the completed response to download the report\n\n### Example\n\n```bash\n# 1. Create the report\ncurl -X POST https://elicit.com/api/v1/reports \\\n  -H \"Authorization: Bearer elk_live_your_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"researchQuestion\": \"What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?\"}'\n\n# 2. Poll for completion (repeat until status is \"completed\" or \"failed\")\ncurl https://elicit.com/api/v1/reports/{reportId} \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"description":"Report configuration","content":{"application/json":{"schema":{"type":"object","properties":{"researchQuestion":{"type":"string","minLength":1,"maxLength":2000,"description":"The research question to investigate. Elicit will search for relevant papers, screen them, and extract data to produce a structured report.","example":"What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?"},"maxSearchPapers":{"type":"integer","minimum":1,"maximum":5000,"default":50,"description":"Maximum number of papers to retrieve during the search phase. More papers means a more comprehensive but slower report. Defaults to 50.","example":50},"maxExtractPapers":{"type":"integer","minimum":1,"maximum":500,"default":10,"description":"Maximum number of papers to include in the final extraction table. Papers are screened for relevance before extraction. Defaults to 10.","example":10}},"required":["researchQuestion"]},"examples":{"basic":{"summary":"Basic report","value":{"researchQuestion":"What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?"}},"customized":{"summary":"Report with custom paper limits","value":{"researchQuestion":"What is the evidence for cognitive behavioral therapy in treating insomnia?","maxSearchPapers":1000,"maxExtractPapers":100}}}}}},"responses":{"202":{"description":"Report creation accepted. The report is now being generated asynchronously. Use the `reportId` to poll for status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReportResponse"},"example":{"reportId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","status":"processing","url":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029"}}}},"400":{"description":"Invalid request. Check that `researchQuestion` is present and within length limits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"researchQuestion is required"}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}}}},"402":{"description":"Insufficient quota. The user's plan does not have enough remaining workflow quota to create this report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_quota","message":"Workflow quota exceeded. Please upgrade your plan or wait for the next billing cycle."}}}}},"403":{"description":"API access is not available on your current plan. Upgrade to Pro or above to use the API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"api_access_denied","message":"API access is not available on your current plan. Please upgrade to Pro or above."}}}}},"500":{"description":"An unexpected error occurred. Retry after a short delay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"Internal server error"}}}}}}},"get":{"tags":["Reports"],"summary":"List reports","description":"List all reports for the authenticated user, ordered by creation date (newest first).\n\nResults are paginated using cursor-based pagination. Use the `nextCursor` value from the response to fetch the next page.\n\n### Example\n\n```bash\n# First page\ncurl https://elicit.com/api/v1/reports?limit=10 \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n\n# Next page\ncurl \"https://elicit.com/api/v1/reports?limit=10&cursor=2025-06-15T14:30:00.000Z\" \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n\n# Filter to API-created reports only\ncurl https://elicit.com/api/v1/reports?source=api \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","security":[{"BearerAuth":[]}],"parameters":[{"in":"query","name":"limit","description":"Maximum number of reports to return (default: 20, max: 100)","schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of reports to return (default: 20, max: 100)","example":20}},{"in":"query","name":"cursor","description":"Pagination cursor from a previous response's nextCursor field. Omit for the first page.","schema":{"type":"string","description":"Pagination cursor from a previous response's nextCursor field. Omit for the first page.","example":"2025-06-15T14:30:00.000Z"}},{"in":"query","name":"source","description":"Filter by how the report was created","schema":{"type":"string","enum":["api","user"],"description":"Filter by how the report was created","example":"api"}},{"in":"query","name":"status","description":"Filter by report status","schema":{"type":"string","enum":["processing","completed","failed","unknown"],"description":"Filter by report status","example":"completed"}}],"responses":{"200":{"description":"List of reports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListReportsResponse"},"example":{"reports":[{"reportId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","status":"completed","title":"What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?","url":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029","source":"api","createdAt":"2025-06-15T14:30:00.000Z"}],"nextCursor":null}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}}}},"403":{"description":"API access is not available on your current plan. Upgrade to Pro or above to use the API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"api_access_denied","message":"API access is not available on your current plan. Please upgrade to Pro or above."}}}}}}}},"/api/v1/reports/{reportId}":{"get":{"tags":["Reports"],"summary":"Get report status and results","description":"Poll the status of a report created via `POST /api/v1/reports`.\n\n### Status transitions\n\n- **processing** — Elicit is actively searching, screening, and extracting data. You can watch progress in real time at the `url`.\n- **completed** — The report is finished. The `result` field contains the report content.\n- **failed** — Something went wrong. The `error` field contains details.\n- **unknown** — Status is not tracked for this report (legacy or user-created reports).\n\n### Polling recommendation\n\nPoll every 30–60 seconds. Reports typically complete in 5–15 minutes depending on the number of papers.\n\n### Including the full report body\n\nBy default, the `reportBody` and `abstract` fields are omitted to keep polling responses lightweight. To include them, add `?include=reportBody` to the request.\n\n### Example\n\n```bash\n# Poll for status\ncurl https://elicit.com/api/v1/reports/{reportId} \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n\n# Fetch with full report body\ncurl \"https://elicit.com/api/v1/reports/{reportId}?include=reportBody\" \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"reportId","description":"The report ID (UUID) returned from the create report endpoint","schema":{"type":"string","description":"The report ID (UUID) returned from the create report endpoint","example":"5ad08bfb-cbe0-4911-a8c3-309760d33029"},"required":true},{"in":"query","name":"include","description":"Set to 'reportBody' to include the full report markdown and abstract in the response","schema":{"type":"string","const":"reportBody","description":"Set to 'reportBody' to include the full report markdown and abstract in the response"}}],"responses":{"200":{"description":"Report status and results (if completed).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetReportResponse"},"examples":{"processing":{"summary":"Report is being generated","value":{"reportId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","status":"processing","url":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029"}},"completed":{"summary":"Report completed with results","value":{"reportId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","status":"completed","url":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029","result":{"title":"GLP-1 Receptor Agonists and Cardiovascular Outcomes: A Systematic Review","summary":"This review analyzed 42 studies examining the cardiovascular effects of GLP-1 receptor agonists. The evidence suggests significant reductions in major adverse cardiovascular events (MACE), with semaglutide showing the strongest effect (HR 0.74, 95% CI 0.58-0.95). Liraglutide also demonstrated cardiovascular benefit in the LEADER trial (HR 0.87, 95% CI 0.78-0.97). Most studies were industry-funded RCTs with follow-up periods of 2-5 years.","reportBody":"# Introduction\n\nGLP-1 receptor agonists have emerged as a major therapeutic class...\n\n# Methods\n\nWe conducted a systematic review of randomized controlled trials...","abstract":"This systematic review examines the cardiovascular effects of GLP-1 receptor agonists across 42 studies..."},"pdfUrl":"https://s3.amazonaws.com/...","docxUrl":"https://s3.amazonaws.com/..."}},"failed":{"summary":"Report generation failed","value":{"reportId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","status":"failed","url":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029","error":{"code":"report_generation_failed","message":"Report generation failed during the extraction phase. Please try again."}}}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}}}},"403":{"description":"API access is not available on your current plan. Upgrade to Pro or above to use the API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"api_access_denied","message":"API access is not available on your current plan. Please upgrade to Pro or above."}}}}},"404":{"description":"Report not found. Either the report ID is invalid or the report belongs to a different user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"report_not_found","message":"Report not found"}}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key obtained from your Elicit account settings page. Keys use the format `elk_live_...`."}},"schemas":{"SearchFilters":{"type":"object","properties":{"minYear":{"type":"integer","description":"Minimum publication year","example":2020},"maxYear":{"type":"integer","description":"Maximum publication year","example":2025},"minEpochS":{"type":"integer","description":"Minimum publication date as Unix epoch seconds","example":1672531200},"maxEpochS":{"type":"integer","description":"Maximum publication date as Unix epoch seconds","example":1773721943},"maxQuartile":{"type":"integer","minimum":1,"maximum":4,"description":"Maximum journal quartile (1 = top 25%)","example":2},"includeKeywords":{"type":"array","items":{"type":"string"},"description":"Keywords that must appear in the paper","example":["semaglutide","liraglutide"]},"excludeKeywords":{"type":"array","items":{"type":"string"},"description":"Keywords to exclude from results","example":["rodent","mouse model"]},"typeTags":{"type":"array","items":{"type":"string","enum":["Review","Meta-Analysis","Systematic Review","RCT","Longitudinal"]},"description":"Filter by study type","example":["RCT","Meta-Analysis"]},"hasPdf":{"type":"boolean","description":"Only include papers with available PDFs","example":false},"pubmedOnly":{"type":"boolean","description":"Only include papers from PubMed","example":false},"retracted":{"type":"string","enum":["exclude_retracted","include_retracted","only_retracted"],"description":"How to handle retracted papers. Defaults to exclude_retracted.","example":"exclude_retracted"}}},"SearchResponse":{"type":"object","properties":{"papers":{"type":"array","items":{"$ref":"#/components/schemas/Paper"},"description":"List of papers matching the query"}},"required":["papers"]},"Paper":{"type":"object","properties":{"elicitId":{"type":["string","null"],"description":"Elicit internal paper identifier"},"title":{"type":"string","description":"Paper title"},"authors":{"type":"array","items":{"type":"string"},"description":"List of author names"},"year":{"type":["integer","null"],"description":"Publication year"},"abstract":{"type":["string","null"],"description":"Paper abstract"},"doi":{"type":["string","null"],"description":"Digital Object Identifier"},"pmid":{"type":["string","null"],"description":"PubMed identifier"},"venue":{"type":["string","null"],"description":"Publication venue"},"citedByCount":{"type":["integer","null"],"description":"Number of citations this paper has received"},"urls":{"type":"array","items":{"type":"string"},"description":"URLs for the paper"}},"required":["elicitId","title","authors","year","abstract","doi","pmid","venue","citedByCount","urls"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code","example":"invalid_request"},"message":{"type":"string","description":"Human-readable error message","example":"Invalid search request"}},"required":["code","message"]}},"required":["error"]},"CreateReportResponse":{"type":"object","properties":{"reportId":{"type":"string","description":"Unique identifier for the report. Use this to poll for status.","example":"5ad08bfb-cbe0-4911-a8c3-309760d33029"},"status":{"type":"string","const":"processing","description":"Initial status is always processing"},"url":{"type":"string","description":"URL to view the report in the Elicit web interface as it progresses","example":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029"}},"required":["reportId","status","url"]},"ListReportsResponse":{"type":"object","properties":{"reports":{"type":"array","items":{"$ref":"#/components/schemas/ReportListItem"},"description":"List of reports"},"nextCursor":{"type":["string","null"],"description":"Cursor for the next page of results. Null if there are no more results.","example":"2025-06-15T14:30:00.000Z"}},"required":["reports","nextCursor"]},"ReportListItem":{"type":"object","properties":{"reportId":{"type":"string","description":"Unique identifier for the report","example":"5ad08bfb-cbe0-4911-a8c3-309760d33029"},"status":{"type":"string","enum":["processing","completed","failed","unknown"],"description":"Current status of the report"},"title":{"type":"string","description":"Report title (the research question)","example":"What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?"},"url":{"type":"string","description":"URL to view the report in the Elicit web interface","example":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029"},"source":{"type":"string","enum":["api","user"],"description":"How the report was created","example":"api"},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the report was created","example":"2025-06-15T14:30:00.000Z"}},"required":["reportId","status","title","url","source","createdAt"]},"GetReportResponse":{"type":"object","properties":{"reportId":{"type":"string","description":"Unique identifier for the report","example":"5ad08bfb-cbe0-4911-a8c3-309760d33029"},"status":{"type":"string","enum":["processing","completed","failed","unknown"],"description":"Current status of the report. Transitions: processing → completed/failed. Poll until completed or failed."},"url":{"type":"string","description":"URL to view the report in the Elicit web interface","example":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029"},"result":{"$ref":"#/components/schemas/ReportResult","description":"Report output, only present when status is completed"},"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"],"description":"Error details, only present when status is failed"},"pdfUrl":{"type":["string","null"],"description":"Pre-signed URL to download the report as PDF. Only present when status is completed and assets have been generated. Expires after 7 days — re-fetch the report for a fresh URL.","example":"https://s3.amazonaws.com/..."},"docxUrl":{"type":["string","null"],"description":"Pre-signed URL to download the report as DOCX. Only present when status is completed and assets have been generated. Expires after 7 days — re-fetch the report for a fresh URL.","example":"https://s3.amazonaws.com/..."}},"required":["reportId","status","url"]},"ReportResult":{"type":"object","properties":{"title":{"type":"string","description":"Auto-generated title for the report","example":"GLP-1 Receptor Agonists and Cardiovascular Outcomes: A Systematic Review"},"summary":{"type":"string","description":"AI-generated executive summary of the findings","example":"This review analyzed 42 studies examining the cardiovascular effects of GLP-1 receptor agonists. The evidence suggests significant reductions in major adverse cardiovascular events (MACE), with semaglutide showing the strongest effect (HR 0.74, 95% CI 0.58-0.95)..."},"reportBody":{"type":["string","null"],"description":"Full report content in markdown format. Only included when ?include=reportBody is specified.","example":"# Introduction\n\nGLP-1 receptor agonists have emerged as..."},"abstract":{"type":["string","null"],"description":"Report abstract in markdown format. Only included when ?include=reportBody is specified.","example":"This systematic review examines the cardiovascular effects of..."}},"required":["title","summary"]}}}}