---
title: "smry Public Reader OpenAPI"
description: "Human-readable guide to the canonical OpenAPI 3.1 contract."
canonical: "https://r.smry.ai/openapi.json"
last-updated: "2026-08-29"
---

# smry Public Reader OpenAPI

The canonical OpenAPI 3.1 document is https://r.smry.ai/openapi.json.

## Operations

- GET /api/v1/read?url=<public-url> returns clean text by default.
- POST /api/v1/read accepts a typed JSON body plus a required Idempotency-Key.
- POST /api/v1/read/batch accepts 1-10 typed read operations and returns every
  per-source result in one JSON response.
- POST /api/v1/read/jobs returns 202 Accepted plus Location and a job_id; poll
  GET /api/v1/read/jobs/{jobId}, then follow result_url when state is complete.
- Send Accept: application/json for typed metadata and paragraph blocks.
- Add limit=1..100 to page large JSON documents; follow next_cursor with the
  same limit until has_more is false.
- HEAD /api/v1/read?url=<public-url> returns source metadata without a body.
- OPTIONS advertises the permitted reader methods and custom headers.

## Errors and recovery

JSON clients receive RFC 9457-style application/problem+json documents with a
stable code, a human-readable detail, a concrete resolution, and a retryable
flag. A 429 includes Retry-After and current RateLimit metadata.

## Stability

Version 1 is backward compatible. New optional response fields may be added.
Any breaking contract will use a new major API path and the old path will carry
Deprecation, Sunset, and migration Link headers before removal. See
https://r.smry.ai/api/versioning.md.