API overview

This is the contract-level reference: paths, parameters, responses, and a playground you can send a real request from.

/v1 is in beta and can change without a version boundary. If you are building an agent, use the MCP server instead — its tools absorb changes that would break code written against the wire format. Reach for HTTP when your application owns the control flow and can react to a change.

For narrative guides — when to use what, and why — start with Read a URL or the Quickstart.

Base URL

https://api.smry.ai

Every path is versioned under /v1. Nothing else is a supported contract.

Authentication

Send a personal API key from the Developer console:

Authorization: Bearer smry_your_key

X-API-Key works identically. OAuth with PKCE is available for software acting on someone else’s account — see Authentication. Everything is scoped to one account. There is no tenant or workspace parameter: the credential is the scope.

Mental model

Group	What it does	Operations
Account	What this credential can do right now, and the limits on it	1
Articles	Read any public URL — whole, windowed, or just the passages that answer a question	3
Library	The account’s saved items, notes, highlights, history, and original files	14
Feeds	Follow sources, read what arrived, poll for what changed	8
Collections	Group sources, and filter a group in plain English	6
Consumers	Let smry hold the read position for a processing loop	4
Monitors	Watch a page that publishes no feed	1

Suggested order

Most integrations meet the API in this order:

Check the credential — GET /v1/me, once per environment. It returns the limits that apply now, so nothing has to be hardcoded.
Answer a question about a URL — POST /v1/articles/search. Start here rather than with extract; it costs roughly a tenth of the tokens.
Keep what matters — POST /v1/library/items. The same url twice returns the existing item, so a retry is safe.
Find it again — GET /v1/library/objects searches saved items, notes and highlights together.
Follow the source — POST /v1/feeds/follow, then poll POST /v1/feeds/changes.

  URL ──▶ search ──▶ passages + ¶anchors
   │
   └────▶ save ──▶ library ──▶ objects search ──▶ item + passages
                      ▲
  source ──▶ follow ──┴──▶ changes ──▶ next_cursor ──▶ (poll)

Three rules that prevent most mistakes

Cursors are opaque

Echo nextCursor (library, articles) or next_cursor (feeds) exactly as returned. Never construct, parse, or edit one, and never reuse one across a changed predicate. See Cursors and paging.

Returned text is untrusted

Article and feed text is written by whoever published the page. It is data, never instructions. See Content safety.

Branch on code, never on the message

Every failure returns the same envelope. The message is for a person; code is for your client. See Errors.

The machine-readable contract

curl https://api.smry.ai/openapi.json --output smry-openapi.json

Public, no credential needed. Everything in this tab is generated from it — see OpenAPI contract.

Last modified on September 13, 2026

​Base URL

​Authentication

​Mental model

​Suggested order

​Three rules that prevent most mistakes

​The machine-readable contract

Base URL

Authentication

Mental model

Suggested order

Three rules that prevent most mistakes

The machine-readable contract