Docs
Give it to your agent
Paste this to an AI agent. It reads the guide below, signs you in with a code sent to your e-mail address, and publishes what you ask for.
Read https://putlive.dev/llms.txt and follow it: it explains how to publish what you made with putlive and give me a link. If you can use skills, install the putlive skill first with `curl -fsSL https://putlive.dev/install.sh | sh`. Publish what I ask as a private link, tell me who can open it, ask me before you make it more public, and never publish anything that looks like a password, a key or someone else's personal data.
Install the skill
An agent that can use skills can install the putlive skill. The installer writes two files into the agent's skills folder, asks before it replaces an old copy, and runs nothing it downloads:
curl -fsSL https://putlive.dev/install.sh | shThe skill's files are listed at /.well-known/skills/index.json and, in the layout of the draft Agent Skills discovery RFC, at /.well-known/agent-skills/index.json.
The API
The API is at https://api.putlive.dev. Its description (OpenAPI 3.1) is /openapi.json; the guide below is also served as plain text at /llms.txt.
The guide for agents
This is the text an agent reads. It is the same as https://putlive.dev/llms.txt.
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 <name>.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
- 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.
- 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. - Never publish secrets or other people's data. Not API keys, tokens, passwords,
.envfiles, 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. - 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.
- 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. - 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.
- Ask the user for their e-mail address (and the invitation code if they have not signed in before).
- 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 <key>. 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":"<h1>Hello</h1>"}]}'
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 usersite.urland say who can open it.checking(HTTP 202): the checks are still running. CallPOST https://api.putlive.dev/v1/releases/<release.id>/finalize?wait=60again, 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 arejectedsite, which cannot be updated, so it has to be deleted (DELETE https://api.putlive.dev/v1/sites/<site.id>) and published again as a new site. Show thereasons. If this was an update, the version that was live keeps serving meanwhile.rejected: refused by the safety checks. Show thereasonsto 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
- For each file work out its path (relative,
/separators, no..), its size in bytes and its SHA-256 in lower-case hex. POST https://api.putlive.dev/v1/siteswith{"files":[{"path":"index.html","size":14,"sha256":"<64 hex>"}]}(you may addinlineFilesfor small text files). The answer is 201 withuploads(one entry per file the service does not hold yet),finalizeUrlandrelease.id.- For each entry of
uploads:curl -sS -X PUT "<url>" -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/octet-stream' --data-binary @file. Use theurlexactly as given: each path segment is already percent-encoded. POSTthefinalizeUrl(add?wait=60). If it answersupload_incomplete,error.missinglists the paths to upload again.
To publish a new version of a site you already made, POST https://api.putlive.dev/v1/sites/<site.id>/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/<site.id>/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, oremailDomains) 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/<id>, POST /v1/sites/<id>/rollback, DELETE /v1/sites/<id> (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
statuspending_reviewandreasons. 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 arejectedsite 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 hassite.statuspending_reviewand cannot be changed meanwhile (pending_reviewerror). A held update leavessite.statuslive: the version that was live keeps serving until the person decides. - Refused.
statusisrejectedandreasonssays 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/usageshows the numbers andtransfer.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. Readmessageandhint, 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, thepublicmode 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 withGET /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 withconflict: its files are kept until the case is closed. Show the user themessageandhint; do not retry.limit_exceeded(403): a limit is reached;error.limitnames it:sites,storage,file_size,files,publishes_per_day,email_list,api_keysordisk. Forsitesorstorageoffer to delete a site you no longer need, with the user's word. Forfile_sizeandfilespublish fewer or smaller files. Forpublishes_per_daywait or combine changes. Forapi_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. Fordiskthe 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 frominlineFilestofilesand upload them.upload_incomplete(409): files are missing or arrived with another size or hash;error.missinglists 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 withstatuspending_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). WaitRetry-Afterseconds, 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.
The putlive API: error catalogue
Every answer of the API that is not a success has the same body (ApiErrorBody in @app/shared, ApiErrorBody in
https://api.putlive.dev/openapi.json):
{ "error": { "code": "limit_exceeded", "message": "…", "hint": "…", "limit": "sites", "missing": ["a.png"] } }
codeis one of the twelve below. Decide bycode, never by the wording ofmessage.messageis a sentence for a person.hint(optional) says what to do next.limit(optional) is set bylimit_exceededandtoo_large.missing(optional) is set byupload_incomplete.- Every answer carries
Cache-Control: no-store.rate_limitedcarriesRetry-After(seconds),unauthorizedcarriesWWW-Authenticate: Bearer. - The statuses are the same in the OpenAPI document at
https://api.putlive.dev/openapi.jsonand in the guide athttps://putlive.dev/llms.txt.
"Retry" below means the same request, unchanged. "Change the request" means the request was wrong or does not fit the state. "Ask the user" means: stop, tell the person in plain words what happened and what the options are.
| Code | HTTP | Next step in one word |
|---|---|---|
invalid_request | 400 | change the request |
unauthorized | 401 | sign in again / ask for a new code |
forbidden | 403 | stop, ask the user |
not_found | 404 | check the id |
conflict | 409 | read the message; retry once or change the request |
limit_exceeded | 403 | by limit |
too_large | 413 | send less |
upload_incomplete | 409 | upload missing again |
pending_review | 409 | wait, ask the user |
rejected | 403 | stop, tell the reasons |
rate_limited | 429 | wait Retry-After |
unavailable | 503 | retry with growing pauses |
Three codes share 403 (forbidden, limit_exceeded, rejected) and three share 409 (conflict, upload_incomplete,
pending_review): the status alone does not tell them apart, code does.
invalid_request — 400
What happened. The request is malformed or breaks a rule: a body that is not JSON, an unknown key (the top level of a
publication and of every body is strict: an unknown key is refused, never dropped), a wrong type, a path that cannot be
published (.., a leading /, a backslash, an empty segment, two paths equal when letter case is ignored, anything
under __gate/), a file that is also a folder, an empty file list, a sha256 that is not 64 lower-case hex characters, a path
in both files and inlineFiles, an upload path that is not in the file list, an access setting the mode does not use (a
password with link), a wait that is not a number, a malformed e-mail address, a report without the good-faith statement.
What to do. Read message and hint: they say what is wrong. Fix the request and send it again. A refused publication
stored nothing, so nothing needs cleaning up. Never send the same request again unchanged.
unauthorized — 401
What happened. On a call with a key: the Authorization: Bearer <key> header is missing, malformed, unknown or the key was
revoked (all look the same from outside). On POST /v1/auth/token: the sign-in code is wrong, expired, already used or used up
its 5 looks (all look the same).
What to do. For a key: sign in again (POST /v1/auth/code, then POST /v1/auth/token) and use the new key. For a code:
request a new code first, then ask the user for the new one. Do not ask the user for the same code twice in a row, and never
guess a code: it has 8 digits, works once, for 10 minutes, and is looked at 5 times.
forbidden — 403
What happened. The request is understood and refused on purpose:
- sign-up needs an invitation (
hint:invite required); the address has no account and sent no valid invite; - the country is closed (the United Kingdom at launch), or the address is a throw-away mail domain;
- the
publicaccess mode on the Free plan; - the site is switched off (
quarantined) and cannot be updated; - the upload session of a release ended (it lasts 30 minutes from the creation of the release).
What to do. Do not retry; it will be refused again. Ask the user. For an ended upload session create a new release
(POST /v1/sites/{id}/releases) and upload the files again. For a switched-off site the user should contact support.
not_found — 404
What happened. There is no such site, release or report token, or it belongs to another account (the answer is the same, on
purpose), or the id is not a UUID. A report token is also not_found when it was used or is older than 24 hours.
What to do. Check the id with GET /v1/sites. Do not retry the same id.
conflict — 409
What happened. The request does not fit the state of the site, or another change was being finished:
- "another change to this site or account is being finished": a lock was busy for 2 seconds;
- a rollback of a site that is not live, a version that is not kept, a version that is already live, or on the Free plan (which keeps only the live version, so there is no earlier one);
- the storage holds files that are not in the release's file list;
- an upload to a release that is no longer open;
- a delete of 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: the files are kept until the case is closed, and the message says what to do.
What to do. Read message. If another change is being finished, wait a few seconds and repeat once. Otherwise change the
request: for a closed release start a new one; for a delete refused for a site under review, show the user the message (reply to the e-mail
about the site; the site can be deleted once the case is closed) and do not retry; for a rollback choose a kept version (the message lists them) or do not roll back.
limit_exceeded — 403
What happened. A limit of the plan or of the service is reached. error.limit says which:
limit | Meaning | What to do |
|---|---|---|
sites | the account has as many sites as its plan allows | with the user's word delete a site you no longer need (DELETE /v1/sites/{id}), or update an existing site |
storage | the account would hold more than its plan's storage | delete a site you no longer need, or publish fewer or smaller files; files a safety check refused are kept 30 days and count (the hint says how to free them) |
file_size | one file is over the plan's file size | compress or split the file, or leave it out |
files | more than 2500 files in one site | bundle the site, or drop files it does not need |
publishes_per_day | the plan's number of publications in 24 hours (four for each site the plan allows: 20 on Free); the message names it | wait, and put several changes into one publication |
email_list | too many addresses and domains in an e-mail list (the plan's cap, and 1000 on any plan) | shorten the list; the user can upgrade the plan |
api_keys | an account holds at most 20 active keys, so POST /v1/auth/token cannot make another (the code is not used up by the refusal) | the user revokes a key they no longer use, on the keys page of the dashboard, then calls again with the same code (or asks for a new one) |
disk | the storage is nearly full, so publishing or uploading is paused for a moment (for Free accounts first) | try again later, in minutes, not seconds; tell the user if it lasts |
What to do. Follow the row. Ask the user before deleting anything. Do not retry the same request while the cause stands.
too_large — 413
What happened. The request body is over its limit; error.limit says the limit (for example 2097152 bytes for a
publication, or 256 KB of inline files). The body is cut off while it is read, so a huge body is never stored.
What to do. Send less. Move large files from inlineFiles to files and upload them with PUT; split an e-mail list.
upload_incomplete — 409
What happened. Files are missing, or arrived with another size or hash than the file list says, or an upload announced
another Content-Length, was longer than announced, or stopped early. error.missing lists the paths (at most 100; the message
counts the rest). Nothing is live yet.
What to do. Upload exactly the listed paths again with PUT /v1/uploads/{releaseId}/{path} (each path segment percent-encoded),
then call finalize again. If the file changed while you worked, recompute its size and hash and start a new release.
pending_review — 409
What happened. The site waits for a person to look at it (a publication of a Free account was held: a password field, links that could not be checked, a page that may imitate another service). It cannot be changed until that is done.
What to do. Do not retry in a loop. Tell the user that the publication is waiting for a review and why (reasons of the
publication answer). A publication that waits too long for a person (72 hours) is refused.
Not to be confused with the status of a publication's answer. A publish or finalize call whose release was itself held
answers HTTP 200 with status: "pending_review" and reasons (it is not this error): stop, tell the user that a person will look
at it and that the decision comes by mail. For an update the version that was live keeps serving meanwhile (site.status stays
live). status: "checking" (HTTP 202) is different: the checks are still running, call finalize again.
rejected — 403
What happened. The safety checks refused the site (malware, a dangerous link, a page that imitates another service). It
cannot be updated. reasons of the publication answer say why in plain sentences.
What to do. Stop. Show the reasons to the user. Do not send the same files again. If the user thinks it is a mistake they can
contact support. A first publication that was refused leaves a site in the status rejected; delete it to free its storage.
rate_limited — 429
What happened. Too many requests. The budgets: 120 requests a minute per API key for everything except uploads, 1200 a
minute per key for PUT /v1/uploads/...; per hour: 5 sign-in codes per e-mail address, 20 per client network, 20 code
redemptions per client network, 10 reports per client network, 60 report-confirmation attempts per client network.
What to do. Wait Retry-After seconds (also in the header), then continue. Slow down: space the calls and upload fewer
files in parallel.
unavailable — 503
What happened. The service, or the storage behind it, could not answer. Nothing was changed: a change the storage must enforce (an access change, a delete, a publication) is made on the storage first and is not recorded if the storage fails. It can also mean that the service is not set up to publish, that the checks could not be started (finalize again), or, on a sign-up, that sign-ups are paused for a moment while the service makes room.
What to do. Retry the same request after a pause, up to three times with growing pauses (for example 2, 10 and 30 seconds). If it still fails, tell the user. Do not start a second release for the same files while the first may still be open.
What a visitor sees
These are not API errors, but an agent is asked about them. A published site answers visitors with 404 for an address it does
not know, 410 for a site that was taken offline (unpublished) or whose access expired or was revoked, 451 for a closed country
or a site that was switched off after a report or a check (quarantined), and 509 when the account has used its monthly
transfer. GET /v1/usage shows transfer.usedBytes, transfer.limitBytes and transfer.resetsAt; the site is served again
from that moment.