Documentation API

The documentation API is public and requires no key, cookie, or organization. Use https://docs.periplus.dev as the origin. Responses include API version: "1" and a content revision, which changes when the documentation changes. The app and MCP use this same API.

Search sections

curl 'https://docs.periplus.dev/api/v1/search?q=pin%20expiry&limit=5'

q is required and accepts 1–200 characters. limit defaults to 5 and accepts integers from 1 to 10. audience=all leaves out guides whose audience is people before the limit applies. Search matches all normalized query terms across an article's title, summary, and section text, including code. It is lexical search; it does not use embeddings.

The response contains query, total, and items. Each item includes topic, title, section, section_title, url, excerpt, markdown, and score. The URL opens the exact section on this site. Markdown contains the complete matched section, bounded to 16,000 characters. Scores are ranking hints, not confidence estimates. No matches returns an empty list and a hint to retry with fewer or different keywords.

Browse and read

curl 'https://docs.periplus.dev/api/v1/docs'
curl 'https://docs.periplus.dev/api/v1/docs/pins'
curl 'https://docs.periplus.dev/api/v1/docs/pins?section=duration'

The catalogue returns items with topic, title, summary, group, audience, and url. audience is people for guides an MCP agent cannot act on (accounts, administration and the REST reference), otherwise all; audience=all lists only the all guides, as in search. An article adds markdown and sections, with stable IDs, titles, URLs, and Markdown. A section containing a top-level SQL code block also exposes its first example as sql for the app's explicit, non-executing editor handoff. section restricts the response to one section. Full articles are bounded to 120,000 characters.

Unknown topics or sections return 404. Invalid search input, and section on the catalogue (it needs a topic), return 400. Errors use a JSON detail field. Content is scoped to the published article catalogue; file paths and repository runbooks are unavailable.

Browser and agent clients

Public GET responses allow cross-origin reads without credentials. Successful responses may be cached for 60 seconds in browsers and 300 seconds by shared caches. Compare revision when combining responses from different caches. Documentation changes are published through a new docs build.

In MCP, use docs_search(query, limit) and docs_read(topic, section) (omit topic to list the guides). Those tools retain MCP authentication and auditing, but their documentation requests carry no customer credentials. They return a retryable error when the docs service is unavailable. Use schema_get for the live query catalogue and signatures.