{"openapi":"3.1.0","info":{"title":"getJSON API","version":"1.0.0","summary":"Turn any document (PDF, image, text, CSV) or link (X, Bluesky, Mastodon, Hacker News, GitHub, Google Docs, web page) into structured JSON with AI.","description":"getJSON reads any content a user or an agent points at, a web page or a file, and returns JSON in your schema, validated. Try and use it without an account.\n\nRead a link with no key: GET https://getjson.de/<url> (or /r/{url}, or POST / with a file) returns the envelope; add a schema and it fills result (3 calls per day and network without a key). Extraction with a key is asynchronous: POST /v1/extract returns a jobId, then poll GET /v1/jobs/{id} until status is \"completed\" or \"failed\". No key? An agent gets a trial key with no email and no human: POST /api/agent/trial/challenge, solve the sha256 proof-of-work, POST /api/agent/trial. The trial key has 2 credits, runs the budget mode, and lasts 24 h unless a human opens its claim_url. A full account (5 free credits) comes from POST /api/agent/signup and POST /api/agent/verify. Guide: https://getjson.de/llms.txt. MCP server: https://getjson.de/mcp.\n\nRate limits: 100 requests per minute per key (30 for /v1/sources); a read without a key allows 20 per minute and IP. Every response carries RateLimit-Policy and RateLimit (draft-ietf-httpapi-ratelimit-headers-11) plus RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a 429 adds Retry-After.\n\nVersioning: the version is in the path (/v1). /v1 only gets additions (new endpoints, optional fields, enum values), so ignore unknown fields. A breaking change ships as /v2. Before a /v1 endpoint goes away, its responses carry Deprecation (RFC 9745), Sunset (RFC 8594) and Link rel=\"deprecation\", at least 6 months before the sunset date.","contact":{"url":"https://getjson.de"}},"externalDocs":{"description":"Guide for agents","url":"https://getjson.de/llms.txt"},"servers":[{"url":"https://getjson.de"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key that starts with gj_. Headless: a trial key from POST /api/agent/trial (proof-of-work, no email), or a full-account key from POST /api/agent/signup and POST /api/agent/verify (email code). In the browser: https://getjson.de/settings/api-keys."}},"headers":{"RetryAfter":{"description":"Seconds to wait before the next request","schema":{"type":"integer"}},"RateLimit":{"description":"Remaining quota, e.g. \"default\";r=87;t=42 (r = requests left, t = seconds until reset)","schema":{"type":"string"}},"RateLimitPolicy":{"description":"Quota policy, e.g. \"default\";q=100;w=60 (q requests per w seconds)","schema":{"type":"string"}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable message, or a list of validation issues"},"code":{"type":"string","description":"Machine code, e.g. feature_not_in_plan"}}},"Envelope":{"type":"object","required":["source","content","meta","wall","result"],"properties":{"source":{"type":"object","required":["url","finalUrl","kind","platform","provider","fetchedAt","cached"],"properties":{"url":{"type":"string"},"finalUrl":{"type":"string"},"kind":{"type":"string","enum":["post","article","page","file","thread","repo","issue","document"]},"platform":{"type":"string","enum":["x","bluesky","mastodon","hackernews","github","google","web","file"]},"provider":{"type":"string"},"fetchedAt":{"type":"string","format":"date-time"},"cached":{"type":"boolean"}}},"content":{"type":["object","null"],"description":"The text and its facts. null when a wall blocks the content.","properties":{"title":{"type":["string","null"]},"text":{"type":"string","description":"Markdown for articles and pages, plain text for posts"},"author":{"type":["object","null"]},"publishedDate":{"type":["string","null"]},"language":{"type":["string","null"]},"wordCount":{"type":"integer"},"engagement":{"type":"object","additionalProperties":{"type":["number","null"]}},"hashtags":{"type":"array","items":{"type":"string"}},"mentions":{"type":"array","items":{"type":"string"}},"linkedContent":{"type":"array","items":{"type":"object"}},"truncated":{"type":"boolean"}}},"meta":{"type":["object","null"],"description":"The page metadata object, when an HTML page was read"},"wall":{"type":["object","null"],"description":"Why the content cannot be read; content is null. login: the page answers 401, or a Google document is not public. bot_protection: the page answers 403 or a Cloudflare challenge (cf-mitigated: challenge). no_text: a scan, an image or a page with no text, such as a JavaScript shell. unsupported: a GitHub file that is not text. too_large: a file over the limit. paywall, not_found and not_html are reserved and not set yet. A page that answers 429 or 5xx is a 502 error, not a wall.","properties":{"kind":{"type":"string","enum":["login","paywall","bot_protection","not_found","not_html","too_large","unsupported","no_text"]},"message":{"type":"string"},"hint":{"type":["string","null"]}}},"result":{"description":"The extraction in the caller's schema, validated against it, or null without a schema"}}},"Job":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","classifying","processing","completed","failed"]},"result":{"description":"The extracted JSON once status is completed"},"error_message":{"type":["string","null"]},"error_code":{"type":"string","enum":["schema_mismatch"],"description":"Set when the result broke the schema, also after one retry"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}},"model":{"type":"string"},"tokens_used":{"type":["integer","null"]},"processing_time_ms":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}},"SavedSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"schema":{"type":"object","additionalProperties":true},"is_default":{"type":"boolean"},"share_id":{"type":["string","null"],"description":"The public id while the schema is shared, else null"},"created_at":{"type":"string","format":"date-time"}}},"Model":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"creditsPerRequest":{"type":"integer"}},"additionalProperties":true},"LinkMetadata":{"type":"object","properties":{"platform":{"type":"string","const":"web"},"url":{"type":"string","description":"The requested link"},"finalUrl":{"type":"string","description":"The link after redirects"},"canonicalUrl":{"type":["string","null"],"description":"link rel=\"canonical\""},"title":{"type":["string","null"],"description":"<title>, else og:title, else twitter:title"},"description":{"type":["string","null"],"description":"meta description, else og:description, else twitter:description"},"siteName":{"type":["string","null"],"description":"og:site_name, else application-name"},"type":{"type":["string","null"],"description":"og:type"},"lang":{"type":["string","null"],"description":"<html lang>, else og:locale"},"author":{"type":["string","null"],"description":"meta author, else article:author, else twitter:creator"},"publishedTime":{"type":["string","null"]},"modifiedTime":{"type":["string","null"]},"keywords":{"type":"array","items":{"type":"string"},"description":"meta keywords"},"themeColor":{"type":["string","null"]},"image":{"type":["string","null"],"description":"Absolute preview image URL: og:image, else twitter:image"},"favicon":{"type":"string","description":"Absolute favicon URL: the first rel=icon, else apple-touch-icon, else /favicon.ico"},"icons":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"rel":{"type":"string"},"sizes":{"type":["string","null"]},"type":{"type":["string","null"]}}}},"openGraph":{"type":"object","description":"og:* tags without the prefix, plus article:*, profile:*, book:*, music:* and video:* tags. Repeated tags are arrays.","additionalProperties":true},"twitter":{"type":"object","description":"twitter:* tags without the prefix","additionalProperties":true},"jsonLd":{"type":"array","items":{},"description":"Up to 10 parsed application/ld+json blocks"},"oembedUrl":{"type":["string","null"],"description":"Absolute URL of the page's JSON oEmbed endpoint"}}}}},"paths":{"/r/{url}":{"get":{"operationId":"readLink","summary":"Read a link as JSON without a key (0 credits, no AI)","description":"The same call works as GET /<url>, for example https://getjson.de/https://x.com/jack/status/20 or https://getjson.de/example.com/page. This path is the explicit form: the link is URL-encoded. The answer is the envelope. With a schema or instructions the call runs the budget mode, waits up to 60 s and fills `result`; without a key a network has 3 such calls per day (a /24 for IPv4, a /64 for IPv6) and nothing is kept for more than 1 hour. A key lifts the read limit from 20 to 100 per minute; send a schema call with a key to POST /v1/extract. Accept: text/markdown returns the title and the text.","security":[{},{"apiKey":[]}],"parameters":[{"name":"url","in":"path","required":true,"description":"The URL-encoded http or https link. A link without a scheme gets https://.","schema":{"type":"string"},"example":"https%3A%2F%2Fexample.com%2Fpost"},{"name":"schema","in":"query","description":"A JSON Schema object, URL-encoded (at most 16,000 characters; draft 2020-12, or draft-07 by $schema). Runs the extraction and fills `result`, validated against the schema. The header X-JSON-Schema carries the same. In place of the JSON, the value may be a shared schema id (s_ and 10 characters); an unknown id answers 404 with code schema_not_found. With the id in the path (GET /{schemaId}/{url}), this parameter belongs to the link.","schema":{"type":"string"}},{"name":"instructions","in":"query","description":"Guidance for the extraction (at most 2,000 characters). Alone, it runs the extraction too.","schema":{"type":"string"}},{"name":"model","in":"query","description":"Without a key only \"budget\". Another mode answers 403 keyless_mode.","schema":{"type":"string","default":"budget"}},{"name":"max_chars","in":"query","description":"Cut content.text after this many characters. At most 500,000.","schema":{"type":"integer","minimum":1,"maximum":500000,"default":20000}},{"name":"full","in":"query","description":"1 keeps the whole text.","schema":{"type":"string","enum":["1","true"]}},{"name":"X-JSON-Schema","in":"header","description":"The JSON Schema as a one-line JSON string, in place of the schema parameter.","schema":{"type":"string"}}],"responses":{"200":{"description":"The envelope. A wall is no error: `wall` is filled and `content` is null. With a schema, `result` holds the extraction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}},"text/markdown":{"schema":{"type":"string"},"description":"With Accept: text/markdown and no schema: the title and the text."}}},"400":{"description":"Not a link, a private or internal address, an invalid schema, a schema id in the path and a schema in X-JSON-Schema (schema_conflict), or use_extract (a schema call with a key)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"401":{"description":"The key in the Authorization header is wrong","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"403":{"description":"A mode other than budget without a key (keyless_mode)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"404":{"description":"The page or file answers 404 or 410, or no schema is shared under the id (schema_not_found)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"413":{"description":"The file is larger than the limit (5 MB without a key)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"415":{"description":"A file type that is not supported","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"422":{"description":"The result breaks the schema, also after one retry (schema_mismatch); errors names the fields","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"429":{"description":"Rate limited (rate_limited), or the 3 keyless schema calls of this network are used up today (keyless_limit)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}}},"502":{"description":"The link is unreachable, or the extraction failed (extraction_failed)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"503":{"description":"The daily budget for keyless calls is used up (keyless_budget)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"504":{"description":"The page, or the 60 s extraction, did not answer in time","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}}}}},"/{schemaId}/{url}":{"get":{"operationId":"readLinkWithSharedSchema","summary":"Read a link into a shared schema without a key","description":"Put a shared schema id in front of any link: https://getjson.de/s_7Kq2hnAb9Z/https://news.ycombinator.com/item?id=1. The link keeps its own query string, a parameter named schema included. The call runs like GET /r/{url} with that schema. An unknown id answers 404 with code schema_not_found; a schema in X-JSON-Schema as well answers 400 with code schema_conflict.","security":[{},{"apiKey":[]}],"parameters":[{"name":"schemaId","in":"path","required":true,"description":"A shared schema id: s_ and 10 characters. Its owner turned sharing on.","schema":{"type":"string","pattern":"^s_[A-Za-z0-9]{10}$"},"example":"s_7Kq2hnAb9Z"},{"name":"url","in":"path","required":true,"description":"The http or https link, as it is or URL-encoded. A link without a scheme gets https://.","schema":{"type":"string"},"example":"news.ycombinator.com/item?id=1"},{"name":"instructions","in":"query","description":"Guidance for the extraction (at most 2,000 characters). Alone, it runs the extraction too.","schema":{"type":"string"}},{"name":"model","in":"query","description":"Without a key only \"budget\". Another mode answers 403 keyless_mode.","schema":{"type":"string","default":"budget"}},{"name":"max_chars","in":"query","description":"Cut content.text after this many characters. At most 500,000.","schema":{"type":"integer","minimum":1,"maximum":500000,"default":20000}},{"name":"full","in":"query","description":"1 keeps the whole text.","schema":{"type":"string","enum":["1","true"]}},{"name":"X-JSON-Schema","in":"header","description":"The JSON Schema as a one-line JSON string, in place of the schema parameter.","schema":{"type":"string"}}],"responses":{"200":{"description":"The envelope. A wall is no error: `wall` is filled and `content` is null. With a schema, `result` holds the extraction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}},"text/markdown":{"schema":{"type":"string"},"description":"With Accept: text/markdown and no schema: the title and the text."}}},"400":{"description":"Not a link, a private or internal address, an invalid schema, a schema id in the path and a schema in X-JSON-Schema (schema_conflict), or use_extract (a schema call with a key)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"401":{"description":"The key in the Authorization header is wrong","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"403":{"description":"A mode other than budget without a key (keyless_mode)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"404":{"description":"The page or file answers 404 or 410, or no schema is shared under the id (schema_not_found)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"413":{"description":"The file is larger than the limit (5 MB without a key)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"415":{"description":"A file type that is not supported","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"422":{"description":"The result breaks the schema, also after one retry (schema_mismatch); errors names the fields","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"429":{"description":"Rate limited (rate_limited), or the 3 keyless schema calls of this network are used up today (keyless_limit)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}}},"502":{"description":"The link is unreachable, or the extraction failed (extraction_failed)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"503":{"description":"The daily budget for keyless calls is used up (keyless_budget)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"504":{"description":"The page, or the 60 s extraction, did not answer in time","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}}}}},"/":{"post":{"operationId":"readFile","summary":"Read a file as JSON without a key (0 credits, no AI)","description":"Send a PDF, PNG, JPEG, WebP, TXT or CSV. The answer is the envelope: the text of a PDF with a text layer, a TXT or a CSV; wall.kind no_text for a scan or an image. With a schema or instructions the call runs like GET /r/{url}. Without a key a file may have 5 MB.","security":[{},{"apiKey":[]}],"parameters":[{"name":"schema","in":"query","description":"A JSON Schema object, URL-encoded (at most 16,000 characters; draft 2020-12, or draft-07 by $schema). Runs the extraction and fills `result`, validated against the schema. The header X-JSON-Schema carries the same. In place of the JSON, the value may be a shared schema id (s_ and 10 characters); an unknown id answers 404 with code schema_not_found. With the id in the path (GET /{schemaId}/{url}), this parameter belongs to the link.","schema":{"type":"string"}},{"name":"instructions","in":"query","description":"Guidance for the extraction (at most 2,000 characters). Alone, it runs the extraction too.","schema":{"type":"string"}},{"name":"model","in":"query","description":"Without a key only \"budget\". Another mode answers 403 keyless_mode.","schema":{"type":"string","default":"budget"}},{"name":"max_chars","in":"query","description":"Cut content.text after this many characters. At most 500,000.","schema":{"type":"integer","minimum":1,"maximum":500000,"default":20000}},{"name":"full","in":"query","description":"1 keeps the whole text.","schema":{"type":"string","enum":["1","true"]}},{"name":"X-JSON-Schema","in":"header","description":"The JSON Schema as a one-line JSON string, in place of the schema parameter.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"schema":{"type":"string","description":"A JSON Schema as a JSON string (at most 16,000 characters)"},"instructions":{"type":"string","description":"At most 2,000 characters"},"model":{"type":"string","default":"budget"}}}}}},"responses":{"200":{"description":"The envelope. A wall is no error: `wall` is filled and `content` is null. With a schema, `result` holds the extraction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}},"text/markdown":{"schema":{"type":"string"},"description":"With Accept: text/markdown and no schema: the title and the text."}}},"400":{"description":"Not a link, a private or internal address, an invalid schema, a schema id in the path and a schema in X-JSON-Schema (schema_conflict), or use_extract (a schema call with a key)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"401":{"description":"The key in the Authorization header is wrong","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"403":{"description":"A mode other than budget without a key (keyless_mode)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"404":{"description":"The page or file answers 404 or 410, or no schema is shared under the id (schema_not_found)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"413":{"description":"The file is larger than the limit (5 MB without a key)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"415":{"description":"A file type that is not supported","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"422":{"description":"The result breaks the schema, also after one retry (schema_mismatch); errors names the fields","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"429":{"description":"Rate limited (rate_limited), or the 3 keyless schema calls of this network are used up today (keyless_limit)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}}},"502":{"description":"The link is unreachable, or the extraction failed (extraction_failed)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"503":{"description":"The daily budget for keyless calls is used up (keyless_budget)","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}},"504":{"description":"The page, or the 60 s extraction, did not answer in time","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine code, e.g. keyless_limit"},"hint":{"type":["string","null"],"description":"What to do next"},"errors":{"type":"array","maxItems":20,"description":"The fields that break the schema, for schema_mismatch","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"JSON Pointer into result, e.g. /items/0/total"},"message":{"type":"string"}}}}}}}}}}}},"/v1/extract":{"post":{"operationId":"extract","summary":"Start a JSON extraction from a file or a link","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Max 50 MB. One of: application/pdf, image/png, image/jpeg, image/webp, text/plain, text/csv. Required unless url is set."},"url":{"type":"string","description":"An X post ID or any http(s) link. X, Bluesky, Mastodon, Hacker News, GitHub (repository, issue, pull request, release, file) and public Google Docs, Sheets and Slides links are read from their source; a link to a PDF, PNG, JPEG, WebP, TXT or CSV file is downloaded (50 MB, 5 MB for a trial key); any other web page is read as an article (Readability, Markdown). With model \"auto\" and no schema, schema_id or instructions, the result comes from the source at 0 credits, with any balance: the X post, or the envelope (source, content, meta, wall, result) for every other source. With a schema or instructions, the AI reads the source text, or the file itself for a file link. Read errors (400, 404, 413, 415, 502, 503, 504) return before a job starts. Required unless file is set."},"model":{"type":"string","description":"A mode (auto, standard, premium, budget, ocr, multilingual) or a model id from GET /v1/models. Default claude-sonnet (1 credit). \"auto\" reserves up to 3 credits and refunds the rest."},"schema":{"type":"string","description":"Inline JSON Schema, as a JSON string (at most 16,000 characters). Every account may use it; it costs the credits of the model. Draft 2020-12, or draft-07 by $schema. The result is validated against it: a result that breaks it gets one retry, then the job fails with error_code schema_mismatch and the credits are refunded. A schema that does not compile, or a pattern that can backtrack without bound (such as ^(a+)+$), answers 400 before any credit is spent."},"schema_id":{"type":"string","description":"A saved schema id (uuid). Needs the Pro plan; an inline schema does not. Or a shared schema id (s_ and 10 characters) of any account: it needs no plan and costs the credits of the model, like an inline schema."},"instructions":{"type":"string","description":"Extra extraction instructions"}}}}}},"responses":{"202":{"description":"Job accepted","content":{"application/json":{"schema":{"type":"object","required":["jobId","status"],"properties":{"jobId":{"type":"string","format":"uuid"},"status":{"type":"string"}}}}}},"400":{"description":"Invalid input, or a link that is invalid or internal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The balance cannot cover the credits this extraction reserves. For a trial key: the trial allowance is used up, and the error names the claim_url.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan does not include a requested feature, or a trial key asked for a model other than budget (the error names the claim_url)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The linked post, document or page was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"File too large: 50 MB, or 5 MB for a trial key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The linked file type is not supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}}},"502":{"description":"The linked post, document or page could not be fetched","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The shared daily budget for agent trials is used up (trial keys only), or the link's source is rate limited (GitHub) or switched off; try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The linked page did not respond in time","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/jobs":{"get":{"operationId":"listJobs","summary":"List recent jobs","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"A page of jobs","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}}}}}},"/v1/jobs/{id}":{"get":{"operationId":"getJob","summary":"Get job status and result","parameters":[{"name":"id","in":"path","required":true,"description":"Job id from POST /v1/extract","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}}}}}},"/v1/balance":{"get":{"operationId":"getBalance","summary":"Get the credit balance","responses":{"200":{"description":"Balance","content":{"application/json":{"schema":{"type":"object","properties":{"balance":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}}}}}},"/v1/models":{"get":{"operationId":"listModels","summary":"List AI models and their credit cost","responses":{"200":{"description":"Models","content":{"application/json":{"schema":{"type":"object","properties":{"models":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}}}}}},"/v1/sources/x/{idOrUrl}":{"get":{"operationId":"getXPost","summary":"Fetch an X post as normalised JSON, without AI (0 credits)","parameters":[{"name":"idOrUrl","in":"path","required":true,"description":"Post ID or URL-encoded X post URL","schema":{"type":"string"}}],"responses":{"200":{"description":"The post","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object"}}}}}},"400":{"description":"Not a valid X post reference","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Post not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}}}}}},"/v1/sources/link/{url}":{"get":{"operationId":"getLinkMetadata","summary":"Fetch the metadata of a web page as JSON, without AI (0 credits)","description":"Reads the <head> of a public HTML page: no JavaScript, no article text. http and https on ports 80 and 443 only, no credentials in the link, 10 s in total, at most 5 redirects, the first 1 MB. Private and internal addresses are refused on every redirect hop. X post links return 400; use /v1/sources/x/{idOrUrl}. Limited to 30 requests per minute per key. Results are cached for 10 minutes, 404s for 5 minutes.","parameters":[{"name":"url","in":"path","required":true,"description":"URL-encoded http or https link. A link without a scheme gets https://.","schema":{"type":"string"},"example":"https%3A%2F%2Fbun.sh%2Fblog%2Fbun-v1.2"}],"responses":{"200":{"description":"The page metadata","content":{"application/json":{"schema":{"type":"object","properties":{"link":{"$ref":"#/components/schemas/LinkMetadata"}}}}}},"400":{"description":"Not a valid http(s) link, an X post link, an unknown host, a non-default port, credentials in the link, or a private or internal address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The page answers 404 or 410","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The link is not an HTML page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}}},"502":{"description":"The page is unreachable, answers another error status, or redirects too often","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The page did not respond in time","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/schemas":{"get":{"operationId":"listSchemas","summary":"List saved schemas","responses":{"200":{"description":"Schemas","content":{"application/json":{"schema":{"type":"object","properties":{"schemas":{"type":"array","items":{"$ref":"#/components/schemas/SavedSchema"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}}}}},"post":{"operationId":"createSchema","summary":"Save a schema for reuse","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","schema"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":["string","null"],"maxLength":1000},"schema":{"type":"object","description":"A JSON Schema object","additionalProperties":true},"is_default":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"$ref":"#/components/schemas/SavedSchema"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}}}}}},"/v1/schemas/{id}":{"get":{"operationId":"getSchema","summary":"Get a saved schema","parameters":[{"name":"id","in":"path","required":true,"description":"Schema id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The schema","content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"$ref":"#/components/schemas/SavedSchema"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}}}}},"patch":{"operationId":"updateSchema","summary":"Update a saved schema","parameters":[{"name":"id","in":"path","required":true,"description":"Schema id","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":["string","null"],"maxLength":1000},"schema":{"type":"object","description":"A JSON Schema object","additionalProperties":true},"is_default":{"type":"boolean"},"shared":{"type":"boolean","description":"true shares the schema: it gets a share_id (s_ and 10 characters) that any caller can pass as ?schema= on the read path or as schema_id. false makes it private again; the old id stops working."}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"$ref":"#/components/schemas/SavedSchema"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}}}}},"delete":{"operationId":"deleteSchema","summary":"Delete a saved schema","parameters":[{"name":"id","in":"path","required":true,"description":"Schema id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"deleted"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; wait for Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}}}}}},"/api/agent/trial/challenge":{"post":{"operationId":"agentTrialChallenge","summary":"Get a proof-of-work challenge for a trial key","security":[],"responses":{"200":{"description":"Find a solution so that sha256(challenge + ':' + solution) starts with `difficulty` zero bits. Valid for 5 minutes, once.","content":{"application/json":{"schema":{"type":"object","required":["challenge","difficulty"],"properties":{"challenge":{"type":"string"},"difficulty":{"type":"integer"},"algorithm":{"const":"sha256"},"expires_at":{"type":"string","format":"date-time"}}}}}},"429":{"description":"Too many attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/trial":{"post":{"operationId":"agentTrial","summary":"Exchange a solved challenge for a trial key, no email needed","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["challenge","solution"],"properties":{"challenge":{"type":"string"},"solution":{"type":"string","maxLength":128}}}}}},"responses":{"201":{"description":"A trial key. Give claim_url to a human to keep the key past expires_at.","content":{"application/json":{"schema":{"type":"object","required":["key","claim_url","expires_at"],"properties":{"key":{"type":"string","pattern":"^gj_"},"claim_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"limits":{"type":"object","properties":{"credits":{"type":"integer"},"mode":{"type":"string"},"max_file_mb":{"type":"number"}}}}}}}},"400":{"description":"Missing, wrong, expired or reused proof-of-work","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many trials from this network today, or too many attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The daily budget for agent trials is used up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/signup":{"post":{"operationId":"agentSignup","summary":"Start headless sign-up or sign-in: emails a 6-digit code","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Code sent. Ask the account owner for the code from the email.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/verify":{"post":{"operationId":"agentVerify","summary":"Exchange the emailed code for a new API key","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","code"],"properties":{"email":{"type":"string","format":"email"},"code":{"type":"string","pattern":"^[0-9]{6}$"},"key_name":{"type":"string","default":"agent"}}}}}},"responses":{"201":{"description":"The API key. It is shown only once.","content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string","pattern":"^gj_"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key_prefix":{"type":"string"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Wrong or expired code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}