{"openapi":"3.1.0","info":{"title":"putlive API","version":"1.0.0","summary":"Publish what an AI agent made and get a link.","description":"putlive hosts the work of AI agents (a page, a site, a file) and returns a link. The link is private by default: a secret address that search engines are told to skip. Wider access is set only by an explicit request.\n\nSign in with an e-mailed 8-digit code (`POST /v1/auth/code`, then `POST /v1/auth/token`) and send the key as `Authorization: Bearer <key>`. A guide written for agents, with what every error code means and what to do, is at https://putlive.dev/llms.txt.\n\nRequest budgets: 120 a minute per key for everything except uploads, 1200 a minute for `PUT /v1/uploads/...`. Over a budget the answer is `rate_limited` with `Retry-After`.\n\nEvery answer of `/v1` is `Cache-Control: no-store`. Every error has the shape of `ApiErrorBody`; match on `error.code`, never on the message."},"servers":[{"url":"https://api.putlive.dev","description":"The API"}],"tags":[{"name":"auth","description":"Sign in by an e-mailed code. No key needed."},{"name":"account","description":"The account behind a key."},{"name":"sites","description":"Publish, update, protect and remove sites."},{"name":"reports","description":"Report a published address. No key needed."}],"paths":{"/v1/auth/code":{"post":{"operationId":"requestSignInCode","tags":["auth"],"summary":"E-mail a sign-in code","description":"Sends a 8-digit code to the address. The code works once, for 10 minutes; a new code replaces the one that is waiting.\n\nThe answer is 204 whether or not the address has an account. The one exception: an address that has no account and sends no valid `invite` is refused with `forbidden` and the hint `invite required` (accounts are by invitation for now).\n\nAt most 5 codes an hour are sent to one address. Open to everybody: no key.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignInCodeRequest"},"example":{"email":"person@example.com","invite":"EXAMPLE-INVITE-CODE"}}}},"responses":{"204":{"description":"If the address can sign in, a mail with the code is on its way."},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}},"x-error-codes":["invalid_request","forbidden","too_large","rate_limited","unavailable"]}},"/v1/auth/token":{"post":{"operationId":"redeemSignInCode","tags":["auth"],"summary":"Trade the e-mailed code for an API key","description":"The key is in this answer and nowhere else: it is shown once and stored only as a hash. The first use of a valid invite creates the account (Free plan).\n\nThe code is read as people copy it (`0000 0000` or `0000-0000`). A code is looked at 5 times and then dies; ask for a new one. A wrong, expired or used code is always the same `unauthorized`.\n\nAn account holds at most 20 active keys: at that number the answer is `limit_exceeded` (`api_keys`) and the code is not used up; revoke a key on the keys page of the dashboard and call again with the same code (it works for 10 minutes and 5 looks).\n\nOpen to everybody: no key.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"},"example":{"email":"person@example.com","code":"0000 0000","key_name":"my agent"}}}},"responses":{"200":{"description":"The new API key and the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"},"example":{"api_key":"ah_EXAMPLE000000000000000000000000000000000","account":{"id":"00000000-0000-4000-8000-000000000000","email":"person@example.com","plan":"free"}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}},"x-error-codes":["invalid_request","unauthorized","forbidden","limit_exceeded","too_large","rate_limited","unavailable"]}},"/v1/me":{"get":{"operationId":"getAccount","tags":["account"],"summary":"The account behind the key","description":"The account, the limits of its plan and what it holds now. Counts against the per-key request budget like every other call.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"$ref":"#/components/responses/Error401"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}},"x-error-codes":["unauthorized","rate_limited","unavailable"]}},"/v1/usage":{"get":{"operationId":"getUsage","tags":["account"],"summary":"What the account uses against its plan","description":"Sites, storage, and the transfer of this UTC month. `transfer.resetsAt` is the first moment of the next month. The transfer is counted from the edge's access log every ten minutes, so it can be that much behind. When the monthly transfer of a Free account is used up, its live sites answer visitors with 509 until `resetsAt`.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The numbers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"$ref":"#/components/responses/Error401"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}},"x-error-codes":["unauthorized","rate_limited","unavailable"]}},"/v1/sites":{"get":{"operationId":"listSites","tags":["sites"],"summary":"The sites of the account","description":"The sites that are not deleted, newest first.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The sites.","content":{"application/json":{"schema":{"type":"object","required":["sites"],"additionalProperties":false,"properties":{"sites":{"type":"array","items":{"$ref":"#/components/schemas/Site"}}}}}}},"401":{"$ref":"#/components/responses/Error401"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}},"x-error-codes":["unauthorized","rate_limited","unavailable"]},"post":{"operationId":"createSite","tags":["sites"],"summary":"Publish a new site","description":"Creates a site and its first release. The address is random and secret (`access.mode` is `link`, `noindex`) unless the request says otherwise.\n\nTwo ways: list `files` (path, size, sha256) and upload each with `PUT /v1/uploads/{releaseId}/{path}`, then `POST /v1/releases/{id}/finalize`; or send only `inlineFiles` (text, 256 KB together) and the request is finalized for you. Both together are allowed: the inline files are stored now, the others are uploaded.\n\nEvery release of a Free account is checked before it is served. It may be held for a person (`site.status` `pending_review`) or refused (`rejected`, with `reasons`).\n\nLimits: 2500 files, a body of 2 MB, 4 publications in 24 hours for each site the plan allows (20 on Free; every release counts, the first of a site too), and the limits of the plan.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Wait"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishRequest"},"example":{"title":"Quarterly report","inlineFiles":[{"path":"index.html","content":"<h1>Hello</h1>"}]}}}},"responses":{"200":{"description":"The request carried only `inlineFiles`, so it was finalized in the same call and the answer is settled. `status` is one of `live`, `pending_review`, `rejected`, `superseded`. `live`: The release is served. `pending_review`: The release is held for a person; `reasons` says why. Nothing to retry: tell the user that a person will look at it and that the decision comes by mail. If nobody has looked within 72 hours the publication is refused. An update can then be published again; a first publication leaves a `rejected` site that cannot be updated, so the files are published again as a new site and the refused site can be deleted to free its place. For an update, the version that was live keeps serving meanwhile. `rejected`: The safety checks refused the release; `reasons` says why. Do not send the same files again. `superseded`: A newer release went live first, so this one is not served.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalizeResult"}}}},"201":{"description":"The request listed `files`: this is the ticket. PUT each file named in `uploads` before `expiresAt` (30 minutes), then POST `finalizeUrl`. Files the site already holds are not listed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishTicket"}}}},"202":{"description":"Finalized, but the answer is not settled after the wait (`wait`, default 20, at most 60 seconds). `status` is `checking`. `checking`: The checks are still running. Call `POST /v1/releases/{id}/finalize` again with the `release.id` of this answer; it is safe to repeat.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalizeResult"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"409":{"$ref":"#/components/responses/Error409"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}},"x-error-codes":["invalid_request","unauthorized","forbidden","conflict","limit_exceeded","too_large","rate_limited","unavailable"]}},"/v1/sites/{id}":{"get":{"operationId":"getSite","tags":["sites"],"summary":"One site","description":"A site of the account. Somebody else's site, a deleted one and an id that is not a UUID are all `not_found`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The id of the site.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The site.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}},"x-error-codes":["unauthorized","not_found","rate_limited","unavailable"]},"delete":{"operationId":"deleteSite","tags":["sites"],"summary":"Delete a site","description":"The site stops answering and its files are removed; the address is never given to anybody else. A site that is switched off (`quarantined`), waits for a person (`pending_review`, or an update held for a person) or has a report that its sender confirmed and we have not decided yet is NOT deleted: the answer is `conflict` with a message that says why and what to do (reply to the e-mail about the site; delete it once the case is closed), and its files are kept. Do not retry it. When the storage cannot be reached the answer is `unavailable`: repeat the same call.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The id of the site.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"The site is deleted."},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}},"x-error-codes":["unauthorized","not_found","conflict","rate_limited","unavailable"]}},"/v1/sites/{id}/access":{"patch":{"operationId":"updateSiteAccess","tags":["sites"],"summary":"Who may open a site","description":"Changes the mode, the password, the e-mail list, the expiry or the revocation of a site. What the request leaves out stays; what the new mode does not use is cleared. The edge is told first: when it cannot take the change nothing changes and the answer is `unavailable`.\n\n`link` (default): anyone with the secret address. `password`: a visitor asks for it (8 to 256 characters). `email`: a visitor gets a code by mail if the address is on the list (5 entries on Free, 1000 at most). `public`: searchable, no secret in the link; not on the Free plan (`forbidden`). Widening access is the user's decision, not the agent's.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The id of the site.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessRequest"},"example":{"mode":"email","emails":["person@example.com"],"expiresAt":"2030-01-01T00:00:00Z"}}}},"responses":{"200":{"description":"The site with its new access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}},"x-error-codes":["invalid_request","unauthorized","forbidden","not_found","conflict","limit_exceeded","too_large","rate_limited","unavailable"]}},"/v1/sites/{id}/releases":{"post":{"operationId":"createRelease","tags":["sites"],"summary":"Publish a new version of a site","description":"Same request and answers as `POST /v1/sites`. Files the live version already holds are reused and not listed in `uploads`. An update never takes the live version down while it is checked: if the new version is refused or held, the live one keeps serving.\n\nA site that is `quarantined` answers `forbidden`, one in review `pending_review`, a refused one `rejected`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The id of the site.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/Wait"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishRequest"},"example":{"title":"Quarterly report","inlineFiles":[{"path":"index.html","content":"<h1>Hello</h1>"}]}}}},"responses":{"200":{"description":"The request carried only `inlineFiles`, so it was finalized in the same call and the answer is settled. `status` is one of `live`, `pending_review`, `rejected`, `superseded`. `live`: The release is served. `pending_review`: The release is held for a person; `reasons` says why. Nothing to retry: tell the user that a person will look at it and that the decision comes by mail. If nobody has looked within 72 hours the publication is refused. An update can then be published again; a first publication leaves a `rejected` site that cannot be updated, so the files are published again as a new site and the refused site can be deleted to free its place. For an update, the version that was live keeps serving meanwhile. `rejected`: The safety checks refused the release; `reasons` says why. Do not send the same files again. `superseded`: A newer release went live first, so this one is not served.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalizeResult"}}}},"201":{"description":"The request listed `files`: this is the ticket. PUT each file named in `uploads` before `expiresAt` (30 minutes), then POST `finalizeUrl`. Files the site already holds are not listed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishTicket"}}}},"202":{"description":"Finalized, but the answer is not settled after the wait (`wait`, default 20, at most 60 seconds). `status` is `checking`. `checking`: The checks are still running. Call `POST /v1/releases/{id}/finalize` again with the `release.id` of this answer; it is safe to repeat.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalizeResult"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}},"x-error-codes":["invalid_request","unauthorized","forbidden","not_found","conflict","limit_exceeded","too_large","pending_review","rejected","rate_limited","unavailable"]}},"/v1/sites/{id}/rollback":{"post":{"operationId":"rollbackSite","tags":["sites"],"summary":"Put an older version live again","description":"Needs a live site. Without a body, the newest kept version before the current one is used. A Free site keeps only its live version, so there is nothing to go back to (`conflict`). The version that was live stays kept, so going forward again is the same call with its number.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The id of the site.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RollbackRequest"},"example":{"version":1}}}},"responses":{"200":{"description":"The site, now at the older version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}},"x-error-codes":["invalid_request","unauthorized","not_found","conflict","too_large","rate_limited","unavailable"]}},"/v1/releases/{id}/finalize":{"post":{"operationId":"finalizeRelease","tags":["sites"],"summary":"Close the upload and start the checks","description":"Compares what the storage holds with the file list. Anything missing is `upload_incomplete`, naming the paths in `error.missing` (at most 100): upload those again and call this again. Then the checks run; the call waits up to `wait` seconds for them.\n\nSafe to repeat: a release that is no longer open answers with its stored state, the same body the first call got once there is one. The upload session lasts 30 minutes from the creation of the release; after that the answer is `forbidden` and a new release is needed.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The id of the release (`release.id` of the ticket).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/Wait"}],"responses":{"200":{"description":"The answer is settled. `status` is one of `live`, `pending_review`, `rejected`, `superseded`. `live`: The release is served. `pending_review`: The release is held for a person; `reasons` says why. Nothing to retry: tell the user that a person will look at it and that the decision comes by mail. If nobody has looked within 72 hours the publication is refused. An update can then be published again; a first publication leaves a `rejected` site that cannot be updated, so the files are published again as a new site and the refused site can be deleted to free its place. For an update, the version that was live keeps serving meanwhile. `rejected`: The safety checks refused the release; `reasons` says why. Do not send the same files again. `superseded`: A newer release went live first, so this one is not served.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalizeResult"}}}},"202":{"description":"The answer is not settled yet. `status` is `checking`. `checking`: The checks are still running. Call `POST /v1/releases/{id}/finalize` again with the `release.id` of this answer; it is safe to repeat.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalizeResult"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}},"x-error-codes":["invalid_request","unauthorized","forbidden","not_found","conflict","upload_incomplete","pending_review","rejected","rate_limited","unavailable"]}},"/v1/uploads/{releaseId}/{path}":{"put":{"operationId":"uploadFile","tags":["sites"],"summary":"Upload one file of an open release","description":"The body is the raw bytes of the file. `{path}` is the path from the file list, each segment percent-encoded on its own (`a b/c%.txt` is `a%20b/c%25.txt`); the slashes stay slashes. The path must be exactly one of the listed paths.\n\n`{path}` holds slashes, which OpenAPI path parameters do not formally allow: a client generated from this document may percent-encode them as `%2F`. Do not build the URL from the template: use the `url` of the entry in `uploads` exactly as the ticket gives it.\n\nThe size comes from the file list: a `Content-Length` that differs, a body that is longer, or a hash that does not match is `upload_incomplete` with the path in `error.missing`. Upload the file again.\n\nUploads have a budget of their own: 1200 requests a minute per key (every other call: 120).","security":[{"bearerAuth":[]}],"parameters":[{"name":"releaseId","in":"path","required":true,"description":"The id of the release (`release.id` of the ticket).","schema":{"type":"string","format":"uuid"}},{"name":"path","in":"path","required":true,"description":"The file path, segments percent-encoded, slashes between segments kept as `/` (not `%2F`).","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The bytes of the file. A zero-byte file is valid: send an empty body.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"The file is stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadResult"},"example":{"path":"index.html","size":14}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}},"x-error-codes":["invalid_request","unauthorized","forbidden","not_found","conflict","limit_exceeded","too_large","upload_incomplete","pending_review","rejected","rate_limited","unavailable"]}},"/v1/reports":{"post":{"operationId":"fileReport","tags":["reports"],"summary":"Report a published address","description":"Open to everybody, no key: 10 reports an hour per client network. The answer is 201 and the same for every well-formed address under the content domain (`putlive.page`), whether or not a site is there. `quarantined` is always false: the reporter must confirm the receipt that is mailed to them (`POST /v1/reports/confirm`) before anything is decided.\n\n`category` is one of `phishing`, `malware`, `illegal_content`, `copyright`, `adult`, `spam_redirect`, `terms`, `legal_order`. The explanation has 10 to 4000 characters, and `goodFaith` must be true.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportRequest"},"example":{"url":"https://example-report.putlive.page/","category":"phishing","explanation":"The page imitates a bank sign-in form.","reporterEmail":"person@example.com","goodFaith":true}}}},"responses":{"201":{"description":"The report is stored; a receipt is mailed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportReceipt"}}}},"400":{"$ref":"#/components/responses/Error400"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}},"x-error-codes":["invalid_request","too_large","rate_limited","unavailable"]}},"/v1/reports/confirm":{"post":{"operationId":"confirmReport","tags":["reports"],"summary":"Confirm a report with the token of the receipt","description":"The button of the page the receipt's link opens. A link opened by a mail scanner confirms nothing: this request is needed. The token works once, within 24 hours; an unknown, used or expired token is `not_found`. Open to everybody, no key: 60 attempts an hour per client network.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportConfirmRequest"},"example":{"token":"EXAMPLE-TOKEN"}}}},"responses":{"200":{"description":"The report is confirmed.","content":{"application/json":{"schema":{"type":"object","required":["confirmed"],"additionalProperties":false,"properties":{"confirmed":{"const":true}}}}}},"400":{"$ref":"#/components/responses/Error400"},"404":{"$ref":"#/components/responses/Error404"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}},"x-error-codes":["invalid_request","not_found","too_large","rate_limited","unavailable"]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key (`ah_` and 40 letters and digits), from `POST /v1/auth/token`. Exactly `Authorization: Bearer <key>`; no other header, no query parameter, no cookie."}},"parameters":{"Wait":{"name":"wait","in":"query","required":false,"description":"Seconds the call may wait for the checks (0 to 60, more is cut to 60).","schema":{"type":"number","minimum":0,"maximum":60,"default":20}}},"schemas":{"ErrorCode":{"type":"string","enum":["invalid_request","unauthorized","forbidden","not_found","conflict","limit_exceeded","too_large","upload_incomplete","pending_review","rejected","rate_limited","unavailable"],"description":"Every code the API answers with. Each has one HTTP status; the guide at /llms.txt says what to do for each."},"ApiErrorBody":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message"],"additionalProperties":false,"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"A sentence for a person or an agent. Do not match on its wording: match on `code`."},"hint":{"type":"string","description":"What to do next, when there is something specific."},"limit":{"type":"string","description":"`limit_exceeded`: which limit (`disk`, `file_size`, `files`, `sites`, `storage`, `publishes_per_day`, `email_list`, `api_keys`). `too_large`: the size limit of the body."},"missing":{"type":"array","maxItems":100,"items":{"type":"string"},"description":"`upload_incomplete` only: the paths that are missing or arrived with another size or hash."}}}},"example":{"error":{"code":"limit_exceeded","message":"The free plan allows 5 sites and you have 5.","limit":"sites","hint":"Delete a site you no longer need (DELETE /v1/sites/<id>), or update one of the existing sites."}}},"PlanId":{"type":"string","enum":["free","domain","plus","pro"]},"SignInCodeRequest":{"type":"object","required":["email"],"additionalProperties":false,"properties":{"email":{"type":"string","maxLength":320},"invite":{"type":"string","maxLength":128,"description":"The invitation code. Needed by an address that has no account yet."}}},"TokenRequest":{"type":"object","required":["email","code","key_name"],"additionalProperties":false,"properties":{"email":{"type":"string","maxLength":320},"code":{"type":"string","maxLength":16,"description":"The 8 digits from the mail; spaces and hyphens are ignored."},"key_name":{"type":"string","minLength":1,"maxLength":64,"description":"A name for the key so its owner can tell their keys apart. Plain text."}}},"Account":{"type":"object","required":["id","email","plan"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"plan":{"$ref":"#/components/schemas/PlanId"}}},"TokenResponse":{"type":"object","required":["api_key","account"],"additionalProperties":false,"properties":{"api_key":{"type":"string","pattern":"^ah_[0-9A-Za-z]{40}$","description":"Send it as `Authorization: Bearer <key>`. Shown once."},"account":{"$ref":"#/components/schemas/Account"}}},"PlanLimits":{"type":"object","description":"The limits of a plan. The Free plan: 5 sites, 1 GB of storage, 10 GB of transfer a month, 100 MB a file, 1 kept version, 5 e-mail list entries, no `public` mode, a badge on the pages.","required":["sites","publishesPerDay","storageBytes","transferBytesPerMonth","maxFileBytes","customDomains","versionsKept","emailAllowlistMax","customSlug","publicMode","badge"],"additionalProperties":false,"properties":{"sites":{"type":"integer"},"publishesPerDay":{"type":"integer","description":"Publications the account may start in a rolling 24 hours: four for each site the plan allows."},"storageBytes":{"type":"integer"},"transferBytesPerMonth":{"type":"integer"},"maxFileBytes":{"type":"integer"},"customDomains":{"type":"integer"},"versionsKept":{"type":"integer"},"emailAllowlistMax":{"type":["integer","null"],"description":"`null` is unlimited."},"customSlug":{"type":"boolean"},"publicMode":{"type":"boolean"},"badge":{"type":"boolean"}}},"Me":{"type":"object","required":["account","limits","usage"],"additionalProperties":false,"properties":{"account":{"$ref":"#/components/schemas/Account"},"limits":{"$ref":"#/components/schemas/PlanLimits"},"usage":{"type":"object","required":["sites","storageBytes","transferBytesThisMonth"],"additionalProperties":false,"properties":{"sites":{"type":"integer"},"storageBytes":{"type":"integer"},"transferBytesThisMonth":{"type":"integer"}}}}},"Usage":{"type":"object","required":["plan","sites","storage","transfer"],"additionalProperties":false,"properties":{"plan":{"$ref":"#/components/schemas/PlanId"},"sites":{"type":"object","required":["used","limit"],"additionalProperties":false,"properties":{"used":{"type":"integer"},"limit":{"type":"integer"}}},"storage":{"type":"object","required":["usedBytes","limitBytes"],"additionalProperties":false,"properties":{"usedBytes":{"type":"integer"},"limitBytes":{"type":"integer"}}},"transfer":{"type":"object","required":["usedBytes","limitBytes","resetsAt"],"additionalProperties":false,"properties":{"usedBytes":{"type":"integer"},"limitBytes":{"type":"integer"},"resetsAt":{"type":"string","format":"date-time"}}}}},"AccessMode":{"type":"string","enum":["link","password","email","public"]},"AccessRequest":{"type":"object","required":["mode"],"additionalProperties":false,"description":"A setting the mode does not use is refused, not ignored: a `password` sent with `link` is `invalid_request`.","properties":{"mode":{"$ref":"#/components/schemas/AccessMode"},"password":{"type":"string","description":"Only with `password`; 8 to 256 characters. Never stored in plain text."},"emails":{"type":"array","items":{"type":"string"},"description":"Only with `email`. Replaces the list."},"emailDomains":{"type":"array","items":{"type":"string"},"description":"Only with `email`. A lower-case domain with a dot; public and disposable mail domains are refused."},"expiresAt":{"type":["string","null"],"format":"date-time","description":"A date and time WITH a time zone, in the future. `null` removes the expiry."},"revoke":{"type":"boolean","description":"`true` switches access off for everybody; `false` brings it back."}}},"Access":{"type":"object","required":["mode"],"additionalProperties":false,"description":"Who may open the site. The owner sees the lists they set; the password is never returned.","properties":{"mode":{"$ref":"#/components/schemas/AccessMode"},"expiresAt":{"type":"string","format":"date-time"},"revoked":{"const":true},"emails":{"type":"array","items":{"type":"string"}},"emailDomains":{"type":"array","items":{"type":"string"}}}},"SiteStatus":{"type":"string","enum":["pending_upload","checking","live","pending_review","rejected","quarantined","unpublished","deleted"],"description":"`pending_upload`: created, files not closed yet. `checking`: the first release is being checked. `live`: served. `pending_review`: held for a person. `rejected`: refused by the checks. `quarantined`: switched off by a person or a rule, files kept. `unpublished`: taken offline (an idle account), publish again to bring it back. `deleted`."},"ResultStatus":{"type":"string","enum":["live","checking","pending_review","rejected","superseded"],"description":"What the publication answers, one status for the caller to act on. `live`: The release is served. `checking`: The checks are still running. Call `POST /v1/releases/{id}/finalize` again with the `release.id` of this answer; it is safe to repeat. `pending_review`: The release is held for a person; `reasons` says why. Nothing to retry: tell the user that a person will look at it and that the decision comes by mail. If nobody has looked within 72 hours the publication is refused. An update can then be published again; a first publication leaves a `rejected` site that cannot be updated, so the files are published again as a new site and the refused site can be deleted to free its place. For an update, the version that was live keeps serving meanwhile. `rejected`: The safety checks refused the release; `reasons` says why. Do not send the same files again. `superseded`: A newer release went live first, so this one is not served. `pending_review` is the answer, not a status of a release: the site's own status (`site.status`) says whether something is live meanwhile."},"Site":{"type":"object","required":["id","url","slug","status","access","version","storageBytes","updatedAt"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri","description":"The address visitors open: `<slug>.putlive.page`."},"slug":{"type":"string"},"status":{"$ref":"#/components/schemas/SiteStatus"},"access":{"$ref":"#/components/schemas/Access"},"version":{"type":"integer","minimum":0,"description":"The number of the live release; 0 while nothing is live."},"storageBytes":{"type":"integer"},"updatedAt":{"type":"string","format":"date-time"}},"example":{"id":"00000000-0000-4000-8000-000000000000","url":"https://calm-river-0000000000.putlive.page/","slug":"calm-river-0000000000","status":"live","access":{"mode":"link"},"version":1,"storageBytes":14,"updatedAt":"2030-01-01T00:00:00.000Z"}},"FileEntry":{"type":"object","required":["path","size","sha256"],"description":"An unknown key is dropped (`contentType` included: the server decides what a file is from its name). A missing or mistyped `path`, `size` or `sha256` refuses the whole request.","properties":{"path":{"type":"string","description":"A relative path with \"/\" separators: no \"..\", \".\", empty segments, backslashes or control characters; at most 1024 bytes (255 per segment); not under `__gate/`. Two paths that differ only by letter case are refused."},"size":{"type":"integer","minimum":0,"description":"Bytes. A zero-byte file is valid, but the files together may not weigh zero."},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Lower-case hexadecimal."},"contentType":{"type":"string","maxLength":255,"description":"Accepted and ignored."}}},"InlineFile":{"type":"object","required":["path","content"],"description":"An unknown key is dropped. A missing `path` or `content`, or a `content` that is not text, refuses the whole request. The content is text (UTF-8).","properties":{"path":{"type":"string","description":"The same rules as `FileEntry.path`."},"content":{"type":"string"}}},"PublishRequest":{"type":"object","additionalProperties":false,"description":"An unknown key at this level is refused, never dropped. At least one file is needed, and at most 2500 (`files` and `inlineFiles` together). A path may not be in both lists.","properties":{"title":{"type":"string","maxLength":200},"spa":{"type":"boolean","description":"Serve `index.html` for paths that match no file (a single-page app)."},"access":{"$ref":"#/components/schemas/AccessRequest","description":"The access the site starts with. Default: `link`. On an update the access is changed after everything else has worked."},"files":{"type":"array","items":{"$ref":"#/components/schemas/FileEntry"},"description":"Files to upload afterwards with PUT."},"inlineFiles":{"type":"array","items":{"$ref":"#/components/schemas/InlineFile"},"description":"Small text files sent in the request, 256 KB together. With only these the call is finalized for you."}}},"PublishTicket":{"type":"object","required":["site","release","uploads","finalizeUrl","expiresAt"],"additionalProperties":false,"properties":{"site":{"$ref":"#/components/schemas/Site"},"release":{"type":"object","required":["id","number"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"integer","minimum":1}}},"uploads":{"type":"array","description":"Only the files the storage does not hold yet.","items":{"type":"object","required":["path","method","url"],"additionalProperties":false,"properties":{"path":{"type":"string"},"method":{"const":"PUT"},"url":{"type":"string","format":"uri"}}}},"finalizeUrl":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time","description":"The upload session ends 30 minutes after the release was created."}}},"CheckSummary":{"type":"object","required":["name","status"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"`malware`, `links`, `impersonation`, `credential_forms` or `coverage`."},"status":{"type":"string","enum":["passed","failed","skipped","pending"],"description":"`pending`: the check could not run yet or waits for a person. It is never read as passed."},"detail":{"type":"string"}}},"FinalizeResult":{"type":"object","required":["status","release","site","checks"],"additionalProperties":false,"properties":{"status":{"$ref":"#/components/schemas/ResultStatus"},"release":{"type":"object","required":["id","number"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"integer","minimum":1}}},"site":{"$ref":"#/components/schemas/Site"},"checks":{"type":"array","items":{"$ref":"#/components/schemas/CheckSummary"}},"reasons":{"type":"array","items":{"type":"string"},"description":"In plain sentences, why a release was refused or held. Show them to the user."}}},"UploadResult":{"type":"object","required":["path","size"],"additionalProperties":false,"properties":{"path":{"type":"string"},"size":{"type":"integer","minimum":0}}},"RollbackRequest":{"type":"object","additionalProperties":false,"properties":{"version":{"type":"integer","minimum":1,"description":"A release number (`Site.version` of an older state). Without it: the previous version."}}},"ReportRequest":{"type":"object","required":["url","category","explanation","reporterEmail","goodFaith"],"additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2000,"description":"The address of a site published here: one label under `putlive.page`."},"category":{"type":"string","enum":["phishing","malware","illegal_content","copyright","adult","spam_redirect","terms","legal_order"]},"explanation":{"type":"string","minLength":10,"maxLength":4000},"reporterName":{"type":"string","maxLength":200},"reporterEmail":{"type":"string","description":"An address that can receive the receipt; it must be confirmed."},"goodFaith":{"const":true,"description":"The reporter states that the information is accurate and complete to the best of their knowledge."}}},"ReportReceipt":{"type":"object","required":["id","quarantined","message"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"quarantined":{"const":false},"message":{"type":"string"}}},"ReportConfirmRequest":{"type":"object","required":["token"],"additionalProperties":false,"properties":{"token":{"type":"string","maxLength":200}}}},"responses":{"Error400":{"description":"An error. The `error.code` is one of: `invalid_request` (The request is malformed or breaks a rule of the API. Fix it and send it again.)","headers":{"Cache-Control":{"description":"Always `no-store`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}},"Error401":{"description":"An error. The `error.code` is one of: `unauthorized` (No valid API key, or a wrong or expired sign-in code.)","headers":{"Cache-Control":{"description":"Always `no-store`.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Always `Bearer`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}},"Error403":{"description":"An error. The `error.code` is one of: `forbidden` (The request is understood and refused: country, invitation, plan, a switched-off site, an expired upload session.) `limit_exceeded` (A limit of the plan or of the service is reached. `error.limit` names which.) `rejected` (The site was refused by the safety checks and cannot be updated.)","headers":{"Cache-Control":{"description":"Always `no-store`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}},"Error404":{"description":"An error. The `error.code` is one of: `not_found` (No such thing, or it belongs to somebody else.)","headers":{"Cache-Control":{"description":"Always `no-store`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}},"Error409":{"description":"An error. The `error.code` is one of: `conflict` (The request does not fit the current state, or another change was being finished. Read the message.) `upload_incomplete` (Files are missing or arrived with another size or hash. `error.missing` lists them.) `pending_review` (The site waits for a person to review it. Nothing can be changed until that is done.)","headers":{"Cache-Control":{"description":"Always `no-store`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}},"Error413":{"description":"An error. The `error.code` is one of: `too_large` (The request body is over its size limit.)","headers":{"Cache-Control":{"description":"Always `no-store`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}},"Error429":{"description":"An error. The `error.code` is one of: `rate_limited` (Too many requests. Wait for `Retry-After` seconds.)","headers":{"Cache-Control":{"description":"Always `no-store`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds until the request budget is back.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}},"Error503":{"description":"An error. The `error.code` is one of: `unavailable` (The service or its storage cannot answer now. Nothing was changed. Try again.)","headers":{"Cache-Control":{"description":"Always `no-store`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}}}}}