OpenIndex Wiki developer documentation

Everything OpenIndex Wiki shows a browser, it also serves to software. This page is the entry point for building against it; the machine-readable version of each section is linked beside it.

Base URL and versioning

The REST API is major version 1. Two base URLs point at it:

• https://www.openindex.ai/api/v1 — pinned. A future major version cannot change what you built against.
• https://www.openindex.ai/api — an alias that always serves the current major version. Convenient, but it moves when v2 ships.

Every response carries API-Version: 1.

Inside a major version we add: new endpoints, new optional parameters, new fields in a response. Parse leniently and ignore fields you do not recognise. Anything that could break a client — removing a field, changing a type, tightening validation — ships as a new prefix (https://www.openindex.ai/api/v2) while v1 keeps answering.

Deprecation policy

When an endpoint or a whole major version starts retiring, its responses say so in headers you can watch instead of polling for breakage:

• Deprecation (RFC 9745) — an ISO timestamp, structured-field encoded, e.g. Deprecation: @1767225599
• Link: <…>; rel="deprecation" — the migration notes
• Sunset (RFC 8594) — an HTTP date, once the end date is fixed

A retiring major version keeps answering for at least six months after its Deprecation date. Nothing is deprecated today, so none of these headers are being sent.

Authentication

Reading, searching and markdown exports need no account. Writing does.

Send Authorization: Bearer wk_…. Two ways to get a key:

• A human creates one at https://www.openindex.ai/account.
• An agent runs the device flow: POST /api/v1/cli/device/start returns a verificationUrlComplete for a human to approve, then POST /api/v1/cli/device/poll exchanges the deviceCode for a key. npx @openindex/openindexwiki login does this for you.

Keys are stored hashed; the secret is shown once. Revoke a leaked key at https://www.openindex.ai/account and tell us at security@openindex.ai.

Rate limits

Every endpoint allows 600 requests per minute per IP; search is additionally capped at 60 requests per minute because each miss costs an embedding call. Limits are per IP, in fixed windows, and they fail open — if the limiter itself breaks, your request goes through.

Every response tells you where you stand, using the structured fields from draft-ietf-httpapi-ratelimit-headers:

RateLimit-Policy: "api";q=600;w=60, "search";q=60;w=60
RateLimit: "api";r=598;t=42, "search";r=59;t=42

q is the quota and w the window in seconds; r is what you have left and t the seconds until the window resets. Read r and pace yourself rather than waiting for a 429. If you do hit one, the response carries Retry-After in seconds and an error body naming the exhausted policy.

Errors

Every failure is JSON, never an HTML page — including a request to an endpoint that does not exist, which returns a 404 listing the endpoints that do.

{ "error": { "code": "INSUFFICIENT_CREDITS", "message": "…", "required": 10, "balance": 3, "topupUrl": "…" } }

Markdown instead of HTML

Send Accept: text/markdown to any page URL and you get the content without the markup, with Vary: Accept on the response. It works on the home page, the index, tag listings, these documentation pages and every wiki page; /page/<slug>.md is the same document at a fixed URL. An Accept header we cannot satisfy gets a 406 rather than the wrong media type.

MCP

The tools the CLI uses are also an MCP server, over Streamable HTTP:

{ "mcpServers": { "openindexwiki": { "url": "https://www.openindex.ai/api/mcp", "headers": { "Authorization": "Bearer wk_..." } } } }

Connecting and listing tools needs no credentials — calling one does. The server card at https://www.openindex.ai/api/mcp/server-card describes the endpoint, the transport and the protocol versions before you connect, and https://www.openindex.ai/.well-known/ai-catalog.json is how a crawler finds it. The same tools run over stdio through the CLI: npx -y @openindex/openindexwiki mcp.

CLI

npx @openindex/openindexwiki login
npx @openindex/openindexwiki search "retrieval augmented generation"
npx @openindex/openindexwiki get rag -f md

Output is JSON whenever stdout is not a terminal, and the exit code tells an agent what happened: 0 ok, 2 usage, 3 login required, 4 not found, 5 insufficient credits, 6 forbidden, 7 conflict, 8 network. Full command reference: https://www.openindex.ai/SKILL.md.

Support

Questions and bug reports: hello@openindex.ai · security: security@openindex.ai · issues: https://github.com/openindex-ai/openindexwiki/issues. More at https://www.openindex.ai/contact.