Sites
List, inspect and manage websites.
GET /v1/export
Download an owner-authorised archive of website files and stored data. It may include historical private data from before the previous storage model was retired. Keep the archive and any download link private.
No authentication required.
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| token | query | string | yes |
Responses:
| Status | Description |
|---|---|
| 200 | A gzipped tar archive |
| 404 | The link is not valid or has expired |
| 429 | Rate limited (code rate_limited). Saved-data reads allow 30 a second per address with a burst of 60 (SAVED_DATA_READ_PER_SEC, SAVED_DATA_READ_BURST). |
GET /v1/sites
Returns the authenticated account’s own sites, newest edited first (updated_at desc, then created_at desc). all=1 widens an admin’s list to every account’s sites; refused (403) for a non-admin. On simple-hack.app (EVENTS=hosted) only a team key (or a connector bound to a team) deploys, to its own team’s site only; errors 403 no_personal_sites, 403 team_site_only, 403 team_key_scope, 401 team_key_inactive, 409 team_sites_not_ready, 409 submissions_closed, 403 team_site_taken_down.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| query | query | string | Every word must match the name, domain or summary (case-insensitive substrings). | |
| created_after | query | string | Created on or after RFC3339 or YYYY-MM-DD (UTC midnight). | |
| created_before | query | string | Created on or before RFC3339 or YYYY-MM-DD (UTC whole day). | |
| updated_after | query | string | Updated on or after RFC3339 or YYYY-MM-DD (UTC midnight). | |
| updated_before | query | string | Updated on or before RFC3339 or YYYY-MM-DD (UTC whole day). | |
| order | query | string, one of updated, created, name |
Sort key; default updated (last edited first). | |
| limit | query | integer | Maximum results, clamped to 500; default 200 when any filter or paging parameter is present. | |
| offset | query | integer | Skip this many matching sites. | |
| all | query | string, one of 1 |
Admin only: every account’s sites instead of just this one. 403 for a non-admin. |
Responses:
| Status | Description |
|---|---|
| 200 | List of sites |
| 400 | Invalid date (bad_date), order (bad_order), or non-negative integer required for limit/offset (bad_pagination). |
| 401 | Missing or invalid API key — send the X-API-Key header, not Authorization Bearer. The body’s code is missing_api_key, wrong_auth_header, invalid_api_key, key_expired or key_expired_idle (create a new key from the Keys panel). |
| 403 | all=1 from a non-admin. |
PATCH /v1/sites/{sitename}
Change the website’s offline status or name. While offline, visitor storage reads and writes are refused; versions and stored resources remain available to the owner.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sitename | path | string | yes |
Request body:
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | The new name (renames the site). | |
| offline | boolean | true takes the site offline; false puts it back online. |
Responses:
| Status | Description |
|---|---|
| 200 | Renamed (old_name, name, old_url, site_url, old_url_status) or switched (the site object with offline and note) |
| 400 | Invalid request. A saved-data write whose JSON holds a NUL character (\u0000), half of a surrogate pair or bytes that are not UTF-8 is code invalid_json. |
| 401 | Missing or invalid API key — send the X-API-Key header, not Authorization Bearer. The body’s code is missing_api_key, wrong_auth_header, invalid_api_key, key_expired or key_expired_idle (create a new key from the Keys panel). |
| 403 | The operator has taken the site down (code site_suspended) |
| 404 | Not found |
| 409 | Conflict: the code says which (site_exists, domain_taken, append_only, custom_domain_required, not_an_object) |
DELETE /v1/sites/{sitename}
Take the website offline and move it to Recently deleted, retaining its versions and stored resources until the restoration deadline.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sitename | path | string | yes |
Responses:
| Status | Description |
|---|---|
| 204 | Site deleted (restorable for 7 days) |
| 401 | Missing or invalid API key — send the X-API-Key header, not Authorization Bearer. The body’s code is missing_api_key, wrong_auth_header, invalid_api_key, key_expired or key_expired_idle (create a new key from the Keys panel). |
| 404 | Not found |
POST /v1/sites/{sitename}/export-link
Download an owner-authorised archive of website files and stored data. It may include historical private data from before the previous storage model was retired. Keep the archive and any download link private.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | string | Opaque key for a create request. For 24 hours, the same authenticated account, POST path and query, key and exact request body replay the original handler status and body, including errors, without executing it again. A different body under that key returns 409 idempotency_key_reused. Concurrent identical requests wait for the first response. Stored only in this server’s memory; a restart clears it. Authentication and rate limiting still apply to replays. A replay does not extend a minted link’s expiry; use a new key to request a new link. Storage row creates support owner credentials and signed-in visitors; anonymous writes ignore this header. Storage replay also checks current resource permissions and is scoped to the resolved site. | |
| sitename | path | string | yes |
Responses:
| Status | Description |
|---|---|
| 200 | The link |
| 401 | Missing or invalid API key — send the X-API-Key header, not Authorization Bearer. The body’s code is missing_api_key, wrong_auth_header, invalid_api_key, key_expired or key_expired_idle (create a new key from the Keys panel). |
| 404 | Not found |
| 409 | Idempotency-Key reused with a different body (idempotency_key_reused). |
GET /v1/sites/{sitename}/export.tar.gz
Download an owner-authorised archive of website files and stored data. It may include historical private data from before the previous storage model was retired. Keep the archive and any download link private.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sitename | path | string | yes |
Responses:
| Status | Description |
|---|---|
| 200 | A gzipped tar archive |
| 404 | Not found |
| 429 | Rate limited (code rate_limited). Saved-data reads allow 30 a second per address with a burst of 60 (SAVED_DATA_READ_PER_SEC, SAVED_DATA_READ_BURST). |
GET /v1/sites/{sitename}/lock
Owner only (the owner’s key or connector token; a deploy-only key is refused). Says whether the site asks visitors for a passcode and, when it does, the passcode itself and when it was set. The passcode is stored sealed with a server key (AES-256-GCM under PASSCODE_ENC_KEY), so the owner can read it back; the admin’s routes never read it. If the server’s key changed, passcode is absent and note says to set a new one. Never cached (Cache-Control: no-store).
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sitename | path | string | yes |
Responses:
| Status | Description |
|---|---|
| 200 | The site’s passcode state |
| 401 | Missing or invalid API key — send the X-API-Key header, not Authorization Bearer. The body’s code is missing_api_key, wrong_auth_header, invalid_api_key, key_expired or key_expired_idle (create a new key from the Keys panel). |
| 403 | A deploy-only key (deploy_only_key) |
| 404 | Not found |
PUT /v1/sites/{sitename}/lock
Set or generate the owner’s website passcode through this trusted REST route. Visitors must unlock each host before viewing the site. A passcode is a site gate, not per-person privacy for a storage resource.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sitename | path | string | yes |
Request body:
| Name | Type | Required | Description |
|---|---|---|---|
| generate | boolean | true: the server picks 6 random digits | |
| passcode | string | At least PASSCODE_MIN_LENGTH characters (default 6) |
Responses:
| Status | Description |
|---|---|
| 200 | The passcode is set (the answer carries it) |
| 400 | Body is not {“passcode”: “…”} or {“generate”: true} (invalid_request), or the passcode is too short or too long (invalid_passcode) |
| 401 | Missing or invalid API key — send the X-API-Key header, not Authorization Bearer. The body’s code is missing_api_key, wrong_auth_header, invalid_api_key, key_expired or key_expired_idle (create a new key from the Keys panel). |
| 403 | The operator has taken the site down (site_suspended), or a deploy-only key (deploy_only_key) |
| 404 | Not found |
| 409 | passcodes_not_enabled (SITE_PASSCODES is off or PASSCODE_ENC_KEY is unset on this server), or passcode_needs_own_address (every site on this server shares one address, as on a small box or an event box, so an unlock would cover every site) |
| 429 | Rate limited (code rate_limited). Saved-data reads allow 30 a second per address with a burst of 60 (SAVED_DATA_READ_PER_SEC, SAVED_DATA_READ_BURST). |
DELETE /v1/sites/{sitename}/lock
Owner only (the owner’s key or connector token; a deploy-only key is refused). Every address of the site opens to everyone again. Removing a passcode the site does not have is not an error.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sitename | path | string | yes |
Responses:
| Status | Description |
|---|---|
| 200 | The site has no passcode |
| 401 | Missing or invalid API key — send the X-API-Key header, not Authorization Bearer. The body’s code is missing_api_key, wrong_auth_header, invalid_api_key, key_expired or key_expired_idle (create a new key from the Keys panel). |
| 403 | A deploy-only key (deploy_only_key) |
| 404 | Not found |
| 429 | Rate limited (code rate_limited). Saved-data reads allow 30 a second per address with a burst of 60 (SAVED_DATA_READ_PER_SEC, SAVED_DATA_READ_BURST). |
POST /v1/sites/{sitename}/lock/sign-out-everyone
Owner only (the owner’s key or connector token; a deploy-only key is refused). Ends every unlock at once, on every address: each visitor must enter the passcode again. The passcode stays the same.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sitename | path | string | yes |
Responses:
| Status | Description |
|---|---|
| 200 | Everyone is signed out |
| 401 | Missing or invalid API key — send the X-API-Key header, not Authorization Bearer. The body’s code is missing_api_key, wrong_auth_header, invalid_api_key, key_expired or key_expired_idle (create a new key from the Keys panel). |
| 403 | A deploy-only key (deploy_only_key) |
| 404 | Not found |
| 409 | The site has no passcode (no_passcode) |
| 429 | Rate limited (code rate_limited). Saved-data reads allow 30 a second per address with a burst of 60 (SAVED_DATA_READ_PER_SEC, SAVED_DATA_READ_BURST). |
POST /v1/sites/{sitename}/restore
Restore a website from Recently deleted with its versions, stored resources and connected address.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sitename | path | string | yes |
Responses:
| Status | Description |
|---|---|
| 200 | The restored site |
| 401 | Missing or invalid API key — send the X-API-Key header, not Authorization Bearer. The body’s code is missing_api_key, wrong_auth_header, invalid_api_key, key_expired or key_expired_idle (create a new key from the Keys panel). |
| 403 | Site quota reached |
| 404 | No site with that name in Recently deleted |
| 409 | That site is live |