MESSAI.iO

Developers · REST API

Script against the MESSAI corpus

The versioned API, /api/v1, is the stable way in: search and browse the 23,596-paper corpus, fetch a paper, list the parameter catalog, with an API key for a daily quota of your own. The five endpoints that run the website — prediction, full search, paper records, Bayesian priors and the chat — are documented below as well, without that stability promise. Corpus figures as of August 2026.

Versioned API: /api/v1

Every v1 endpoint works without a key, on the per-minute budget of your IP address. With a key, calls draw on your account's own daily quota instead.

1. Get a key

Sign in, open your profile and create a key under API keys. The full key is shown once, when you create it: copy it then. MESSAI stores only a hash, so a lost key cannot be recovered, only replaced. Revoke a key on the same page at any time.

Open your profile

2. Send it with every call

In the X-API-Key header, or as Authorization: Bearer. A revoked, expired or mistyped key gets 401; it never falls back to anonymous access.

X-API-Key: sk_free_…
Authorization: Bearer sk_free_…

3. Watch the limits

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the next request is available). Over the limit, the API answers 429 with Retry-After.

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 86

Limits

Caller Budget Counted per
API key 1,000 requests a day, refilled continuously (one every 86.4 s) Account: all of its keys share one quota
No key 60 requests a minute, in bursts of up to 120 IP address
Signed in on www.messai.io 300 requests a minute, in bursts of up to 600 Account

A read counts as one request. On the website endpoints heavier calls count more: POST /api/ml/predict 10, POST /api/chat 25, any other write 2. API keys apply to /api/v1 only.

Managing keys (GET and POST /api/v1/api-keys, DELETE /api/v1/api-keys/{id}) takes a signed-in session, not an API key: these are the calls your profile page makes.

GET /api/v1/papers

Search and browse papers

Search the corpus by text, or browse it, filtered by system type and publication year. Returns one page of papers with title, authors, year, journal, DOI, system type, paper type and citation count.

Parameters

Query params:
  q           string   Free-text query. Omit to browse the corpus.
  systemType  string   One of the 17 primary system types (MFC, MEC, MES, MDC, …), case-insensitive. Papers the classifier has not labelled never match.
  yearStart   integer  Earliest publication year, inclusive.
  yearEnd     integer  Latest publication year, inclusive.
  sort        string   relevance (best match first with q), date (newest first) or citations. Default relevance.
  page        integer  From 1. Default 1.
  limit       integer  1–100. Default 20.

Example

curl -H 'X-API-Key: sk_free_…' \
  'https://www.messai.io/api/v1/papers?q=biochar+anode&systemType=MFC&yearStart=2020&limit=5' \
  | jq '.data.papers[] | {id, title, year, citationCount}'

Notes

  • Answers `{ papers, pagination: { page, limit, total, pages }, searchType }`. With `q`, each paper carries a `relevanceScore`.
  • Only papers that pass the corpus visibility rules are listed, so every id here opens with GET /api/v1/papers/{id}.
  • `systemType` is the 17-type taxonomy class, or null when the classifier has not labelled the paper.
  • `degraded: true` means the embedding service was down and the results are keyword-ranked only.
GET /api/v1/papers/{id}

One paper

One paper by id: the list fields plus abstract identifiers (PubMed, arXiv), keywords, application domains and the machine-generated summary.

Parameters

Path params:
  id  string  Paper id, as returned by GET /api/v1/papers.

Example

curl -H 'X-API-Key: sk_free_…' 'https://www.messai.io/api/v1/papers/<id>' \
  | jq '.data | {title, year, doi, systemType, aiSummary}'

Notes

  • A paper hidden by the visibility rules, or archived, answers 404 `not_found`.
  • An id that names a merged duplicate returns the surviving paper, with `redirectedFrom` set to the id you asked for.
  • `aiSummary` is machine-generated from the abstract, not the authors' words.
GET /api/v1/parameters

The parameter catalog

The parameters MESSAI extracts from papers: name, canonical slug, unit, category and description.

Parameters

Query params:
  q         string   Matches the slug, name or description.
  category  string   One of the 18 categories (PERFORMANCE, MATERIALS, …), case-insensitive.
  page      integer  From 1. Default 1.
  limit     integer  1–100. Default 50.

Example

curl -H 'X-API-Key: sk_free_…' \
  'https://www.messai.io/api/v1/parameters?q=coulombic+efficiency' \
  | jq '.data.parameters[] | {slug, name, unit, category}'

Notes

  • Answers `{ parameters, pagination: { page, limit, total, pages } }`.
  • `slug` is null on definitions not yet curated; the slug is what the prior endpoint takes.

Responses and errors

Every v1 response is JSON in one envelope. Branch on error.code; error.message is written for people and may change.

Success

{
  "data": { "papers": [ … ], "pagination": { … } },
  "error": null
}

Failure

{
  "data": null,
  "error": {
    "code": "rate_limited",
    "message": "Rate limit reached (apiKey tier). Retry in 86 s."
  }
}
error.code HTTP Meaning
invalid_request 400 A parameter is missing, malformed or unknown; error.details lists the issues.
unauthorized 401 Key management only: no signed-in session.
invalid_api_key 401 The key is not one MESSAI issued.
api_key_revoked 401 The key was revoked on its owner’s profile page.
api_key_expired 401 The key is past the expiry chosen when it was created.
not_found 404 No visible paper with this id (on key management: no key of yours).
key_limit_reached 409 Key management only: the account already has the most active keys allowed; revoke one first.
rate_limited 429 The budget is spent; retry after Retry-After seconds.
internal_error 500 Something failed on our side; retry shortly.
api_keys_unavailable 503 API keys are not enabled on this deployment yet; call without a key.
rate_limiter_unavailable 503 Usage metering is briefly unavailable; retry shortly.
upstream_unavailable 503 The key could not be checked; retry shortly.

Stability promise

  • Within v1, changes are additive only: new endpoints, new optional parameters, new response fields. Ignore fields you do not know.
  • Removing or renaming a field or parameter, or changing what it means, ships as /api/v2. v1 keeps answering for at least six months after v2 is announced on this page.
  • Unknown query parameters are rejected with 400, so a typo never widens a query silently.
  • Machine-readable: /api/openapi.json (OpenAPI 3.1), generated from the handlers’ own validation.

Website endpoints (unversioned)

These five run the MESSAI website and change with it; there is no stability promise. They take no API key: calls are metered per IP address, or per account for a signed-in browser session.

POST /api/ml/predict

Predict performance

Returns power density, current density, coulombic efficiency, voltage, and a multi-block enrichment response for a reactor configuration. MFC routes through the full v1 enrichment; MEC/MES/MDC/MMRC/MBES/MNRC route through their dedicated per-class predictor.

Request body 

{
  "systemType": "MFC",
  "materials": {
    "anodeMaterial": "carbon-cloth",
    "cathodeMaterial": "platinum-carbon",
    "anodeSurfaceArea": 25,
    "cathodeSurfaceArea": 25
  },
  "conditions": {
    "temperature": 30,
    "ph": 7,
    "pressure": 1,
    "substrateConcentration": 1000,
    "externalResistance": 1000
  },
  "configuration": {
    "reactorVolume": 250,
    "electrodeSpacing": 2,
    "numChambers": 1
  }
}

Example

curl -X POST https://www.messai.io/api/ml/predict \
  -H 'Content-Type: application/json' \
  -d @request.json | jq '.powerOutput'

Notes

  • Every enrichment block reports its own `data_status`; missing artifacts surface honestly rather than zero-filling.
  • Hybrid mode opt-in via `?hybrid=true` query or `x-use-hybrid` header.
GET /api/papers/{id}

Single paper detail

Returns the stored ResearchPaper record by id, including authors, abstract, DOI, publication date and primarySystemType.

Parameters 

Path params:
  id  string  Paper id, as returned by search

Example

curl 'https://www.messai.io/api/papers/<id>' \
  | jq '.data | {title, authors, publicationDate, primarySystemType}'

Notes

  • Public; no auth required.
  • There is no public lookup by DOI: /api/papers takes ?search= and matches title, abstract, journal and system type, not DOI. To check a DOI by hand, paste it at /research/upload (a page, not an endpoint).
GET /api/parameters/{slug}/hierarchical-prior

Bayesian posterior for a parameter

Returns the v1 (PyMC NUTS) hierarchical posterior fit for a parameter's slug: pooled μ + 95% CI, per-system_type strata, MCMC diagnostics (R̂, ESS, divergences).

Parameters 

Path params:
  slug  string  Canonical parameter slug (e.g. "power_density_areal")

Example

curl 'https://www.messai.io/api/parameters/power_density_areal/hierarchical-prior' | jq '.pooled'

Notes

  • data_status: "populated" / "awaiting_artifact" / "parameter_not_in_priors" / "read_error" — branch on it.
  • Log-scale parameters return both fit-scale (mu_log, tau_log) and back-transformed (mu, ci95_low, ci95_high).
POST /api/chat

Citation-grounded chat

Stream LLM responses backed by ~50 corpus / ML tools. All factual claims must cite papers retrieved via tool calls.

Request body 

{
  "messages": [{"role": "user", "content": "What anode materials maximise power density for acetate substrates?"}],
  "mode": "general"
}

Example

curl -N -X POST https://www.messai.io/api/chat \
  -H 'Content-Type: application/json' \
  -d @messages.json

Notes

  • Streams as `text/event-stream` (the AI SDK UI message stream).
  • mode: "general" | "lab-design"
  • Larger models need a signed-in browser session.

Use MESSAI from Claude, Cursor or any MCP client

MESSAI is also a Model Context Protocol (MCP) server. Connect your AI assistant once and ask research questions in plain language; it queries the corpus, the priors and the predictor directly and cites its sources.

Server URL

https://www.messai.io/api/mcp

Use the www host: the bare messai.io domain answers MCP requests with a redirect, which some clients do not follow.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "messai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.messai.io/api/mcp"
      ]
    }
  }
}

Cursor and other clients with remote MCP support

{
  "mcpServers": {
    "messai": {
      "url": "https://www.messai.io/api/mcp"
    }
  }
}

15 read-only tools

Papers
search_papers · get_paper
Parameters
list_parameters · get_parameter_distribution · get_parameter_sources · get_prior · get_contradictions · get_parameter_relationships
Modelling
predict_performance · update_with_my_data · export_priors
Discovery
find_similar_studies · find_research_gaps
Reference data
lookup_microbes · lookup_materials
  • Also: three prompts (benchmark_my_reactor, review_parameter, find_research_direction) and parameter resources (messai://parameters, messai://parameter/{slug}).
  • Budget: 60 tool calls per minute per caller; predict_performance counts 10 and update_with_my_data 3. Over budget, a tool answers "retry in N s" instead of ending the session.
  • Numbers come with n, units and ranges. Predictions return insufficient_inputs rather than guessing a missing value.