Skip to main content
The contract is published at https://api.smry.ai/openapi.json. It is generated from the same TypeBox schemas that validate requests at runtime, so a parameter cannot be documented one way and enforced another. Everything in the API Reference tab — navigation, parameters, schemas, responses, the interactive playground, and the curl / Python / JavaScript examples — is generated from that document. No endpoint page is maintained by hand, which is what stops a copied parameter list from becoming a second, slowly-wrong source of truth.

​
Download it

Point a client generator at it, or hand it to an agent as the authoritative contract. It is public and needs no credential.

​
What the document guarantees

These hold on every deploy, and CI fails the build when one breaks:
  • OpenAPI 3.1, with https://api.smry.ai declared as the production server.
  • Only versioned /v1/* paths appear.
  • Every operation has a stable operationId, a summary, a description, a tag that is declared at the document level, and an explicit security requirement.
  • Every operation declares exactly one OAuth scope — smry:read or smry:write — alongside both personal-key schemes.
  • Every operation documents 401, 403, 429, and 503, plus whatever else it can actually return. An operation does not advertise a status it cannot produce.
  • Every failure response references #/components/schemas/Error. There is one error envelope, defined once.
  • Every response and every parameter carries a real description.
  • Every schema in components is referenced by at least one operation.
  • Article and feed text is described as untrusted source material at the contract boundary.

​
What it leaves out

/api/* is smry’s internal App API — the web app, the desktop app, and the browser extension. It is validated by shared source types and caller tests, not published here, and it changes without notice. Do not build on it. MCP publishes protocol-native tool schemas rather than a second OpenAPI document. See the MCP tool reference.

​
The HTTP API is in beta

/v1 is in beta. Breaking changes can land without a version boundary. A field can be renamed, a response shape can tighten, an operation can move between groups. The generated reference and this document always describe what is served right now — they are not a promise about next month. If you are building an agent, connect the MCP server instead. Its tools are shaped around what an agent needs and they absorb changes underneath: when an operation’s parameters move, the tool keeps working. The HTTP surface gives you no such layer — your code is coupled to the wire format. Use HTTP when your application owns the control flow and you can react to a change. Pin what you can, read the errors, and expect to revisit it. Additive changes — a new optional field, a new operation, a widened enum — are routine and land continuously.
Operation summaries are used to build reference page URLs, so an edited summary moves a page. Deep links into the API Reference are stable only for as long as the summary is. Link to operationId in prose when you need permanence.

​
Next

Errors

The envelope, the status codes, and every error code.

MCP tool reference

The same operations, shaped for agent context budgets.
Last modified on September 13, 2026