# Elicit API - **OpenAPI Version:** `3.1.0` - **API Version:** `2.0.0` The Elicit API provides programmatic access to Elicit's research capabilities, including semantic search over 138 million+ academic papers and automated report generation. ## Authentication All API requests require a Bearer token in the `Authorization` header: ```properties Authorization: Bearer elk_live_your_key_here ``` API keys can be created and managed from your [Elicit account settings](https://elicit.com/settings). ## Billing API access requires a Pro plan or above. Search requests are rate-limited based on your plan tier — see the Search endpoint for details. Manage your plan in [account settings](https://elicit.com/settings). ## Code Examples Working examples in curl, Python, and JavaScript, plus integrations (CLI tool, Slack bot, Claude Code skill): **[github.com/elicit/api-examples](https://github.com/elicit/api-examples)** ## Error Handling All errors return a consistent JSON structure with an `error` object containing a machine-readable `code` and a human-readable `message`. ## MCP Server All 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. ### Claude Code ```csharp claude mcp add --transport http elicit https://elicit.com/api/mcp ``` Then run `/mcp`, select the `elicit` server, and choose **Authenticate** to open a browser for login. ### Claude Desktop **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. **Or via config file** — add to `claude_desktop_config.json`: ```json { "mcpServers": { "elicit": { "type": "url", "url": "https://elicit.com/api/mcp" } } } ``` ### Other MCP clients Connect 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`. For 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). ## Servers - **URL:** `https://elicit.com/api/v2` - **Description:** Elicit ## Operations ### Search for academic papers - **Method:** `POST` - **Path:** `/search/papers` - **Tags:** Search Search Elicit's database of over 138 million academic papers using natural language queries. Semantic search uses natural language understanding to find relevant papers even when the exact terms don't match. Set `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. Filters and `searchMode: "keyword"` are mutually exclusive — put any filter expressions directly into the query string when using keyword search. Mixing them returns a 400. To search clinical trials instead, use [`POST /api/v2/search/trials`](#tag/Search/paths/~1search~1trials/post). ### Rate Limits `POST /api/v2/search/papers` and `POST /api/v2/search/trials` share a single rate-limit bucket — requests to either count toward the same per-day total. | Plan | Results per request | Requests per day | | ---------- | ------------------- | ---------------- | | Basic | No access | No access | | Plus | No access | No access | | Pro | 300 | 100 | | Scale | 500 | 200 | | Enterprise | 10,000 | No limit | Every search response — both successful (200) and rate-limit-exceeded (429) — includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers so you can track usage without having to hit the limit. `X-RateLimit-Reset` is a Unix epoch timestamp (seconds) for when the oldest request in your rolling 24-hour window expires and a slot opens up. Plans with no daily limit (Enterprise) do not receive these headers. Upgrade your plan in [account settings](https://elicit.com/settings) for higher limits. ### Example ```bash curl -X POST https://elicit.com/api/v2/search/papers \ -H "Authorization: Bearer elk_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{"query": "effects of sleep deprivation on cognitive performance"}' ``` #### Request Body ##### Content-Type: application/json - **`query` (required)** `string` — The search query string - **`corpus`** `string`, possible values: `"elicit", "pubmed"`, default: `"elicit"` — Paper corpus to search. \`elicit\` (default) searches Elicit's full paper index; \`pubmed\` restricts to PubMed. - **`filters`** `object` — Filters to narrow search results - **`excludeKeywords`** `array` — Keywords to exclude from results **Items:** `string` - **`hasPdf`** `boolean` — Only include papers with available PDFs - **`includeKeywords`** `array` — Keywords that must appear in the paper **Items:** `string` - **`maxEpochS`** `integer` — Maximum publication date as Unix epoch seconds - **`maxQuartile`** `integer` — Maximum journal quartile (1 = top 25%) - **`maxYear`** `integer` — Maximum publication year - **`minEpochS`** `integer` — Minimum publication date as Unix epoch seconds - **`minYear`** `integer` — Minimum publication year - **`pubmedOnly`** `boolean` — Only include papers from PubMed - **`retracted`** `string`, possible values: `"exclude_retracted", "include_retracted", "only_retracted"` — How to handle retracted papers. Defaults to exclude\_retracted. - **`typeTags`** `array` — Filter by study type **Items:** `string`, possible values: `"Review", "Meta-Analysis", "Systematic Review", "RCT", "Longitudinal"` - **`maxResults`** `integer`, default: `10` — Maximum number of results to return (1-10000) - **`searchMode`** `string`, possible values: `"semantic", "keyword"`, default: `"semantic"` — 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:** ```json { "query": "GLP-1 receptor agonists for weight loss", "searchMode": "semantic", "maxResults": 10, "corpus": "elicit", "filters": { "minYear": 2020, "maxYear": 2025, "minEpochS": 1672531200, "maxEpochS": 1783932156, "maxQuartile": 2, "includeKeywords": [ "semaglutide", "liraglutide" ], "excludeKeywords": [ "rodent", "mouse model" ], "typeTags": [ "RCT", "Meta-Analysis" ], "hasPdf": false, "pubmedOnly": false, "retracted": "exclude_retracted" } } ``` #### Responses ##### Status: 200 Search results returned successfully. ###### Content-Type: application/json - **`papers` (required)** `array` — Papers matching the query **Items:** - **`abstract` (required)** `string | null` — Paper abstract - **`authors` (required)** `array` — List of author names **Items:** `string` - **`citedByCount` (required)** `integer | null` — Number of citations this paper has received - **`doi` (required)** `string | null` — Digital Object Identifier - **`elicitId` (required)** `string | null` — Elicit internal paper identifier - **`pmid` (required)** `string | null` — PubMed identifier - **`title` (required)** `string` — Paper title - **`urls` (required)** `array` — URLs for the paper **Items:** `string` - **`venue` (required)** `string | null` — Publication venue - **`year` (required)** `integer | null` — Publication year - **`warnings`** `array` — Non-fatal warnings emitted while executing the search (e.g. phrases ignored by the PubMed parser). **Items:** - **`corpus` (required)** `string`, possible values: `"elicit", "pubmed", "clinical_trials"` — Corpus that emitted the warning - **`message` (required)** `string` — Human-readable warning message - **`searchMode` (required)** `string`, possible values: `"semantic", "keyword"` — Search mode in effect when the warning was emitted - **`warningDetails` (required)** `object` - **`messages` (required)** `array` — Underlying warning messages **Items:** `string` - **`type` (required)** `string` — Warning category **Example:** ```json { "papers": [ { "elicitId": null, "title": "", "authors": [ "" ], "year": null, "abstract": null, "doi": null, "pmid": null, "venue": null, "citedByCount": null, "urls": [ "" ] } ], "warnings": [ { "corpus": "elicit", "searchMode": "semantic", "message": "", "warningDetails": { "type": "", "messages": [ "" ] } } ] } ``` ##### Status: 400 Invalid request. The request body failed validation — check that \`query\` is present and \`maxResults\` is between 1 and 10000. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 401 Authentication failed. The API key is missing, invalid, revoked, or expired. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 402 Insufficient quota. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 403 API access is not available on your current plan. Upgrade to Pro or above to use the API. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 429 Rate limit exceeded for this plan tier. Limits are enforced over a rolling 24-hour window. Check \`X-RateLimit-Reset\` for when the oldest request in your window expires. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 500 An unexpected error occurred. Retry after a short delay. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ### Search clinical trials - **Method:** `POST` - **Path:** `/search/trials` - **Tags:** Search Search for clinical trials. Trial records come from ClinicalTrials.gov. Pass `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. Filters and `searchMode: "keyword"` are mutually exclusive — put filter expressions directly into the query when using keyword search. Mixing them returns a 400. To search academic papers instead, use [`POST /api/v2/search/papers`](#tag/Search/paths/~1search~1papers/post). ### Rate Limits `POST /api/v2/search/papers` and `POST /api/v2/search/trials` share a single rate-limit bucket — requests to either count toward the same per-day total. | Plan | Results per request | Requests per day | | ---------- | ------------------- | ---------------- | | Basic | No access | No access | | Plus | No access | No access | | Pro | 300 | 100 | | Scale | 500 | 200 | | Enterprise | 10,000 | No limit | Every search response — both successful (200) and rate-limit-exceeded (429) — includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers so you can track usage without having to hit the limit. `X-RateLimit-Reset` is a Unix epoch timestamp (seconds) for when the oldest request in your rolling 24-hour window expires and a slot opens up. Plans with no daily limit (Enterprise) do not receive these headers. Upgrade your plan in [account settings](https://elicit.com/settings) for higher limits. ### Example ```bash curl -X POST https://elicit.com/api/v2/search/trials \ -H "Authorization: Bearer elk_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{"query": "semaglutide obesity", "trialFilters": {"phase": ["PHASE3"]}}' ``` #### Request Body ##### Content-Type: application/json - **`query` (required)** `string` — The search query string - **`maxResults`** `integer`, default: `10` — Maximum number of results to return (1-10000) - **`searchMode`** `string`, possible values: `"semantic", "keyword"`, default: `"semantic"` — 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. - **`trialFilters`** `object` — Clinical-trials filters (phase, recruitment status, results) - **`hasResults`** `boolean` — Only include trials that have posted results - **`phase`** `array` — Clinical trial phases to include **Items:** `string`, possible values: `"NA", "EARLY_PHASE1", "PHASE1", "PHASE2", "PHASE3", "PHASE4"` - **`recruitmentStatus`** `array` — Trial recruitment statuses to include **Items:** `string`, possible values: `"ACTIVE_NOT_RECRUITING", "COMPLETED", "ENROLLING_BY_INVITATION", "NOT_YET_RECRUITING", "RECRUITING", "SUSPENDED", "TERMINATED", "WITHDRAWN", "AVAILABLE"` **Example:** ```json { "query": "GLP-1 receptor agonists for weight loss", "searchMode": "semantic", "maxResults": 10, "trialFilters": { "phase": [ "PHASE2", "PHASE3" ], "recruitmentStatus": [ "RECRUITING", "ACTIVE_NOT_RECRUITING" ], "hasResults": true } } ``` #### Responses ##### Status: 200 Trial search results returned successfully. ###### Content-Type: application/json - **`trials` (required)** `array` — Clinical trials matching the query **Items:** - **`completionDate` (required)** `string | null` — Completion date (ISO \`YYYY-MM-DD\` or partial). - **`conditions` (required)** `array` — Conditions / diseases being studied. **Items:** `string` - **`enrollmentCount` (required)** `integer | null` — Actual or anticipated enrollment count. - **`hasResults` (required)** `boolean | null` — Whether the trial has posted results. - **`interventions` (required)** `array` — Intervention names. **Items:** `string` - **`lastUpdatedYear` (required)** `integer | null` — Year the trial record was last updated. - **`leadSponsor` (required)** `string | null` — Lead sponsor name. - **`nctId` (required)** `string` — NCT identifier for the trial - **`overallStatus` (required)** `string | null` — Overall recruitment status (RECRUITING, COMPLETED, TERMINATED, etc.). Null when the trial has no status posted. - **`phase` (required)** `array` — Trial phases (may list multiple, e.g. PHASE2 + PHASE3). Empty for N/A. **Items:** `string` - **`primaryCompletionDate` (required)** `string | null` — Primary completion date (ISO \`YYYY-MM-DD\` or partial). - **`startDate` (required)** `string | null` — Trial start date (ISO \`YYYY-MM-DD\` or partial). - **`studyType` (required)** `string | null` — Study type (INTERVENTIONAL, OBSERVATIONAL, EXPANDED\_ACCESS). - **`summary` (required)** `string | null` — Plain-text trial description / brief summary - **`title` (required)** `string` — Trial title - **`url` (required)** `string` — Link to the trial's public record - **`warnings`** `array` — Non-fatal warnings emitted while executing the search. **Items:** - **`corpus` (required)** `string`, possible values: `"elicit", "pubmed", "clinical_trials"` — Corpus that emitted the warning - **`message` (required)** `string` — Human-readable warning message - **`searchMode` (required)** `string`, possible values: `"semantic", "keyword"` — Search mode in effect when the warning was emitted - **`warningDetails` (required)** `object` - **`messages` (required)** `array` — Underlying warning messages **Items:** `string` - **`type` (required)** `string` — Warning category **Example:** ```json { "trials": [ { "nctId": "NCT05646706", "title": "", "summary": null, "url": "https://clinicaltrials.gov/study/NCT05646706", "overallStatus": null, "phase": [ "" ], "studyType": null, "enrollmentCount": null, "conditions": [ "" ], "interventions": [ "" ], "leadSponsor": null, "startDate": null, "primaryCompletionDate": null, "completionDate": null, "hasResults": null, "lastUpdatedYear": null } ], "warnings": [ { "corpus": "elicit", "searchMode": "semantic", "message": "", "warningDetails": { "type": "", "messages": [ "" ] } } ] } ``` ##### Status: 400 Invalid request. The request body failed validation. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 401 Authentication failed. The API key is missing, invalid, revoked, or expired. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 402 Insufficient quota. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 403 API access is not available on your current plan. Upgrade to Pro or above to use the API. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 429 Rate limit exceeded for this plan tier. Limits are enforced over a rolling 24-hour window. Check \`X-RateLimit-Reset\` for when the oldest request in your window expires. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 500 An unexpected error occurred. Retry after a short delay. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ### Create a new report - **Method:** `POST` - **Path:** `/sessions/reports` - **Tags:** Reports 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. Reports are long-running operations (typically 5–15 minutes). The response includes a `sessionId` and a `links.self` URL that you poll for status. The report is also visible at the `url` returned in the response, where you can watch it progress in real time. ### Workflow 1. **POST /api/v2/sessions/reports** — submit your research question (returns immediately with `sessionId`) 2. **GET `links.self`** (`/api/v2/sessions/reports/:sessionId`) — poll until `status` is `completed` or `failed` 3. Use the `pdfUrl` and `docxUrl` fields on the completed response to download the report ### Example ```bash # 1. Create the report curl -X POST https://elicit.com/api/v2/sessions/reports \ -H "Authorization: Bearer elk_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{"researchQuestion": "What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?"}' # 2. Poll for completion (repeat until status is "completed" or "failed") curl https://elicit.com/api/v2/sessions/reports/{sessionId} \ -H "Authorization: Bearer elk_live_your_key_here" ``` #### Request Body ##### Content-Type: application/json - **`researchQuestion` (required)** `string` — The research question to investigate. Elicit will search for relevant papers, screen them, and extract data to produce a structured report. - **`isPublic`** `boolean`, default: `false` — Whether the report should be publicly accessible via its URL without authentication. Defaults to false. - **`maxExtractPapers`** `integer`, default: `10` — Maximum number of papers to include in the final extraction table. Papers are screened for relevance before extraction. Defaults to 10. - **`maxSearchPapers`** `integer`, default: `50` — Maximum number of papers to retrieve during the search phase. More papers means a more comprehensive but slower report. Defaults to 50. - **`title`** `string` — 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:** ```json { "researchQuestion": "What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?", "title": "GLP-1 Receptor Agonists and Cardiovascular Outcomes", "maxSearchPapers": 50, "maxExtractPapers": 10, "isPublic": false } ``` #### Responses ##### Status: 202 Report creation accepted. The report is now being generated asynchronously. Poll \`links.self\` for status. ###### Content-Type: application/json - **`isPublic` (required)** `boolean` — Whether the report is publicly accessible via its URL without authentication - **`links` (required)** `object` - **`self` (required)** `string` — API URL for this session's full status and results (the typed get endpoint for its type) - **`resume`** `string` — API URL to resume this session. Present only while the session is paused for insufficient quota. - **`sessionId` (required)** `string`, format: `uuid` — The session ID (UUID) returned by the create endpoints and \`GET /sessions\` - **`status` (required)** `string` — Initial status is always processing - **`type` (required)** `string` - **`url` (required)** `string` — URL to view the report in the Elicit web interface as it progresses **Example:** ```json { "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", "resume": "https://elicit.com/api/v2/sessions/5ad08bfb-cbe0-4911-a8c3-309760d33029/resume" } } ``` ##### Status: 400 Invalid request. Check that \`researchQuestion\` is present and within length limits. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 401 Authentication failed. The API key is missing, invalid, revoked, or expired. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 402 Insufficient quota. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 403 API access is not available on your current plan. Upgrade to Pro or above to use the API. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 500 An unexpected error occurred. Retry after a short delay. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ### Get report status and results - **Method:** `GET` - **Path:** `/sessions/reports/{sessionId}` - **Tags:** Reports Poll the status of a report created via `POST /api/v2/sessions/reports`. ### Status transitions - **processing** — Elicit is actively searching, screening, and extracting data. You can watch progress in real time at the `url`. - **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. - **completed** — The report is finished. The `result` field contains the report content. - **failed** — Something went wrong. The `error` field contains details. - **unknown** — Status is not tracked for this report (legacy or user-created reports). ### Polling recommendation Poll every 30–60 seconds. Reports typically complete in 5–15 minutes depending on the number of papers. ### Including the full report body By default, the `reportBody` and `abstract` fields are omitted to keep polling responses lightweight. To include them, add `?include=reportBody` to the request. ### Example ```bash # Poll for status curl https://elicit.com/api/v2/sessions/reports/{sessionId} \ -H "Authorization: Bearer elk_live_your_key_here" # Fetch with full report body curl "https://elicit.com/api/v2/sessions/reports/{sessionId}?include=reportBody" \ -H "Authorization: Bearer elk_live_your_key_here" ``` #### Responses ##### Status: 200 Report status and results (if completed). ###### Content-Type: application/json - **`executionStage` (required)** `string | null`, possible values: `"gathering_sources", "screening_abstract", "screening_fulltext", "extracting_data", "generating_report", "done", null` — 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. - **`isPublic` (required)** `boolean` — Whether the report is publicly accessible via its URL without authentication - **`links` (required)** `object` - **`self` (required)** `string` — API URL for this session's full status and results (the typed get endpoint for its type) - **`resume`** `string` — API URL to resume this session. Present only while the session is paused for insufficient quota. - **`sessionId` (required)** `string`, format: `uuid` — The session ID (UUID) returned by the create endpoints and \`GET /sessions\` - **`status` (required)** `string`, possible values: `"processing", "pausedForInsufficientQuota", "completed", "failed", "unknown"` — 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. - **`type` (required)** `string` - **`url` (required)** `string` — URL to view the report in the Elicit web interface - **`docxUrl`** `string | null` — 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. - **`error`** `object` — Error details, only present when status is failed - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message - **`pdfUrl`** `string | null` — 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. - **`result`** `object` — Report output, only present when status is completed - **`summary` (required)** `string` — AI-generated executive summary of the findings - **`title` (required)** `string` — Auto-generated title for the report - **`abstract`** `string | null` — Report abstract in markdown format. Only included when ?include=reportBody is specified. - **`reportBody`** `string | null` — Full report content in markdown format. Only included when ?include=reportBody is specified. **Example:** ```json { "type": "report", "sessionId": "5ad08bfb-cbe0-4911-a8c3-309760d33029", "status": "processing", "executionStage": "gathering_sources", "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)...", "reportBody": "# Introduction\n\nGLP-1 receptor agonists have emerged as...", "abstract": "This systematic review examines the cardiovascular effects of..." }, "error": { "code": "", "message": "" }, "pdfUrl": "https://s3.amazonaws.com/...", "docxUrl": "https://s3.amazonaws.com/...", "links": { "self": "https://elicit.com/api/v2/sessions/reports/5ad08bfb-cbe0-4911-a8c3-309760d33029", "resume": "https://elicit.com/api/v2/sessions/5ad08bfb-cbe0-4911-a8c3-309760d33029/resume" } } ``` ##### Status: 401 Authentication failed. The API key is missing, invalid, revoked, or expired. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 403 API access is not available on your current plan. Upgrade to Pro or above to use the API. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 404 Report not found. Either the report ID is invalid or the report belongs to a different user. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ### Create a new systematic review - **Method:** `POST` - **Path:** `/sessions/systematic-reviews` - **Tags:** Systematic Reviews Start a systematic review. Elicit will run your configured pipeline, including searches, abstract screening, fulltext screening, extraction, and a report. Systematic 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. ### Plan limits | Plan | Max columns | Max results per query | Max total results | Figure extraction | | ---------- | ----------- | --------------------- | ----------------- | ----------------- | | Pro | 20 | 1,000 | 5,000 | No | | Scale | 30 | 5,000 | 20,000 | Yes | | Enterprise | 40 | 10,000 | 40,000 | Yes | ### Example ```bash curl -X POST https://elicit.com/api/v2/sessions/systematic-reviews \ -H "Authorization: Bearer elk_live_your_key_here" \ -H "Content-Type: application/json" \ -d @config.json ``` #### Request Body ##### Content-Type: application/json - **`researchQuestion` (required)** `string` — The research question the review is investigating. - **`abstractScreening`** `object` — Abstract-stage screening. Supply \`criteria\`, \`generate: true\`, or both. Omit the field to skip. - **`criteria`** `array` — Explicit screening criteria. **Items:** - **`instructions` (required)** `string` — Plain-language instructions used to judge whether a paper meets this criterion - **`name` (required)** `string` — Short name for the criterion - **`generate`** `boolean`, default: `false` — When true, Elicit generates additional screening criteria. - **`extraction`** `object` — Extraction stage. Supply \`questions\`, \`generate\`, or both. Omit to skip extraction entirely. - **`generate`** `boolean`, default: `false` — When true, Elicit generates additional extraction columns. - **`questions`** `array` — Explicit extraction columns. **Items:** - **`instructions` (required)** `string` — Plain-language instructions describing what to extract - **`name` (required)** `string` — Column header for this extraction question - **`choices`** `array` — Optional fixed list of allowed answers. Omit for free-text extraction. When set, the model is constrained to one of these values. **Items:** `string` - **`useFigures`** `boolean`, default: `false` — When true, model may consult figures (higher quality, slower). Subject to plan availability. - **`fulltextScreening`** `object` — Fulltext-stage screening. Supply \`criteria\`, \`reuseAbstractCriteria: true\`, or both. Requires \`abstractScreening\` to be present. Omit to skip. - **`criteria`** `array` — Explicit fulltext-stage criteria. **Items:** - **`instructions` (required)** `string` — Plain-language instructions used to judge whether a paper meets this criterion - **`name` (required)** `string` — Short name for the criterion - **`reuseAbstractCriteria`** `boolean`, default: `false` — When true, the abstract-stage criteria are also applied at the fulltext stage. - **`generateReport`** `boolean`, default: `false` — Generate a full report at the end of the review. Requires \`extraction\`. - **`isPublic`** `boolean`, default: `false` — Whether the review should be publicly accessible via its URL without authentication. Defaults to false. - **`protocolDetails`** `string` — Free-form context (PICO, methodology, inclusion/exclusion rationale) used when Elicit generates screening criteria, extraction columns, or the final report. - **`searches`** `array`, default: `[]` — 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. **Items:** - **`query` (required)** `string` — Search query - **`corpus`** `string`, possible values: `"elicit", "pubmed", "clinical_trials"`, default: `"elicit"` — Corpus to search. \`elicit\` covers \~138M papers across most domains and is the default. \`pubmed\` filters on literature from Pubmed only. \`clinical\_trials\` is registered trials only. - **`maxResults`** `integer`, default: `200` — Maximum number of papers to retrieve from this search. Plan-specific caps apply. - **`searchMode`** `string`, possible values: `"semantic", "keyword"`, default: `"semantic"` — \`semantic\` (default) uses vector-similarity retrieval; \`keyword\` uses literal keyword matching. - **`title`** `string` — Optional title for the review. **Example:** ```json { "researchQuestion": "Do GLP-1 receptor agonists reduce MACE in T2D patients?", "protocolDetails": "", "searches": [], "abstractScreening": { "criteria": [ { "name": "Human study", "instructions": "The study must be conducted in human subjects (not in vitro or animal-only)." } ], "generate": false }, "fulltextScreening": { "criteria": [ { "name": "Human study", "instructions": "The study must be conducted in human subjects (not in vitro or animal-only)." } ], "reuseAbstractCriteria": false }, "extraction": { "questions": [ { "name": "MACE hazard ratio", "instructions": "Extract the hazard ratio and 95% confidence interval for 3-point MACE.", "choices": [ "yes", "no", "maybe" ] } ], "generate": false, "useFigures": false }, "generateReport": true, "title": "", "isPublic": false } ``` #### Responses ##### Status: 202 Systematic review creation accepted. The review is now running asynchronously. Poll \`links.self\` for status. ###### Content-Type: application/json - **`isPublic` (required)** `boolean` — Whether the review is publicly accessible via its URL without authentication - **`links` (required)** `object` - **`self` (required)** `string` — API URL for this session's full status and results (the typed get endpoint for its type) - **`resume`** `string` — API URL to resume this session. Present only while the session is paused for insufficient quota. - **`sessionId` (required)** `string`, format: `uuid` — The session ID (UUID) returned by the create endpoints and \`GET /sessions\` - **`status` (required)** `string` — Initial status is always processing - **`type` (required)** `string` - **`url` (required)** `string` — URL to view the review in the Elicit web interface **Example:** ```json { "type": "systematicReview", "sessionId": "5ad08bfb-cbe0-4911-a8c3-309760d33029", "status": "processing", "url": "", "isPublic": true, "links": { "self": "https://elicit.com/api/v2/sessions/reports/5ad08bfb-cbe0-4911-a8c3-309760d33029", "resume": "https://elicit.com/api/v2/sessions/5ad08bfb-cbe0-4911-a8c3-309760d33029/resume" } } ``` ##### Status: 400 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-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 401 Authentication failed. The API key is missing, invalid, revoked, or expired. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 402 Insufficient quota. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 403 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-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 500 An unexpected error occurred. Retry after a short delay. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ### Get systematic review status and results - **Method:** `GET` - **Path:** `/sessions/systematic-reviews/{sessionId}` - **Tags:** Systematic Reviews Poll the status of a systematic review created via `POST /api/v2/sessions/systematic-reviews`. ### Status transitions - **processing** — the pipeline is running. Watch progress at `url`. - **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. - **completed** — the pipeline finished. Stage-organized exports appear under `data`. Only stages that actually ran are included. - **failed** — something went wrong. The `error` field contains details. `data` may still contain exports for stages that completed before the failure. - **unknown** — status is not tracked (legacy or user-created). ### Response shape `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. - `data.search.{csv,xlsx}` — gather-stage paper list. - `data.screen.{csv,xlsx}` — abstract-screening results. - `data.fulltext.{csv,xlsx}` — fulltext-screening results (only when fulltext screening is configured). - `data.extract.{csv,xlsx}` — extraction-stage results. - `data.report` — structured content under `result`, plus optional `pdf` / `docx` / `txt` (APA reference list) / `bib` (BibTeX) / `ris` presigned download URLs. All stage URLs are presigned for 7 days and serve with `Content-Disposition: attachment` so browser downloads land with the canonical filename. `dataFreshness` is the ISO timestamp when the cached exports were last regenerated, or `null` when nothing has been generated yet. ### Including the full report body By default, `data.report.result.reportBody` and `data.report.result.abstract` are omitted to keep responses light. Append `?include=reportBody` to include them. #### Responses ##### Status: 200 Systematic review status and results (if completed). ###### Content-Type: application/json - **`dataFreshness` (required)** `string | null` — ISO timestamp when the exports in \`data\` were last written to S3. null when no exports have been generated yet. - **`executionStage` (required)** `string | null`, possible values: `"gathering_sources", "screening_abstract", "screening_fulltext", "extracting_data", "generating_report", "done", null` — Current pipeline stage. Advances through gathering\_sources → screening\_abstract → screening\_fulltext → extracting\_data → generating\_report → done. Null for reviews created before this field was introduced or when the stage isn't known. - **`isPublic` (required)** `boolean` — Whether the review is publicly accessible via its URL without authentication - **`links` (required)** `object` - **`self` (required)** `string` — API URL for this session's full status and results (the typed get endpoint for its type) - **`resume`** `string` — API URL to resume this session. Present only while the session is paused for insufficient quota. - **`sessionId` (required)** `string`, format: `uuid` — The session ID (UUID) returned by the create endpoints and \`GET /sessions\` - **`status` (required)** `string`, possible values: `"processing", "pausedForInsufficientQuota", "completed", "failed", "unknown"` — 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. - **`type` (required)** `string` - **`url` (required)** `string` — URL to view the review in the Elicit web interface - **`data`** `object` — Stage-organized content and export URLs. Stages that did not run are omitted. - **`extract`** `object` — Extraction-stage results exports. - **`csv` (required)** `string`, format: `uri` — Presigned URL for the CSV export. Expires in 7 days. - **`xlsx` (required)** `string`, format: `uri` — Presigned URL for the XLSX export. Expires in 7 days. - **`fulltext`** `object` — Fulltext-screening results exports. - **`csv` (required)** `string`, format: `uri` — Presigned URL for the CSV export. Expires in 7 days. - **`xlsx` (required)** `string`, format: `uri` — Presigned URL for the XLSX export. Expires in 7 days. - **`report`** `object` — Report-stage content and exports. - **`result` (required)** `object` — Structured report content (title, summary, optional body + abstract). - **`summary` (required)** `string` — AI-generated executive summary of the findings - **`title` (required)** `string` — Auto-generated title - **`abstract`** `string | null` — Report abstract in markdown format. Only included when ?include=reportBody is specified. - **`reportBody`** `string | null` — Full report content in markdown format. Only included when ?include=reportBody is specified. - **`bib`** `string`, format: `uri` — Presigned URL for the BibTeX bibliography. Expires in 7 days. - **`docx`** `string`, format: `uri` — Presigned URL for the report DOCX. Expires in 7 days. - **`pdf`** `string`, format: `uri` — Presigned URL for the report PDF. Expires in 7 days. - **`ris`** `string`, format: `uri` — Presigned URL for the RIS bibliography. Expires in 7 days. - **`txt`** `string`, format: `uri` — Presigned URL for an APA-style plain-text reference list. Expires in 7 days. - **`screen`** `object` — Abstract-screening results exports. - **`csv` (required)** `string`, format: `uri` — Presigned URL for the CSV export. Expires in 7 days. - **`xlsx` (required)** `string`, format: `uri` — Presigned URL for the XLSX export. Expires in 7 days. - **`search`** `object` — Gather-stage paper list exports. - **`csv` (required)** `string`, format: `uri` — Presigned URL for the CSV export. Expires in 7 days. - **`xlsx` (required)** `string`, format: `uri` — Presigned URL for the XLSX export. Expires in 7 days. - **`error`** `object` — Error details, only present when status is failed - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "type": "systematicReview", "sessionId": "5ad08bfb-cbe0-4911-a8c3-309760d33029", "status": "processing", "executionStage": "gathering_sources", "url": "", "isPublic": true, "error": { "code": "", "message": "" }, "data": { "search": { "csv": "", "xlsx": "" }, "screen": { "csv": "", "xlsx": "" }, "fulltext": { "csv": "", "xlsx": "" }, "extract": { "csv": "", "xlsx": "" }, "report": { "result": { "title": "", "summary": "", "reportBody": null, "abstract": null }, "pdf": "", "docx": "", "txt": "", "bib": "", "ris": "" } }, "dataFreshness": null, "links": { "self": "https://elicit.com/api/v2/sessions/reports/5ad08bfb-cbe0-4911-a8c3-309760d33029", "resume": "https://elicit.com/api/v2/sessions/5ad08bfb-cbe0-4911-a8c3-309760d33029/resume" } } ``` ##### Status: 401 Authentication failed. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 403 API access is not available on your current plan. Upgrade to Pro or above to use the API. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 404 Review not found. Either the review ID is invalid or the review belongs to a different user. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ### List sessions - **Method:** `GET` - **Path:** `/sessions` - **Tags:** Sessions List all sessions — reports and systematic reviews — for the authenticated user in a single feed, ordered by creation date (newest first). Each item carries its `sessionId`, a `type` field (`report` or `systematicReview`), 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. Results are paginated using cursor-based pagination. Use the `nextCursor` value from the response to fetch the next page. Filters apply to both session types; pass `type` to list a single kind. ### Example ```bash # First page curl https://elicit.com/api/v2/sessions?limit=10 \ -H "Authorization: Bearer elk_live_your_key_here" # Next page curl "https://elicit.com/api/v2/sessions?limit=10&cursor=2025-06-15T14:30:00.000Z_5ad08bfb-cbe0-4911-a8c3-309760d33029" \ -H "Authorization: Bearer elk_live_your_key_here" # Only reports created via the API curl "https://elicit.com/api/v2/sessions?type=report&source=api" \ -H "Authorization: Bearer elk_live_your_key_here" ``` #### Responses ##### Status: 200 List of sessions. ###### Content-Type: application/json - **`nextCursor` (required)** `string | null` — Opaque cursor for the next page; pass it back as \`cursor\`. Null if there are no more results. - **`sessions` (required)** `array` — Reports and systematic reviews interleaved, ordered by creation date (newest first) **Items:** - **`createdAt` (required)** `string` — ISO 8601 timestamp of when the report was created - **`executionStage` (required)** `string | null`, possible values: `"gathering_sources", "screening_abstract", "screening_fulltext", "extracting_data", "generating_report", "done", null` — Current pipeline stage, or null when not yet known. See the get endpoint for the value vocabulary. - **`isPublic` (required)** `boolean` — Whether the report is publicly accessible via its URL without authentication - **`links` (required)** `object` - **`self` (required)** `string` — API URL for this session's full status and results (the typed get endpoint for its type) - **`resume`** `string` — API URL to resume this session. Present only while the session is paused for insufficient quota. - **`sessionId` (required)** `string`, format: `uuid` — The session ID (UUID) returned by the create endpoints and \`GET /sessions\` - **`source` (required)** `string`, possible values: `"api", "user"` — How the report was created - **`status` (required)** `string`, possible values: `"processing", "pausedForInsufficientQuota", "completed", "failed", "unknown"` — Current status of the report - **`title` (required)** `string` — Report title (the research question) - **`type` (required)** `string`, possible values: `"report", "systematicReview"` — Which kind of session this is; use it to pick the matching typed get endpoint - **`url` (required)** `string` — URL to view the report in the Elicit web interface **Example:** ```json { "sessions": [ { "type": "report", "sessionId": "5ad08bfb-cbe0-4911-a8c3-309760d33029", "status": "processing", "executionStage": "gathering_sources", "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", "resume": "https://elicit.com/api/v2/sessions/5ad08bfb-cbe0-4911-a8c3-309760d33029/resume" } } ], "nextCursor": "2025-06-15T14:30:00.000Z_5ad08bfb-cbe0-4911-a8c3-309760d33029" } ``` ##### Status: 401 Authentication failed. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 403 API access is not available on your current plan. Upgrade to Pro or above to use the API. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ### Resume a paused session - **Method:** `POST` - **Path:** `/sessions/{sessionId}/resume` - **Tags:** Sessions Resume a report or systematic review that was automatically paused because your account was over its usage limit (`status: "pausedForInsufficientQuota"` from the get endpoints). Pass 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. A 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. ### Example ```bash curl -X POST https://elicit.com/api/v2/sessions/{sessionId}/resume \ -H "Authorization: Bearer elk_live_your_key_here" ``` #### Responses ##### Status: 200 Session resumed. \`status\` reflects the row after the resume; poll \`links.self\` for progress. ###### Content-Type: application/json - **`executionStage` (required)** `string | null`, possible values: `"gathering_sources", "screening_abstract", "screening_fulltext", "extracting_data", "generating_report", "done", null` — The stage the session resumed at - **`isPublic` (required)** `boolean` - **`links` (required)** `object` - **`self` (required)** `string` — API URL for this session's full status and results (the typed get endpoint for its type) - **`resume`** `string` — API URL to resume this session. Present only while the session is paused for insufficient quota. - **`sessionId` (required)** `string`, format: `uuid` — The session ID (UUID) returned by the create endpoints and \`GET /sessions\` - **`status` (required)** `string`, possible values: `"processing", "pausedForInsufficientQuota", "completed", "failed", "unknown"` — Status after the resume — normally processing; completed or failed if the run finished while the resume was in flight. - **`type` (required)** `string`, possible values: `"report", "systematicReview"` — Which kind of session this is; use it to pick the matching typed get endpoint - **`url` (required)** `string` — URL to view this session in the Elicit web interface **Example:** ```json { "type": "report", "sessionId": "5ad08bfb-cbe0-4911-a8c3-309760d33029", "status": "processing", "executionStage": "screening_abstract", "url": "", "isPublic": true, "links": { "self": "https://elicit.com/api/v2/sessions/reports/5ad08bfb-cbe0-4911-a8c3-309760d33029", "resume": "https://elicit.com/api/v2/sessions/5ad08bfb-cbe0-4911-a8c3-309760d33029/resume" } } ``` ##### Status: 401 Authentication failed. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 402 Insufficient quota. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 403 API access is not available on your current plan. Upgrade to Pro or above to use the API. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 404 Session not found. Either the session ID is invalid or the session belongs to a different user. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ##### Status: 409 The session is not currently paused, so there is nothing to resume. ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ## Schemas ### PaperSearchRequest - **Type:**`object` * **`query` (required)** `string` — The search query string * **`corpus`** `string`, possible values: `"elicit", "pubmed"`, default: `"elicit"` — Paper corpus to search. \`elicit\` (default) searches Elicit's full paper index; \`pubmed\` restricts to PubMed. * **`filters`** `object` — Filters to narrow search results - **`excludeKeywords`** `array` — Keywords to exclude from results **Items:** `string` - **`hasPdf`** `boolean` — Only include papers with available PDFs - **`includeKeywords`** `array` — Keywords that must appear in the paper **Items:** `string` - **`maxEpochS`** `integer` — Maximum publication date as Unix epoch seconds - **`maxQuartile`** `integer` — Maximum journal quartile (1 = top 25%) - **`maxYear`** `integer` — Maximum publication year - **`minEpochS`** `integer` — Minimum publication date as Unix epoch seconds - **`minYear`** `integer` — Minimum publication year - **`pubmedOnly`** `boolean` — Only include papers from PubMed - **`retracted`** `string`, possible values: `"exclude_retracted", "include_retracted", "only_retracted"` — How to handle retracted papers. Defaults to exclude\_retracted. - **`typeTags`** `array` — Filter by study type **Items:** `string`, possible values: `"Review", "Meta-Analysis", "Systematic Review", "RCT", "Longitudinal"` * **`maxResults`** `integer`, default: `10` — Maximum number of results to return (1-10000) * **`searchMode`** `string`, possible values: `"semantic", "keyword"`, default: `"semantic"` — 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:** ```json { "query": "GLP-1 receptor agonists for weight loss", "searchMode": "semantic", "maxResults": 10, "corpus": "elicit", "filters": { "minYear": 2020, "maxYear": 2025, "minEpochS": 1672531200, "maxEpochS": 1783932156, "maxQuartile": 2, "includeKeywords": [ "semaglutide", "liraglutide" ], "excludeKeywords": [ "rodent", "mouse model" ], "typeTags": [ "RCT", "Meta-Analysis" ], "hasPdf": false, "pubmedOnly": false, "retracted": "exclude_retracted" } } ``` ### PaperFilters - **Type:**`object` * **`excludeKeywords`** `array` — Keywords to exclude from results **Items:** `string` * **`hasPdf`** `boolean` — Only include papers with available PDFs * **`includeKeywords`** `array` — Keywords that must appear in the paper **Items:** `string` * **`maxEpochS`** `integer` — Maximum publication date as Unix epoch seconds * **`maxQuartile`** `integer` — Maximum journal quartile (1 = top 25%) * **`maxYear`** `integer` — Maximum publication year * **`minEpochS`** `integer` — Minimum publication date as Unix epoch seconds * **`minYear`** `integer` — Minimum publication year * **`pubmedOnly`** `boolean` — Only include papers from PubMed * **`retracted`** `string`, possible values: `"exclude_retracted", "include_retracted", "only_retracted"` — How to handle retracted papers. Defaults to exclude\_retracted. * **`typeTags`** `array` — Filter by study type **Items:** `string`, possible values: `"Review", "Meta-Analysis", "Systematic Review", "RCT", "Longitudinal"` **Example:** ```json { "minYear": 2020, "maxYear": 2025, "minEpochS": 1672531200, "maxEpochS": 1783932156, "maxQuartile": 2, "includeKeywords": [ "semaglutide", "liraglutide" ], "excludeKeywords": [ "rodent", "mouse model" ], "typeTags": [ "RCT", "Meta-Analysis" ], "hasPdf": false, "pubmedOnly": false, "retracted": "exclude_retracted" } ``` ### PaperSearchResponse - **Type:**`object` * **`papers` (required)** `array` — Papers matching the query **Items:** - **`abstract` (required)** `string | null` — Paper abstract - **`authors` (required)** `array` — List of author names **Items:** `string` - **`citedByCount` (required)** `integer | null` — Number of citations this paper has received - **`doi` (required)** `string | null` — Digital Object Identifier - **`elicitId` (required)** `string | null` — Elicit internal paper identifier - **`pmid` (required)** `string | null` — PubMed identifier - **`title` (required)** `string` — Paper title - **`urls` (required)** `array` — URLs for the paper **Items:** `string` - **`venue` (required)** `string | null` — Publication venue - **`year` (required)** `integer | null` — Publication year * **`warnings`** `array` — Non-fatal warnings emitted while executing the search (e.g. phrases ignored by the PubMed parser). **Items:** - **`corpus` (required)** `string`, possible values: `"elicit", "pubmed", "clinical_trials"` — Corpus that emitted the warning - **`message` (required)** `string` — Human-readable warning message - **`searchMode` (required)** `string`, possible values: `"semantic", "keyword"` — Search mode in effect when the warning was emitted - **`warningDetails` (required)** `object` - **`messages` (required)** `array` — Underlying warning messages **Items:** `string` - **`type` (required)** `string` — Warning category **Example:** ```json { "papers": [ { "elicitId": null, "title": "", "authors": [ "" ], "year": null, "abstract": null, "doi": null, "pmid": null, "venue": null, "citedByCount": null, "urls": [ "" ] } ], "warnings": [ { "corpus": "elicit", "searchMode": "semantic", "message": "", "warningDetails": { "type": "", "messages": [ "" ] } } ] } ``` ### Paper - **Type:**`object` * **`abstract` (required)** `string | null` — Paper abstract * **`authors` (required)** `array` — List of author names **Items:** `string` * **`citedByCount` (required)** `integer | null` — Number of citations this paper has received * **`doi` (required)** `string | null` — Digital Object Identifier * **`elicitId` (required)** `string | null` — Elicit internal paper identifier * **`pmid` (required)** `string | null` — PubMed identifier * **`title` (required)** `string` — Paper title * **`urls` (required)** `array` — URLs for the paper **Items:** `string` * **`venue` (required)** `string | null` — Publication venue * **`year` (required)** `integer | null` — Publication year **Example:** ```json { "elicitId": null, "title": "", "authors": [ "" ], "year": null, "abstract": null, "doi": null, "pmid": null, "venue": null, "citedByCount": null, "urls": [ "" ] } ``` ### SearchWarning - **Type:**`object` * **`corpus` (required)** `string`, possible values: `"elicit", "pubmed", "clinical_trials"` — Corpus that emitted the warning * **`message` (required)** `string` — Human-readable warning message * **`searchMode` (required)** `string`, possible values: `"semantic", "keyword"` — Search mode in effect when the warning was emitted * **`warningDetails` (required)** `object` - **`messages` (required)** `array` — Underlying warning messages **Items:** `string` - **`type` (required)** `string` — Warning category **Example:** ```json { "corpus": "elicit", "searchMode": "semantic", "message": "", "warningDetails": { "type": "", "messages": [ "" ] } } ``` ### SearchWarningDetails - **Type:**`object` * **`messages` (required)** `array` — Underlying warning messages **Items:** `string` * **`type` (required)** `string` — Warning category **Example:** ```json { "type": "", "messages": [ "" ] } ``` ### ErrorResponse - **Type:**`object` * **`error` (required)** `object` - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "error": { "code": "invalid_request", "message": "Invalid search request" } } ``` ### TrialSearchRequest - **Type:**`object` * **`query` (required)** `string` — The search query string * **`maxResults`** `integer`, default: `10` — Maximum number of results to return (1-10000) * **`searchMode`** `string`, possible values: `"semantic", "keyword"`, default: `"semantic"` — 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. * **`trialFilters`** `object` — Clinical-trials filters (phase, recruitment status, results) - **`hasResults`** `boolean` — Only include trials that have posted results - **`phase`** `array` — Clinical trial phases to include **Items:** `string`, possible values: `"NA", "EARLY_PHASE1", "PHASE1", "PHASE2", "PHASE3", "PHASE4"` - **`recruitmentStatus`** `array` — Trial recruitment statuses to include **Items:** `string`, possible values: `"ACTIVE_NOT_RECRUITING", "COMPLETED", "ENROLLING_BY_INVITATION", "NOT_YET_RECRUITING", "RECRUITING", "SUSPENDED", "TERMINATED", "WITHDRAWN", "AVAILABLE"` **Example:** ```json { "query": "GLP-1 receptor agonists for weight loss", "searchMode": "semantic", "maxResults": 10, "trialFilters": { "phase": [ "PHASE2", "PHASE3" ], "recruitmentStatus": [ "RECRUITING", "ACTIVE_NOT_RECRUITING" ], "hasResults": true } } ``` ### TrialFilters - **Type:**`object` * **`hasResults`** `boolean` — Only include trials that have posted results * **`phase`** `array` — Clinical trial phases to include **Items:** `string`, possible values: `"NA", "EARLY_PHASE1", "PHASE1", "PHASE2", "PHASE3", "PHASE4"` * **`recruitmentStatus`** `array` — Trial recruitment statuses to include **Items:** `string`, possible values: `"ACTIVE_NOT_RECRUITING", "COMPLETED", "ENROLLING_BY_INVITATION", "NOT_YET_RECRUITING", "RECRUITING", "SUSPENDED", "TERMINATED", "WITHDRAWN", "AVAILABLE"` **Example:** ```json { "phase": [ "PHASE2", "PHASE3" ], "recruitmentStatus": [ "RECRUITING", "ACTIVE_NOT_RECRUITING" ], "hasResults": true } ``` ### TrialSearchResponse - **Type:**`object` * **`trials` (required)** `array` — Clinical trials matching the query **Items:** - **`completionDate` (required)** `string | null` — Completion date (ISO \`YYYY-MM-DD\` or partial). - **`conditions` (required)** `array` — Conditions / diseases being studied. **Items:** `string` - **`enrollmentCount` (required)** `integer | null` — Actual or anticipated enrollment count. - **`hasResults` (required)** `boolean | null` — Whether the trial has posted results. - **`interventions` (required)** `array` — Intervention names. **Items:** `string` - **`lastUpdatedYear` (required)** `integer | null` — Year the trial record was last updated. - **`leadSponsor` (required)** `string | null` — Lead sponsor name. - **`nctId` (required)** `string` — NCT identifier for the trial - **`overallStatus` (required)** `string | null` — Overall recruitment status (RECRUITING, COMPLETED, TERMINATED, etc.). Null when the trial has no status posted. - **`phase` (required)** `array` — Trial phases (may list multiple, e.g. PHASE2 + PHASE3). Empty for N/A. **Items:** `string` - **`primaryCompletionDate` (required)** `string | null` — Primary completion date (ISO \`YYYY-MM-DD\` or partial). - **`startDate` (required)** `string | null` — Trial start date (ISO \`YYYY-MM-DD\` or partial). - **`studyType` (required)** `string | null` — Study type (INTERVENTIONAL, OBSERVATIONAL, EXPANDED\_ACCESS). - **`summary` (required)** `string | null` — Plain-text trial description / brief summary - **`title` (required)** `string` — Trial title - **`url` (required)** `string` — Link to the trial's public record * **`warnings`** `array` — Non-fatal warnings emitted while executing the search. **Items:** - **`corpus` (required)** `string`, possible values: `"elicit", "pubmed", "clinical_trials"` — Corpus that emitted the warning - **`message` (required)** `string` — Human-readable warning message - **`searchMode` (required)** `string`, possible values: `"semantic", "keyword"` — Search mode in effect when the warning was emitted - **`warningDetails` (required)** `object` - **`messages` (required)** `array` — Underlying warning messages **Items:** `string` - **`type` (required)** `string` — Warning category **Example:** ```json { "trials": [ { "nctId": "NCT05646706", "title": "", "summary": null, "url": "https://clinicaltrials.gov/study/NCT05646706", "overallStatus": null, "phase": [ "" ], "studyType": null, "enrollmentCount": null, "conditions": [ "" ], "interventions": [ "" ], "leadSponsor": null, "startDate": null, "primaryCompletionDate": null, "completionDate": null, "hasResults": null, "lastUpdatedYear": null } ], "warnings": [ { "corpus": "elicit", "searchMode": "semantic", "message": "", "warningDetails": { "type": "", "messages": [ "" ] } } ] } ``` ### Trial - **Type:**`object` * **`completionDate` (required)** `string | null` — Completion date (ISO \`YYYY-MM-DD\` or partial). * **`conditions` (required)** `array` — Conditions / diseases being studied. **Items:** `string` * **`enrollmentCount` (required)** `integer | null` — Actual or anticipated enrollment count. * **`hasResults` (required)** `boolean | null` — Whether the trial has posted results. * **`interventions` (required)** `array` — Intervention names. **Items:** `string` * **`lastUpdatedYear` (required)** `integer | null` — Year the trial record was last updated. * **`leadSponsor` (required)** `string | null` — Lead sponsor name. * **`nctId` (required)** `string` — NCT identifier for the trial * **`overallStatus` (required)** `string | null` — Overall recruitment status (RECRUITING, COMPLETED, TERMINATED, etc.). Null when the trial has no status posted. * **`phase` (required)** `array` — Trial phases (may list multiple, e.g. PHASE2 + PHASE3). Empty for N/A. **Items:** `string` * **`primaryCompletionDate` (required)** `string | null` — Primary completion date (ISO \`YYYY-MM-DD\` or partial). * **`startDate` (required)** `string | null` — Trial start date (ISO \`YYYY-MM-DD\` or partial). * **`studyType` (required)** `string | null` — Study type (INTERVENTIONAL, OBSERVATIONAL, EXPANDED\_ACCESS). * **`summary` (required)** `string | null` — Plain-text trial description / brief summary * **`title` (required)** `string` — Trial title * **`url` (required)** `string` — Link to the trial's public record **Example:** ```json { "nctId": "NCT05646706", "title": "", "summary": null, "url": "https://clinicaltrials.gov/study/NCT05646706", "overallStatus": null, "phase": [ "" ], "studyType": null, "enrollmentCount": null, "conditions": [ "" ], "interventions": [ "" ], "leadSponsor": null, "startDate": null, "primaryCompletionDate": null, "completionDate": null, "hasResults": null, "lastUpdatedYear": null } ``` ### ReportSessionCreated - **Type:**`object` * **`isPublic` (required)** `boolean` — Whether the report is publicly accessible via its URL without authentication * **`links` (required)** `object` - **`self` (required)** `string` — API URL for this session's full status and results (the typed get endpoint for its type) - **`resume`** `string` — API URL to resume this session. Present only while the session is paused for insufficient quota. * **`sessionId` (required)** `string`, format: `uuid` — The session ID (UUID) returned by the create endpoints and \`GET /sessions\` * **`status` (required)** `string` — Initial status is always processing * **`type` (required)** `string` * **`url` (required)** `string` — URL to view the report in the Elicit web interface as it progresses **Example:** ```json { "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", "resume": "https://elicit.com/api/v2/sessions/5ad08bfb-cbe0-4911-a8c3-309760d33029/resume" } } ``` ### SessionLinks - **Type:**`object` * **`self` (required)** `string` — API URL for this session's full status and results (the typed get endpoint for its type) * **`resume`** `string` — API URL to resume this session. Present only while the session is paused for insufficient quota. **Example:** ```json { "self": "https://elicit.com/api/v2/sessions/reports/5ad08bfb-cbe0-4911-a8c3-309760d33029", "resume": "https://elicit.com/api/v2/sessions/5ad08bfb-cbe0-4911-a8c3-309760d33029/resume" } ``` ### ReportSessionDetail - **Type:**`object` * **`executionStage` (required)** `string | null`, possible values: `"gathering_sources", "screening_abstract", "screening_fulltext", "extracting_data", "generating_report", "done", null` — 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. * **`isPublic` (required)** `boolean` — Whether the report is publicly accessible via its URL without authentication * **`links` (required)** `object` - **`self` (required)** `string` — API URL for this session's full status and results (the typed get endpoint for its type) - **`resume`** `string` — API URL to resume this session. Present only while the session is paused for insufficient quota. * **`sessionId` (required)** `string`, format: `uuid` — The session ID (UUID) returned by the create endpoints and \`GET /sessions\` * **`status` (required)** `string`, possible values: `"processing", "pausedForInsufficientQuota", "completed", "failed", "unknown"` — 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. * **`type` (required)** `string` * **`url` (required)** `string` — URL to view the report in the Elicit web interface * **`docxUrl`** `string | null` — 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. * **`error`** `object` — Error details, only present when status is failed - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message * **`pdfUrl`** `string | null` — 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. * **`result`** `object` — Report output, only present when status is completed - **`summary` (required)** `string` — AI-generated executive summary of the findings - **`title` (required)** `string` — Auto-generated title for the report - **`abstract`** `string | null` — Report abstract in markdown format. Only included when ?include=reportBody is specified. - **`reportBody`** `string | null` — Full report content in markdown format. Only included when ?include=reportBody is specified. **Example:** ```json { "type": "report", "sessionId": "5ad08bfb-cbe0-4911-a8c3-309760d33029", "status": "processing", "executionStage": "gathering_sources", "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)...", "reportBody": "# Introduction\n\nGLP-1 receptor agonists have emerged as...", "abstract": "This systematic review examines the cardiovascular effects of..." }, "error": { "code": "", "message": "" }, "pdfUrl": "https://s3.amazonaws.com/...", "docxUrl": "https://s3.amazonaws.com/...", "links": { "self": "https://elicit.com/api/v2/sessions/reports/5ad08bfb-cbe0-4911-a8c3-309760d33029", "resume": "https://elicit.com/api/v2/sessions/5ad08bfb-cbe0-4911-a8c3-309760d33029/resume" } } ``` ### ReportResult - **Type:**`object` * **`summary` (required)** `string` — AI-generated executive summary of the findings * **`title` (required)** `string` — Auto-generated title for the report * **`abstract`** `string | null` — Report abstract in markdown format. Only included when ?include=reportBody is specified. * **`reportBody`** `string | null` — Full report content in markdown format. Only included when ?include=reportBody is specified. **Example:** ```json { "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)...", "reportBody": "# Introduction\n\nGLP-1 receptor agonists have emerged as...", "abstract": "This systematic review examines the cardiovascular effects of..." } ``` ### SystematicReviewSessionCreated - **Type:**`object` * **`isPublic` (required)** `boolean` — Whether the review is publicly accessible via its URL without authentication * **`links` (required)** `object` - **`self` (required)** `string` — API URL for this session's full status and results (the typed get endpoint for its type) - **`resume`** `string` — API URL to resume this session. Present only while the session is paused for insufficient quota. * **`sessionId` (required)** `string`, format: `uuid` — The session ID (UUID) returned by the create endpoints and \`GET /sessions\` * **`status` (required)** `string` — Initial status is always processing * **`type` (required)** `string` * **`url` (required)** `string` — URL to view the review in the Elicit web interface **Example:** ```json { "type": "systematicReview", "sessionId": "5ad08bfb-cbe0-4911-a8c3-309760d33029", "status": "processing", "url": "", "isPublic": true, "links": { "self": "https://elicit.com/api/v2/sessions/reports/5ad08bfb-cbe0-4911-a8c3-309760d33029", "resume": "https://elicit.com/api/v2/sessions/5ad08bfb-cbe0-4911-a8c3-309760d33029/resume" } } ``` ### SystematicReviewSessionDetail - **Type:**`object` * **`dataFreshness` (required)** `string | null` — ISO timestamp when the exports in \`data\` were last written to S3. null when no exports have been generated yet. * **`executionStage` (required)** `string | null`, possible values: `"gathering_sources", "screening_abstract", "screening_fulltext", "extracting_data", "generating_report", "done", null` — Current pipeline stage. Advances through gathering\_sources → screening\_abstract → screening\_fulltext → extracting\_data → generating\_report → done. Null for reviews created before this field was introduced or when the stage isn't known. * **`isPublic` (required)** `boolean` — Whether the review is publicly accessible via its URL without authentication * **`links` (required)** `object` - **`self` (required)** `string` — API URL for this session's full status and results (the typed get endpoint for its type) - **`resume`** `string` — API URL to resume this session. Present only while the session is paused for insufficient quota. * **`sessionId` (required)** `string`, format: `uuid` — The session ID (UUID) returned by the create endpoints and \`GET /sessions\` * **`status` (required)** `string`, possible values: `"processing", "pausedForInsufficientQuota", "completed", "failed", "unknown"` — 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. * **`type` (required)** `string` * **`url` (required)** `string` — URL to view the review in the Elicit web interface * **`data`** `object` — Stage-organized content and export URLs. Stages that did not run are omitted. - **`extract`** `object` — Extraction-stage results exports. - **`csv` (required)** `string`, format: `uri` — Presigned URL for the CSV export. Expires in 7 days. - **`xlsx` (required)** `string`, format: `uri` — Presigned URL for the XLSX export. Expires in 7 days. - **`fulltext`** `object` — Fulltext-screening results exports. - **`csv` (required)** `string`, format: `uri` — Presigned URL for the CSV export. Expires in 7 days. - **`xlsx` (required)** `string`, format: `uri` — Presigned URL for the XLSX export. Expires in 7 days. - **`report`** `object` — Report-stage content and exports. - **`result` (required)** `object` — Structured report content (title, summary, optional body + abstract). - **`summary` (required)** `string` — AI-generated executive summary of the findings - **`title` (required)** `string` — Auto-generated title - **`abstract`** `string | null` — Report abstract in markdown format. Only included when ?include=reportBody is specified. - **`reportBody`** `string | null` — Full report content in markdown format. Only included when ?include=reportBody is specified. - **`bib`** `string`, format: `uri` — Presigned URL for the BibTeX bibliography. Expires in 7 days. - **`docx`** `string`, format: `uri` — Presigned URL for the report DOCX. Expires in 7 days. - **`pdf`** `string`, format: `uri` — Presigned URL for the report PDF. Expires in 7 days. - **`ris`** `string`, format: `uri` — Presigned URL for the RIS bibliography. Expires in 7 days. - **`txt`** `string`, format: `uri` — Presigned URL for an APA-style plain-text reference list. Expires in 7 days. - **`screen`** `object` — Abstract-screening results exports. - **`csv` (required)** `string`, format: `uri` — Presigned URL for the CSV export. Expires in 7 days. - **`xlsx` (required)** `string`, format: `uri` — Presigned URL for the XLSX export. Expires in 7 days. - **`search`** `object` — Gather-stage paper list exports. - **`csv` (required)** `string`, format: `uri` — Presigned URL for the CSV export. Expires in 7 days. - **`xlsx` (required)** `string`, format: `uri` — Presigned URL for the XLSX export. Expires in 7 days. * **`error`** `object` — Error details, only present when status is failed - **`code` (required)** `string` — Machine-readable error code - **`message` (required)** `string` — Human-readable error message **Example:** ```json { "type": "systematicReview", "sessionId": "5ad08bfb-cbe0-4911-a8c3-309760d33029", "status": "processing", "executionStage": "gathering_sources", "url": "", "isPublic": true, "error": { "code": "", "message": "" }, "data": { "search": { "csv": "", "xlsx": "" }, "screen": { "csv": "", "xlsx": "" }, "fulltext": { "csv": "", "xlsx": "" }, "extract": { "csv": "", "xlsx": "" }, "report": { "result": { "title": "", "summary": "", "reportBody": null, "abstract": null }, "pdf": "", "docx": "", "txt": "", "bib": "", "ris": "" } }, "dataFreshness": null, "links": { "self": "https://elicit.com/api/v2/sessions/reports/5ad08bfb-cbe0-4911-a8c3-309760d33029", "resume": "https://elicit.com/api/v2/sessions/5ad08bfb-cbe0-4911-a8c3-309760d33029/resume" } } ``` ### ReviewData - **Type:**`object` * **`extract`** `object` — Extraction-stage results exports. - **`csv` (required)** `string`, format: `uri` — Presigned URL for the CSV export. Expires in 7 days. - **`xlsx` (required)** `string`, format: `uri` — Presigned URL for the XLSX export. Expires in 7 days. * **`fulltext`** `object` — Fulltext-screening results exports. - **`csv` (required)** `string`, format: `uri` — Presigned URL for the CSV export. Expires in 7 days. - **`xlsx` (required)** `string`, format: `uri` — Presigned URL for the XLSX export. Expires in 7 days. * **`report`** `object` — Report-stage content and exports. - **`result` (required)** `object` — Structured report content (title, summary, optional body + abstract). - **`summary` (required)** `string` — AI-generated executive summary of the findings - **`title` (required)** `string` — Auto-generated title - **`abstract`** `string | null` — Report abstract in markdown format. Only included when ?include=reportBody is specified. - **`reportBody`** `string | null` — Full report content in markdown format. Only included when ?include=reportBody is specified. - **`bib`** `string`, format: `uri` — Presigned URL for the BibTeX bibliography. Expires in 7 days. - **`docx`** `string`, format: `uri` — Presigned URL for the report DOCX. Expires in 7 days. - **`pdf`** `string`, format: `uri` — Presigned URL for the report PDF. Expires in 7 days. - **`ris`** `string`, format: `uri` — Presigned URL for the RIS bibliography. Expires in 7 days. - **`txt`** `string`, format: `uri` — Presigned URL for an APA-style plain-text reference list. Expires in 7 days. * **`screen`** `object` — Abstract-screening results exports. - **`csv` (required)** `string`, format: `uri` — Presigned URL for the CSV export. Expires in 7 days. - **`xlsx` (required)** `string`, format: `uri` — Presigned URL for the XLSX export. Expires in 7 days. * **`search`** `object` — Gather-stage paper list exports. - **`csv` (required)** `string`, format: `uri` — Presigned URL for the CSV export. Expires in 7 days. - **`xlsx` (required)** `string`, format: `uri` — Presigned URL for the XLSX export. Expires in 7 days. **Example:** ```json { "search": { "csv": "", "xlsx": "" }, "screen": { "csv": "", "xlsx": "" }, "fulltext": { "csv": "", "xlsx": "" }, "extract": { "csv": "", "xlsx": "" }, "report": { "result": { "title": "", "summary": "", "reportBody": null, "abstract": null }, "pdf": "", "docx": "", "txt": "", "bib": "", "ris": "" } } ``` ### StageData - **Type:**`object` * **`csv` (required)** `string`, format: `uri` — Presigned URL for the CSV export. Expires in 7 days. * **`xlsx` (required)** `string`, format: `uri` — Presigned URL for the XLSX export. Expires in 7 days. **Example:** ```json { "csv": "", "xlsx": "" } ``` ### ReportData - **Type:**`object` * **`result` (required)** `object` — Structured report content (title, summary, optional body + abstract). - **`summary` (required)** `string` — AI-generated executive summary of the findings - **`title` (required)** `string` — Auto-generated title - **`abstract`** `string | null` — Report abstract in markdown format. Only included when ?include=reportBody is specified. - **`reportBody`** `string | null` — Full report content in markdown format. Only included when ?include=reportBody is specified. * **`bib`** `string`, format: `uri` — Presigned URL for the BibTeX bibliography. Expires in 7 days. * **`docx`** `string`, format: `uri` — Presigned URL for the report DOCX. Expires in 7 days. * **`pdf`** `string`, format: `uri` — Presigned URL for the report PDF. Expires in 7 days. * **`ris`** `string`, format: `uri` — Presigned URL for the RIS bibliography. Expires in 7 days. * **`txt`** `string`, format: `uri` — Presigned URL for an APA-style plain-text reference list. Expires in 7 days. **Example:** ```json { "result": { "title": "", "summary": "", "reportBody": null, "abstract": null }, "pdf": "", "docx": "", "txt": "", "bib": "", "ris": "" } ``` ### ReviewResult - **Type:**`object` * **`summary` (required)** `string` — AI-generated executive summary of the findings * **`title` (required)** `string` — Auto-generated title * **`abstract`** `string | null` — Report abstract in markdown format. Only included when ?include=reportBody is specified. * **`reportBody`** `string | null` — Full report content in markdown format. Only included when ?include=reportBody is specified. **Example:** ```json { "title": "", "summary": "", "reportBody": null, "abstract": null } ``` ### ListSessionsResponse - **Type:**`object` * **`nextCursor` (required)** `string | null` — Opaque cursor for the next page; pass it back as \`cursor\`. Null if there are no more results. * **`sessions` (required)** `array` — Reports and systematic reviews interleaved, ordered by creation date (newest first) **Items:** - **`createdAt` (required)** `string` — ISO 8601 timestamp of when the report was created - **`executionStage` (required)** `string | null`, possible values: `"gathering_sources", "screening_abstract", "screening_fulltext", "extracting_data", "generating_report", "done", null` — Current pipeline stage, or null when not yet known. See the get endpoint for the value vocabulary. - **`isPublic` (required)** `boolean` — Whether the report is publicly accessible via its URL without authentication - **`links` (required)** `object` - **`self` (required)** `string` — API URL for this session's full status and results (the typed get endpoint for its type) - **`resume`** `string` — API URL to resume this session. Present only while the session is paused for insufficient quota. - **`sessionId` (required)** `string`, format: `uuid` — The session ID (UUID) returned by the create endpoints and \`GET /sessions\` - **`source` (required)** `string`, possible values: `"api", "user"` — How the report was created - **`status` (required)** `string`, possible values: `"processing", "pausedForInsufficientQuota", "completed", "failed", "unknown"` — Current status of the report - **`title` (required)** `string` — Report title (the research question) - **`type` (required)** `string`, possible values: `"report", "systematicReview"` — Which kind of session this is; use it to pick the matching typed get endpoint - **`url` (required)** `string` — URL to view the report in the Elicit web interface **Example:** ```json { "sessions": [ { "type": "report", "sessionId": "5ad08bfb-cbe0-4911-a8c3-309760d33029", "status": "processing", "executionStage": "gathering_sources", "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", "resume": "https://elicit.com/api/v2/sessions/5ad08bfb-cbe0-4911-a8c3-309760d33029/resume" } } ], "nextCursor": "2025-06-15T14:30:00.000Z_5ad08bfb-cbe0-4911-a8c3-309760d33029" } ``` ### SessionListItem - **Type:**`object` * **`createdAt` (required)** `string` — ISO 8601 timestamp of when the report was created * **`executionStage` (required)** `string | null`, possible values: `"gathering_sources", "screening_abstract", "screening_fulltext", "extracting_data", "generating_report", "done", null` — Current pipeline stage, or null when not yet known. See the get endpoint for the value vocabulary. * **`isPublic` (required)** `boolean` — Whether the report is publicly accessible via its URL without authentication * **`links` (required)** `object` - **`self` (required)** `string` — API URL for this session's full status and results (the typed get endpoint for its type) - **`resume`** `string` — API URL to resume this session. Present only while the session is paused for insufficient quota. * **`sessionId` (required)** `string`, format: `uuid` — The session ID (UUID) returned by the create endpoints and \`GET /sessions\` * **`source` (required)** `string`, possible values: `"api", "user"` — How the report was created * **`status` (required)** `string`, possible values: `"processing", "pausedForInsufficientQuota", "completed", "failed", "unknown"` — Current status of the report * **`title` (required)** `string` — Report title (the research question) * **`type` (required)** `string`, possible values: `"report", "systematicReview"` — Which kind of session this is; use it to pick the matching typed get endpoint * **`url` (required)** `string` — URL to view the report in the Elicit web interface **Example:** ```json { "type": "report", "sessionId": "5ad08bfb-cbe0-4911-a8c3-309760d33029", "status": "processing", "executionStage": "gathering_sources", "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", "resume": "https://elicit.com/api/v2/sessions/5ad08bfb-cbe0-4911-a8c3-309760d33029/resume" } } ``` ### ResumeSessionResponse - **Type:**`object` * **`executionStage` (required)** `string | null`, possible values: `"gathering_sources", "screening_abstract", "screening_fulltext", "extracting_data", "generating_report", "done", null` — The stage the session resumed at * **`isPublic` (required)** `boolean` * **`links` (required)** `object` - **`self` (required)** `string` — API URL for this session's full status and results (the typed get endpoint for its type) - **`resume`** `string` — API URL to resume this session. Present only while the session is paused for insufficient quota. * **`sessionId` (required)** `string`, format: `uuid` — The session ID (UUID) returned by the create endpoints and \`GET /sessions\` * **`status` (required)** `string`, possible values: `"processing", "pausedForInsufficientQuota", "completed", "failed", "unknown"` — Status after the resume — normally processing; completed or failed if the run finished while the resume was in flight. * **`type` (required)** `string`, possible values: `"report", "systematicReview"` — Which kind of session this is; use it to pick the matching typed get endpoint * **`url` (required)** `string` — URL to view this session in the Elicit web interface **Example:** ```json { "type": "report", "sessionId": "5ad08bfb-cbe0-4911-a8c3-309760d33029", "status": "processing", "executionStage": "screening_abstract", "url": "", "isPublic": true, "links": { "self": "https://elicit.com/api/v2/sessions/reports/5ad08bfb-cbe0-4911-a8c3-309760d33029", "resume": "https://elicit.com/api/v2/sessions/5ad08bfb-cbe0-4911-a8c3-309760d33029/resume" } } ```