Rivul Atlas REST API Reference
The Rivul Atlas REST API is the paper search Rivul MCP uses, over plain HTTPS: free for every account, read-only, and described by OpenAPI 3.1.
On this page
Endpoints
Every endpoint is on https://rivul.ai. Search and usage need an API key; the OpenAPI document does not.
| Method and path | Purpose | Key scope |
|---|---|---|
| POST /api/atlas/v1/search | Search papers in the Rivul Index | search:read |
| GET /api/atlas/v1/usage | Today's API usage and recent requests; never counts toward usage | usage:read (or search:read) |
| GET /api/atlas/openapi.json | The OpenAPI 3.1 description of this API | None |
Authenticate
- Step 1: Open Rivul MCP, under Agents, then Access keys, and click Create key for an API key. The full key is shown once; copy it into a private environment variable such as RIVUL_ATLAS_KEY.
- Step 2: Send it on every request as Authorization: Bearer followed by the key. Keys start with rv_atlas_.
The REST API accepts API keys only. An MCP key, meant for AI clients, is refused with 403. A workspace holds one active API key at a time; revoke it to create another.
Search papers
Send a JSON body. Only query is required; unknown fields are rejected.
curl https://rivul.ai/api/atlas/v1/search \
--header "Authorization: Bearer $RIVUL_ATLAS_KEY" \
--header 'Content-Type: application/json' \
--data '{"query":"sodium ion batteries","limit":10}'Request fields
| Field | Type | Accepted values | Default |
|---|---|---|---|
| query | string | Required. 1 to 500 characters | — |
| limit | integer | 1 to 50 | 10 |
| offset | integer | 0 to 1,000 | 0 |
| sort | string | relevance, most_cited, newest, oldest | relevance |
| year_min, year_max | integer | 1000 to 9999; year_min at most year_max | — |
| min_citations | integer | 0 or greater | — |
| open_access_only | boolean | true or false | — |
| topic, field | string | 1 to 200 characters | — |
Response
A search returns { object: "list", data, meta }. Each item in data is one work with openalex_id, title, authors and is_oa, and, when the record has them, publication_year, publication_date, doi, venue, work_type, snippet, cited_by_count, topic, field, oa_url and landing_url.
meta reports total_matches, offset, page_size, has_more and next_offset for paging, snapshot_at for the date of the index snapshot, and request_id for support. To read the next page, send the same request with offset set to next_offset while has_more is true.
Author lists and snippets are shortened, and nothing in the response says so: confirm authors against the DOI or landing page before you cite a record.
Check usage
GET /api/atlas/v1/usage returns the UTC day, used, limit and remaining for the API, and up to 25 recent requests. limit and remaining are null unless an operator cap is set. Search responses also carry an X-Rivul-Api-Calls-Used header.
curl https://rivul.ai/api/atlas/v1/usage \
--header "Authorization: Bearer $RIVUL_ATLAS_KEY"Errors
Errors are application/problem+json (RFC 9457) with status, code, detail and request_id. Quote the request_id when you report a problem.
| Status | code | What to do |
|---|---|---|
| 400 | validation | Fix the fields listed in details.fields. |
| 401 | unauthorized | The key is missing, mistyped or revoked. Create a new API key. |
| 403 | forbidden | The key cannot use this product or scope, for example an MCP key on the REST API. |
| 413 | validation | The body is over 16 KiB. |
| 415 | validation | Send Content-Type: application/json. |
| 429 | rate_limit | A fair-use window was reached. Wait for Retry-After, then retry. |
| 429 | quota | An operator daily cap was reached. It resets at 00:00 UTC. |
| 502, 503, 504 | unavailable, timeout | Retry shortly with backoff. |
OpenAPI document
https://rivul.ai/api/atlas/openapi.json describes every endpoint, field and error. Import it into an API client or a code generator. It needs no key.
Something here wrong or missing? Use the contact form.