---
title: "smry Public Reader sandbox and testing"
description: "Deterministic Reader API sandbox, safety guarantees, and production migration."
canonical: "https://r.smry.ai/docs/testing"
last-updated: "2026-08-29"
---

# smry Public Reader sandbox and testing

The Public Reader provides a deterministic, read-only sandbox at
https://r.smry.ai/api/v1/sandbox/read. It lets agents, generated clients, CI
jobs, and developers verify the production JSON contract without fetching an
external source, consuming extraction capacity, changing account data, or
holding a credential.

## Sandbox endpoint

- URL: https://r.smry.ai/api/v1/sandbox/read
- Methods: GET, HEAD, OPTIONS
- Authentication: none
- Price: $0
- External network work: none
- Production data reads or writes: none
- Response marker: `X-Smry-Sandbox: true`
- Schema: `ArticleDocument` in https://r.smry.ai/openapi.json

## Try the sandbox

```bash
curl --fail --silent --show-error \
  --header "Accept: application/json" \
  https://r.smry.ai/api/v1/sandbox/read
```

The response is stable across calls. It contains the same source URL, title,
author, publisher, language, two typed blocks, token totals, pagination fields,
and `sandbox: true` marker every time. No URL parameter is accepted, so an
untrusted or private address cannot escape the fixture.

## Browser and generated-client testing

Browser clients may preflight the endpoint with OPTIONS. Successful, HEAD,
preflight, and method-error responses carry CORS headers. The
`X-Smry-Sandbox` response header is exposed to browser JavaScript. The GET
response conforms to the same OpenAPI `ArticleDocument` schema as a live JSON
read, including `total_blocks`, `total_tokens`, `has_more`,
`next_cursor`, and typed `anchor`, `kind`, `tokens`, and `text`
fields on every block.

## Safety guarantees

- The fixture is compiled into the Worker and does not call an extractor.
- The endpoint never reads or mutates a smry account, library, feed, or file.
- Credentials are neither required nor accepted for sandbox behavior.
- GET and HEAD are the only data methods; every write method returns 405.
- A 405 is an RFC 9457-style `application/problem+json` response.
- Cache entries contain only the public deterministic fixture.
- The endpoint is suitable for automated tests and repeated dry runs.

## Move to a live public read

After a client parses the sandbox response and handles structured errors,
switch the request URL to https://r.smry.ai/api/v1/read and add an exact public
HTTP or HTTPS source in the `url` query parameter. Keep
`Accept: application/json` to receive the same `ArticleDocument` schema.
Live reads may fetch public source material and are therefore subject to the
published 5-per-10-second burst and 60-per-minute sustained policies. Do not
send private URLs, cookies, authorization headers, or publisher credentials.

## Production migration checklist

1. Confirm the sandbox response header is `X-Smry-Sandbox: true`.
2. Validate the response against `ArticleDocument` from the OpenAPI document.
3. Handle 405 and other problem documents by their stable `code` field.
4. Change only the endpoint and add the exact public `url` parameter.
5. Respect `RateLimit` and `Retry-After` response headers on live reads.
6. Attribute extracted material to the returned `source_url`.
7. Never use the live endpoint to bypass a paywall or private access control.