{ "openapi": "3.1.0", "info": { "title": "Elide Docs API", "version": "1.0.0", "summary": "Search and read the Elide documentation as Markdown.", "description": "Read-only access to the Elide documentation at elide.help: list pages, fetch any page as Markdown, run ranked full-text search, and check the status of a report sent through the MCP server's submit_report tool. No authentication. Responses allow any origin (CORS `*`). Errors use RFC 9457 `application/problem+json` with a stable `code` and a `resolution` hint.\n\nRate limit: 120 requests per 60 seconds per client IP, advertised in the `RateLimit-Policy` header; over the limit, the API returns 429 with `Retry-After`.\n\nVersioning: The version is in the path (/api/v1). Changes within v1 only add fields and operations. A breaking change ships as /api/v2; v1 then sends Deprecation and Sunset headers (RFC 9745, RFC 8594) for at least 180 days before it is removed.", "contact": { "name": "Elide support", "url": "https://github.com/elide-dev/elide/issues" }, "license": { "name": "Apache 2.0", "identifier": "Apache-2.0" }, "x-api-lifecycle": { "status": "stable", "versioning": "url-path", "deprecationHeaders": [ "Deprecation", "Sunset" ], "sunsetNoticeDays": 180, "policy": "https://elide.help/developers#versioning" } }, "externalDocs": { "description": "Elide developer surfaces: API, MCP server, llms.txt", "url": "https://elide.help/developers" }, "servers": [ { "url": "https://elide.help", "description": "Elide documentation" } ], "tags": [ { "name": "Pages", "description": "Documentation pages and their Markdown." }, { "name": "Search", "description": "Full-text search over the documentation." }, { "name": "Reports", "description": "Status of bug, performance, expectation and feature reports sent by coding agents." } ], "security": [], "paths": { "/api/v1": { "get": { "operationId": "getApiIndex", "tags": [ "Pages" ], "summary": "Describe the API", "description": "Returns the API version and status, every operation with its URL template, the rate limit and the versioning policy. `/api` returns the same document.", "responses": { "200": { "description": "The API index.", "headers": { "Link": { "$ref": "#/components/headers/Link" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIndex" } } } }, "405": { "description": "The method is not GET or HEAD. The `Allow` header lists the supported methods.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The client exceeded the rate limit. Retry after the number of seconds in `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "RateLimit": { "description": "Remaining quota (`r`) and seconds until reset (`t`).", "schema": { "type": "string" } } } } } } }, "/api/v1/pages": { "get": { "operationId": "listPages", "tags": [ "Pages" ], "summary": "List documentation pages", "description": "Returns every documentation page in navigation order with its slug, HTML and Markdown URLs, title, description and section. Use the slug with getPage to fetch a page's Markdown.", "parameters": [ { "name": "section", "in": "query", "required": false, "description": "Only return pages from this top-level section, by id (for example `toolchain` or `api`). The ids are listed in the `sections` field of the response.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "responses": { "200": { "description": "All matching pages.", "headers": { "Link": { "$ref": "#/components/headers/Link" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageList" } } } }, "400": { "description": "The section is not a known section id.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "The method is not GET or HEAD. The `Allow` header lists the supported methods.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The client exceeded the rate limit. Retry after the number of seconds in `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "RateLimit": { "description": "Remaining quota (`r`) and seconds until reset (`t`).", "schema": { "type": "string" } } } } } } }, "/api/v1/pages/{slug}": { "get": { "operationId": "getPage", "tags": [ "Pages" ], "summary": "Get a page as Markdown", "description": "Returns one documentation page: its metadata, its section headings and its full Markdown body. Slugs come from listPages or searchDocs.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Canonical page slug, for example `installation` or `tooling-jvm-maven`.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" } } ], "responses": { "200": { "description": "The page and its Markdown.", "headers": { "Link": { "$ref": "#/components/headers/Link" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page" } } } }, "404": { "description": "No page has this slug.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "The method is not GET or HEAD. The `Allow` header lists the supported methods.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The client exceeded the rate limit. Retry after the number of seconds in `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "RateLimit": { "description": "Remaining quota (`r`) and seconds until reset (`t`).", "schema": { "type": "string" } } } } } } }, "/api/v1/search": { "get": { "operationId": "searchDocs", "tags": [ "Search" ], "summary": "Search the documentation", "description": "Ranked full-text search over pages and their sections, code samples, release notes and documented gaps, weighting titles over headings, descriptions and bodies. Each result carries a snippet, the matching heading and anchor, and a 0–1 score; fetch the full page with getPage.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search terms, for example `kotlin compiler flags`.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } } ], "responses": { "200": { "description": "Results, best match first.", "headers": { "Link": { "$ref": "#/components/headers/Link" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResults" } } } }, "400": { "description": "q is missing or too long, or limit is out of range.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "The method is not GET or HEAD. The `Allow` header lists the supported methods.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The client exceeded the rate limit. Retry after the number of seconds in `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "RateLimit": { "description": "Remaining quota (`r`) and seconds until reset (`t`).", "schema": { "type": "string" } } } } } } }, "/api/v1/reports/{id}": { "get": { "operationId": "getReportStatus", "tags": [ "Reports" ], "summary": "Get a report's status", "description": "Returns the status of a report sent with the MCP server's submit_report tool: queued, filed (with the public issue URL), duplicate, declined or needs_human. Not cached.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The report_id returned by submit_report.", "schema": { "type": "string", "pattern": "^r_[a-z2-7]{16}$" } } ], "responses": { "200": { "description": "The report's status.", "headers": { "Link": { "$ref": "#/components/headers/Link" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportStatus" } } } }, "404": { "description": "No report has this id.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "The method is not GET or HEAD. The `Allow` header lists the supported methods.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The client exceeded the rate limit. Retry after the number of seconds in `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "RateLimit": { "description": "Remaining quota (`r`) and seconds until reset (`t`).", "schema": { "type": "string" } } } } } } } }, "components": { "headers": { "Link": { "description": "Links to this OpenAPI description, the developer docs and the API catalog.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "The rate limit: quota `q` requests per window `w` seconds, per client IP.", "schema": { "type": "string", "example": "\"docs\";q=120;w=60" } }, "Deprecation": { "description": "RFC 9745. Sent once this API version is deprecated: the date it was deprecated, as a structured-field date (`@`). Absent while the version is current.", "schema": { "type": "string", "example": "@1798761600" } }, "Sunset": { "description": "RFC 8594. Sent with `Deprecation`: the HTTP date after which this version may stop responding, at least 180 days later.", "schema": { "type": "string", "example": "Thu, 01 Jul 2027 00:00:00 GMT" } } }, "schemas": { "ApiIndex": { "type": "object", "required": [ "name", "version", "status", "openapi", "operations" ], "properties": { "name": { "type": "string" }, "version": { "type": "string", "description": "Path version, `v1`." }, "status": { "type": "string", "enum": [ "stable", "deprecated" ] }, "documentation": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "operations": { "type": "array", "items": { "type": "object", "required": [ "operationId", "method", "href" ], "properties": { "operationId": { "type": "string" }, "method": { "type": "string" }, "href": { "type": "string", "description": "URL template (RFC 6570)." } } } }, "rateLimit": { "type": "object", "properties": { "quota": { "type": "integer" }, "windowSeconds": { "type": "integer" }, "scope": { "type": "string" } } }, "versioning": { "type": "string" } } }, "Section": { "type": "object", "required": [ "id", "title" ], "properties": { "id": { "type": "string", "description": "Section id, used by the section filter." }, "title": { "type": "string" } } }, "PageSummary": { "type": "object", "required": [ "slug", "path", "url", "markdownUrl", "title", "description", "section", "sectionTitle", "group" ], "properties": { "slug": { "type": "string", "description": "Canonical page slug." }, "path": { "type": "string", "description": "Site path of the HTML page." }, "url": { "type": "string", "format": "uri", "description": "HTML page URL." }, "markdownUrl": { "type": "string", "format": "uri", "description": "The same page as `text/markdown`." }, "title": { "type": "string" }, "description": { "type": "string" }, "section": { "type": "string", "description": "Top-level section id." }, "sectionTitle": { "type": "string" }, "group": { "type": "string", "description": "Group within the section." } } }, "PageList": { "type": "object", "required": [ "count", "sections", "pages" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/Section" } }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/PageSummary" } } } }, "Page": { "allOf": [ { "$ref": "#/components/schemas/PageSummary" }, { "type": "object", "required": [ "headings", "markdown" ], "properties": { "headings": { "type": "array", "items": { "type": "string" }, "description": "Section headings (levels 2–4) in document order." }, "markdown": { "type": "string", "description": "The page as Markdown, starting with its title." } } } ] }, "SearchResult": { "allOf": [ { "$ref": "#/components/schemas/PageSummary" }, { "type": "object", "required": [ "score", "snippet" ], "properties": { "score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Relevance from 0 to 1; higher is better." }, "kind": { "type": "string", "enum": [ "page", "section", "sample", "release", "gap" ], "description": "What matched: a whole page, a section, a code sample, a release or a documented gap." }, "heading": { "type": "string", "description": "Best-matching heading." }, "anchor": { "type": "string", "description": "Fragment id of the heading on the page." }, "since": { "type": "string", "description": "Release version, for release results." }, "gap": { "type": "object", "description": "For gap results: what Elide does not do.", "properties": { "statement": { "type": "string" }, "source_url": { "type": "string", "format": "uri" } } }, "snippet": { "type": "string", "description": "Text around the first match." } } } ] }, "SearchResults": { "type": "object", "required": [ "query", "count", "results" ], "properties": { "query": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } } } }, "ReportStatus": { "type": "object", "required": [ "report_id", "status", "updated_at" ], "properties": { "report_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "filed", "duplicate", "declined", "needs_human" ] }, "issue_url": { "type": "string", "format": "uri", "description": "The public issue in elide-dev/elide, once filed." }, "benchmark_pr": { "type": "string", "format": "uri", "description": "A pull request adding a benchmark for the report." }, "updated_at": { "type": "string", "format": "date-time" }, "dry_run": { "type": "boolean", "description": "Present on test deployments, which never file reports." } } }, "Problem": { "type": "object", "description": "RFC 9457 problem details.", "required": [ "type", "title", "status", "detail", "instance", "code", "resolution" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string" }, "instance": { "type": "string", "format": "uri" }, "code": { "type": "string", "enum": [ "invalid_parameter", "page_not_found", "report_not_found", "api_route_not_found", "method_not_allowed", "rate_limited" ] }, "resolution": { "type": "string", "description": "What to change to make the request succeed." }, "documentation_url": { "type": "string", "format": "uri" } } } } } }