{"openapi":"3.1.0","info":{"title":"Elicit API","version":"2.0.0","description":"The Elicit API provides programmatic access to Elicit's research capabilities, including semantic search over 138 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. 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`.\n\n## MCP Server\n\nAll API functionality is also available via [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server, enabling use from Claude Desktop, Claude Code, and other MCP-compatible clients. Authentication is via OAuth 2.0.\n\n### Claude Code\n\n```\nclaude mcp add --transport http elicit https://elicit.com/api/mcp\n```\n\nThen run `/mcp`, select the `elicit` server, and choose **Authenticate** to open a browser for login.\n\n### Claude Desktop\n\n**Via the UI:** Click the icon next to your name > **Settings** > **Connectors** > **Add custom connector**. Enter `Elicit` for the name and `https://elicit.com/api/mcp` for the URL.\n\n**Or via config file** — add to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"elicit\": {\n      \"type\": \"url\",\n      \"url\": \"https://elicit.com/api/mcp\"\n    }\n  }\n}\n```\n\n### Other MCP clients\n\nConnect any MCP client using HTTP transport to `https://elicit.com/api/mcp`. OAuth discovery is available at `https://elicit.com/api/mcp/.well-known/oauth-protected-resource`.\n\nFor MCP setup guides, tool reference, and usage examples, see [github.com/elicit/api-examples/tree/main/integrations/mcp](https://github.com/elicit/api-examples/tree/main/integrations/mcp).","termsOfService":"https://elicit.com/operations/terms","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/api/v2","description":"Elicit"}],"tags":[{"name":"Search","description":"One-shot searches over papers and clinical trials."},{"name":"Sessions","description":"Long-running research sessions. Reports, systematic reviews, and Research Agent sessions are kinds of sessions; list and resume them uniformly here, or use the typed subsections to create them and fetch results."},{"name":"Reports","description":"Create reports and fetch their status and results."},{"name":"Systematic Reviews","description":"Create systematic reviews and fetch their status and results."},{"name":"Usage","description":"Report plan usage and extra usage — the account-settings usage meter, over the API."},{"name":"Research Agent","description":"Early-access, stateful research sessions with incremental activity, follow-up messages, file uploads, and downloadable artifacts."},{"name":"Library","description":"Your library: saved papers (sources) and the collections that group them, including items shared with you.\n\n### Conventions\n\n- A detail endpoint returns the resource. A list endpoint returns `{ <items>, nextCursor, totalCount }`. Send `nextCursor` as `cursor` to get the next page. `nextCursor` is `null` on the last page.\n- You see your own sources and collections plus any shared with you. Each carries your `role`. On a collection, `reader`, `writer`, or `owner`: readers view; writers also add and remove sources and edit the name and description; owners also delete it and change who it is shared with. On a source, `reader` or `writer`: writers edit its metadata, attach a PDF, delete it, and add it to collections.\n- A shared collection owns its papers. Adding one of your sources to it copies the paper into the collection; your own source is unchanged, and you are a `writer` on the copy if you own or can edit the collection and a `reader` if you can only view it. Removing a paper from such a collection moves it to the collection's trash for 30 days.\n- An id you cannot see returns `404`. An action your role does not allow returns `403 forbidden`.\n- Creating one resource returns `201` and the resource. A bulk operation returns `200` and a per-item report or a count. A count of `0` means the request changed nothing. Requests are safe to repeat.\n- A duplicate is not an error. Saving a paper that is already in your library returns the existing source with `created: false` and `duplicateOf` set; with `onDuplicate: create`, a copy is saved with `created: true` and `duplicateOf` names the original. A PDF import reports the file as `duplicate`. Papers match by Elicit id, then DOI, then title corroborated by authors or year; a title alone does not match. Items in one request are also matched against each other.\n- A bulk request is all-or-nothing. One unknown id fails the request, and the error names the ids. Nothing is applied.\n- Deleting a source is a soft delete. A repeat returns `204`. Deleting a collection is permanent. Its sources stay in the library. A repeat returns `404`.\n- DOIs saved through the API are stored in bare lowercase form (`10.1056/nejmoa2307563`). Input and the `doi` filter accept `doi.org` URLs, `doi:` prefixes, and any letter case.\n- A malformed id, or an unknown query parameter or body key, returns `400 invalid_request` with the field name."}],"paths":{"/search/papers":{"post":{"tags":["Search"],"summary":"Search for academic papers","description":"Search Elicit's database of over 138 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\nSet `corpus` to `pubmed` to restrict results to PubMed, or leave it as the default `elicit` for the full paper index. Set `searchMode` to `\"keyword\"` to interpret the query as a Lucene-style boolean expression instead of natural language.\n\nFilters and `searchMode: \"keyword\"` are mutually exclusive — put any filter expressions directly into the query string when using keyword search. Mixing them returns a 400.\n\nTo search clinical trials instead, use [`POST /api/v2/search/trials`](#tag/Search/paths/~1search~1trials/post).\n\n### Limits\n\nEach plan caps how many results a single search request may return:\n\n| Plan | Results per request |\n|------|--------------------|\n| Basic | No access |\n| Plus | No access |\n| Pro | 300 |\n| Scale | 500 |\n| Enterprise | 10,000 |\n\nSearch is rate-limited only by the global limit of 100 requests per minute per IP address, applied across all endpoints and all plans. Exceeding it returns a `429` and blocks the IP for 5 minutes.\n\nUpgrade your plan in [account settings](https://elicit.com/settings) for higher per-request result caps.\n\n### Example\n\n```bash\ncurl -X POST https://elicit.com/api/v2/search/papers \\\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":{"$ref":"#/components/schemas/PaperSearchRequest"},"examples":{"elicit":{"summary":"Elicit paper index (default) with filters","value":{"query":"GLP-1 receptor agonists for weight loss","filters":{"minEpochS":1672531200,"maxEpochS":1789411179,"includeKeywords":["semaglutide","liraglutide"],"excludeKeywords":["rodent","mouse model"],"typeTags":["RCT","Meta-Analysis"],"hasPdf":true},"maxResults":20}},"pubmed":{"summary":"PubMed (keyword / Lucene query)","value":{"query":"\"semaglutide\"[Title/Abstract] AND \"diabetes\"[MeSH]","corpus":"pubmed","searchMode":"keyword","maxResults":20}}}}}},"responses":{"200":{"description":"Search results returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaperSearchResponse"},"example":{"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"],"studyTypeTags":["Meta-Analysis"],"journalQuartile":1,"fullTextUrl":"https://example.com/paper.pdf"}],"warnings":[]}}}},"400":{"description":"Invalid request. The request body failed validation — check that `query` is present and `maxResults` is between 1 and 10000.","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"}}}}}}},"402":{"description":"Insufficient quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_quota","message":"Insufficient quota."}}}}},"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. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/search/trials":{"post":{"tags":["Search"],"summary":"Search clinical trials","description":"Search for clinical trials. Trial records come from ClinicalTrials.gov.\n\nPass `trialFilters` to narrow by phase, recruitment status, or whether the trial has posted results. Set `searchMode` to `\"keyword\"` to send the query as a Lucene-style boolean expression directly to the underlying advanced-filter API.\n\nFilters and `searchMode: \"keyword\"` are mutually exclusive — put filter expressions directly into the query when using keyword search. Mixing them returns a 400.\n\nTo search academic papers instead, use [`POST /api/v2/search/papers`](#tag/Search/paths/~1search~1papers/post).\n\n### Limits\n\nEach plan caps how many results a single search request may return:\n\n| Plan | Results per request |\n|------|--------------------|\n| Basic | No access |\n| Plus | No access |\n| Pro | 300 |\n| Scale | 500 |\n| Enterprise | 10,000 |\n\nSearch is rate-limited only by the global limit of 100 requests per minute per IP address, applied across all endpoints and all plans. Exceeding it returns a `429` and blocks the IP for 5 minutes.\n\nUpgrade your plan in [account settings](https://elicit.com/settings) for higher per-request result caps.\n\n### Example\n\n```bash\ncurl -X POST https://elicit.com/api/v2/search/trials \\\n  -H \"Authorization: Bearer elk_live_your_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"semaglutide obesity\", \"trialFilters\": {\"phase\": [\"PHASE3\"]}}'\n```","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"description":"Trial search parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrialSearchRequest"},"examples":{"filtered":{"summary":"Phase 3, currently recruiting","value":{"query":"semaglutide obesity","trialFilters":{"phase":["PHASE3"],"recruitmentStatus":["RECRUITING","ACTIVE_NOT_RECRUITING"]},"maxResults":20}},"keyword":{"summary":"Keyword / Lucene query","value":{"query":"AREA[Condition]\"obesity\" AND AREA[InterventionName]\"semaglutide\"","searchMode":"keyword","maxResults":20}}}}}},"responses":{"200":{"description":"Trial search results returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrialSearchResponse"},"example":{"trials":[{"nctId":"NCT05646706","title":"A Research Study on Semaglutide for Weight Loss","summary":"This study will look at how much weight participants lose...","url":"https://clinicaltrials.gov/study/NCT05646706","overallStatus":"COMPLETED","phase":["PHASE3"],"studyType":"INTERVENTIONAL","enrollmentCount":1407,"conditions":["Obesity"],"interventions":["Semaglutide","Placebo"],"leadSponsor":"Novo Nordisk A/S","startDate":"2022-10-10","primaryCompletionDate":"2024-04-12","completionDate":"2024-05-24","hasResults":true,"lastUpdatedYear":2025}],"warnings":[]}}}},"400":{"description":"Invalid request. The request body failed validation.","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"},"example":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}}}},"402":{"description":"Insufficient quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_quota","message":"Insufficient quota."}}}}},"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. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/sessions/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 `sessionId` and a `links.self` URL that you poll for status.\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/v2/sessions/reports** — submit your research question (returns immediately with `sessionId`)\n2. **GET `links.self`** (`/api/v2/sessions/reports/:sessionId`) — poll until `status` is `completed` or `failed`\n3. Use the `pdfUrl` and `docxUrl` fields on the completed response to download the report, and `txtUrl`, `bibUrl`, and `risUrl` to download its reference list (APA text, BibTeX, and RIS)\n\n### Example\n\n```bash\n# 1. Create the report\ncurl -X POST https://elicit.com/api/v2/sessions/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/v2/sessions/reports/{sessionId} \\\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?"},"title":{"type":"string","minLength":1,"maxLength":200,"description":"Optional title for the report. If provided, Elicit will use this as the report title instead of generating one automatically from the research question.","example":"GLP-1 Receptor Agonists and Cardiovascular Outcomes"},"maxSearchPapers":{"type":"integer","minimum":1,"maximum":1000,"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":80,"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},"isPublic":{"type":"boolean","default":false,"description":"Whether the report should be publicly accessible via its URL without authentication. Defaults to false.","example":false}},"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":80}},"publicReport":{"summary":"Public report","value":{"researchQuestion":"What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?","isPublic":true}},"withTitle":{"summary":"Report with custom title","value":{"researchQuestion":"What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?","title":"GLP-1 Receptor Agonists and Cardiovascular Outcomes"}}}}}},"responses":{"202":{"description":"Report creation accepted. The report is now being generated asynchronously. Poll `links.self` for status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportSessionCreated"},"example":{"type":"report","sessionId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","status":"processing","url":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029","isPublic":false,"links":{"self":"https://elicit.com/api/v2/sessions/reports/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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_quota","message":"Insufficient quota."}}}}},"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"}}}}}}}},"/sessions/reports/{sessionId}":{"get":{"tags":["Reports"],"summary":"Get report status and results","description":"Poll the status of a report created via `POST /api/v2/sessions/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- **pausedForInsufficientQuota** — The account exceeded its usage limit mid-run. The report stays paused until resumed via the `links.resume` URL (or the Elicit web interface) once the limit is resolved.\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/v2/sessions/reports/{sessionId} \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n\n# Fetch with full report body\ncurl \"https://elicit.com/api/v2/sessions/reports/{sessionId}?include=reportBody\" \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"sessionId","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","schema":{"type":"string","format":"uuid","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","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/ReportSessionDetail"},"examples":{"processing":{"summary":"Report is being generated","value":{"type":"report","sessionId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","status":"processing","url":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029","isPublic":false,"links":{"self":"https://elicit.com/api/v2/sessions/reports/5ad08bfb-cbe0-4911-a8c3-309760d33029"}}},"completed":{"summary":"Report completed with results","value":{"type":"report","sessionId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","status":"completed","url":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029","isPublic":false,"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/...","txtUrl":"https://s3.amazonaws.com/...","bibUrl":"https://s3.amazonaws.com/...","risUrl":"https://s3.amazonaws.com/...","links":{"self":"https://elicit.com/api/v2/sessions/reports/5ad08bfb-cbe0-4911-a8c3-309760d33029"}}},"failed":{"summary":"Report generation failed","value":{"type":"report","sessionId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","status":"failed","url":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029","isPublic":false,"links":{"self":"https://elicit.com/api/v2/sessions/reports/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"}}}}}}}},"/sessions/systematic-reviews":{"post":{"tags":["Systematic Reviews"],"summary":"Create a new systematic review","description":"Start a systematic review. Elicit runs the stages you configure — searches, abstract screening, fulltext screening, extraction, and a report. Each stage runs only when you include it; omit a stage to skip it. The default example below runs a complete review end-to-end.\n\nSystematic reviews are long-running operations. The response includes a `sessionId` and a `links.self` URL (`/api/v2/sessions/systematic-reviews/:sessionId`) that you poll for status. You can also watch progress live at the `url` in the response.\n\n### Plan limits\n\n| Plan | Max columns | Max results per query | Max total results | Figure extraction |\n|------|-------------|----------------------|-------------------|-------------------|\n| Pro | 20 | 1,000 | 5,000 | No |\n| Scale | 30 | 5,000 | 20,000 | Yes |\n| Enterprise | 40 | 10,000 | 40,000 | Yes |\n\n### Example\n\n```bash\ncurl -X POST https://elicit.com/api/v2/sessions/systematic-reviews \\\n-H \"Authorization: Bearer elk_live_your_key_here\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n  \"researchQuestion\": \"Do GLP-1 receptor agonists reduce MACE in T2D patients?\",\n  \"searches\": [{ \"query\": \"GLP-1 cardiovascular outcomes\", \"maxResults\": 200 }],\n  \"abstractScreening\": { \"generate\": true },\n  \"fulltextScreening\": { \"reuseAbstractCriteria\": true },\n  \"extraction\": { \"generate\": true, \"useFigures\": false },\n  \"generateReport\": true\n}'\n```","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"description":"Systematic review configuration","content":{"application/json":{"schema":{"type":"object","properties":{"researchQuestion":{"type":"string","minLength":1,"maxLength":2000,"description":"The research question the review is investigating.","example":"Do GLP-1 receptor agonists reduce MACE in T2D patients?"},"protocolDetails":{"type":"string","maxLength":10000,"description":"Free-form context (PICO, methodology, inclusion/exclusion rationale) used when Elicit generates screening criteria, extraction columns, or the final report."},"searches":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":2000,"description":"Search query","example":"GLP-1 receptor agonist cardiovascular outcomes"},"corpus":{"type":"string","enum":["elicit","pubmed","clinical_trials"],"description":"Corpus to search. `elicit` (default) searches Elicit's full academic paper index, spanning most research domains. `pubmed` restricts results to PubMed. `clinical_trials` returns registered trials only.","example":"elicit","default":"elicit"},"searchMode":{"type":"string","enum":["semantic","keyword"],"default":"semantic","description":"`semantic` (default) uses vector-similarity retrieval; `keyword` uses literal keyword matching."},"maxResults":{"type":"integer","minimum":1,"maximum":10000,"default":200,"description":"Maximum number of papers to retrieve from this search. Plan-specific caps apply.","example":200}},"required":["query"]},"maxItems":20,"default":[],"description":"Searches that feed the review pipeline. If omitted or empty, Elicit runs a semantic search using `researchQuestion` as the query. Total search results are subject to plan-specific limits."},"abstractScreening":{"type":"object","properties":{"criteria":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Short name for the criterion","example":"Human study"},"instructions":{"type":"string","minLength":1,"maxLength":2000,"description":"Plain-language instructions used to judge whether a paper meets this criterion","example":"The study must be conducted in human subjects (not in vitro or animal-only)."}},"required":["name","instructions"]},"maxItems":40,"description":"Explicit screening criteria."},"generate":{"type":"boolean","default":false,"description":"When true, Elicit generates additional screening criteria."},"depth":{"type":"string","enum":["fast","thorough"],"default":"thorough","description":"How thoroughly Elicit judges each abstract against your criteria. `thorough` (default) applies the criteria in full and records the quotes behind each decision. `fast` costs a fraction as much per paper, but wrongly excludes more papers that met your criteria and returns decisions without supporting quotes — use it to triage a large candidate set, not for a final screen. Send the same request with `dryRun: true` to compare what each setting costs in credits."}},"description":"Abstract-stage screening. Supply `criteria`, `generate: true`, or both. Omit the field to skip."},"fulltextScreening":{"type":"object","properties":{"criteria":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Short name for the criterion","example":"Human study"},"instructions":{"type":"string","minLength":1,"maxLength":2000,"description":"Plain-language instructions used to judge whether a paper meets this criterion","example":"The study must be conducted in human subjects (not in vitro or animal-only)."}},"required":["name","instructions"]},"maxItems":40,"description":"Explicit fulltext-stage criteria."},"reuseAbstractCriteria":{"type":"boolean","default":false,"description":"When true, the abstract-stage criteria are also applied at the fulltext stage."},"depth":{"type":"string","enum":["fast","thorough"],"default":"thorough","description":"How thoroughly Elicit judges each full text against your criteria. `thorough` (default) applies the criteria in full and records the quotes behind each decision. `fast` costs less per paper, but wrongly excludes more papers that met your criteria and returns decisions without supporting quotes. Send the same request with `dryRun: true` to compare what each setting costs in credits."}},"description":"Fulltext-stage screening. Supply `criteria`, `reuseAbstractCriteria: true`, or both. Requires `abstractScreening` to be present. Omit to skip."},"extraction":{"type":"object","properties":{"questions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Column header for this extraction question","example":"MACE hazard ratio"},"instructions":{"type":"string","minLength":1,"maxLength":2000,"description":"Plain-language instructions describing what to extract","example":"Extract the hazard ratio and 95% confidence interval for 3-point MACE."},"choices":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"minItems":2,"maxItems":10,"description":"Optional fixed list of allowed answers. Omit for free-text extraction. When set, the model is constrained to one of these values.","example":["yes","no","maybe"]}},"required":["name","instructions"]},"maxItems":40,"description":"Explicit extraction columns."},"generate":{"type":"boolean","default":false,"description":"When true, Elicit generates additional extraction columns."},"useFigures":{"type":"boolean","default":false,"description":"When true, Elicit also reads figures and charts when answering your extraction questions, so it can pick up results that appear only in a figure. Extraction takes longer and costs extra credits on every column (returned as `figuresCredits` in a `dryRun` estimate). Requires a plan that includes figure extraction."}},"description":"Extraction stage. Supply `questions`, `generate`, or both. Omit to skip extraction entirely."},"generateReport":{"type":"boolean","default":false,"description":"Generate a full report at the end of the review. Requires `extraction`.","example":true},"title":{"type":"string","minLength":1,"maxLength":200,"description":"Optional title for the review."},"isPublic":{"type":"boolean","default":false,"description":"Whether the review should be publicly accessible via its URL without authentication. Defaults to false.","example":false},"dryRun":{"type":"boolean","const":false,"description":"Deprecated. Omit this field to create the review."}},"required":["researchQuestion"]},"examples":{"full":{"summary":"Full systematic review — search, screening, extraction, and report","value":{"researchQuestion":"Do GLP-1 receptor agonists reduce MACE in T2D patients?","searches":[{"query":"GLP-1 cardiovascular outcomes","maxResults":200}],"abstractScreening":{"generate":true},"fulltextScreening":{"reuseAbstractCriteria":true},"extraction":{"generate":true,"useFigures":false},"generateReport":true}},"fulltextCopy":{"summary":"Provided abstract criteria, fulltext copying them, provided extraction","value":{"researchQuestion":"Do GLP-1 receptor agonists reduce MACE in T2D patients?","searches":[{"query":"GLP-1 cardiovascular outcomes"}],"abstractScreening":{"criteria":[{"name":"RCT","instructions":"Randomized controlled trial"},{"name":"T2D adults","instructions":"Population is adults with T2D"}]},"fulltextScreening":{"reuseAbstractCriteria":true},"extraction":{"questions":[{"name":"N","instructions":"Total randomized"},{"name":"MACE HR","instructions":"Hazard ratio and 95% CI for 3-point MACE"}],"useFigures":true},"generateReport":true}},"additive":{"summary":"Provided + generated together: layer your criteria, let Elicit add more","value":{"researchQuestion":"Do GLP-1 receptor agonists reduce MACE in T2D patients?","searches":[{"query":"GLP-1 cardiovascular outcomes","maxResults":500}],"abstractScreening":{"criteria":[{"name":"RCT","instructions":"Randomized controlled trial"}],"generate":true},"fulltextScreening":{"criteria":[{"name":"3-point MACE defined","instructions":"Primary endpoint is 3-point MACE"}],"reuseAbstractCriteria":true},"extraction":{"questions":[{"name":"N","instructions":"Total randomized"}],"generate":true,"useFigures":false}}},"searchOnly":{"summary":"Search only — gather papers, no screening/extraction/report","description":"Omitting `abstractScreening`, `fulltextScreening`, `extraction`, and `generateReport` skips those stages. This runs a single semantic search over the research question and stops at the gathered-paper list.","value":{"researchQuestion":"Do GLP-1 receptor agonists reduce MACE in T2D patients?"}}}}}},"responses":{"202":{"description":"Systematic review creation accepted. The review is now running asynchronously. Poll `links.self` for status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystematicReviewSessionCreated"},"example":{"type":"systematicReview","sessionId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","status":"processing","url":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029","isPublic":false,"links":{"self":"https://elicit.com/api/v2/sessions/systematic-reviews/5ad08bfb-cbe0-4911-a8c3-309760d33029"}}}}},"400":{"description":"Invalid request. Check that the config matches the schema — e.g. each enabled stage has at least one source of material (`criteria` / `questions` and/or `generate`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"abstract screening must specify `criteria`, `generate: true`, or both"}}}}},"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_quota","message":"Insufficient quota."}}}}},"403":{"description":"Access denied. Either API access is not available on your plan, or the systematic-reviews surface requires features your plan does not include (guided flow, or figure extraction when `useFigures: true`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"apiAccess":{"summary":"API access not available on plan","value":{"error":{"code":"api_access_denied","message":"API access is not available on your current plan. Please upgrade to Pro or above."}}},"guidedFlow":{"summary":"Plan does not include systematic reviews","value":{"error":{"code":"guided_flow_required","message":"Systematic reviews aren't included in your current plan. Upgrade to a plan that includes systematic reviews to create one."}}},"figureExtraction":{"summary":"Plan does not include reading figures","value":{"error":{"code":"figure_extraction_required","message":"Reading figures during extraction isn't included in your current plan. Upgrade, or set `extraction.useFigures` to `false`."}}}}}}},"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"}}}}}}}},"/sessions/systematic-reviews/{sessionId}":{"get":{"tags":["Systematic Reviews"],"summary":"Get systematic review status and results","description":"Poll the status of a systematic review created via `POST /api/v2/sessions/systematic-reviews`.\n\n### Status transitions\n\n- **processing** — the pipeline is running. Watch progress at `url`.\n- **pausedForInsufficientQuota** — the account exceeded its usage limit mid-run. The review stays paused until resumed via the `links.resume` URL (or the Elicit web interface) once the limit is resolved.\n- **completed** — the pipeline finished. Stage-organized exports appear under `data`. Only stages that actually ran are included.\n- **failed** — something went wrong. The `error` field contains details. `data` may still contain exports for stages that completed before the failure.\n- **unknown** — status is not tracked (legacy or user-created).\n\n### Response shape\n\n`data` is populated as soon as each stage's outputs land — you don't need to wait for `status: completed`. Stages that haven't produced data yet (or that aren't part of this review's config) are simply omitted.\n\n- `data.search.{csv,xlsx}` — gather-stage paper list.\n- `data.screen.{csv,xlsx}` — abstract-screening results.\n- `data.fulltext.{csv,xlsx}` — fulltext-screening results (only when fulltext screening is configured).\n- `data.extract.{csv,xlsx}` — extraction-stage results.\n- `data.report` — structured content under `result`, plus optional `pdf` / `docx` / `txt` (APA reference list) / `bib` (BibTeX) / `ris` presigned download URLs.\n\nAll stage URLs are presigned for 7 days and serve with `Content-Disposition: attachment` so browser downloads land with the canonical filename.\n\n`dataFreshness` is the ISO timestamp when the cached exports were last regenerated, or `null` when nothing has been generated yet.\n\n### Including the full report body\n\nBy default, `data.report.result.reportBody` and `data.report.result.abstract` are omitted to keep responses light. Append `?include=reportBody` to include them.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"sessionId","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","schema":{"type":"string","format":"uuid","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","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":"Systematic review status and results (if completed).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystematicReviewSessionDetail"},"examples":{"processing":{"summary":"Review is running","value":{"type":"systematicReview","sessionId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","links":{"self":"https://elicit.com/api/v2/sessions/systematic-reviews/5ad08bfb-cbe0-4911-a8c3-309760d33029"},"status":"processing","url":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029","isPublic":false,"dataFreshness":null}},"searchReady":{"summary":"Review still processing — search results already downloadable","value":{"type":"systematicReview","sessionId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","links":{"self":"https://elicit.com/api/v2/sessions/systematic-reviews/5ad08bfb-cbe0-4911-a8c3-309760d33029"},"status":"processing","url":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029","isPublic":false,"data":{"search":{"csv":"https://s3.amazonaws.com/...","xlsx":"https://s3.amazonaws.com/..."}},"dataFreshness":"2025-06-15T14:35:42.000Z"}},"completedWithReport":{"summary":"Review completed with all stages and a full report","value":{"type":"systematicReview","sessionId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","links":{"self":"https://elicit.com/api/v2/sessions/systematic-reviews/5ad08bfb-cbe0-4911-a8c3-309760d33029"},"status":"completed","url":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029","isPublic":false,"data":{"search":{"csv":"https://s3.amazonaws.com/...","xlsx":"https://s3.amazonaws.com/..."},"screen":{"csv":"https://s3.amazonaws.com/...","xlsx":"https://s3.amazonaws.com/..."},"fulltext":{"csv":"https://s3.amazonaws.com/...","xlsx":"https://s3.amazonaws.com/..."},"extract":{"csv":"https://s3.amazonaws.com/...","xlsx":"https://s3.amazonaws.com/..."},"report":{"result":{"title":"GLP-1 Receptor Agonists and Cardiovascular Outcomes","summary":"This review analyzed 42 studies examining the cardiovascular effects of GLP-1 receptor agonists..."},"pdf":"https://s3.amazonaws.com/...","docx":"https://s3.amazonaws.com/...","txt":"https://s3.amazonaws.com/...","bib":"https://s3.amazonaws.com/...","ris":"https://s3.amazonaws.com/..."}},"dataFreshness":"2025-06-15T14:35:42.000Z"}},"failedAfterScreen":{"summary":"Review failed mid-pipeline; partial exports remain available","value":{"type":"systematicReview","sessionId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","links":{"self":"https://elicit.com/api/v2/sessions/systematic-reviews/5ad08bfb-cbe0-4911-a8c3-309760d33029"},"status":"failed","url":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029","isPublic":false,"error":{"code":"review_failed","message":"Systematic review failed. Any stages that completed before the failure are still downloadable."},"data":{"search":{"csv":"https://s3.amazonaws.com/...","xlsx":"https://s3.amazonaws.com/..."},"screen":{"csv":"https://s3.amazonaws.com/...","xlsx":"https://s3.amazonaws.com/..."}},"dataFreshness":"2025-06-15T14:35:42.000Z"}}}}}},"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."}}}}},"404":{"description":"Review not found. Either the review ID is invalid or the review belongs to a different user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"review_not_found","message":"Systematic review not found"}}}}}}}},"/sessions":{"get":{"tags":["Sessions"],"summary":"List sessions","description":"List all sessions — reports, systematic reviews, and research-agent sessions — for the authenticated user in a single feed, ordered by creation date (newest first).\n\nEach item carries its `sessionId`, a `type` field (`report`, `systematicReview`, or `agent`), and a `links` object with the URLs for the item's follow-up requests: `links.self` is the typed get endpoint for its full status and results, and `links.resume` appears only while the session is paused for insufficient quota. Agent items omit `executionStage` (agent sessions have no pipeline stages); for them `status: \"completed\"` means idle and awaiting input rather than terminally finished.\n\nResults are paginated using cursor-based pagination. Use the `nextCursor` value from the response to fetch the next page. Filters apply to all session types; pass `type` to list a single kind.\n\n### Example\n\n```bash\n# First page\ncurl https://elicit.com/api/v2/sessions?limit=10 \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n\n# Next page\ncurl \"https://elicit.com/api/v2/sessions?limit=10&cursor=2025-06-15T14:30:00.000Z_5ad08bfb-cbe0-4911-a8c3-309760d33029\" \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n\n# Only reports created via the API\ncurl \"https://elicit.com/api/v2/sessions?type=report&source=api\" \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","security":[{"BearerAuth":[]}],"parameters":[{"in":"query","name":"limit","description":"Maximum number of sessions to return (default: 50, max: 100)","schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of sessions to return (default: 50, max: 100)","example":20}},{"in":"query","name":"cursor","description":"Opaque pagination cursor from a previous response's nextCursor field. Omit for the first page.","schema":{"type":"string","description":"Opaque pagination cursor from a previous response's nextCursor field. Omit for the first page.","example":"2025-06-15T14:30:00.000Z_5ad08bfb-cbe0-4911-a8c3-309760d33029"}},{"in":"query","name":"source","description":"Filter by how the session was created","schema":{"type":"string","enum":["user","api","mcp","agent_session"],"description":"Filter by how the session was created","example":"api"}},{"in":"query","name":"type","description":"Filter to a single session type","schema":{"type":"string","enum":["report","systematicReview","agent"],"description":"Filter to a single session type","example":"report"}},{"in":"query","name":"status","description":"Filter by session status","schema":{"type":"string","enum":["processing","pausedForInsufficientQuota","completed","failed","unknown"],"description":"Filter by session status","example":"completed"}}],"responses":{"200":{"description":"List of sessions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSessionsResponse"},"example":{"sessions":[{"type":"report","sessionId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","status":"completed","executionStage":"done","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","isPublic":false,"links":{"self":"https://elicit.com/api/v2/sessions/reports/5ad08bfb-cbe0-4911-a8c3-309760d33029"}},{"type":"systematicReview","sessionId":"e3d0f5c4-88f6-4c3f-b6a3-0b57a2f1d3aa","status":"pausedForInsufficientQuota","executionStage":"screening_abstract","title":"Do GLP-1 receptor agonists reduce MACE in T2D patients?","url":"https://elicit.com/review/e3d0f5c4-88f6-4c3f-b6a3-0b57a2f1d3aa","source":"user","createdAt":"2025-06-14T09:12:00.000Z","isPublic":false,"links":{"self":"https://elicit.com/api/v2/sessions/systematic-reviews/e3d0f5c4-88f6-4c3f-b6a3-0b57a2f1d3aa","resume":"https://elicit.com/api/v2/sessions/e3d0f5c4-88f6-4c3f-b6a3-0b57a2f1d3aa/resume"}},{"type":"agent","sessionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","status":"processing","title":"Compare biologics for moderate-to-severe plaque psoriasis","url":"https://elicit.com/agent/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","source":"api","createdAt":"2025-06-13T18:45:00.000Z","isPublic":false,"links":{"self":"https://elicit.com/api/v2/sessions/agents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}}],"nextCursor":null,"totalCount":2}}}},"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."}}}}}}}},"/sessions/{sessionId}/resume":{"post":{"tags":["Sessions"],"summary":"Resume a paused session","description":"Resume a report, systematic review, or research-agent session that was automatically paused because your account was over its usage limit (`status: \"pausedForInsufficientQuota\"` from the get endpoints).\n\nPass the `sessionId` from the create response or `GET /api/v2/sessions` — the session type is resolved automatically. Paused sessions also carry a ready-made `links.resume` URL for this endpoint.\n\nA paused session stays paused until it is explicitly resumed. Once the usage limit is resolved (for example after upgrading or when a new billing period starts), call this endpoint — or use the resume banner in the Elicit web interface — to continue the run.\n\n### Example\n\n```bash\ncurl -X POST https://elicit.com/api/v2/sessions/{sessionId}/resume \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"sessionId","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","schema":{"type":"string","format":"uuid","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","example":"5ad08bfb-cbe0-4911-a8c3-309760d33029"},"required":true}],"responses":{"200":{"description":"Session resumed. `status` reflects the row after the resume; poll `links.self` for progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResumeSessionResponse"},"example":{"type":"systematicReview","sessionId":"e3d0f5c4-88f6-4c3f-b6a3-0b57a2f1d3aa","status":"processing","executionStage":"screening_abstract","url":"https://elicit.com/review/e3d0f5c4-88f6-4c3f-b6a3-0b57a2f1d3aa","isPublic":false,"links":{"self":"https://elicit.com/api/v2/sessions/systematic-reviews/e3d0f5c4-88f6-4c3f-b6a3-0b57a2f1d3aa"}}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}}}},"402":{"description":"Insufficient quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_quota","message":"Insufficient quota."}}}}},"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":"Session not found. Either the session ID is invalid or the session belongs to a different user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"session_not_found","message":"Session not found"}}}}},"409":{"description":"The session is not currently paused, so there is nothing to resume.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"session_not_paused","message":"Session is not paused."}}}}}}}},"/sessions/{sessionId}/shares":{"post":{"tags":["Sessions"],"summary":"Share a session","description":"Share a session read-only with another person by email. Works for every session type — reports, systematic reviews, and Research Agent sessions. Sessions are shared read-only: the recipient can view the session but cannot modify, resume, stop, or re-share it (agent sessions are read-only by design; report and systematic-review shares are read-only through the API).\n\nIf the email belongs to an existing Elicit account the share takes effect immediately (`status: \"registered\"`). Otherwise a pending invitation is created and an email is sent (`status: \"invited\"`); the share activates when they create an account.\n\nOnly the session owner can manage shares. A recipient of a shared **agent** session sees it in `GET /api/v2/sessions` with `role: \"shared\"`; a recipient of a shared **report** or **systematic review** opens it via the returned web-app `url` — it will **not** appear in their `GET /api/v2/sessions` list, which stays owner-only for review sessions.\n\n### Example\n\n```bash\ncurl -X POST https://elicit.com/api/v2/sessions/{sessionId}/shares \\\n  -H \"Authorization: Bearer elk_live_your_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\":\"colleague@example.com\"}'\n```","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"sessionId","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","schema":{"type":"string","format":"uuid","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","example":"5ad08bfb-cbe0-4911-a8c3-309760d33029"},"required":true}],"requestBody":{"required":true,"description":"Recipient email","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address to share the session with, as a read-only recipient.","example":"colleague@example.com"}},"required":["email"]}}}},"responses":{"201":{"description":"The session was shared with the recipient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSessionShareResponse"},"examples":{"registered":{"summary":"Recipient has an Elicit account","value":{"sessionId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","share":{"email":"colleague@example.com","status":"registered","role":"reader"},"url":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029"}},"invited":{"summary":"Pending invitation for an email without an account","value":{"sessionId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","share":{"email":"colleague@example.com","status":"invited","role":"reader"},"url":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029"}}}}}},"400":{"description":"Invalid request. The email is missing/malformed, or it is the caller's own address (you cannot share a session with yourself).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Malformed email","value":{"error":{"code":"invalid_request","message":"Invalid request"}}},"selfShare":{"summary":"Sharing with yourself","value":{"error":{"code":"self_share","message":"Cannot share a resource with yourself"}}}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"403":{"description":"The share could not be created: the session's recipient cap was reached, or inviting people without an Elicit account is not available on this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"capExceeded":{"summary":"Recipient cap reached","value":{"error":{"code":"cap_exceeded","message":"This session has reached its sharing limit"}}},"gateDenied":{"summary":"Inviting non-account emails not available","value":{"error":{"code":"gate_denied","message":"Inviting people without an account is not available"}}}}}}},"404":{"description":"Session not found. The session ID is invalid or belongs to a different user (or, for an agent session, the Research Agent API is not enabled for this account).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"sessionNotFound":{"summary":"Session not found","value":{"error":{"code":"session_not_found","message":"Session not found"}}},"earlyAccessNotEnabled":{"summary":"Research Agent API early access is not enabled","value":{"error":{"code":"not_found","message":"Not found"}}}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}},"get":{"tags":["Sessions"],"summary":"List a session's shares","description":"List everyone a session is shared with **read-only** — both registered recipients and pending email invitations. Reports and systematic reviews can also have editors or reviewers added in the Elicit web app; those higher-permission collaborators are managed there and are not returned here. Only the session owner can list shares.\n\n### Example\n\n```bash\ncurl https://elicit.com/api/v2/sessions/{sessionId}/shares \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"sessionId","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","schema":{"type":"string","format":"uuid","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","example":"5ad08bfb-cbe0-4911-a8c3-309760d33029"},"required":true}],"responses":{"200":{"description":"The session's current read-only shares.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSessionSharesResponse"},"example":{"sessionId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","shares":[{"email":"colleague@example.com","status":"registered","role":"reader"},{"email":"invitee@example.com","status":"invited","role":"reader"}],"url":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"Session not found. The session ID is invalid or belongs to a different user (or, for an agent session, the Research Agent API is not enabled for this account).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"sessionNotFound":{"summary":"Session not found","value":{"error":{"code":"session_not_found","message":"Session not found"}}},"earlyAccessNotEnabled":{"summary":"Research Agent API early access is not enabled","value":{"error":{"code":"not_found","message":"Not found"}}}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}},"delete":{"tags":["Sessions"],"summary":"Revoke a session share","description":"Revoke a read-only share by email. Removes either an active share (for a registered recipient) or a pending invitation. Only the session owner can revoke shares.\n\nThe operation is idempotent: revoking an email that isn't currently shared returns `revoked: false` with `200 OK`.\n\n### Example\n\n```bash\ncurl -X DELETE https://elicit.com/api/v2/sessions/{sessionId}/shares \\\n  -H \"Authorization: Bearer elk_live_your_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\":\"colleague@example.com\"}'\n```","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"sessionId","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","schema":{"type":"string","format":"uuid","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","example":"5ad08bfb-cbe0-4911-a8c3-309760d33029"},"required":true}],"requestBody":{"required":true,"description":"Email whose share to revoke","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address whose share (or pending invite) should be revoked.","example":"colleague@example.com"}},"required":["email"]}}}},"responses":{"200":{"description":"The share was revoked, or there was nothing to revoke (idempotent).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteSessionShareResponse"},"example":{"sessionId":"5ad08bfb-cbe0-4911-a8c3-309760d33029","email":"colleague@example.com","revoked":true}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"Session not found. The session ID is invalid or belongs to a different user (or, for an agent session, the Research Agent API is not enabled for this account).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"sessionNotFound":{"summary":"Session not found","value":{"error":{"code":"session_not_found","message":"Session not found"}}},"earlyAccessNotEnabled":{"summary":"Research Agent API early access is not enabled","value":{"error":{"code":"not_found","message":"Not found"}}}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/usage":{"get":{"tags":["Usage"],"summary":"Get usage status","description":"Report the authenticated account's current usage against its plan.\n\nReturns whether the account still has usage available (`hasUsageRemaining`), the percentage of plan usage consumed this billing period, the billing-period bounds, and — only when extra usage is enabled — the extra-usage spend and limit in USD cents.\n\n### Example\n\n```bash\ncurl https://elicit.com/api/v2/usage \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Current usage status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUsageResponse"}}}},"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."}}}}},"409":{"description":"Usage reporting is not available for this account, or usage data is not ready yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"notAvailable":{"summary":"Usage reporting not available for this account","value":{"error":{"code":"not_credits_pricing","message":"Usage reporting is not available for this account."}}},"notReady":{"summary":"Usage data not provisioned yet — retry shortly","value":{"error":{"code":"usage_unavailable","message":"Usage data is not ready yet; retry shortly."}}}}}}}}}},"/sessions/agents":{"post":{"tags":["Research Agent"],"summary":"Create a Research Agent session","description":"Start a stateful Research Agent session. Elicit investigates the query asynchronously, reports its activity as structured events, and may produce downloadable artifacts.\n\nThe response returns immediately with a `sessionId`. Use the events endpoint to follow the research, then send messages to refine or continue it. The session is also available at the returned `url`.\n\nThis endpoint is in early access. It returns `404 not_found` unless the Research Agent API has been enabled for the authenticated account or organization.\n\n### End-to-end workflow\n\nA full research task may involve several requests against a single session. To drive it end to end:\n\n1. **(Optional) Upload files.** POST /api/v2/files, PUT the bytes to the presigned URL, and keep each `file_id` (see the Upload endpoint).\n2. **Create the session.** POST /api/v2/sessions/agents with your `query` and any `attachments`. The response is immediate with `status: \"processing\"` and a `sessionId`.\n3. **Poll for activity.** GET /api/v2/sessions/agents/:sessionId/events. Pass the returned `cursor` unchanged on each subsequent poll to receive immutable event occurrences not observed at that checkpoint. Append them in response order and deduplicate retries by `eventId`. Poll every 3–10 seconds while the top-level `status` is `processing`.\n4. **Detect idle.** The agent is ready for another request when a `session_idle` event appears and the top-level `status` returns to `completed`. For a Research Agent session, `completed` means **idle and awaiting input** — not that the session is permanently closed. Watch for these events along the way:\n   - `question` — the agent needs input; answer it with a follow-up message.\n   - `error` — the agent encountered an error; `retryable` indicates whether resending is worthwhile.\n   - `session_paused` — the account hit its usage limit; the status becomes `pausedForInsufficientQuota`. Resolve the limit, then resume the session via POST /api/v2/sessions/:sessionId/resume (or the Elicit web interface) before continuing.\n5. **Send a follow-up.** POST /api/v2/sessions/agents/:sessionId/messages with your message (and any `attachments`). Correlate the returned `messageId` with the matching `user_message` event, then return to step 3.\n6. **Retrieve artifacts.** GET /api/v2/sessions/agents/:sessionId/artifacts to list what the agent produced: files appear under `artifacts` (GET .../artifacts/:artifactId/download for a short-lived presigned download URL — treat it as a credential), and interactive outputs (tables, prose, presentations, figures) appear under `deliveredOutputs` (GET .../artifacts/:artifactId/content for their contents).\n7. **(Optional) Stop early.** POST /api/v2/sessions/agents/:sessionId/stop to interrupt a running turn, then poll the events endpoint for the `session_stopped` event.\n\n### Session status\n\nThe list, detail, and events endpoints all report the same top-level `status`:\n\n- `processing` — the agent is working (or the session has not started yet).\n- `completed` — idle and awaiting input; the latest work finished successfully.\n- `failed` — the latest work ended with an error.\n- `pausedForInsufficientQuota` — paused at the account usage limit; resume once the limit clears.\n- `unknown` — status could not be determined (legacy sessions only).\n\nAll errors return the standard `{ \"error\": { \"code\", \"message\" } }` envelope.\n\n### Example\n\n```bash\n# Minimal\ncurl -X POST https://elicit.com/api/v2/sessions/agents \\\n  -H \"Authorization: Bearer elk_live_your_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\":\"What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?\"}'\n\n# With an uploaded file attached to the initial turn\ncurl -X POST https://elicit.com/api/v2/sessions/agents \\\n  -H \"Authorization: Bearer elk_live_your_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\":\"Summarize the attached trial and compare it to the current literature.\",\"attachments\":[{\"file_id\":\"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d\"}]}'\n```","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"description":"Initial Research Agent query","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":2000,"description":"The initial query for the research agent. Elicit creates a stateful research session that investigates the query. The session is continuable in the Elicit web interface.","example":"What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?"},"attachments":{"type":"array","items":{"type":"object","properties":{"file_id":{"type":"string","format":"uuid","description":"The file_id returned by POST /api/v2/files for a previously uploaded file.","example":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}},"required":["file_id"]},"maxItems":20,"description":"Files to attach to this turn, each referencing a file_id from POST /api/v2/files. Attached files are made available to the research agent exactly as uploads made in the web interface are."}},"required":["query"]}}}},"responses":{"202":{"description":"Session creation accepted. The Research Agent is processing the initial query asynchronously.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentSessionResponse"},"example":{"sessionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","status":"processing","url":"https://elicit.com/agent/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}}}},"400":{"description":"Invalid request. `query` must contain 1–2,000 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request"}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"402":{"description":"Insufficient quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_quota","message":"Insufficient quota."}}}}},"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":"Research Agent API early access is not enabled for this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"Not found"}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/sessions/agents/{sessionId}":{"get":{"tags":["Research Agent"],"summary":"Get Research Agent session status","description":"Fetch the status and basic metadata of a research-agent session — the typed detail endpoint that an agent item's `links.self` in `GET /api/v2/sessions` points to.\n\n### Status values\n\n- **processing** — The agent is working, or the session is queued and hasn't started.\n- **completed** — The agent is idle and awaiting input. This is *not* a terminal state: the session can be continued (agent sessions have no terminal \"finished\" state).\n- **failed** — The last turn ended with an error.\n- **pausedForInsufficientQuota** — The account exceeded its usage limit. The session stays paused until resumed via the `links.resume` URL (or the Elicit web interface).\n\nNo event payload is returned here; use the session's events endpoint for the reduced activity stream.\n\n### Example\n\n```bash\ncurl https://elicit.com/api/v2/sessions/agents/{sessionId} \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"sessionId","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","schema":{"type":"string","format":"uuid","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","example":"5ad08bfb-cbe0-4911-a8c3-309760d33029"},"required":true}],"responses":{"200":{"description":"Research-agent session status and metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSessionDetail"},"examples":{"processing":{"summary":"Agent is working","value":{"type":"agent","sessionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","status":"processing","title":"Compare biologics for moderate-to-severe plaque psoriasis","url":"https://elicit.com/agent/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","source":"api","createdAt":"2026-07-23T14:30:00.000Z","isPublic":false,"links":{"self":"https://elicit.com/api/v2/sessions/agents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}}},"completed":{"summary":"Agent is idle, awaiting input (not terminally finished)","value":{"type":"agent","sessionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","status":"completed","title":"Compare biologics for moderate-to-severe plaque psoriasis","url":"https://elicit.com/agent/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","source":"api","createdAt":"2026-07-23T14:30:00.000Z","isPublic":false,"links":{"self":"https://elicit.com/api/v2/sessions/agents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}}},"failed":{"summary":"The last turn ended with an error","value":{"type":"agent","sessionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","status":"failed","title":"Compare biologics for moderate-to-severe plaque psoriasis","url":"https://elicit.com/agent/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","source":"api","createdAt":"2026-07-23T14:30:00.000Z","isPublic":false,"links":{"self":"https://elicit.com/api/v2/sessions/agents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}}},"paused":{"summary":"Paused for insufficient quota — resume available","value":{"type":"agent","sessionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","status":"pausedForInsufficientQuota","title":"Compare biologics for moderate-to-severe plaque psoriasis","url":"https://elicit.com/agent/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","source":"api","createdAt":"2026-07-23T14:30:00.000Z","isPublic":false,"links":{"self":"https://elicit.com/api/v2/sessions/agents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","resume":"https://elicit.com/api/v2/sessions/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/resume"}}}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"The Research Agent API is not enabled for this account, or the session does not exist or belongs to another user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"earlyAccessNotEnabled":{"summary":"Research Agent API early access is not enabled","value":{"error":{"code":"not_found","message":"Not found"}}},"sessionNotFound":{"summary":"Session not found","value":{"error":{"code":"session_not_found","message":"Session not found"}}}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/sessions/agents/{sessionId}/events":{"get":{"tags":["Research Agent"],"summary":"Get Research Agent session events","description":"Get a reduced view of a Research Agent session's activity.\n\nStreaming text, thinking, and tool-input deltas are collapsed into complete typed entries. With no `cursor`, the response contains the full reduced history. Pass the returned cursor unchanged on the next poll to receive immutable event occurrences not observed at that checkpoint.\n\nThe public event kinds are `user_message`, `agent_message`, `question`, `activity`, `artifacts_delivered`, `delivered_outputs`, `error`, `session_idle`, `session_paused`, `session_resumed`, `stop_requested`, and `session_stopped`. Internal tool names, sandbox paths, raw tool results, and candidate counters are never returned.\n\nEvery event includes a stable `eventId` and an ISO 8601 `createdAt` timestamp when available. Events are immutable and append-only. A resource can have several snapshots: for example, an `activity` may first be `started` and later `completed`. Those occurrences share an `activityId` but have distinct `eventId` values. Append incremental responses in response order and deduplicate retries by `eventId`.\n\nThe top-level `status` has exactly the same meaning and value as the list and detail endpoints. Lifecycle facts that are not part of the shared session status vocabulary are represented by explicit events: the agent becomes ready for more input with `session_idle`, a stop completes with `session_stopped`, and pause/resume use `session_paused`/`session_resumed`.\n\n### Polling example\n\n```bash\n# Full history\ncurl https://elicit.com/api/v2/sessions/agents/{sessionId}/events \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n\n# Only event occurrences not observed at the cursor checkpoint\ncurl \"https://elicit.com/api/v2/sessions/agents/{sessionId}/events?cursor={cursor}\" \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```\n\nPoll every 3–10 seconds while `status` is `processing`. The agent is ready for another request when a `session_idle` event appears and the status returns to `completed` (idle, awaiting input). A `question` event indicates that the agent needs input. A `session_stopped` event confirms that a stop request was processed. If a cursor is rejected, refetch once without a cursor and rebuild local event state.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"sessionId","schema":{"type":"string","format":"uuid"},"required":true},{"in":"query","name":"cursor","description":"Opaque cursor from a previous response. When provided, only immutable event occurrences after that checkpoint are returned. Omit it to receive the full history.","schema":{"type":"string","description":"Opaque cursor from a previous response. When provided, only immutable event occurrences after that checkpoint are returned. Omit it to receive the full history."}}],"responses":{"200":{"description":"Full or incremental reduced session activity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAgentSessionEventsResponse"},"example":{"sessionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","status":"processing","events":[{"eventId":"evt_a834376a97b8a7d8259b5c42","kind":"user_message","createdAt":"2026-07-23T14:30:00.000Z","messageId":"msg_a834376a97b8a7d8259b5c42","text":"What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?","isInitial":true},{"eventId":"evt_7f19a13d5ce4e961866933fa","kind":"activity","createdAt":"2026-07-23T14:30:03.000Z","activityId":"activity_e66e32cf495d58e6553b736f","status":"started","title":"Searching for controlled studies","summary":null}],"cursor":"eyJ2IjoxLCJzaWQiOiJhMWIyYzNkNCIsInUiOjIsInciOjEwfQ","url":"https://elicit.com/agent/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}}}},"400":{"description":"The cursor is malformed, belongs to another session, or is ahead of the session's current position. Retry without a cursor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Malformed cursor","value":{"error":{"code":"invalid_cursor","message":"Malformed cursor."}}},"wrongSession":{"summary":"Cursor belongs to another session","value":{"error":{"code":"cursor_session_mismatch","message":"Cursor does not belong to this session."}}},"ahead":{"summary":"Cursor is ahead of the current stream","value":{"error":{"code":"cursor_out_of_range","message":"Cursor is ahead of the session's current position; refetch without a cursor."}}}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"The Research Agent API is not enabled for this account, or the session does not exist or belongs to another user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"earlyAccessNotEnabled":{"summary":"Research Agent API early access is not enabled","value":{"error":{"code":"not_found","message":"Not found"}}},"sessionNotFound":{"summary":"Session not found","value":{"error":{"code":"session_not_found","message":"Session not found"}}}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/sessions/agents/{sessionId}/messages":{"post":{"tags":["Research Agent"],"summary":"Send a message to a Research Agent session","description":"Insert a follow-up message and start another asynchronous turn. Use messages to refine a result, answer the agent, redirect the research, or request another artifact.\n\nThe response includes a `messageId`. The corresponding `user_message` event carries the same value, allowing the client to confirm delivery.\n\nAttach previously uploaded files by including their `file_id`s in the `attachments` array (see the Upload endpoint).\n\nIf the session is paused for insufficient quota, resolve the usage limit and resume it via `POST /api/v2/sessions/:sessionId/resume` (or the Elicit web interface) before sending another message.\n\n### Example\n\n```bash\ncurl -X POST https://elicit.com/api/v2/sessions/agents/{sessionId}/messages \\\n  -H \"Authorization: Bearer elk_live_your_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"message\":\"Focus on randomized controlled trials only.\"}'\n```","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"sessionId","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"required":true,"description":"Follow-up message","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":2000,"description":"The message to insert into the running research agent session.","example":"Focus on randomized controlled trials only."},"attachments":{"type":"array","items":{"type":"object","properties":{"file_id":{"type":"string","format":"uuid","description":"The file_id returned by POST /api/v2/files for a previously uploaded file.","example":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}},"required":["file_id"]},"maxItems":20,"description":"Files to attach to this turn, each referencing a file_id from POST /api/v2/files. Attached files are made available to the research agent exactly as uploads made in the web interface are."}},"required":["message"]}}}},"responses":{"202":{"description":"Message accepted. The session is processing another turn.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostAgentSessionMessageResponse"},"example":{"sessionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","status":"processing","messageId":"msg_8d9a5f42e7c64ba18bddca21","url":"https://elicit.com/agent/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}}}},"400":{"description":"Invalid request. `message` must contain 1–2,000 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"402":{"description":"Insufficient quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_quota","message":"Insufficient quota."}}}}},"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":"The Research Agent API is not enabled for this account, or the session does not exist or belongs to another user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"earlyAccessNotEnabled":{"summary":"Research Agent API early access is not enabled","value":{"error":{"code":"not_found","message":"Not found"}}},"sessionNotFound":{"summary":"Session not found","value":{"error":{"code":"session_not_found","message":"Session not found"}}}}}}},"409":{"description":"The session failed or is paused for insufficient quota and cannot accept a message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"failed":{"summary":"Session failed","value":{"error":{"code":"session_failed","message":"Session has failed and cannot accept new messages."}}},"paused":{"summary":"Session paused","value":{"error":{"code":"session_paused","message":"Session is paused for insufficient quota. Resume it before inserting messages."}}}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/files":{"post":{"tags":["Research Agent","Library"],"summary":"Upload a file","description":"Stage a file so it can be attached to a Research Agent turn or imported into your library. This is a two-step, presigned upload:\n\n1. **POST /api/v2/files** with the filename, MIME type, and exact byte size. The response returns a `file_id` and a short-lived presigned `upload_url`.\n2. **PUT** the raw file bytes to `upload_url` with the same `Content-Type` and a `Content-Length` matching `size_bytes`. Do not send an `Authorization` header on the PUT — the URL is already signed.\n\nThen either pass `{ \"file_id\": \"...\" }` in the `attachments` array of a create-session or send-message request — attached files are made available to the agent exactly as uploads made in the web interface are — or pass the `file_id` in `fileIds` to `POST /api/v2/library/imports` to parse the PDF into your library. A staged file can be used once.\n\nThe request/response fields for this endpoint are deliberately `snake_case` (`content_type`, `size_bytes`, `file_id`, `upload_url`, `expires_at`), unlike the camelCase used elsewhere in the v2 surface. Files are capped at 30 MB, and a session accepts a bounded number of attachments; the `upload_url` and `file_id` expire at `expires_at`.\n\nThis endpoint is in early access. It returns `404 not_found` unless the Research Agent API has been enabled for the authenticated account or organization.\n\n### Example\n\n```bash\n# 1. Register the upload\ncurl -X POST https://elicit.com/api/v2/files \\\n  -H \"Authorization: Bearer elk_live_your_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"filename\":\"trial-results.pdf\",\"content_type\":\"application/pdf\",\"size_bytes\":245678}'\n\n# 2. Upload the bytes to the returned upload_url\ncurl -X PUT \"{upload_url}\" \\\n  -H \"Content-Type: application/pdf\" \\\n  --data-binary @trial-results.pdf\n\n# 3. Attach {\"file_id\": \"...\"} to a create-session or /messages request,\n#    or import it with POST /library/imports {\"fileIds\": [\"...\"]}\n```","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"description":"File metadata for the presigned upload","content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":512,"description":"Original filename of the upload. Used as the display name in the session.","example":"trial-results.pdf"},"content_type":{"type":"string","minLength":1,"maxLength":255,"description":"MIME type of the file.","example":"application/pdf"},"size_bytes":{"type":"integer","exclusiveMinimum":0,"maximum":31457280,"description":"Exact size of the file in bytes. Must match the uploaded object exactly. Maximum 31457280 bytes (30 MB).","example":245678}},"required":["filename","content_type","size_bytes"]}}}},"responses":{"200":{"description":"Upload registered. PUT the file bytes to `upload_url` before it expires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFileResponse"},"example":{"file_id":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","upload_url":"https://s3.amazonaws.com/...","expires_at":"2026-07-23T15:00:00.000Z"}}}},"400":{"description":"Invalid request. The filename, content type, or size is missing or invalid, or the size exceeds the 30 MB limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Invalid request"}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"402":{"description":"Insufficient quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_quota","message":"Insufficient quota."}}}}},"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":"Research Agent API early access is not enabled for this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"Not found"}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/sessions/agents/{sessionId}/artifacts":{"get":{"tags":["Research Agent"],"summary":"List Research Agent session artifacts","description":"List files and interactive outputs produced in a Research Agent session.\n\nFile-backed artifacts are listed under `artifacts`. Only the latest version of each is listed. A delivered file appears once as `agent-delivered-file`; `agent-saved-file` denotes a workspace file that the agent saved but did not deliver.\n\nInteractive outputs delivered as session outputs (tables, prose, presentations, figures) are listed under `deliveredOutputs`; retrieve their contents from the artifact content endpoint.\n\nUse the opaque, session-scoped `artifactId` with the download endpoint (for `artifacts`) or the content endpoint (for `deliveredOutputs`). Do not construct or decode artifact IDs.\n\n### Example\n\n```bash\ncurl https://elicit.com/api/v2/sessions/agents/{sessionId}/artifacts \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"sessionId","schema":{"type":"string","format":"uuid"},"required":true}],"responses":{"200":{"description":"Latest artifacts produced in the session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAgentSessionArtifactsResponse"},"example":{"sessionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","artifacts":[{"artifactId":"YWdlbnQtZGVsaXZlcmVkLWZpbGU6...","kind":"agent-delivered-file","format":"docx","filename":"cardiovascular_outcomes.docx","contentType":"application/vnd.openxmlformats-officedocument.wordprocessingml.document","sizeBytes":48231,"createdAt":"2026-07-23T14:42:10.000Z"}],"deliveredOutputs":[{"artifactId":"aW50ZXJhY3RpdmUtdGFibGU6...","kind":"table","title":"Biologics for plaque psoriasis","caption":"Comparison of efficacy outcomes across included trials","rowCount":12,"downloadFormats":["csv","xlsx"],"createdAt":"2026-07-23T14:41:05.000Z"}],"url":"https://elicit.com/agent/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"The Research Agent API is not enabled for this account, or the session does not exist or belongs to another user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"earlyAccessNotEnabled":{"summary":"Research Agent API early access is not enabled","value":{"error":{"code":"not_found","message":"Not found"}}},"sessionNotFound":{"summary":"Session not found","value":{"error":{"code":"session_not_found","message":"Session not found"}}}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/sessions/agents/{sessionId}/artifacts/{artifactId}/content":{"get":{"tags":["Research Agent"],"summary":"Get interactive artifact contents","description":"Materialize the contents of an interactive artifact listed under `deliveredOutputs` on the list-artifacts endpoint.\n\nThe response is structured JSON discriminated on `kind`: tables carry `columns` and `rows`; prose and figures carry supported content (cleaned text, the original markdown, and resolved citations); presentations carry slides. The default `format` is `json` (omitting the parameter is equivalent to `?format=json`). Tables can also be downloaded with `?format=csv` or `?format=xlsx`, and prose with `?format=md`. File responses are served with `Content-Disposition: attachment`, not as JSON. Unsupported kind/format combinations return `400 download_not_available`.\n\n### Example\n\n```bash\n# Structured JSON\ncurl https://elicit.com/api/v2/sessions/agents/{sessionId}/artifacts/{artifactId}/content \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n\n# Table as CSV\ncurl \"https://elicit.com/api/v2/sessions/agents/{sessionId}/artifacts/{artifactId}/content?format=csv\" \\\n  -H \"Authorization: Bearer elk_live_your_key_here\" \\\n  -O -J\n\n# Prose as portable Markdown\ncurl \"https://elicit.com/api/v2/sessions/agents/{sessionId}/artifacts/{artifactId}/content?format=md\" \\\n  -H \"Authorization: Bearer elk_live_your_key_here\" \\\n  -O -J\n```","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"sessionId","schema":{"type":"string","format":"uuid"},"required":true},{"in":"path","name":"artifactId","schema":{"type":"string","minLength":1},"required":true},{"in":"query","name":"format","description":"Response format: omit or \"json\" for the JSON body; \"csv\"/\"xlsx\" to download a table as a file, or \"md\" to download prose as Markdown.","schema":{"type":"string","enum":["json","csv","xlsx","md"],"description":"Response format: omit or \"json\" for the JSON body; \"csv\"/\"xlsx\" to download a table as a file, or \"md\" to download prose as Markdown."}}],"responses":{"200":{"description":"Contents of the interactive artifact: structured JSON, a CSV/XLSX file for a table, or a Markdown file for prose.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAgentSessionArtifactContentResponse"},"example":{"artifactId":"aW50ZXJhY3RpdmUtdGFibGU6...","kind":"table","title":"Biologics for plaque psoriasis","caption":"Comparison of efficacy outcomes across included trials","columns":["Study","Intervention","PASI 90 at week 16"],"rows":[{"Study":{"text":"UNCOVER-3","citations":[],"source":null},"Intervention":{"text":"Ixekizumab 80 mg Q2W","citations":[],"source":null},"PASI 90 at week 16":{"text":"68%","citations":[],"source":null}}],"url":"https://elicit.com/agent/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}},"text/csv":{"schema":{"type":"string","format":"binary"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}},"text/markdown":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"The requested file format is not available for this artifact kind. Tables support CSV/XLSX and prose supports Markdown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"download_not_available","message":"The requested download format is not available for this artifact."}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"Research Agent API early access is not enabled, the session was not found, or the artifact is not in the session's current deliveredOutputs list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"earlyAccessNotEnabled":{"summary":"Research Agent API early access is not enabled","value":{"error":{"code":"not_found","message":"Not found"}}},"sessionNotFound":{"summary":"Session not found","value":{"error":{"code":"session_not_found","message":"Session not found"}}},"artifactNotFound":{"summary":"Artifact not found","value":{"error":{"code":"artifact_not_found","message":"Artifact not found"}}}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/sessions/agents/{sessionId}/artifacts/{artifactId}/download":{"get":{"tags":["Research Agent"],"summary":"Create an artifact download URL","description":"Create a short-lived presigned URL for an artifact returned by the list-artifacts endpoint.\n\nThe URL expires after 30 minutes. Call this endpoint again to issue a fresh URL. Treat the URL as a credential while it is valid: do not log it or store it as a permanent share link.\n\n### Example\n\n```bash\ncurl https://elicit.com/api/v2/sessions/agents/{sessionId}/artifacts/{artifactId}/download \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"sessionId","schema":{"type":"string","format":"uuid"},"required":true},{"in":"path","name":"artifactId","schema":{"type":"string","minLength":1},"required":true}],"responses":{"200":{"description":"Short-lived artifact download URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadAgentSessionArtifactResponse"},"example":{"downloadUrl":"https://s3.amazonaws.com/...","expiresAt":"2026-07-23T15:12:10.000Z","filename":"cardiovascular_outcomes.docx","contentType":"application/vnd.openxmlformats-officedocument.wordprocessingml.document"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"Research Agent API early access is not enabled, the session was not found, or the artifact is not in the session's current artifact list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"earlyAccessNotEnabled":{"summary":"Research Agent API early access is not enabled","value":{"error":{"code":"not_found","message":"Not found"}}},"sessionNotFound":{"summary":"Session not found","value":{"error":{"code":"session_not_found","message":"Session not found"}}},"artifactNotFound":{"summary":"Artifact not found","value":{"error":{"code":"artifact_not_found","message":"Artifact not found"}}}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/sessions/agents/{sessionId}/stop":{"post":{"tags":["Research Agent"],"summary":"Stop a Research Agent session","description":"Request an asynchronous interrupt using the same stop action as the Elicit web interface.\n\nStopping does not delete or permanently close the session. The session remains visible and may be continued later. When the response status is `stopping`, poll the events endpoint until a `session_stopped` event appears.\n\nThe operation is idempotent. If the session is already stopped or failed, it returns the existing state with `200 OK`.\n\n### Example\n\n```bash\ncurl -X POST https://elicit.com/api/v2/sessions/agents/{sessionId}/stop \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"sessionId","schema":{"type":"string","format":"uuid"},"required":true}],"responses":{"200":{"description":"The session had already stopped or failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StopAgentSessionResponse"},"examples":{"stopped":{"summary":"Already stopped","value":{"sessionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","status":"stopped","url":"https://elicit.com/agent/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}},"failed":{"summary":"Already failed","value":{"sessionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","status":"failed","url":"https://elicit.com/agent/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}}}}}},"202":{"description":"The stop request was queued. Poll the events endpoint until the session is stopped.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StopAgentSessionResponse"},"example":{"sessionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","status":"stopping","url":"https://elicit.com/agent/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"The Research Agent API is not enabled for this account, or the session does not exist or belongs to another user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"earlyAccessNotEnabled":{"summary":"Research Agent API early access is not enabled","value":{"error":{"code":"not_found","message":"Not found"}}},"sessionNotFound":{"summary":"Session not found","value":{"error":{"code":"session_not_found","message":"Session not found"}}}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/library/sources":{"get":{"tags":["Library"],"security":[{"BearerAuth":[]}],"summary":"List library sources","description":"Returns your own sources, newest first. A shared collection's papers are listed with `collectionId`, and each carries your `role`.\n\nFilters combine with AND. `q` matches each term as a case-insensitive substring of the title, authors, abstract, venue, or Elicit id. A DOI-shaped term matches the DOI. `doi` and `elicitId` are exact filters. `fullTextStatus` filters by whether parsed full text is attached.\n\nDefault page size 50, maximum 100. `totalCount` counts all matches, not the page.\n\n### Example\n\n```bash\ncurl \"https://elicit.com/api/v2/library/sources?q=semaglutide&fullTextStatus=available\" \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","parameters":[{"in":"query","name":"q","description":"Search query: whitespace-separated words and \"quoted phrases\" (max 10 terms). Every term must match the title, an author, the abstract, the venue, the Elicit id, or — for DOI-shaped terms — the DOI (case-insensitive substring). Terms are ANDed; there is no OR — run one request per alternative.","schema":{"type":"string","maxLength":500,"description":"Search query: whitespace-separated words and \"quoted phrases\" (max 10 terms). Every term must match the title, an author, the abstract, the venue, the Elicit id, or — for DOI-shaped terms — the DOI (case-insensitive substring). Terms are ANDed; there is no OR — run one request per alternative."}},{"in":"query","name":"doi","description":"Exact DOI match; doi.org URLs and doi: prefixes are accepted.","schema":{"type":"string","minLength":1,"maxLength":512,"description":"Exact DOI match; doi.org URLs and doi: prefixes are accepted."}},{"in":"query","name":"elicitId","schema":{"type":"string","minLength":1,"maxLength":256}},{"in":"query","name":"collectionId","description":"Restrict to one collection.","schema":{"type":"string","format":"uuid","description":"Restrict to one collection."}},{"in":"query","name":"yearMin","schema":{"type":"integer","minimum":1000,"maximum":9999}},{"in":"query","name":"yearMax","schema":{"type":"integer","minimum":1000,"maximum":9999}},{"in":"query","name":"fullTextStatus","description":"Only sources whose fullTextStatus matches.","schema":{"type":"string","enum":["pending","available","unavailable"],"description":"Only sources whose fullTextStatus matches."}},{"in":"query","name":"cursor","description":"Pagination cursor from a previous response's nextCursor.","schema":{"type":"string","maxLength":200,"description":"Pagination cursor from a previous response's nextCursor."}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"One page of matching sources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListLibrarySourcesResponse"},"example":{"sources":[{"id":"8e2d4d52-3b8a-4f6c-9e1a-2c7b6d5e4f30","title":"Semaglutide and cardiovascular outcomes in obesity without diabetes","authors":["A. Michael Lincoff","Kirstine Brown-Frandsen","Helen M. Colhoun"],"year":2023,"venue":"New England Journal of Medicine","abstract":"Semaglutide, a glucagon-like peptide-1 receptor agonist, has been shown to…","doi":"10.1056/nejmoa2307563","url":"https://www.nejm.org/doi/full/10.1056/NEJMoa2307563","elicitId":"W4388464589","pdfUrls":[],"collectionIds":["b458052a-84e2-4e47-b5c4-00e11390a265"],"role":"writer","fullTextStatus":"available","createdAt":"2026-08-30T09:12:44.000Z","updatedAt":"2026-08-30T09:13:20.000Z","links":{"self":"https://elicit.com/api/v2/library/sources/8e2d4d52-3b8a-4f6c-9e1a-2c7b6d5e4f30","fullText":"https://elicit.com/api/v2/library/sources/8e2d4d52-3b8a-4f6c-9e1a-2c7b6d5e4f30/full-text"}}],"nextCursor":null,"totalCount":1}}}},"400":{"description":"A malformed id, or an unknown or invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"params.sourceId: Invalid uuid"}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}},"post":{"tags":["Library"],"security":[{"BearerAuth":[]}],"summary":"Save library sources","description":"Saves 1–100 papers. Each item is one of: an `elicitId`; a `pdfUrls` entry, metadata optional; or a `title` with at least one of `doi`, `authors`, `year`, `venue`, `abstract`, `url`. A `doi` alone is rejected. Elicit fills missing metadata from its corpus or the parsed PDF. `pdfUrls` is how to attach a PDF: Elicit fetches and parses it in the background when the paper is not in the corpus. Do not download PDFs yourself; for local files, use imports.\n\nThe response lists each item in request order. An item that matches a paper already in your library returns that source with `created: false` and `duplicateOf` set. With `onDuplicate: skip` (default), fields the existing source lacked are filled from the item and listed in `updatedFields`. Existing values do not change. Adding `pdfUrls`, `doi`, or `elicitId` to an existing source starts enrichment for it again. With `onDuplicate: create`, a copy is saved and the pair is recorded as a potential duplicate. `collectionIds` adds every returned source to those collections; each source's `collections` reports, per collection, the id the collection holds for the paper and whether this call added it. A group collection holds its own copy under a different id, so the returned source's `collectionIds` does not list it.\n\nMetadata and full text for new sources arrive asynchronously. A new source starts with `fullTextStatus: pending`. When `fullTextStatus` changes, enrichment is complete. A source that still has `title: null` at that point has an identifier that is not in the corpus.\n\n### Example\n\n```bash\ncurl -X POST https://elicit.com/api/v2/library/sources \\\n  -H \"Authorization: Bearer elk_live_your_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"sources\":[{\"doi\":\"10.1056/NEJMoa2307563\"},{\"title\":\"Attention Is All You Need\",\"authors\":[\"Ashish Vaswani\"],\"year\":2017}],\"collectionIds\":[\"b458052a-84e2-4e47-b5c4-00e11390a265\"]}'\n```","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/CreateLibrarySourceItem"},"minItems":1,"maxItems":100},"collectionIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100,"description":"Collections you own or can edit to add every returned source to, duplicates included."},"onDuplicate":{"type":"string","enum":["skip","create"],"description":"skip (default): an item matching an already-saved source returns that source, updating any fields it lacked, instead of creating one. create: saves anyway and records a potential-duplicate pair for the app's review-duplicates flow."}},"required":["sources"],"additionalProperties":false}}}},"responses":{"200":{"description":"One entry per item, in request order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLibrarySourcesResponse"},"example":{"sources":[{"id":"8e2d4d52-3b8a-4f6c-9e1a-2c7b6d5e4f30","title":"Semaglutide and cardiovascular outcomes in obesity without diabetes","authors":["A. Michael Lincoff","Kirstine Brown-Frandsen","Helen M. Colhoun"],"year":2023,"venue":"New England Journal of Medicine","abstract":"Semaglutide, a glucagon-like peptide-1 receptor agonist, has been shown to…","doi":"10.1056/nejmoa2307563","url":"https://www.nejm.org/doi/full/10.1056/NEJMoa2307563","elicitId":"W4388464589","pdfUrls":[],"collectionIds":[],"role":"writer","fullTextStatus":"pending","createdAt":"2026-08-30T09:12:44.000Z","updatedAt":"2026-08-30T09:13:20.000Z","links":{"self":"https://elicit.com/api/v2/library/sources/8e2d4d52-3b8a-4f6c-9e1a-2c7b6d5e4f30","fullText":"https://elicit.com/api/v2/library/sources/8e2d4d52-3b8a-4f6c-9e1a-2c7b6d5e4f30/full-text"},"created":true,"duplicateOf":null,"updatedFields":[],"collections":[{"collectionId":"b458052a-84e2-4e47-b5c4-00e11390a265","sourceId":"5b0d3f2a-8c41-4e7b-9d6e-2f1a7c3b9e84","added":true}]}]}}}},"400":{"description":"A malformed id, or an unknown or invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"params.sourceId: Invalid uuid"}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"The collection does not exist or is not visible to you.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"Collection not found."}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/library/sources/{sourceId}":{"get":{"tags":["Library"],"security":[{"BearerAuth":[]}],"summary":"Retrieve a library source","description":"Retrieves a source by id.\n\n`fullTextStatus` values: `pending`, Elicit has not finished looking for a PDF; `available`, full text is ready; `unavailable`, no PDF was found.\n\n### Example\n\n```bash\ncurl https://elicit.com/api/v2/library/sources/{sourceId} \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","parameters":[{"in":"path","name":"sourceId","schema":{"type":"string","format":"uuid"},"required":true}],"responses":{"200":{"description":"The source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LibrarySource"},"example":{"id":"8e2d4d52-3b8a-4f6c-9e1a-2c7b6d5e4f30","title":"Semaglutide and cardiovascular outcomes in obesity without diabetes","authors":["A. Michael Lincoff","Kirstine Brown-Frandsen","Helen M. Colhoun"],"year":2023,"venue":"New England Journal of Medicine","abstract":"Semaglutide, a glucagon-like peptide-1 receptor agonist, has been shown to…","doi":"10.1056/nejmoa2307563","url":"https://www.nejm.org/doi/full/10.1056/NEJMoa2307563","elicitId":"W4388464589","pdfUrls":[],"collectionIds":["b458052a-84e2-4e47-b5c4-00e11390a265"],"role":"writer","fullTextStatus":"available","createdAt":"2026-08-30T09:12:44.000Z","updatedAt":"2026-08-30T09:13:20.000Z","links":{"self":"https://elicit.com/api/v2/library/sources/8e2d4d52-3b8a-4f6c-9e1a-2c7b6d5e4f30","fullText":"https://elicit.com/api/v2/library/sources/8e2d4d52-3b8a-4f6c-9e1a-2c7b6d5e4f30/full-text"}}}}},"400":{"description":"A malformed id, or an unknown or invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"params.sourceId: Invalid uuid"}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"The source does not exist or is not visible to you.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"Source not found."}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}},"delete":{"tags":["Library"],"security":[{"BearerAuth":[]}],"summary":"Delete a library source","description":"Deletes a source you are a `writer` on: your own, or a shared collection's paper when you own or can edit that collection; that paper goes to the collection's trash. A repeat returns `204`. A source you can only read returns `403`.\n\n### Example\n\n```bash\ncurl -X DELETE https://elicit.com/api/v2/library/sources/{sourceId} \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","parameters":[{"in":"path","name":"sourceId","schema":{"type":"string","format":"uuid"},"required":true}],"responses":{"204":{"description":"Deleted (or already deleted)."},"400":{"description":"A malformed id, or an unknown or invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"params.sourceId: Invalid uuid"}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"The source does not exist or is not visible to you.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"Source not found."}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/library/sources/{sourceId}/full-text":{"get":{"tags":["Library"],"security":[{"BearerAuth":[]}],"summary":"Retrieve a source's full text","description":"Returns the parsed full text of the source's PDF as markdown: title, abstract, and body.\n\nA `404` has one of three codes. `full_text_pending`: the PDF search or parse is in progress; retry later. `full_text_unavailable`: no PDF was found. `not_found`: the source is not visible to you.\n\n### Example\n\n```bash\ncurl https://elicit.com/api/v2/library/sources/{sourceId}/full-text \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","parameters":[{"in":"path","name":"sourceId","schema":{"type":"string","format":"uuid"},"required":true}],"responses":{"200":{"description":"The parsed full text.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetLibrarySourceFullTextResponse"},"example":{"markdown":"# Semaglutide and cardiovascular outcomes in obesity without diabetes\\n\\nSemaglutide, a glucagon-like peptide-1 receptor agonist, has been shown to…"}}}},"400":{"description":"A malformed id, or an unknown or invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"params.sourceId: Invalid uuid"}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"The source is not visible to you, or has no full text (yet). Check the code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"pending":{"summary":"Not yet: retry later","value":{"error":{"code":"full_text_pending","message":"Full text is not available yet for this source; retry once fullTextStatus is available."}}},"unavailable":{"summary":"Never: no PDF was found","value":{"error":{"code":"full_text_unavailable","message":"No full text exists for this source."}}},"notFound":{"summary":"Source not found","value":{"error":{"code":"not_found","message":"Source not found."}}}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/library/collections":{"get":{"tags":["Library"],"security":[{"BearerAuth":[]}],"summary":"List library collections","description":"Returns the collections you own and the collections shared with you. `role` is your access level. `sharedVia` is set on collections shared with you. `links.sources` lists the sources in the collection.\n\nSend `nextCursor` as `cursor` to get the next page.\n\n### Example\n\n```bash\ncurl https://elicit.com/api/v2/library/collections \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","parameters":[{"in":"query","name":"cursor","description":"Pagination cursor from a previous response's nextCursor.","schema":{"type":"string","format":"uuid","description":"Pagination cursor from a previous response's nextCursor."}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"One page of collections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListLibraryCollectionsResponse"},"example":{"collections":[{"id":"b458052a-84e2-4e47-b5c4-00e11390a265","name":"GLP-1 cardiovascular trials","description":"Outcome trials for the meta-analysis.","role":"owner","kind":"group","sourceCount":12,"links":{"self":"https://elicit.com/api/v2/library/collections/b458052a-84e2-4e47-b5c4-00e11390a265","sources":"https://elicit.com/api/v2/library/sources?collectionId=b458052a-84e2-4e47-b5c4-00e11390a265"}}],"nextCursor":null,"totalCount":1}}}},"400":{"description":"A malformed id, or an unknown or invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"params.sourceId: Invalid uuid"}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}},"post":{"tags":["Library"],"security":[{"BearerAuth":[]}],"summary":"Create a collection","description":"Creates an empty collection. Names are not unique. Store the returned id.\n\n### Example\n\n```bash\ncurl -X POST https://elicit.com/api/v2/library/collections \\\n  -H \"Authorization: Bearer elk_live_your_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"GLP-1 cardiovascular trials\"}'\n```","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":300},"description":{"type":"string","maxLength":2000}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"The new collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LibraryCollection"},"example":{"id":"b458052a-84e2-4e47-b5c4-00e11390a265","name":"GLP-1 cardiovascular trials","description":"Outcome trials for the meta-analysis.","role":"owner","kind":"group","sourceCount":0,"links":{"self":"https://elicit.com/api/v2/library/collections/b458052a-84e2-4e47-b5c4-00e11390a265","sources":"https://elicit.com/api/v2/library/sources?collectionId=b458052a-84e2-4e47-b5c4-00e11390a265"}}}}},"400":{"description":"A malformed id, or an unknown or invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"params.sourceId: Invalid uuid"}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/library/collections/{collectionId}":{"get":{"tags":["Library"],"security":[{"BearerAuth":[]}],"summary":"Retrieve a library collection","description":"Retrieves a collection by id. `role` is your access level.\n\n### Example\n\n```bash\ncurl https://elicit.com/api/v2/library/collections/{collectionId} \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","format":"uuid"},"required":true}],"responses":{"200":{"description":"The collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LibraryCollection"},"example":{"id":"b458052a-84e2-4e47-b5c4-00e11390a265","name":"GLP-1 cardiovascular trials","description":"Outcome trials for the meta-analysis.","role":"owner","kind":"group","sourceCount":12,"links":{"self":"https://elicit.com/api/v2/library/collections/b458052a-84e2-4e47-b5c4-00e11390a265","sources":"https://elicit.com/api/v2/library/sources?collectionId=b458052a-84e2-4e47-b5c4-00e11390a265"}}}}},"400":{"description":"A malformed id, or an unknown or invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"params.sourceId: Invalid uuid"}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"The collection does not exist or is not visible to you.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"Collection not found."}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}},"patch":{"tags":["Library"],"security":[{"BearerAuth":[]}],"summary":"Update a collection","description":"Updates `name` and/or `description`. Omitted fields do not change. A body with neither returns `400`. Needs edit access.\n\n### Example\n\n```bash\ncurl -X PATCH https://elicit.com/api/v2/library/collections/{collectionId} \\\n  -H \"Authorization: Bearer elk_live_your_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"description\":\"Outcome trials, 2016 onward.\"}'\n```","parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":300},"description":{"type":"string","maxLength":2000}},"additionalProperties":false}}}},"responses":{"200":{"description":"The updated collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LibraryCollection"},"example":{"id":"b458052a-84e2-4e47-b5c4-00e11390a265","name":"GLP-1 cardiovascular trials","description":"Outcome trials for the meta-analysis.","role":"owner","kind":"group","sourceCount":12,"links":{"self":"https://elicit.com/api/v2/library/collections/b458052a-84e2-4e47-b5c4-00e11390a265","sources":"https://elicit.com/api/v2/library/sources?collectionId=b458052a-84e2-4e47-b5c4-00e11390a265"}}}}},"400":{"description":"A malformed id, or an unknown or invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"params.sourceId: Invalid uuid"}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"The collection does not exist or is not visible to you.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"Collection not found."}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}},"delete":{"tags":["Library"],"security":[{"BearerAuth":[]}],"summary":"Delete a collection","description":"Deletes a collection you own. Its sources stay in their owners' libraries. A repeat returns `404`.\n\n### Example\n\n```bash\ncurl -X DELETE https://elicit.com/api/v2/library/collections/{collectionId} \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","format":"uuid"},"required":true}],"responses":{"204":{"description":"Deleted."},"400":{"description":"A malformed id, or an unknown or invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"params.sourceId: Invalid uuid"}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"The collection does not exist or is not visible to you.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"Collection not found."}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/library/imports":{"post":{"tags":["Library"],"security":[{"BearerAuth":[]}],"summary":"Import uploaded PDFs","description":"Imports uploaded PDFs into your library. Elicit parses each file, extracts its metadata, attaches the full text, and checks for duplicates.\n\n1. Stage each file with `POST /api/v2/files` and PUT the bytes to `upload_url`.\n2. Send the `file_id`s here. The response is `202` and an import with every file `pending`. `collectionId` adds each imported paper to a collection, duplicates included.\n3. Poll `links.self` until `status` is `completed`.\n\nEach file ends as `created` (`sourceId`), `duplicate` (`duplicateOf`), or `failed` (`error`). A file id can be imported once. Files must be PDFs. A byte-identical copy of a PDF in your library is always a `duplicate`. A rejected request imports nothing and uses no file ids. Requires the early-access Research Agent API.\n\n### Example\n\n```bash\ncurl -X POST https://elicit.com/api/v2/library/imports \\\n  -H \"Authorization: Bearer elk_live_your_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"fileIds\":[\"5515a6d4-1b17-4f0d-8484-ccc783b912bc\"],\"collectionId\":\"b458052a-84e2-4e47-b5c4-00e11390a265\"}'\n```","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100,"description":"Ids of staged files whose bytes have been uploaded. PDFs only; each file imports once."},"collectionId":{"type":"string","format":"uuid","description":"A collection you own or can edit to add the imported sources to, duplicates included."},"onDuplicate":{"type":"string","enum":["skip","create"],"description":"skip (default): a PDF matching an already-saved source is reported as its duplicate and not saved. create: saves it as a new source anyway."}},"required":["fileIds"],"additionalProperties":false}}}},"responses":{"202":{"description":"Import accepted; every file is pending. Poll `links.self`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LibraryImport"},"example":{"id":"d1e66555-8d92-4701-b46f-7c64a7ab1d4f","status":"processing","files":[{"fileId":"5515a6d4-1b17-4f0d-8484-ccc783b912bc","filename":"lincoff-2023.pdf","status":"pending","sourceId":null,"duplicateOf":null,"error":null}],"createdAt":"2026-09-01T22:07:28.814Z","completedAt":null,"links":{"self":"https://elicit.com/api/v2/library/imports/d1e66555-8d92-4701-b46f-7c64a7ab1d4f"}}}}},"400":{"description":"A file is not a PDF, a file has not been uploaded, or the body is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"notPdf":{"summary":"Not a PDF","value":{"error":{"code":"unsupported_file_type","message":"Only PDFs can be imported: 5515a6d4-1b17-4f0d-8484-ccc783b912bc."}}},"notUploaded":{"summary":"Staged but the bytes were never PUT","value":{"error":{"code":"file_not_uploaded","message":"File has not been uploaded yet."}}}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"A file_id is unknown or belongs to another user, the collection is not visible to you, or the Research Agent API is not enabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"attachment_not_found","message":"File 5515a6d4-1b17-4f0d-8484-ccc783b912bc was not found."}}}}},"409":{"description":"A file_id was already imported or attached to a session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"attachment_already_used","message":"File 5515a6d4-1b17-4f0d-8484-ccc783b912bc has already been used."}}}}},"410":{"description":"The staged upload expired before it was imported; stage it again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"attachment_expired","message":"Attachment upload has expired."}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/library/imports/{importId}":{"get":{"tags":["Library"],"security":[{"BearerAuth":[]}],"summary":"Retrieve an import","description":"Retrieves an import. `status` is `processing` or `completed`. `completed` does not mean that every file succeeded.\n\nFile `status` values: `pending`; `created`, with `sourceId`; `duplicate`, with `duplicateOf`; `failed`, with `error`. `error.code` values: `invalid-file`, do not retry; `processing-error` and `server-error`, a retry may succeed; `unknown`.\n\n### Example\n\n```bash\ncurl https://elicit.com/api/v2/library/imports/{importId} \\\n  -H \"Authorization: Bearer elk_live_your_key_here\"\n```","parameters":[{"in":"path","name":"importId","schema":{"type":"string","format":"uuid"},"required":true}],"responses":{"200":{"description":"The import and its per-file results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LibraryImport"},"example":{"id":"d1e66555-8d92-4701-b46f-7c64a7ab1d4f","status":"completed","files":[{"fileId":"5515a6d4-1b17-4f0d-8484-ccc783b912bc","filename":"lincoff-2023.pdf","status":"created","sourceId":"8e2d4d52-3b8a-4f6c-9e1a-2c7b6d5e4f30","duplicateOf":null,"error":null},{"fileId":"8f1c2b3a-4d5e-4f60-8a7b-9c0d1e2f3a4b","filename":"vaswani-2017.pdf","status":"duplicate","sourceId":null,"duplicateOf":"2c5f7a9b-1d3e-4f5a-8b7c-6d9e0f1a2b3c","error":null}],"createdAt":"2026-09-01T22:07:28.814Z","completedAt":"2026-09-01T22:08:05.102Z","links":{"self":"https://elicit.com/api/v2/library/imports/d1e66555-8d92-4701-b46f-7c64a7ab1d4f"}}}}},"400":{"description":"A malformed id, or an unknown or invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"params.sourceId: Invalid uuid"}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"The import does not exist or is not visible to you.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"Import not found."}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}},"/library/collections/{collectionId}/sources":{"post":{"tags":["Library"],"security":[{"BearerAuth":[]}],"summary":"Add sources to a collection","description":"Adds up to 500 of your sources to a collection you own or can edit. `addedCount` is the number added.\n\nA source is skipped if it is already in the collection, or if a paper in the collection is the same paper. Papers match by Elicit id, DOI, title, or identical PDF. Each skipped source appears in `duplicates` with `duplicateOf`, the id of the paper already in the collection (its own id when it was already a member). Each added source appears in `added` with `collectionSourceId`, the id the collection holds for it: in a group collection the collection gets its own copy of each added source, under its own id, and your source stays yours.\n\nIf any id is not a source you own, the request returns `404` and adds nothing.\n\n### Example\n\n```bash\ncurl -X POST https://elicit.com/api/v2/library/collections/{collectionId}/sources \\\n  -H \"Authorization: Bearer elk_live_your_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"sourceIds\":[\"8e2d4d52-3b8a-4f6c-9e1a-2c7b6d5e4f30\"]}'\n```","parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":500,"description":"Ids of your library sources."}},"required":["sourceIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"How many sources were newly added.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddLibraryCollectionSourcesResponse"},"example":{"addedCount":1,"added":[{"sourceId":"8e2d4d52-3b8a-4f6c-9e1a-2c7b6d5e4f30","collectionSourceId":"5b0d3f2a-8c41-4e7b-9d6e-2f1a7c3b9e84"}],"duplicates":[]}}}},"400":{"description":"A malformed id, or an unknown or invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"params.sourceId: Invalid uuid"}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"The collection is not visible to you, or a sourceId is not a source you own. Nothing is applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"collection":{"summary":"Collection not found","value":{"error":{"code":"not_found","message":"Collection not found."}}},"sources":{"summary":"Some sources aren't yours","value":{"error":{"code":"not_found","message":"Sources not found in your library: 8e2d4d52-3b8a-4f6c-9e1a-2c7b6d5e4f30."}}}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}},"delete":{"tags":["Library"],"security":[{"BearerAuth":[]}],"summary":"Remove sources from a collection","description":"Removes sources from a collection you own or can edit, whichever member added them. A member's own source stays in their library; a shared collection's own paper goes to the collection's trash for 30 days. Send the ids in a JSON body. `removedCount` is the number removed; an id that is not in the collection is skipped.\n\n### Example\n\n```bash\ncurl -X DELETE https://elicit.com/api/v2/library/collections/{collectionId}/sources \\\n  -H \"Authorization: Bearer elk_live_your_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"sourceIds\":[\"8e2d4d52-3b8a-4f6c-9e1a-2c7b6d5e4f30\"]}'\n```","parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":500,"description":"Ids of your library sources."}},"required":["sourceIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"How many memberships were removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveLibraryCollectionSourcesResponse"},"example":{"removedCount":1}}}},"400":{"description":"A malformed id, or an unknown or invalid query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"params.sourceId: Invalid uuid"}}}}},"401":{"description":"Authentication failed. The API key is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid":{"summary":"Invalid, revoked, or expired key","value":{"error":{"code":"invalid_api_key","message":"Invalid API key"}}},"missing":{"summary":"No Authorization header","value":{"error":{"code":"missing_authorization","message":"Authorization header is required"}}}}}}},"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":"The collection does not exist or is not visible to you.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"Collection not found."}}}}},"429":{"description":"Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudflareRateLimitError"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please 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"}}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key obtained from your Elicit account settings page. Keys use the format `elk_live_...`."}},"schemas":{"PaperSearchRequest":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":2000,"description":"The search query string","example":"GLP-1 receptor agonists for weight loss"},"searchMode":{"type":"string","enum":["semantic","keyword"],"default":"semantic","description":"How to interpret `query`. `semantic` (default) runs Elicit's semantic search. `keyword` sends the query as a Lucene-style boolean expression directly to the corpus search API. Mutually exclusive with `filters` / `trialFilters` — put filter expressions into the query string in keyword mode.","example":"semantic"},"maxResults":{"type":"integer","minimum":1,"maximum":10000,"default":10,"description":"Maximum number of results to return (1-10000)"},"corpus":{"type":"string","enum":["elicit","pubmed"],"default":"elicit","description":"Paper corpus to search. `elicit` (default) searches Elicit's full paper index; `pubmed` restricts to PubMed.","example":"elicit"},"filters":{"$ref":"#/components/schemas/PaperFilters","description":"Filters to narrow search results"}},"required":["query"]},"PaperFilters":{"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":1789411179},"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"}}},"PaperSearchResponse":{"type":"object","properties":{"papers":{"type":"array","items":{"$ref":"#/components/schemas/Paper"},"description":"Papers matching the query"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/SearchWarning"},"description":"Non-fatal warnings emitted while executing the search (e.g. phrases ignored by the PubMed parser)."}},"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"},"studyTypeTags":{"type":"array","items":{"type":"string"},"description":"Study design tags (e.g. RCT, Meta-Analysis, Systematic Review, Review, Longitudinal). Populated for the `elicit` corpus; empty for the `pubmed` corpus."},"journalQuartile":{"type":["integer","null"],"minimum":1,"maximum":4,"description":"SJR journal quartile (1 = top 25%). Null when the journal is unranked/unknown or for the `pubmed` corpus."},"fullTextUrl":{"type":["string","null"],"description":"Best available full-text / PDF link, or null when none is known."}},"required":["elicitId","title","authors","year","abstract","doi","pmid","venue","citedByCount","urls","studyTypeTags","journalQuartile","fullTextUrl"]},"SearchWarning":{"type":"object","properties":{"corpus":{"type":"string","enum":["elicit","pubmed","clinical_trials"],"description":"Corpus that emitted the warning"},"searchMode":{"type":"string","enum":["semantic","keyword"],"description":"Search mode in effect when the warning was emitted"},"message":{"type":"string","description":"Human-readable warning message"},"warningDetails":{"$ref":"#/components/schemas/SearchWarningDetails"}},"required":["corpus","searchMode","message","warningDetails"]},"SearchWarningDetails":{"type":"object","properties":{"type":{"type":"string","description":"Warning category"},"messages":{"type":"array","items":{"type":"string"},"description":"Underlying warning messages"}},"required":["type","messages"]},"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"]},"CloudflareRateLimitError":{"type":"object","properties":{"error":{"type":"string","description":"Error label. Always `Rate limit exceeded` for the burst limit.","example":"Rate limit exceeded"},"message":{"type":"string","description":"Human-readable detail.","example":"Too many requests. Please try again later."}},"required":["error","message"]},"TrialSearchRequest":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":2000,"description":"The search query string","example":"GLP-1 receptor agonists for weight loss"},"searchMode":{"type":"string","enum":["semantic","keyword"],"default":"semantic","description":"How to interpret `query`. `semantic` (default) runs Elicit's semantic search. `keyword` sends the query as a Lucene-style boolean expression directly to the corpus search API. Mutually exclusive with `filters` / `trialFilters` — put filter expressions into the query string in keyword mode.","example":"semantic"},"maxResults":{"type":"integer","minimum":1,"maximum":10000,"default":10,"description":"Maximum number of results to return (1-10000)"},"trialFilters":{"$ref":"#/components/schemas/TrialFilters","description":"Clinical-trials filters (phase, recruitment status, results)"}},"required":["query"]},"TrialFilters":{"type":"object","properties":{"phase":{"type":"array","items":{"type":"string","enum":["NA","EARLY_PHASE1","PHASE1","PHASE2","PHASE3","PHASE4"]},"description":"Clinical trial phases to include","example":["PHASE2","PHASE3"]},"recruitmentStatus":{"type":"array","items":{"type":"string","enum":["ACTIVE_NOT_RECRUITING","COMPLETED","ENROLLING_BY_INVITATION","NOT_YET_RECRUITING","RECRUITING","SUSPENDED","TERMINATED","WITHDRAWN","AVAILABLE"]},"description":"Trial recruitment statuses to include","example":["RECRUITING","ACTIVE_NOT_RECRUITING"]},"hasResults":{"type":"boolean","description":"Only include trials that have posted results","example":true}}},"TrialSearchResponse":{"type":"object","properties":{"trials":{"type":"array","items":{"$ref":"#/components/schemas/Trial"},"description":"Clinical trials matching the query"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/SearchWarning"},"description":"Non-fatal warnings emitted while executing the search."}},"required":["trials"]},"Trial":{"type":"object","properties":{"nctId":{"type":"string","description":"NCT identifier for the trial","example":"NCT05646706"},"title":{"type":"string","description":"Trial title"},"summary":{"type":["string","null"],"description":"Plain-text trial description / brief summary"},"url":{"type":"string","description":"Link to the trial's public record","example":"https://clinicaltrials.gov/study/NCT05646706"},"overallStatus":{"type":["string","null"],"description":"Overall recruitment status (RECRUITING, COMPLETED, TERMINATED, etc.). Null when the trial has no status posted."},"phase":{"type":"array","items":{"type":"string"},"description":"Trial phases (may list multiple, e.g. PHASE2 + PHASE3). Empty for N/A."},"studyType":{"type":["string","null"],"description":"Study type (INTERVENTIONAL, OBSERVATIONAL, EXPANDED_ACCESS)."},"enrollmentCount":{"type":["integer","null"],"description":"Actual or anticipated enrollment count."},"conditions":{"type":"array","items":{"type":"string"},"description":"Conditions / diseases being studied."},"interventions":{"type":"array","items":{"type":"string"},"description":"Intervention names."},"leadSponsor":{"type":["string","null"],"description":"Lead sponsor name."},"startDate":{"type":["string","null"],"description":"Trial start date (ISO `YYYY-MM-DD` or partial)."},"primaryCompletionDate":{"type":["string","null"],"description":"Primary completion date (ISO `YYYY-MM-DD` or partial)."},"completionDate":{"type":["string","null"],"description":"Completion date (ISO `YYYY-MM-DD` or partial)."},"hasResults":{"type":["boolean","null"],"description":"Whether the trial has posted results."},"lastUpdatedYear":{"type":["integer","null"],"description":"Year the trial record was last updated."}},"required":["nctId","title","summary","url","overallStatus","phase","studyType","enrollmentCount","conditions","interventions","leadSponsor","startDate","primaryCompletionDate","completionDate","hasResults","lastUpdatedYear"]},"ReportSessionCreated":{"type":"object","properties":{"type":{"type":"string","const":"report"},"sessionId":{"type":"string","format":"uuid","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","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"},"isPublic":{"type":"boolean","description":"Whether the report is publicly accessible via its URL without authentication","example":false},"links":{"$ref":"#/components/schemas/SessionLinks"}},"required":["type","sessionId","status","url","isPublic","links"]},"SessionLinks":{"type":"object","properties":{"self":{"type":"string","description":"API URL for this session's full status and results (the typed get endpoint for its type)","example":"https://elicit.com/api/v2/sessions/reports/5ad08bfb-cbe0-4911-a8c3-309760d33029"},"resume":{"type":"string","description":"API URL to resume this session. Present only while the session is paused for insufficient quota.","example":"https://elicit.com/api/v2/sessions/5ad08bfb-cbe0-4911-a8c3-309760d33029/resume"}},"required":["self"]},"ReportSessionDetail":{"type":"object","properties":{"type":{"type":"string","const":"report"},"sessionId":{"type":"string","format":"uuid","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","example":"5ad08bfb-cbe0-4911-a8c3-309760d33029"},"status":{"type":"string","enum":["processing","pausedForInsufficientQuota","completed","failed","unknown"],"description":"Current status of the report. Transitions: processing ⇄ pausedForInsufficientQuota (paused when the account exceeds its usage limit; stays paused until explicitly resumed via the resume endpoint or the Elicit web interface), processing → completed/failed. Poll until completed or failed."},"executionStage":{"type":["string","null"],"enum":["gathering_sources","screening_abstract","screening_fulltext","extracting_data","generating_report","done",null],"description":"Current pipeline stage. Advances through gathering_sources → screening_abstract → extracting_data → generating_report → done. Null for reports created before this field was introduced or when the stage isn't known."},"url":{"type":"string","description":"URL to view the report in the Elicit web interface","example":"https://elicit.com/review/5ad08bfb-cbe0-4911-a8c3-309760d33029"},"isPublic":{"type":"boolean","description":"Whether the report is publicly accessible via its URL without authentication","example":false},"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/..."},"txtUrl":{"type":["string","null"],"description":"Pre-signed URL to download the report's reference list as a plain-text (APA) file. Only present when status is completed and the report has a non-empty bibliography. Expires after 7 days — re-fetch the report for a fresh URL.","example":"https://s3.amazonaws.com/..."},"bibUrl":{"type":["string","null"],"description":"Pre-signed URL to download the report's references as a BibTeX (.bib) file. Only present when status is completed and the report has a non-empty bibliography. Expires after 7 days — re-fetch the report for a fresh URL.","example":"https://s3.amazonaws.com/..."},"risUrl":{"type":["string","null"],"description":"Pre-signed URL to download the report's references as an RIS (.ris) file. Only present when status is completed and the report has a non-empty bibliography. Expires after 7 days — re-fetch the report for a fresh URL.","example":"https://s3.amazonaws.com/..."},"exportsStatus":{"type":"string","enum":["ready","generating","unavailable"],"description":"Availability of the reference-list exports (`txtUrl`/`bibUrl`/`risUrl`); `pdfUrl`/`docxUrl` are unaffected. Only present when status is completed. `ready`: absent URLs genuinely have no export. `generating`: the exports are currently being generated and nothing is cached yet. `unavailable`: export generation failed and nothing is cached."},"links":{"$ref":"#/components/schemas/SessionLinks"}},"required":["type","sessionId","status","executionStage","url","isPublic","links"]},"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"]},"SystematicReviewSessionCreated":{"type":"object","properties":{"type":{"type":"string","const":"systematicReview"},"sessionId":{"type":"string","format":"uuid","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","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 review in the Elicit web interface"},"isPublic":{"type":"boolean","description":"Whether the review is publicly accessible via its URL without authentication"},"links":{"$ref":"#/components/schemas/SessionLinks"}},"required":["type","sessionId","status","url","isPublic","links"]},"SystematicReviewSessionDetail":{"type":"object","properties":{"type":{"type":"string","const":"systematicReview"},"sessionId":{"type":"string","format":"uuid","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","example":"5ad08bfb-cbe0-4911-a8c3-309760d33029"},"status":{"type":"string","enum":["processing","pausedForInsufficientQuota","completed","failed","unknown"],"description":"Current status. Transitions: processing ⇄ pausedForInsufficientQuota (paused when the account exceeds its usage limit; stays paused until explicitly resumed via the resume endpoint or the Elicit web interface), processing → completed/failed. Poll until completed or failed."},"executionStage":{"type":["string","null"],"enum":["gathering_sources","screening_abstract","screening_fulltext","extracting_data","generating_report","done",null],"description":"Current pipeline stage. Advances through gathering_sources → screening_abstract → screening_fulltext → extracting_data → generating_report → done. Null when the stage isn't known — treat it as unknown, not as not-started."},"url":{"type":"string","description":"URL to view the review in the Elicit web interface"},"isPublic":{"type":"boolean","description":"Whether the review is publicly accessible via its URL without authentication"},"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"},"data":{"$ref":"#/components/schemas/ReviewData","description":"Stage-organized content and export URLs: per-stage `search`/`screen`/`fulltext`/`extract` CSV + XLSX downloads and `report` content plus pdf/docx/txt/bib/ris downloads. When `exportsStatus` is `ready`, stages absent from `data` did not run; when it is `generating` or `unavailable`, download URLs are temporarily missing rather than nonexistent."},"dataFreshness":{"type":["string","null"],"description":"ISO timestamp when the exports in `data` were last written to S3. null when no exports have been generated yet — see `exportsStatus` for why."},"exportsStatus":{"type":"string","enum":["ready","generating","unavailable"],"description":"Availability of the export download URLs in `data`. `ready`: the URLs reflect the latest complete export set. `generating`: exports are currently being generated and nothing is cached yet. `unavailable`: export generation failed and nothing is cached — the structured report content still ships."},"links":{"$ref":"#/components/schemas/SessionLinks"}},"required":["type","sessionId","status","executionStage","url","isPublic","dataFreshness","exportsStatus","links"]},"ReviewData":{"type":"object","properties":{"search":{"$ref":"#/components/schemas/StageData","description":"Gather-stage paper list exports."},"screen":{"$ref":"#/components/schemas/StageData","description":"Abstract-screening results exports."},"fulltext":{"$ref":"#/components/schemas/StageData","description":"Fulltext-screening results exports."},"extract":{"$ref":"#/components/schemas/StageData","description":"Extraction-stage results exports."},"report":{"$ref":"#/components/schemas/ReportData","description":"Report-stage content and exports."}}},"StageData":{"type":"object","properties":{"csv":{"type":"string","format":"uri","description":"Presigned URL for the CSV export. Expires in 7 days."},"xlsx":{"type":"string","format":"uri","description":"Presigned URL for the XLSX export. Expires in 7 days."}},"required":["csv","xlsx"]},"ReportData":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/ReviewResult","description":"Structured report content (title, summary, optional body + abstract)."},"pdf":{"type":"string","format":"uri","description":"Presigned URL for the report PDF. Expires in 7 days."},"docx":{"type":"string","format":"uri","description":"Presigned URL for the report DOCX. Expires in 7 days."},"txt":{"type":"string","format":"uri","description":"Presigned URL for an APA-style plain-text reference list of the papers synthesized in the report. Expires in 7 days."},"bib":{"type":"string","format":"uri","description":"Presigned URL for a BibTeX bibliography of the papers synthesized in the report. Expires in 7 days."},"ris":{"type":"string","format":"uri","description":"Presigned URL for a RIS bibliography of the papers synthesized in the report. Expires in 7 days."}},"required":["result"]},"ReviewResult":{"type":"object","properties":{"title":{"type":"string","description":"Auto-generated title"},"summary":{"type":"string","description":"AI-generated executive summary of the findings"},"reportBody":{"type":["string","null"],"description":"Full report content in markdown format. Only included when ?include=reportBody is specified."},"abstract":{"type":["string","null"],"description":"Report abstract in markdown format. Only included when ?include=reportBody is specified."}},"required":["title","summary"]},"ListSessionsResponse":{"type":"object","properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/SessionListItem"},"description":"Reports, systematic reviews, and research-agent sessions interleaved, ordered by creation date (newest first)"},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page; pass it back as `cursor`. Null if there are no more results.","example":"2025-06-15T14:30:00.000Z_5ad08bfb-cbe0-4911-a8c3-309760d33029"},"totalCount":{"type":"integer","description":"Total sessions matching the filters across all pages."}},"required":["sessions","nextCursor","totalCount"]},"SessionListItem":{"type":"object","properties":{"type":{"type":"string","enum":["report","systematicReview","agent"],"description":"Which kind of session this is; use it to pick the matching typed get endpoint"},"sessionId":{"type":"string","format":"uuid","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","example":"5ad08bfb-cbe0-4911-a8c3-309760d33029"},"status":{"type":"string","enum":["processing","pausedForInsufficientQuota","completed","failed","unknown"],"description":"Current status of the report"},"executionStage":{"type":["string","null"],"enum":["gathering_sources","screening_abstract","screening_fulltext","extracting_data","generating_report","done",null],"description":"Current pipeline stage, or null when not yet known. Omitted entirely for agent sessions, which have no pipeline stages."},"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":["user","api","mcp","agent_session"],"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"},"isPublic":{"type":"boolean","description":"Whether the report is publicly accessible via its URL without authentication","example":false},"role":{"type":"string","enum":["owner","shared"],"description":"The caller's relationship to this session: \"owner\" for a session the caller created, or \"shared\" for an agent session another user shared with them read-only. Reports and systematic reviews are always \"owner\"."},"links":{"$ref":"#/components/schemas/SessionLinks"}},"required":["type","sessionId","status","title","url","source","createdAt","isPublic","links"]},"ResumeSessionResponse":{"type":"object","properties":{"type":{"type":"string","enum":["report","systematicReview","agent"],"description":"Which kind of session was resumed"},"sessionId":{"type":"string","format":"uuid","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","example":"5ad08bfb-cbe0-4911-a8c3-309760d33029"},"status":{"type":"string","enum":["processing","pausedForInsufficientQuota","completed","failed","unknown"],"description":"Status after the resume — normally processing; completed or failed if the run finished while the resume was in flight."},"executionStage":{"type":["string","null"],"enum":["gathering_sources","screening_abstract","screening_fulltext","extracting_data","generating_report","done",null],"description":"The stage the session resumed at","example":"screening_abstract"},"url":{"type":"string","description":"URL to view this session in the Elicit web interface"},"isPublic":{"type":"boolean"},"links":{"$ref":"#/components/schemas/SessionLinks"}},"required":["type","sessionId","status","executionStage","url","isPublic","links"]},"CreateSessionShareResponse":{"type":"object","properties":{"sessionId":{"type":"string","description":"Unique identifier for the session."},"share":{"$ref":"#/components/schemas/SessionShare"},"url":{"type":"string","description":"URL to view and continue the session in the Elicit web interface."}},"required":["sessionId","share","url"]},"SessionShare":{"type":"object","properties":{"email":{"type":"string","description":"Email address the session is shared with.","example":"colleague@example.com"},"status":{"type":"string","enum":["registered","invited"],"description":"\"registered\" when the recipient already has an Elicit account and can read the session now; \"invited\" when a pending invitation was created for an email without an account."},"role":{"type":"string","const":"reader","description":"Access level of the share. Sessions are always shared read-only."}},"required":["email","status","role"]},"ListSessionSharesResponse":{"type":"object","properties":{"sessionId":{"type":"string","description":"Unique identifier for the session."},"shares":{"type":"array","items":{"$ref":"#/components/schemas/SessionShare"},"description":"Everyone the session is currently shared with — both registered recipients and pending email invitations."},"url":{"type":"string","description":"URL to view and continue the session in the Elicit web interface."}},"required":["sessionId","shares","url"]},"DeleteSessionShareResponse":{"type":"object","properties":{"sessionId":{"type":"string","description":"Unique identifier for the session."},"email":{"type":"string","description":"Email address whose share was revoked."},"revoked":{"type":"boolean","description":"Whether an existing share or pending invite was removed. False when there was nothing to revoke (the call is idempotent either way)."}},"required":["sessionId","email","revoked"]},"GetUsageResponse":{"type":"object","properties":{"hasUsageRemaining":{"type":"boolean","description":"Whether the account still has usage available this billing period. False once both the plan limit and (if enabled) the extra-usage limit are exhausted."},"percentUsed":{"type":"number","description":"Percentage of plan usage consumed this billing period."},"periodStart":{"type":"string","description":"ISO 8601 start of the current billing period."},"periodEnd":{"type":"string","description":"ISO 8601 end of the current billing period. Monthly usage limits reset at this time."},"extraUsage":{"oneOf":[{"$ref":"#/components/schemas/ExtraUsage"},{"type":"null"}],"description":"Extra-usage amount and limit in USD cents. Null when extra usage is not enabled."}},"required":["hasUsageRemaining","percentUsed","periodStart","periodEnd","extraUsage"]},"ExtraUsage":{"type":"object","properties":{"limitUsdCents":{"type":["integer","null"],"description":"The extra-usage spending limit in USD cents, or null when extra usage is uncapped."},"spentUsdCents":{"type":"integer","description":"Extra-usage spend so far this billing period, in USD cents."}},"required":["limitUsdCents","spentUsdCents"]},"CreateAgentSessionResponse":{"type":"object","properties":{"sessionId":{"type":"string","description":"Unique identifier for the research agent session.","example":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"},"status":{"type":"string","const":"processing","description":"Initial status is always processing."},"url":{"type":"string","description":"URL to view and continue the session in the Elicit web interface.","example":"https://elicit.com/agent/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}},"required":["sessionId","status","url"]},"AgentSessionDetail":{"type":"object","properties":{"type":{"type":"string","const":"agent","description":"Discriminator identifying this as a research-agent session."},"sessionId":{"type":"string","format":"uuid","description":"The session ID (UUID) returned by the create endpoints and `GET /sessions`","example":"5ad08bfb-cbe0-4911-a8c3-309760d33029"},"status":{"type":"string","enum":["processing","pausedForInsufficientQuota","completed","failed","unknown"],"description":"Current status of the session: \"processing\" (running, or not yet started), \"completed\" (idle and awaiting input — not terminally finished), \"failed\" (the last turn ended with an error), or \"pausedForInsufficientQuota\" (paused at the account usage limit; resume once the limit clears)."},"title":{"type":"string","description":"Human-readable title of the session."},"url":{"type":"string","description":"URL to view and continue the session in the Elicit web interface."},"source":{"type":"string","enum":["user","api","mcp","agent_session"],"description":"How the session was created.","example":"api"},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the session was created.","example":"2025-06-15T14:30:00.000Z"},"isPublic":{"type":"boolean","description":"Whether the session is publicly accessible via its URL without authentication."},"links":{"$ref":"#/components/schemas/SessionLinks"}},"required":["type","sessionId","status","title","url","source","createdAt","isPublic","links"]},"GetAgentSessionEventsResponse":{"type":"object","properties":{"sessionId":{"type":"string","description":"Unique identifier for the research agent session."},"status":{"type":"string","enum":["processing","pausedForInsufficientQuota","completed","failed","unknown"],"description":"Current status of the session. Uses exactly the same value and semantics as the list and detail endpoints."},"events":{"type":"array","items":{"$ref":"#/components/schemas/ReducedAgentEvent"},"description":"Append-only view of the session's activity. Streaming deltas are collapsed into immutable resource snapshots; raw stream events are never returned. Later snapshots retain the same resource ID and receive a new eventId. With no cursor this is the full history; with a cursor it contains only later occurrences."},"cursor":{"type":"string","description":"Opaque session-bound checkpoint. Always present. Pass it unchanged as the `cursor` query param on the next poll to receive later event occurrences."},"url":{"type":"string","description":"URL to view and continue the session in the Elicit web interface."}},"required":["sessionId","status","events","cursor","url"]},"ReducedAgentEvent":{"oneOf":[{"type":"object","properties":{"eventId":{"type":"string","description":"Stable opaque identifier for this immutable public event occurrence."},"createdAt":{"type":["string","null"],"description":"ISO 8601 timestamp for the event. Null for historical events without one."},"kind":{"type":"string","const":"user_message"},"messageId":{"type":"string"},"text":{"type":"string"},"isInitial":{"type":"boolean"}},"required":["eventId","createdAt","kind","messageId","text","isInitial"]},{"type":"object","properties":{"eventId":{"type":"string","description":"Stable opaque identifier for this immutable public event occurrence."},"createdAt":{"type":["string","null"],"description":"ISO 8601 timestamp for the event. Null for historical events without one."},"kind":{"type":"string","const":"agent_message"},"messageId":{"type":"string"},"text":{"type":"string","description":"The agent's reply. Contains inline `<citations>…</citations>` markup wrapping one or more comma-separated reference tokens; split them and match each token against `citations[].reference` to resolve it. Strip the markup for display."},"citations":{"type":"array","items":{"type":"object","properties":{"citationId":{"type":"string","description":"Identifier for this citation within the agent message."},"reference":{"type":["string","null"],"description":"The inline citation this entry resolves. It matches, character for character, a single reference token inside the `<citations>…</citations>` markup in the message text (one entry per token, after comma-separated tokens are split). Use it to map inline references in the text to this citation; use the `source` field to identify the underlying source. `null` for citations with no inline reference (e.g. legacy quotes-array or artifact-content citations)."},"quote":{"type":"string","description":"The passage from the source that supports the message."},"source":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Title of the cited work."},"authors":{"type":"array","items":{"type":"string"},"description":"Authors of the cited work, in display order."},"year":{"type":["integer","null"],"description":"Publication year."},"doi":{"type":["string","null"],"description":"Digital Object Identifier (DOI), when available."},"url":{"type":["string","null"],"description":"Best available URL for the cited work."},"venue":{"type":["string","null"],"description":"Journal, conference, repository, or other publication venue."}},"required":["title","authors","year","doi","url","venue"]}},"required":["citationId","reference","quote","source"]}},"suggestedFollowUps":{"type":"array","items":{"type":"string"}}},"required":["eventId","createdAt","kind","messageId","text","citations","suggestedFollowUps"]},{"type":"object","properties":{"eventId":{"type":"string","description":"Stable opaque identifier for this immutable public event occurrence."},"createdAt":{"type":["string","null"],"description":"ISO 8601 timestamp for the event. Null for historical events without one."},"kind":{"type":"string","const":"question"},"questionId":{"type":"string"},"text":{"type":"string"},"responseFormat":{"type":"string","enum":["text","single_select","multi_select"]},"options":{"type":["array","null"],"items":{"type":"object","properties":{"optionId":{"type":"string"},"label":{"type":"string"}},"required":["optionId","label"]}},"prefilledText":{"type":["string","null"]}},"required":["eventId","createdAt","kind","questionId","text","responseFormat","options","prefilledText"]},{"type":"object","properties":{"eventId":{"type":"string","description":"Stable opaque identifier for this immutable public event occurrence."},"createdAt":{"type":["string","null"],"description":"ISO 8601 timestamp for the event. Null for historical events without one."},"kind":{"type":"string","const":"activity"},"activityId":{"type":"string"},"status":{"type":"string","enum":["started","completed","failed"]},"title":{"type":"string"},"summary":{"type":["string","null"]}},"required":["eventId","createdAt","kind","activityId","status","title","summary"]},{"type":"object","properties":{"eventId":{"type":"string","description":"Stable opaque identifier for this immutable public event occurrence."},"createdAt":{"type":["string","null"],"description":"ISO 8601 timestamp for the event. Null for historical events without one."},"kind":{"type":"string","const":"artifacts_delivered"},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/PublicAgentArtifact"},"minItems":1}},"required":["eventId","createdAt","kind","artifacts"]},{"type":"object","properties":{"eventId":{"type":"string","description":"Stable opaque identifier for this immutable public event occurrence."},"createdAt":{"type":["string","null"],"description":"ISO 8601 timestamp for the event. Null for historical events without one."},"kind":{"type":"string","const":"delivered_outputs"},"deliveredOutputs":{"type":"array","items":{"$ref":"#/components/schemas/DeliveredOutputEventSnapshot"},"minItems":1,"description":"Artifacts delivered by this source-history occurrence. This is an immutable metadata snapshot; query the artifacts resource for currently supported download formats."}},"required":["eventId","createdAt","kind","deliveredOutputs"]},{"type":"object","properties":{"eventId":{"type":"string","description":"Stable opaque identifier for this immutable public event occurrence."},"createdAt":{"type":["string","null"],"description":"ISO 8601 timestamp for the event. Null for historical events without one."},"kind":{"type":"string","const":"error"},"code":{"type":"string","enum":["agent_timed_out","agent_api_error","agent_failed"]},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["eventId","createdAt","kind","code","message","retryable"]},{"type":"object","properties":{"eventId":{"type":"string","description":"Stable opaque identifier for this immutable public event occurrence."},"createdAt":{"type":["string","null"],"description":"ISO 8601 timestamp for the event. Null for historical events without one."},"kind":{"type":"string","const":"session_idle"}},"required":["eventId","createdAt","kind"]},{"type":"object","properties":{"eventId":{"type":"string","description":"Stable opaque identifier for this immutable public event occurrence."},"createdAt":{"type":["string","null"],"description":"ISO 8601 timestamp for the event. Null for historical events without one."},"kind":{"type":"string","const":"session_paused"}},"required":["eventId","createdAt","kind"]},{"type":"object","properties":{"eventId":{"type":"string","description":"Stable opaque identifier for this immutable public event occurrence."},"createdAt":{"type":["string","null"],"description":"ISO 8601 timestamp for the event. Null for historical events without one."},"kind":{"type":"string","const":"session_resumed"}},"required":["eventId","createdAt","kind"]},{"type":"object","properties":{"eventId":{"type":"string","description":"Stable opaque identifier for this immutable public event occurrence."},"createdAt":{"type":["string","null"],"description":"ISO 8601 timestamp for the event. Null for historical events without one."},"kind":{"type":"string","const":"stop_requested"}},"required":["eventId","createdAt","kind"]},{"type":"object","properties":{"eventId":{"type":"string","description":"Stable opaque identifier for this immutable public event occurrence."},"createdAt":{"type":["string","null"],"description":"ISO 8601 timestamp for the event. Null for historical events without one."},"kind":{"type":"string","const":"session_stopped"}},"required":["eventId","createdAt","kind"]}]},"PublicAgentArtifact":{"type":"object","properties":{"artifactId":{"type":"string","description":"Opaque identifier for the artifact, stable within a session. Pass it to the download endpoint to retrieve the file. Never a raw storage key."},"kind":{"type":"string","enum":["agent-saved-file","agent-delivered-file","prose-export","presentation-export","figure-export","report-asset","report-citation"],"description":"The kind of artifact produced in the session. A delivered file lists once as \"agent-delivered-file\"; \"agent-saved-file\" denotes a file the agent saved to its workspace but did not deliver."},"format":{"type":["string","null"],"description":"Subtype within the artifact (e.g. \"pdf\", \"docx\", \"pptx\"). For agent files it is the filename extension; null only when the filename has no extension."},"filename":{"type":"string","description":"Suggested filename for the downloaded artifact."},"contentType":{"type":["string","null"],"description":"MIME type of the artifact, when known."},"sizeBytes":{"type":["number","null"],"description":"Size of the artifact in bytes, when known."},"createdAt":{"type":["string","null"],"description":"ISO 8601 timestamp of when the artifact was produced, when known.","example":"2025-06-15T14:30:00.000Z"}},"required":["artifactId","kind","format","filename","contentType","sizeBytes","createdAt"]},"DeliveredOutputEventSnapshot":{"type":"object","properties":{"artifactId":{"type":"string","description":"Opaque identifier for the interactive artifact, stable within a session. Pass it to the artifact content endpoint to retrieve its contents. Never a raw storage key or entity hash."},"kind":{"type":"string","enum":["table","prose","presentation","figure"],"description":"The kind of interactive artifact: table, prose, presentation, or figure."},"title":{"type":"string","description":"Human-readable title of the artifact."},"caption":{"type":["string","null"],"description":"Optional caption describing the artifact."},"rowCount":{"type":["integer","null"],"description":"Number of rows for a table artifact; null for non-table kinds."},"createdAt":{"type":["string","null"],"description":"ISO 8601 timestamp of when the artifact was delivered, when known.","example":"2025-06-15T14:30:00.000Z"}},"required":["artifactId","kind","title","caption","rowCount","createdAt"]},"PostAgentSessionMessageResponse":{"type":"object","properties":{"sessionId":{"type":"string","description":"Unique identifier for the research agent session."},"status":{"type":"string","const":"processing","description":"The session is processing the inserted message."},"messageId":{"type":"string","description":"Identifier of the inserted message. Correlate it with the messageId on the matching user_message event."},"url":{"type":"string","description":"URL to view and continue the session in the Elicit web interface."}},"required":["sessionId","status","messageId","url"]},"CreateFileResponse":{"type":"object","properties":{"file_id":{"type":"string","description":"Opaque identifier for the staged upload. Pass it in the `attachments` array of a create-session or send-message request to attach the file to that turn.","example":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"},"upload_url":{"type":"string","description":"Short-lived presigned S3 PUT URL. Upload the file bytes directly to it with the same Content-Type and Content-Length declared here."},"expires_at":{"type":"string","description":"ISO 8601 timestamp after which the upload URL and the staged file_id are no longer valid.","example":"2026-07-23T15:00:00.000Z"}},"required":["file_id","upload_url","expires_at"]},"GetAgentSessionArtifactsResponse":{"type":"object","properties":{"sessionId":{"type":"string","description":"Unique identifier for the research agent session."},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/PublicAgentArtifact"},"description":"File-backed artifacts produced in the session. Only the latest version of each artifact is listed. Retrieve contents via the download endpoint."},"deliveredOutputs":{"type":"array","items":{"$ref":"#/components/schemas/PublicDeliveredOutput"},"description":"Interactive outputs (tables, prose, presentations, figures) delivered as session outputs. Only the latest delivery of each is listed. Retrieve contents via the artifact content endpoint."},"url":{"type":"string","description":"URL to view and continue the session in the Elicit web interface."}},"required":["sessionId","artifacts","deliveredOutputs","url"]},"PublicDeliveredOutput":{"type":"object","properties":{"artifactId":{"type":"string","description":"Opaque identifier for the interactive artifact, stable within a session. Pass it to the artifact content endpoint to retrieve its contents. Never a raw storage key or entity hash."},"kind":{"type":"string","enum":["table","prose","presentation","figure"],"description":"The kind of interactive artifact: table, prose, presentation, or figure."},"title":{"type":"string","description":"Human-readable title of the artifact."},"caption":{"type":["string","null"],"description":"Optional caption describing the artifact."},"rowCount":{"type":["integer","null"],"description":"Number of rows for a table artifact; null for non-table kinds."},"createdAt":{"type":["string","null"],"description":"ISO 8601 timestamp of when the artifact was delivered, when known.","example":"2025-06-15T14:30:00.000Z"},"downloadFormats":{"type":"array","items":{"type":"string","enum":["csv","xlsx","md"]},"description":"File formats this artifact can be downloaded as from the content endpoint via ?format=<fmt> (tables: csv/xlsx; prose: md; empty for other kinds). The JSON body is returned when no format is given."}},"required":["artifactId","kind","title","caption","rowCount","createdAt","downloadFormats"]},"GetAgentSessionArtifactContentResponse":{"oneOf":[{"type":"object","properties":{"artifactId":{"type":"string","description":"Opaque identifier for the interactive artifact, echoing the request. Can also be re-requested with ?format=<fmt> to download as a file (tables: csv/xlsx, prose: md)."},"title":{"type":"string","description":"Human-readable title of the artifact."},"caption":{"type":["string","null"],"description":"Optional caption describing the artifact."},"url":{"type":"string","description":"URL to view and continue the session in the Elicit web interface."},"kind":{"type":"string","const":"table"},"columns":{"type":"array","items":{"type":"string"},"description":"Ordered column keys for the table, in first-seen order across the rows."},"rows":{"type":"array","items":{"type":"object","additionalProperties":{"type":"object","properties":{"text":{"type":["string","null"],"description":"Human-readable cell text with inline citation markup removed. Null when the cell has no text value."},"citations":{"type":"array","items":{"type":"object","properties":{"citationId":{"type":"string","description":"Identifier for this citation within the agent message."},"reference":{"type":["string","null"],"description":"The inline citation this entry resolves. It matches, character for character, a single reference token inside the `<citations>…</citations>` markup in the message text (one entry per token, after comma-separated tokens are split). Use it to map inline references in the text to this citation; use the `source` field to identify the underlying source. `null` for citations with no inline reference (e.g. legacy quotes-array or artifact-content citations)."},"quote":{"type":"string","description":"The passage from the source that supports the message."},"source":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Title of the cited work."},"authors":{"type":"array","items":{"type":"string"},"description":"Authors of the cited work, in display order."},"year":{"type":["integer","null"],"description":"Publication year."},"doi":{"type":["string","null"],"description":"Digital Object Identifier (DOI), when available."},"url":{"type":["string","null"],"description":"Best available URL for the cited work."},"venue":{"type":["string","null"],"description":"Journal, conference, repository, or other publication venue."}},"required":["title","authors","year","doi","url","venue"]}},"required":["citationId","reference","quote","source"]},"description":"Citations backing this cell, resolved to the same shape as message citations."},"source":{"type":["object","null"],"properties":{"title":{"type":["string","null"],"description":"Title of the cited work."},"authors":{"type":"array","items":{"type":"string"},"description":"Authors of the cited work, in display order."},"year":{"type":["integer","null"],"description":"Publication year."},"doi":{"type":["string","null"],"description":"Digital Object Identifier (DOI), when available."},"url":{"type":["string","null"],"description":"Best available URL for the cited work."},"venue":{"type":["string","null"],"description":"Journal, conference, repository, or other publication venue."}},"required":["title","authors","year","doi","url","venue"],"description":"The cited source when this cell is a resolved source reference; otherwise null."}},"required":["text","citations","source"]}},"description":"Table rows, each a mapping from column key to cell."}},"required":["artifactId","title","caption","url","kind","columns","rows"]},{"type":"object","properties":{"artifactId":{"type":"string","description":"Opaque identifier for the interactive artifact, echoing the request. Can also be re-requested with ?format=<fmt> to download as a file (tables: csv/xlsx, prose: md)."},"title":{"type":"string","description":"Human-readable title of the artifact."},"caption":{"type":["string","null"],"description":"Optional caption describing the artifact."},"url":{"type":"string","description":"URL to view and continue the session in the Elicit web interface."},"kind":{"type":"string","const":"prose"},"content":{"type":"object","properties":{"text":{"type":"string","description":"Human-readable content with inline citation markup removed."},"markdown":{"type":"string","description":"The original markdown content, including inline citation markup."},"citations":{"type":"array","items":{"type":"object","properties":{"citationId":{"type":"string","description":"Identifier for this citation within the agent message."},"reference":{"type":["string","null"],"description":"The inline citation this entry resolves. It matches, character for character, a single reference token inside the `<citations>…</citations>` markup in the message text (one entry per token, after comma-separated tokens are split). Use it to map inline references in the text to this citation; use the `source` field to identify the underlying source. `null` for citations with no inline reference (e.g. legacy quotes-array or artifact-content citations)."},"quote":{"type":"string","description":"The passage from the source that supports the message."},"source":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Title of the cited work."},"authors":{"type":"array","items":{"type":"string"},"description":"Authors of the cited work, in display order."},"year":{"type":["integer","null"],"description":"Publication year."},"doi":{"type":["string","null"],"description":"Digital Object Identifier (DOI), when available."},"url":{"type":["string","null"],"description":"Best available URL for the cited work."},"venue":{"type":["string","null"],"description":"Journal, conference, repository, or other publication venue."}},"required":["title","authors","year","doi","url","venue"]}},"required":["citationId","reference","quote","source"]},"description":"Citations backing this content, resolved to the same shape as message citations."}},"required":["text","markdown","citations"]}},"required":["artifactId","title","caption","url","kind","content"]},{"type":"object","properties":{"artifactId":{"type":"string","description":"Opaque identifier for the interactive artifact, echoing the request. Can also be re-requested with ?format=<fmt> to download as a file (tables: csv/xlsx, prose: md)."},"title":{"type":"string","description":"Human-readable title of the artifact."},"caption":{"type":["string","null"],"description":"Optional caption describing the artifact."},"url":{"type":"string","description":"URL to view and continue the session in the Elicit web interface."},"kind":{"type":"string","const":"presentation"},"slides":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Slide title."},"content":{"type":"object","properties":{"text":{"type":"string","description":"Human-readable content with inline citation markup removed."},"markdown":{"type":"string","description":"The original markdown content, including inline citation markup."},"citations":{"type":"array","items":{"type":"object","properties":{"citationId":{"type":"string","description":"Identifier for this citation within the agent message."},"reference":{"type":["string","null"],"description":"The inline citation this entry resolves. It matches, character for character, a single reference token inside the `<citations>…</citations>` markup in the message text (one entry per token, after comma-separated tokens are split). Use it to map inline references in the text to this citation; use the `source` field to identify the underlying source. `null` for citations with no inline reference (e.g. legacy quotes-array or artifact-content citations)."},"quote":{"type":"string","description":"The passage from the source that supports the message."},"source":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Title of the cited work."},"authors":{"type":"array","items":{"type":"string"},"description":"Authors of the cited work, in display order."},"year":{"type":["integer","null"],"description":"Publication year."},"doi":{"type":["string","null"],"description":"Digital Object Identifier (DOI), when available."},"url":{"type":["string","null"],"description":"Best available URL for the cited work."},"venue":{"type":["string","null"],"description":"Journal, conference, repository, or other publication venue."}},"required":["title","authors","year","doi","url","venue"]}},"required":["citationId","reference","quote","source"]},"description":"Citations backing this content, resolved to the same shape as message citations."}},"required":["text","markdown","citations"]},"speakerNotes":{"type":["string","null"],"description":"Speaker notes, when present."}},"required":["title","content","speakerNotes"]},"description":"Ordered slides, each with a title and supported content."}},"required":["artifactId","title","caption","url","kind","slides"]},{"type":"object","properties":{"artifactId":{"type":"string","description":"Opaque identifier for the interactive artifact, echoing the request. Can also be re-requested with ?format=<fmt> to download as a file (tables: csv/xlsx, prose: md)."},"title":{"type":"string","description":"Human-readable title of the artifact."},"caption":{"type":["string","null"],"description":"Optional caption describing the artifact."},"url":{"type":"string","description":"URL to view and continue the session in the Elicit web interface."},"kind":{"type":"string","const":"figure"},"description":{"type":"object","properties":{"text":{"type":"string","description":"Human-readable content with inline citation markup removed."},"markdown":{"type":"string","description":"The original markdown content, including inline citation markup."},"citations":{"type":"array","items":{"type":"object","properties":{"citationId":{"type":"string","description":"Identifier for this citation within the agent message."},"reference":{"type":["string","null"],"description":"The inline citation this entry resolves. It matches, character for character, a single reference token inside the `<citations>…</citations>` markup in the message text (one entry per token, after comma-separated tokens are split). Use it to map inline references in the text to this citation; use the `source` field to identify the underlying source. `null` for citations with no inline reference (e.g. legacy quotes-array or artifact-content citations)."},"quote":{"type":"string","description":"The passage from the source that supports the message."},"source":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Title of the cited work."},"authors":{"type":"array","items":{"type":"string"},"description":"Authors of the cited work, in display order."},"year":{"type":["integer","null"],"description":"Publication year."},"doi":{"type":["string","null"],"description":"Digital Object Identifier (DOI), when available."},"url":{"type":["string","null"],"description":"Best available URL for the cited work."},"venue":{"type":["string","null"],"description":"Journal, conference, repository, or other publication venue."}},"required":["title","authors","year","doi","url","venue"]}},"required":["citationId","reference","quote","source"]},"description":"Citations backing this content, resolved to the same shape as message citations."}},"required":["text","markdown","citations"]},"renderer":{"type":["string","null"],"description":"Figure renderer, when known."},"spec":{"type":["string","null"],"description":"Figure spec, when known."}},"required":["artifactId","title","caption","url","kind","description","renderer","spec"]}]},"DownloadAgentSessionArtifactResponse":{"type":"object","properties":{"downloadUrl":{"type":"string","description":"Short-lived presigned URL to download the artifact contents."},"expiresAt":{"type":"string","description":"ISO 8601 timestamp after which the download URL is no longer valid.","example":"2025-06-15T15:00:00.000Z"},"filename":{"type":"string","description":"Suggested filename for the downloaded artifact."},"contentType":{"type":["string","null"],"description":"MIME type of the artifact, when known."}},"required":["downloadUrl","expiresAt","filename","contentType"]},"StopAgentSessionResponse":{"type":"object","properties":{"sessionId":{"type":"string","description":"Unique identifier for the research agent session."},"status":{"type":"string","enum":["stopping","stopped","failed"],"description":"\"stopping\" when a stop was queued (the session halts asynchronously; poll the events endpoint for the session_stopped event). \"stopped\" or \"failed\" when the session had already ended and no stop was needed."},"url":{"type":"string","description":"URL to view and continue the session in the Elicit web interface."}},"required":["sessionId","status","url"]},"ListLibrarySourcesResponse":{"type":"object","properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/LibrarySource"}},"nextCursor":{"type":["string","null"],"description":"Pass as ?cursor= to fetch the next page; null on the last page."},"totalCount":{"type":"integer","description":"Total matches for the query across all pages."}},"required":["sources","nextCursor","totalCount"]},"LibrarySource":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Stable id of the source."},"title":{"type":["string","null"]},"authors":{"type":"array","items":{"type":"string"}},"year":{"type":["integer","null"]},"venue":{"type":["string","null"]},"abstract":{"type":["string","null"],"description":"Abstract as markdown."},"doi":{"type":["string","null"]},"url":{"type":["string","null"]},"elicitId":{"type":["string","null"],"description":"Elicit corpus id, present once the paper has been matched to the corpus."},"pdfUrls":{"type":"array","items":{"type":"string"}},"collectionIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Collections this source belongs to that are visible to you."},"role":{"type":"string","enum":["writer","reader"],"description":"Your role on this source: `writer` for your own sources and for a shared collection's papers when you own or can edit that collection; `reader` for a shared collection's papers you can only view. Any role can read the source and use it in reviews. Writers edit metadata, attach a PDF, delete, and add to collections."},"fullTextStatus":{"type":"string","enum":["pending","available","unavailable"],"description":"Whether parsed full text is attached: pending — a PDF is still parsing, or none has been looked for yet; available — parsed and attached; unavailable — looked for, none found."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"links":{"type":"object","properties":{"self":{"type":"string","description":"API URL of this source."},"fullText":{"type":"string","description":"API URL of the parsed full text; 404s until fullTextStatus is available."}},"required":["self","fullText"]}},"required":["id","title","authors","year","venue","abstract","doi","url","elicitId","pdfUrls","collectionIds","role","fullTextStatus","createdAt","updatedAt","links"]},"CreateLibrarySourceItem":{"anyOf":[{"$ref":"#/components/schemas/CorpusReferenceItem"},{"$ref":"#/components/schemas/DocumentItem"},{"$ref":"#/components/schemas/CitationItem"}]},"CorpusReferenceItem":{"type":"object","properties":{"title":{"type":"string","maxLength":2000},"authors":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500},"maxItems":200},"year":{"type":"integer","minimum":1000,"maximum":9999},"venue":{"type":"string","maxLength":1000},"abstract":{"type":"string","maxLength":50000,"description":"Plain text or markdown; blank lines separate paragraphs."},"doi":{"type":"string","minLength":1,"maxLength":512,"description":"Send the title and authors with it, so the record is useful if the DOI is not in Elicit's corpus."},"elicitId":{"type":"string","minLength":1,"maxLength":256},"url":{"type":"string","format":"uri","maxLength":2048},"pdfUrls":{"type":"array","items":{"type":"string","format":"uri","maxLength":2048},"maxItems":20,"description":"Direct PDF links. Fetched and parsed when the paper is not in the Elicit corpus; a PDF URL alone is enough."}},"required":["elicitId"],"additionalProperties":false,"description":"A paper from Elicit search, by `elicitId`. Other fields are optional."},"DocumentItem":{"type":"object","properties":{"title":{"type":"string","maxLength":2000},"authors":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500},"maxItems":200},"year":{"type":"integer","minimum":1000,"maximum":9999},"venue":{"type":"string","maxLength":1000},"abstract":{"type":"string","maxLength":50000,"description":"Plain text or markdown; blank lines separate paragraphs."},"doi":{"type":"string","minLength":1,"maxLength":512,"description":"Send the title and authors with it, so the record is useful if the DOI is not in Elicit's corpus."},"elicitId":{"type":"string","minLength":1,"maxLength":256},"url":{"type":"string","format":"uri","maxLength":2048},"pdfUrls":{"type":"array","items":{"type":"string","format":"uri","maxLength":2048},"minItems":1,"maxItems":20,"description":"Direct PDF links. Fetched and parsed when the paper is not in the Elicit corpus; a PDF URL alone is enough."}},"required":["pdfUrls"],"additionalProperties":false,"description":"A PDF by URL. Elicit parses it and fills the metadata; other fields are optional."},"CitationItem":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":2000},"authors":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500},"maxItems":200},"year":{"type":"integer","minimum":1000,"maximum":9999},"venue":{"type":"string","maxLength":1000},"abstract":{"type":"string","maxLength":50000,"description":"Plain text or markdown; blank lines separate paragraphs."},"doi":{"type":"string","minLength":1,"maxLength":512,"description":"Send the title and authors with it, so the record is useful if the DOI is not in Elicit's corpus."},"elicitId":{"type":"string","minLength":1,"maxLength":256},"url":{"type":"string","format":"uri","maxLength":2048},"pdfUrls":{"type":"array","items":{"type":"string","format":"uri","maxLength":2048},"maxItems":20,"description":"Direct PDF links. Fetched and parsed when the paper is not in the Elicit corpus; a PDF URL alone is enough."}},"required":["title"],"additionalProperties":false,"description":"A paper by `title` plus at least one of `doi`, `authors`, `year`, `venue`, `abstract`, `url`.","anyOf":[{"required":["doi"]},{"required":["authors"]},{"required":["year"]},{"required":["venue"]},{"required":["abstract"]},{"required":["url"]}]},"CreateLibrarySourcesResponse":{"type":"object","properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/CreatedLibrarySource"}}},"required":["sources"]},"CreatedLibrarySource":{"allOf":[{"$ref":"#/components/schemas/LibrarySource"}],"properties":{"updatedFields":{"type":"array","items":{"type":"string"},"description":"Fields this call populated on an already-saved source; empty when the source was created or nothing changed."},"created":{"type":"boolean","description":"Whether this call saved a new source. False when the item matched an already-saved source under onDuplicate skip: that existing source is returned, with any fields it lacked populated from the item."},"duplicateOf":{"type":["string","null"],"format":"uuid","description":"Id of the already-saved source this item matched, if any. Under onDuplicate create the returned source is the newly saved copy and the pair is recorded as a potential duplicate."},"collections":{"type":"array","items":{"type":"object","properties":{"collectionId":{"type":"string","format":"uuid"},"sourceId":{"type":"string","format":"uuid","description":"Id of this paper inside the collection. A group collection keeps its own copy, so this differs from the returned source's id; a personal collection holds the source itself."},"added":{"type":"boolean","description":"Whether this call added the paper. False when the collection already had it; sourceId is then the paper already there."}},"required":["collectionId","sourceId","added"]},"description":"One entry per requested collectionId."}},"required":["updatedFields","created","duplicateOf","collections"]},"GetLibrarySourceFullTextResponse":{"type":"object","properties":{"markdown":{"type":"string","description":"The parsed paper — title, abstract, and body — as markdown."}},"required":["markdown"]},"ListLibraryCollectionsResponse":{"type":"object","properties":{"collections":{"type":"array","items":{"$ref":"#/components/schemas/LibraryCollection"}},"nextCursor":{"type":["string","null"]},"totalCount":{"type":"integer"}},"required":["collections","nextCursor","totalCount"]},"LibraryCollection":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"role":{"type":"string","enum":["owner","writer","reader"],"description":"Your access level. A reader can view the collection. A writer can also add and remove sources and edit the name and description. An owner can also delete the collection and change who it is shared with."},"kind":{"type":"string","enum":["personal","group"],"description":"`personal`: never shared; lists your own sources. `group`: has been shared at least once; owns copies of its sources, and stays a group collection."},"sharedVia":{"type":"string","enum":["direct","organization"],"description":"`direct` if the owner shared the collection with you. `organization` if the owner shared it with your organization. Absent on your own collections."},"sourceCount":{"type":"integer"},"links":{"type":"object","properties":{"self":{"type":"string","description":"API URL of this collection."},"sources":{"type":"string","description":"URL listing the sources in this collection."}},"required":["self","sources"]}},"required":["id","name","description","role","kind","sourceCount","links"]},"LibraryImport":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["processing","completed"]},"files":{"type":"array","items":{"type":"object","properties":{"fileId":{"type":"string","format":"uuid"},"filename":{"type":"string"},"status":{"type":"string","enum":["pending","created","duplicate","failed"]},"sourceId":{"type":["string","null"],"format":"uuid"},"duplicateOf":{"type":["string","null"],"format":"uuid","description":"The already-saved source this file matched."},"error":{"type":["object","null"],"properties":{"code":{"type":"string","enum":["duplicate","processing-error","server-error","invalid-file","unknown"]},"message":{"type":"string"}},"required":["code","message"],"description":"processing-error and server-error may succeed on retry."}},"required":["fileId","filename","status","sourceId","duplicateOf","error"]}},"createdAt":{"type":"string"},"completedAt":{"type":["string","null"]},"links":{"type":"object","properties":{"self":{"type":"string","description":"Poll this URL until status is completed."}},"required":["self"]}},"required":["id","status","files","createdAt","completedAt","links"]},"AddLibraryCollectionSourcesResponse":{"type":"object","properties":{"addedCount":{"type":"integer","description":"Sources newly added; sources already in the collection are skipped."},"added":{"type":"array","items":{"type":"object","properties":{"sourceId":{"type":"string","format":"uuid"},"collectionSourceId":{"type":"string","format":"uuid","description":"Id of the paper inside the collection. A group collection keeps its own copy, so this differs from sourceId; a personal collection holds the source itself."}},"required":["sourceId","collectionSourceId"]},"description":"The sources this call added."},"duplicates":{"type":"array","items":{"type":"object","properties":{"sourceId":{"type":"string","format":"uuid"},"duplicateOf":{"type":"string","format":"uuid","description":"The id of the source that is already in the collection; the source itself when it was already a member."}},"required":["sourceId","duplicateOf"]},"description":"Sources that were not added because the collection already has the same paper. Papers match by Elicit id, DOI, title, or identical PDF."}},"required":["addedCount","added","duplicates"]},"RemoveLibraryCollectionSourcesResponse":{"type":"object","properties":{"removedCount":{"type":"integer","description":"Sources removed; ids not in the collection are skipped. A member's own source stays in their library. A shared collection's own paper moves to the collection's trash for 30 days."}},"required":["removedCount"]}}},"x-tagGroups":[{"name":"Search","tags":["Search"]},{"name":"Sessions","tags":["Sessions","Reports","Systematic Reviews","Research Agent"]},{"name":"Usage","tags":["Usage"]},{"name":"Library","tags":["Library"]}]}