{
  "openapi": "3.1.0",
  "info": {
    "title": "smry Public Reader API",
    "version": "1.0.0",
    "description": "Credential-free, read-only extraction of public source URLs as clean text or structured JSON.",
    "contact": {
      "email": "michael@smry.ai"
    }
  },
  "servers": [
    {
      "url": "https://r.smry.ai",
      "description": "Production public reader"
    }
  ],
  "paths": {
    "/api/v1/sandbox/read": {
      "get": {
        "operationId": "readSandboxFixture",
        "summary": "Exercise the Reader JSON contract without external work",
        "description": "Returns a deterministic ArticleDocument fixture without fetching a source, consuming extraction capacity, or mutating production data.",
        "responses": {
          "200": {
            "description": "Deterministic structured article fixture.",
            "headers": {
              "X-Smry-Sandbox": {
                "description": "Always true for the deterministic sandbox response.",
                "schema": {
                  "type": "boolean",
                  "const": true
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleDocument"
                }
              }
            }
          },
          "405": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "default": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          }
        },
        "security": [],
        "tags": [
          "Public reading"
        ]
      },
      "head": {
        "operationId": "inspectSandboxFixture",
        "summary": "Inspect the deterministic sandbox without transferring its body",
        "responses": {
          "200": {
            "description": "Sandbox metadata in X-Smry-Sandbox.",
            "headers": {
              "X-Smry-Sandbox": {
                "schema": {
                  "type": "boolean",
                  "const": true
                }
              }
            }
          },
          "default": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          }
        },
        "security": [],
        "tags": [
          "Public reading"
        ]
      }
    },
    "/api/v1/read": {
      "get": {
        "operationId": "readPublicSource",
        "summary": "Read a public source as clean, source-grounded text",
        "description": "Returns one source paragraph per line by default. Use Accept: application/json for structured blocks and metadata.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "Exact public HTTP or HTTPS source URL.",
            "schema": {
              "type": "string",
              "format": "uri"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Continuation cursor returned as next_cursor by the preceding JSON page.",
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]*$"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum article blocks returned in this page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "X-Smry-Query",
            "in": "header",
            "description": "Return relevance-ranked paragraphs matching this text.",
            "schema": {
              "type": "string",
              "maxLength": 512
            }
          },
          {
            "name": "X-Smry-Lines",
            "in": "header",
            "description": "Return one paragraph number or an inclusive range such as 90-95.",
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]*(?:-[1-9][0-9]*)?$"
            }
          },
          {
            "name": "X-Smry-Passages",
            "in": "header",
            "description": "Maximum ranked passages for X-Smry-Query.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 8
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Clean source text or structured article blocks.",
            "headers": {
              "X-Smry-Source": {
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "X-Smry-Blocks": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Policy": {
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleDocument"
                }
              }
            }
          },
          "400": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "403": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "416": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "422": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "429": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "502": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "503": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "504": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "default": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          }
        },
        "security": [],
        "tags": [
          "Public reading"
        ]
      },
      "post": {
        "operationId": "readPublicSourceFromJson",
        "summary": "Read a public source from a JSON request",
        "description": "Idempotent JSON form of the public read operation for agent clients that cannot conveniently encode a source URL or focused query in request headers.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Stable caller-generated key for this logical read. Reuse it only when retrying the same request.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PostReadRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Clean source text or structured article blocks.",
            "headers": {
              "Idempotency-Key": {
                "description": "The accepted request key.",
                "schema": {
                  "type": "string"
                }
              },
              "Idempotency-Replayed": {
                "description": "True when this response was replayed from the first completed request.",
                "schema": {
                  "type": "boolean"
                }
              },
              "X-Smry-Source": {
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "RateLimit-Policy": {
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleDocument"
                }
              }
            }
          },
          "400": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "403": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "409": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "415": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "416": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "422": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "425": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "429": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "502": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "503": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "504": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "default": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          }
        },
        "security": [],
        "tags": [
          "Public reading"
        ]
      },
      "head": {
        "operationId": "inspectPublicSource",
        "summary": "Read source metadata without transferring the document body",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Source metadata in X-Smry response headers."
          },
          "400": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "429": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "default": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          }
        },
        "security": [],
        "tags": [
          "Public reading"
        ]
      }
    },
    "/api/v1/read/batch": {
      "post": {
        "operationId": "readPublicSourcesBatch",
        "summary": "Read multiple public sources in one batch request",
        "description": "Executes 1-10 read-only source operations and returns an ordered per-item result. Each operation is independently rate-limited and may succeed or fail without hiding the other results.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchReadRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ordered results for every submitted read operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchReadResponse"
                }
              }
            }
          },
          "400": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "415": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "429": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "503": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "default": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          }
        },
        "security": [],
        "tags": [
          "Public reading"
        ]
      }
    },
    "/api/v1/read/jobs": {
      "post": {
        "operationId": "createPublicSourceReadJob",
        "summary": "Start an asynchronous public source read",
        "description": "Persists a job before returning 202 Accepted. Poll the Location URL until state is complete or failed, then follow result_url for the cached document.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AsyncReadRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The read job was accepted and persisted.",
            "headers": {
              "Location": {
                "description": "Absolute URL to poll for this job.",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "Retry-After": {
                "description": "Minimum seconds before the first poll.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AsyncReadJob"
                }
              }
            }
          },
          "400": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "415": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "503": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "default": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          }
        },
        "security": [],
        "tags": [
          "Public reading"
        ]
      }
    },
    "/api/v1/read/jobs/{jobId}": {
      "get": {
        "operationId": "getPublicSourceReadJob",
        "summary": "Poll an asynchronous public source read",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current durable state and result URL for the job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AsyncReadJob"
                }
              }
            }
          },
          "404": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "503": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          },
          "default": {
            "description": "Typed, recoverable reader error.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PlainTextError"
                }
              }
            }
          }
        },
        "security": [],
        "tags": [
          "Public reading"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "PostReadRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Exact public HTTP or HTTPS source URL."
          },
          "query": {
            "type": "string",
            "maxLength": 512,
            "description": "Optional focused question or search phrase."
          },
          "lines": {
            "type": "string",
            "pattern": "^[1-9][0-9]*(?:-[1-9][0-9]*)?$",
            "description": "One paragraph number or an inclusive range."
          },
          "passages": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "default": 8
          },
          "format": {
            "type": "string",
            "enum": [
              "json",
              "text"
            ],
            "default": "json"
          }
        }
      },
      "BatchReadRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requests"
        ],
        "properties": {
          "requests": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/PostReadRequest"
            }
          }
        }
      },
      "BatchReadResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "count",
          "results"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10
          },
          "results": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "index",
                "url",
                "status",
                "ok",
                "content_type",
                "output"
              ],
              "properties": {
                "index": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "status": {
                  "type": "integer",
                  "minimum": 200,
                  "maximum": 599
                },
                "ok": {
                  "type": "boolean"
                },
                "content_type": {
                  "type": "string"
                },
                "output": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ArticleDocument"
                    },
                    {
                      "$ref": "#/components/schemas/Problem"
                    },
                    {
                      "type": "string"
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "AsyncReadRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Exact public HTTP or HTTPS source URL to read."
          }
        }
      },
      "AsyncReadJob": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "job_id",
          "state",
          "source_url",
          "created_at",
          "completed_at",
          "upstream_status",
          "status_url",
          "result_url"
        ],
        "properties": {
          "job_id": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "pending",
              "complete",
              "failed"
            ]
          },
          "source_url": {
            "type": "string",
            "format": "uri"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "upstream_status": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 200,
            "maximum": 599
          },
          "status_url": {
            "type": "string",
            "format": "uri"
          },
          "result_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "ArticleDocument": {
        "type": "object",
        "required": [
          "source_url",
          "total_blocks",
          "total_tokens",
          "has_more",
          "next_cursor",
          "blocks"
        ],
        "properties": {
          "source_url": {
            "type": "string",
            "format": "uri"
          },
          "reader_url": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "author": {
            "type": [
              "string",
              "null"
            ]
          },
          "publisher": {
            "type": [
              "string",
              "null"
            ]
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "language": {
            "type": [
              "string",
              "null"
            ]
          },
          "total_blocks": {
            "type": "integer",
            "minimum": 0
          },
          "total_tokens": {
            "type": "integer",
            "minimum": 0
          },
          "has_more": {
            "type": "boolean",
            "description": "True when another page of article blocks is available."
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[1-9][0-9]*$",
            "description": "Pass this value as cursor on the next request; null marks the final page."
          },
          "blocks": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "anchor",
                "kind",
                "tokens",
                "text"
              ],
              "properties": {
                "anchor": {
                  "type": "integer",
                  "minimum": 1
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "heading",
                    "paragraph",
                    "reference"
                  ]
                },
                "tokens": {
                  "type": "integer",
                  "minimum": 0
                },
                "text": {
                  "type": "string"
                }
              }
            }
          },
          "query": {
            "type": "string"
          },
          "matched_blocks": {
            "type": "integer",
            "minimum": 0
          },
          "passages": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "anchor",
                "text",
                "section",
                "rank",
                "score",
                "tokens"
              ],
              "properties": {
                "anchor": {
                  "type": "integer",
                  "minimum": 1
                },
                "text": {
                  "type": "string"
                },
                "section": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "rank": {
                  "type": "integer",
                  "minimum": 1
                },
                "score": {
                  "type": "number",
                  "minimum": 0
                },
                "tokens": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            }
          }
        }
      },
      "Problem": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "instance",
          "code",
          "resolution",
          "retryable"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri-reference"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599
          },
          "detail": {
            "type": "string"
          },
          "instance": {
            "type": "string",
            "format": "uri"
          },
          "code": {
            "type": "string"
          },
          "resolution": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          }
        }
      },
      "PlainTextError": {
        "type": "string",
        "description": "A concise shell-friendly error followed by an actionable recovery step."
      }
    },
    "securitySchemes": {
      "smryAccountOAuth": {
        "type": "oauth2",
        "description": "Optional scoped OAuth for the separate api.smry.ai account API. The public reader operations in this document remain credential-free.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://clerk.smry.ai/oauth/authorize",
            "tokenUrl": "https://clerk.smry.ai/oauth/token",
            "scopes": {
              "smry:read": "Read private smry account resources.",
              "smry:write": "Read and mutate private smry account resources, including MCP tools."
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Public reading",
      "description": "Credential-free, read-only retrieval of public source material."
    }
  ]
}