# putlive > putlive hosts what an AI agent made (a page, a small site, a single-page app, a file) and gives back a link. The link is private by default. This page is written for you, the agent: read it before you publish. The API is at https://api.putlive.dev. Its machine-readable description (OpenAPI 3.1) is https://api.putlive.dev/openapi.json. Published sites live at `.putlive.page`. ## What this service is for Use it when a person asks you to put something online or share it as a link: "publish this", "host this", "share this as a link", "put this online", "make this page private". You send the files, the service checks them, and you get an address you can hand to the person. It serves static files only. No code of yours runs on the server. A page can have scripts that run in the visitor's browser, but there is no backend, no database and no secret kept for you. ## Rules that always apply 1. **The default is a private link.** A new site gets a long random address and tells search engines to skip it. Anyone who has the address can open it. That is the safe starting point. 2. **Widening access needs the user's word.** Do not set `public`, and do not remove a password or an e-mail list, unless the user said so in this conversation. Narrowing access (a password, a list of addresses, an expiry) you may offer. 3. **Never publish secrets or other people's data.** Not API keys, tokens, passwords, `.env` files, private keys, cookies, or exports that hold other people's personal data. If a file looks like one of these, stop and ask the user. A published file can be opened by everyone who has the link. 4. **A page that calls a model from inside a sandbox will not work once published.** An artifact or demo that calls an AI model through the sandbox it was made in (no key of its own) has no such sandbox here, so those calls fail. Tell the user before you publish. 5. **Tell the user the truth about the result.** Say the address, who can open it, and, if the service held or refused the publication, why (see below). Do not call something published that is not `live`. 6. **Keep the API key secret.** It is shown once. Do not print it in the chat, do not write it into a file you publish, do not commit it. ## Install You can use the HTTP API below with `curl` alone (and `sha256sum` when you upload files). You can also install the Agent Skill of this service, which teaches an agent the same steps and brings a publisher script that needs only `bash`, `curl` and `jq`: run `curl -fsSL https://putlive.dev/install.sh | sh` (it writes two files into your skills folder, asks before replacing an old copy, runs nothing it downloads and says what it wrote). The skill's files are also at https://putlive.dev/.well-known/skills/index.json. The command-line client of this service is not released yet: do not run `npx` or `npm install` for a package of this name, it is not ours. ## Sign in Accounts are by invitation for now. The user needs an invitation code (the `invite`) the first time. After that the e-mail address alone is enough. 1. Ask the user for their e-mail address (and the invitation code if they have not signed in before). 2. Request a code: ``` curl -sS -X POST https://api.putlive.dev/v1/auth/code \ -H 'Content-Type: application/json' \ -d '{"email":"person@example.com","invite":"EXAMPLE-INVITE"}' ``` The answer is 204 and nothing else. A mail with an **8-digit code** is on its way, shown as two groups of four (`0000 0000`). It works once and for 10 minutes. 3. Ask the user to read the code from their mail and tell it to you. **Never guess a code.** A code is looked at 5 times and then it is dead. If the code was wrong or too old, **do not ask for it again straight away: request a new code first** (step 2), then ask for the new one. At most 5 codes an hour go to one address. 4. Trade the code for a key: ``` curl -sS -X POST https://api.putlive.dev/v1/auth/token \ -H 'Content-Type: application/json' \ -d '{"email":"person@example.com","code":"0000 0000","key_name":"my agent"}' ``` The answer holds `api_key` (it starts with `ah_`). Keep it for the rest of the session and send it on every call as `Authorization: Bearer `. If you lose it, sign in again for a new one. Sign-up from some countries is refused (`forbidden`); the United Kingdom is closed at the launch. Throw-away e-mail domains are refused too. ## Publish with one request For a small page or site (text files, up to 256 KB together) one request is enough. The service stores the files, runs the checks and answers when they are done: ``` curl -sS -X POST 'https://api.putlive.dev/v1/sites?wait=60' \ -H "Authorization: Bearer $API_KEY" \ -H 'Content-Type: application/json' \ -d '{"title":"My page","inlineFiles":[{"path":"index.html","content":"

Hello

"}]}' ``` The answer has `status`, `site.url` (the address to give the user), `site.id` and `release.id`. Act on `status`, and only on it: - `live`: it went up. Give the user `site.url` and say who can open it. - `checking` (HTTP 202): the checks are still running. Call `POST https://api.putlive.dev/v1/releases//finalize?wait=60` again, and again, until the status is something else. Repeating that call is safe. - `pending_review` (HTTP 200): the publication is held for a person. **Stop. There is nothing to retry and nothing to wait for in a loop.** Tell the user that a person will look at it and that the decision comes by e-mail. If nobody has looked within 72 hours the publication is refused: an update can then be published again, but a first publication leaves a `rejected` site, which cannot be updated, so it has to be deleted (`DELETE https://api.putlive.dev/v1/sites/`) and published again as a new site. Show the `reasons`. If this was an update, the version that was live keeps serving meanwhile. - `rejected`: refused by the safety checks. Show the `reasons` to the user; do not send the same files again. A single-page app that must answer every path with `index.html`: add `"spa":true`. ## Publish a bigger site, or binary files 1. For each file work out its path (relative, `/` separators, no `..`), its size in bytes and its SHA-256 in lower-case hex. 2. `POST https://api.putlive.dev/v1/sites` with `{"files":[{"path":"index.html","size":14,"sha256":"<64 hex>"}]}` (you may add `inlineFiles` for small text files). The answer is 201 with `uploads` (one entry per file the service does not hold yet), `finalizeUrl` and `release.id`. 3. For each entry of `uploads`: `curl -sS -X PUT "" -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/octet-stream' --data-binary @file`. Use the `url` exactly as given: each path segment is already percent-encoded. 4. `POST` the `finalizeUrl` (add `?wait=60`). If it answers `upload_incomplete`, `error.missing` lists the paths to upload again. To publish a new version of a site you already made, `POST https://api.putlive.dev/v1/sites//releases` with the same body. Files that did not change are reused. The upload session of a release lasts 30 minutes. A publication has at most 2500 files; an account may start 4 publications in 24 hours for each site the plan allows (20 on Free). ## Who can open a site `PATCH https://api.putlive.dev/v1/sites//access` with a `mode`: - `link` (default): anyone with the secret address. - `password`: visitors are asked for a password you set (`password`, 8 to 256 characters). - `email`: visitors give an e-mail address from your list (`emails`, or `emailDomains`) and get a code by mail. - `public`: searchable, no secret in the address. Not on the Free plan (`forbidden`), and never without the user's word. Optional: `expiresAt` (a date and time with a time zone, in the future, or `null`) and `revoke` (`true` switches access off for everybody). Other calls: `GET /v1/sites`, `GET /v1/sites/`, `POST /v1/sites//rollback`, `DELETE /v1/sites/` (refused with `conflict` while the site is switched off, waits for a person or has a report that its sender confirmed and we have not decided yet: tell the user the message and stop), `GET /v1/me`, `GET /v1/usage`. ## What happens after you publish - **Every publication of a Free account is checked before it is served.** The checks look for malware, for dangerous links, for pages that imitate another service, and for password or card forms. This takes seconds, sometimes longer. - **Held for a person.** A publication that looks risky (for example a page with a password field, or links that could not be checked) is held. The answer has `status` `pending_review` and `reasons`. A person looks at it and the decision comes to the user by e-mail; after 72 hours without a decision it is refused. A held update can then be published again; a held first publication leaves a `rejected` site that cannot be updated, so delete it and publish the files as a new site. Tell the user the publication is waiting for a review and why (`reasons`) and stop: do not retry, do not poll. A held first publication has `site.status` `pending_review` and cannot be changed meanwhile (`pending_review` error). A held update leaves `site.status` `live`: the version that was live keeps serving until the person decides. - **Refused.** `status` is `rejected` and `reasons` says why in plain sentences. Show the reasons to the user. Do not try to get the same files through again; fix the cause or stop. - **An update never takes the live version down while it is checked.** If the new version is held or refused, the old one keeps serving. - **A site can answer visitors with 509 for the rest of the month** when the account has used its monthly transfer. `GET /v1/usage` shows the numbers and `transfer.resetsAt`, when they reset. The site comes back by itself at that moment. - **An account that is not used for 90 days loses its publications.** After two warnings by mail the sites go offline at 90 days (the files are kept for a while) and are deleted later. Using the API key or signing in counts as use. - A site can be switched off after a report or a check (`quarantined`). It cannot be updated then (`forbidden`); the user should contact support. ## Errors Every error is JSON: `{"error":{"code","message","hint?","limit?","missing?"}}`. Decide by `code`, never by the wording of `message`. Show the user the `message` and the `hint` when you cannot fix the cause yourself. This list is complete: it holds every code the API answers with. - `invalid_request` (400): the request is wrong. Read `message` and `hint`, fix the request, send it again. Do not repeat it unchanged. - `unauthorized` (401): no valid key, or the sign-in code was wrong or too old. For a key: sign in again. For a code: request a new code first, then ask the user for it. - `forbidden` (403): refused on purpose: no invitation, a country that is closed, a throw-away address, the `public` mode on the Free plan, a switched-off site, or an upload session that ended. Do not retry. Tell the user; for an ended session start a new release. - `not_found` (404): no such site or release, or it is not this account's. Check the id with `GET /v1/sites`. - `conflict` (409): the request does not fit the state (for example "not live", "already live", "no earlier version"), or another change was being finished. If the message says another change is in progress, wait a few seconds and repeat once. Otherwise change the request. Deleting a site that is switched off, waits for a person or has a report that its sender confirmed and we have not decided yet is refused with `conflict`: its files are kept until the case is closed. Show the user the `message` and `hint`; do not retry. - `limit_exceeded` (403): a limit is reached; `error.limit` names it: `sites`, `storage`, `file_size`, `files`, `publishes_per_day`, `email_list`, `api_keys` or `disk`. For `sites` or `storage` offer to delete a site you no longer need, with the user's word. For `file_size` and `files` publish fewer or smaller files. For `publishes_per_day` wait or combine changes. For `api_keys` (signing in by a code: an account holds at most 20 active keys, and the refusal does not use the code up) ask the user to revoke a key they no longer use on the keys page of the dashboard, then call again with the same code, or ask for a new one. For `disk` the service is paused for a moment: try again later (minutes, not seconds). The user can upgrade the plan. - `too_large` (413): the request body is over its limit (`error.limit`). Send less: move large files from `inlineFiles` to `files` and upload them. - `upload_incomplete` (409): files are missing or arrived with another size or hash; `error.missing` lists the paths. Upload exactly those again, then finalize again. - `pending_review` (409): the site waits for a person, so it cannot be changed now. Do not retry. Tell the user. (The answer of a publication that was itself held is not this error: it is a 200 with `status` `pending_review`, see above.) - `rejected` (403): the safety checks refused the site. Do not retry. Tell the user the reasons. - `rate_limited` (429): too many requests (120 a minute per key, 1200 a minute for uploads, and per-hour limits on sign-in, reports and report confirmations: 5 codes an hour per address, 10 reports an hour and 60 confirmation attempts an hour per client network). Wait `Retry-After` seconds, then continue; slow down. - `unavailable` (503): the service or its storage cannot answer. Nothing was changed. Wait a little and repeat the same call, up to three times with growing pauses, then tell the user. On a sign-up it can also mean that sign-ups are paused for a moment while the service makes room. ## Report a page Anyone can report an address under `putlive.page` with `POST https://api.putlive.dev/v1/reports` (no key) or at https://putlive.dev/report. The reporter must confirm the receipt that is mailed to them.