Lune Research API service contract

The REST API is not a supported public integration path. Install Lune through its connector or plugin in a web chatbot, or add the MCP server to a local agent. Do not send research requests to api.luneresearch.com directly.

Lune publishes this contract so operators can inspect the service used by the official MCP server, CLI, and dashboard. It also records versioning, deprecation, error, and rate-limit behavior in one stable place.

• Web chatbot connectors and plugins

• Local agents and MCP setup

• MCP server manifest

• Interactive reference

• OpenAPI 3.1 JSON

• Authentication guide

• Exact scope reference

Version contract

The major REST version is part of the URL. Backward-compatible additions stay within the current major version. These include new optional response fields, new endpoints, and new optional request parameters whose omission preserves the previous behavior. A change that removes or renames a field, changes its meaning or type, makes an optional input required, or alters existing status semantics requires a new major path such as /api/v2.

Lune will announce a planned breaking retirement at least 180 days before the sunset date. While an endpoint is deprecated, its responses will include all of the following signals:

Deprecation: @1782863999
Sunset: Wed, 30 Dec 2026 23:59:59 GMT
Link: <https://luneresearch.com/docs/api>; rel="deprecation"

Deprecation follows RFC 9745 and uses a Structured Fields date. Sunset follows RFC 8594 and uses an HTTP date. The sunset date will never precede the deprecation date. The linked policy will name the replacement and migration steps. Lune API v1 is not deprecated, so current v1 responses do not carry either date header.

Rate-limit fields

The short burst guard is scoped by organization or client IP. A request whose guard records live state publishes the current IETF HTTPAPI field format:

RateLimit-Policy: "burst";q=30;w=1
RateLimit: "burst";r=29;t=1

q is the policy quota, w is its window in seconds, r is the available quota after the current request, and t is the effective window remaining in seconds. Publicly cacheable responses publish the static policy only, so a shared cache cannot replay one visitor's remaining capacity to another. A guard that fails open because its counter is unavailable also publishes policy only. Every throttled 429 publishes zero remaining capacity and a retry delay.

A throttled response is 429 Too Many Requests and includes both a zero remaining value and Retry-After:

RateLimit: "burst";r=0;t=1
Retry-After: 1

The daily plan allowance is separate from the one-second burst guard. Read it from /api/v1/account/whoami. If a billable call exceeds both its daily allowance and prepaid credits, the API returns 402 Payment Required with a typed body that tells the caller whether to stop, retry a smaller batch, or retry once because capacity returned. A 402 deliberately has no Retry-After header.

Errors

Use HTTP status first, then the machine field in the JSON body. Authentication failures return 401. A scope failure returns 403 with required and granted lists. Quota exhaustion returns 402. Burst throttling returns 429. Validation failures return 422 with typed field locations. OAuth token endpoint errors use the flat RFC 6749 error and error_description shape.

Client identity

Lune's published MCP server and CLI send X-Lune-Client so usage logs can distinguish an official client without reading tool inputs or response bodies. This header is operational metadata, not an invitation to build a direct REST client.