--- title: "smry public reader developer portal" description: "Typed HTTP, MCP, skill, limits, and recovery documentation." canonical: "https://r.smry.ai/developers.md" last-updated: "2026-08-29" --- # smry public reader developer portal r.smry.ai is a credential-free, read-only HTTP interface for extracting clean, source-grounded text from public URLs. Use the prefix URL for shell work or the typed `GET /api/v1/read?url=...` operation for OpenAPI clients. ## Quickstart ```bash curl -sS --get "https://r.smry.ai/api/v1/read" \ --data-urlencode "url=https://example.com/article" \ -H "Accept: application/json" ``` Use the idempotent JSON form when a long source URL or focused query is easier to send in a request body: ```bash curl -sS "https://r.smry.ai/api/v1/read" \ -X POST \ -H "Content-Type: application/json" \ -H "Idempotency-Key: read-example-1" \ --data '{"url":"https://example.com/article","query":"key findings"}' ``` The first completed response is retained for 24 hours. An identical retry with the same key replays that response without another extraction, rate-limit charge, or usage event. Reusing the key with a different body returns 409. For multi-source work, submit up to 10 typed reads in one real batch operation: ```bash curl -sS "https://r.smry.ai/api/v1/read/batch" \ -X POST \ -H "Content-Type: application/json" \ --data '{"requests":[{"url":"https://example.com/one"},{"url":"https://example.com/two","query":"key findings"}]}' ``` The response preserves input order and includes each operation's HTTP status, content type, and output. One unavailable source does not hide successful reads. For a source that may outlive one request, create a durable asynchronous job: ```bash curl -i -sS "https://r.smry.ai/api/v1/read/jobs" \ -X POST \ -H "Content-Type: application/json" \ --data '{"url":"https://example.com/long-report.pdf"}' ``` The server returns `202 Accepted`, a `Location` status URL, `Retry-After`, and a JSON `job_id`. Poll `GET /api/v1/read/jobs/{jobId}` until `state` is `complete` or `failed`. Completed jobs include the ordinary `result_url`. For large articles, add `limit=20` to the GET operation. The JSON response returns `has_more` and `next_cursor`; pass that cursor on the next request or follow the standard `Link: <...>; rel="next"` response header. Do not combine cursor pagination with relevance queries or an explicit line range. ## Official CLI Install the supported, read-only `smry` command from the public Homebrew tap: ```bash brew install mrmps/smry/smry smry --json --query "key findings" https://example.com/report.pdf ``` The CLI source, release history, formula, and checksums are public at [mrmps/homebrew-smry](https://github.com/mrmps/homebrew-smry). It requires no smry account or API key and calls the same `GET /api/v1/read` operation documented below. The versioned [release artifact](https://github.com/mrmps/homebrew-smry/releases/latest) and [Homebrew formula](https://github.com/mrmps/homebrew-smry/blob/main/Formula/smry.rb) are independently inspectable before installation. ## Official Go SDK Install the supported Go module for typed reads, batches, asynchronous jobs, polling, and RFC 9457 errors: ```bash go get github.com/mrmps/smry-go@v0.1.0 ``` The package reference is published at [pkg.go.dev](https://pkg.go.dev/github.com/mrmps/smry-go); source, tests, version tags, and the MIT license are at [mrmps/smry-go](https://github.com/mrmps/smry-go). The module uses only Go's standard library, defaults to https://r.smry.ai, and requires no API key. ## Machine interfaces - [OpenAPI 3.1](https://r.smry.ai/openapi.json) - [API catalog](https://r.smry.ai/.well-known/api-catalog) - [ARD catalog](https://r.smry.ai/.well-known/ard.json) - [Agent Skills index](https://r.smry.ai/.well-known/agent-skills/index.json) - [skills.sh listing](https://www.skills.sh/mrmps/homebrew-smry/smry) - [MCP server card](https://r.smry.ai/.well-known/mcp/server-card.json) - [Smithery MCP registry listing](https://smithery.ai/servers/miryaboy/smry-public-reader) - [Official MCP Registry listing](https://registry.modelcontextprotocol.io/?q=ai.smry.r%2Fsmry-product) - [Authentication guide](https://r.smry.ai/auth.md) - [Sandbox and testing guide](https://r.smry.ai/docs/testing) ## Safe sandbox Use `GET https://r.smry.ai/api/v1/sandbox/read` to exercise the Reader JSON contract without fetching an external source, consuming extraction capacity, or changing production data. The deterministic fixture returns the same heading, paragraph blocks, outline, and `X-Smry-Sandbox: true` marker on every request. It accepts only GET, HEAD, and OPTIONS, needs no credential, and is safe for CI, generated clients, onboarding, and agent dry runs. Switch to `GET /api/v1/read?url=...` only after the client handles the sandbox response. The dedicated [sandbox and testing guide](https://r.smry.ai/docs/testing) includes the complete request, response, safety, and production-migration contract. ## Authentication Public reader calls require no authentication. The optional MCP and Developer API on api.smry.ai access user-owned resources and therefore require an eligible paid plan plus either scoped OAuth or a personal key. OAuth is preferred for interactive agent clients; personal keys are created and revoked in smry's developer settings for local or unattended clients. Credentials must remain in a protected credential store and must never be committed. ## Stability and recovery The public reader is rate limited to 5 requests per 10 seconds and 60 requests per minute per IP. Responses advertise both active policies through `RateLimit-Policy`, the current quota through `RateLimit`, compatibility limit fields, and `Retry-After` on 429. JSON errors use `application/problem+json` with a stable `code`, human-readable `detail`, and concrete `resolution`. The OpenAPI contract uses a versioned document and unique operation IDs. New backward-compatible fields may be added. Any future breaking REST contract will use a new major path or document and will be announced with `Deprecation`, `Sunset`, and migration links before removal.