Account
Account profile, credentials and connected apps.
GET /v1/me
Current user
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Responses:
| Status | Description |
|---|---|
| 200 | Current user |
| 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). |
PATCH /v1/me
Changing the handle changes every address (https://<handle>.simple-host.app/ and https://<site>.<handle>.simple-host.app/). Before anything is published it changes freely. After that (even once every site is gone) it can change once every 30 days: the old handle stays reserved for this account and every old address redirects to the new one. A new handle gets its own certificate; until it is issued, sites briefly use the fallback https://<handle>.simple-host.app/<site>/. What pages kept in visitors’ browsers starts empty at the new address, and visitors sign in again.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Request body:
| Name | Type | Required | Description |
|---|---|---|---|
| display_name | string | Trimmed; empty clears the name. Never used in URLs. | |
| handle | string | The <handle> in your address https://<handle>.simple-host.app/. Must not be reserved or already taken (handles and free <name>.simple-host.app addresses share one namespace). | |
| signin_alerts | boolean | Sign-in alert emails (default true): one email after each sign-in or app connection, at most one per browser or app a day. Needs one of the account’s own API keys (a connected app or the admin key gets 400 not_an_account_key). |
Responses:
| Status | Description |
|---|---|
| 200 | Updated account profile |
| 400 | Invalid profile, or signin_alerts sent without an account key (code not_an_account_key) |
| 401 | API key required |
| 409 | The handle cannot be had: code handle_taken (another account’s handle or old handle, or a site’s claimed free name; error says “That address is taken: <handle>.simple-host.app is already in use. Try another.”) or handle_reserved. A malformed handle is 400 invalid_handle. |
| 429 | The handle already changed within the last 30 days after publishing |
DELETE /v1/me
Permanently delete the signed-in account and its websites, stored resources and connected apps. This cannot be undone; offer the account export first.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Request body:
| Name | Type | Required | Description |
|---|---|---|---|
| confirm | string | yes | The account’s handle, or its email when it has no handle. Case-insensitive. |
Responses:
| Status | Description |
|---|---|
| 204 | Deleted |
| 400 | confirm missing (code confirm_required) or does not match (code confirm_mismatch) |
| 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 | Suspended account (code account_suspended), a site of the account taken down (code site_suspended) or admin account (code admin_account) |
| 409 | The account still holds event hostnames (code event_hostnames) |
| 429 | Too many requests from this address |
POST /v1/me/api-key/rotate
The “Sign out everywhere” button. Replaces all of the authenticated owner’s API keys with one new key and returns it. Every older key stops working immediately, and every connected app (see /v1/me/connections) is disconnected. Keys are stored only as SHA-256 hashes, so this response is the only time the new key is shown.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Responses:
| Status | Description |
|---|---|
| 200 | API key rotated |
| 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). |
GET /v1/me/connections
The AI apps (ChatGPT, Claude, Grok, a GPT Action) this account has connected through the Simple Host connector (OAuth at /oauth/authorize, MCP at /mcp). Each is listed once, however many times it was connected.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Responses:
| Status | Description |
|---|---|
| 200 | Connected apps, newest first |
| 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). |
DELETE /v1/me/connections/{client_id}
Revokes every token this account granted to the app. It has to be connected again, with a fresh sign-in, to be used.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| client_id | path | string | yes |
Responses:
| Status | Description |
|---|---|
| 204 | Disconnected |
| 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 | No connected app with that id |
GET /v1/me/deleted-sites
List websites recently deleted by this account, including their restoration deadline.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Responses:
| Status | Description |
|---|---|
| 200 | Recently deleted sites, most recently deleted first |
| 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). |
POST /v1/me/email
Emails a 6-digit code to the new address and another to the current one (15 minutes, 3 tries). Send both to POST /v1/me/email/verify to finish. Asking looks the same for every address. Needs one of the account’s own API keys: a connected app or the admin key gets 400 not_an_account_key. Refused for the plugin reviewer account (and for moving any account to its address), admin, event and preview accounts, and accounts whose sign-in name is not an email address. Rate-limited per address and per account, like sign-in.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Request body:
| Name | Type | Required | Description |
|---|---|---|---|
| string | yes |
Responses:
| Status | Description |
|---|---|
| 202 | Codes sent |
| 400 | Not an account key (code not_an_account_key), not an email (code invalid_email), already the sign-in email (code same_email), or the reviewer’s address (code reserved_email) |
| 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 reviewer, an admin, event or preview account, or one with no email to confirm from (codes reviewer_account, admin_account, event_account, preview_account, no_current_email) |
| 429 | Too many requests |
GET /v1/me/email/undo
Shows a page with an Undo button and changes nothing. No sign-in; the token is the authorization. 404 page when the link was used or is older than 7 days. Emailed links carry the token in the fragment (#t=), so it never reaches a server log: without t the GET returns a small page whose script posts the fragment’s token back with peek=1, which shows this confirmation. Links sent before v0.7.1 carry ?t= and keep working until they expire.
No authentication required.
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| t | query | string |
Responses:
| Status | Description |
|---|---|
| 200 | HTML confirmation page with the button |
| 404 | HTML page; the link was used or has expired |
| 429 | Too many requests |
POST /v1/me/email/undo
The confirmation page’s button (with peek=1, only the confirmation page). Puts the account back on the old address, signs out every API key and every sign-in on sites, removes Google/GitHub sign-ins and connected apps added since the change, and spends every undo link of the account. HTML page.
No authentication required.
Request body: application/x-www-form-urlencoded
Responses:
| Status | Description |
|---|---|
| 200 | HTML page; the account signs in with the old address again |
| 404 | HTML page; the link was used or has expired |
| 409 | HTML page; another account signs in with the old address now |
| 429 | Too many requests |
POST /v1/me/email/verify
Moves the account to the new address: from now on sign-in codes go there. The handle, sites and connected apps stay; every other API key of the account is signed out (the one making the call stays); linked Google/GitHub sign-ins stay (GET /v1/me/identities lists them). Open sign-in codes for the old address stop working, the account’s emailed idle-site links end, and the old address gets a notice naming the new one masked (n***@example.com) with an undo link valid for 7 days. An address another account signs in with is refused here, after the codes are verified (409 email_taken). Needs one of the account’s own API keys.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Request body:
| Name | Type | Required | Description |
|---|---|---|---|
| code | string | yes | The 6-digit code emailed to the new address |
| current_code | string | yes | The 6-digit code emailed to the current address |
Responses:
| Status | Description |
|---|---|
| 200 | Changed |
| 400 | Not an account key (code not_an_account_key), a code missing (code codes_required), no change waiting (code no_pending_change), or the reviewer’s address (code reserved_email) |
| 401 | Wrong or expired code, or too many tries (code invalid_code) |
| 403 | The reviewer, an admin, event or preview account (see step 1) |
| 409 | Another account signs in with that address (code email_taken) |
| 429 | Too many requests |
GET /v1/me/export.tar.gz
Deprecated.
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).
Responses:
| Status | Description |
|---|---|
| 200 | The same .zip as GET /v1/me/export.zip |
| 400 | Not one of the account’s own API keys (code not_an_account_key) |
| 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 account is suspended (code account_suspended) |
| 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/me/export.zip
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).
Responses:
| Status | Description |
|---|---|
| 200 | A .zip file (Content-Disposition names it simple-host-<handle>-<date>.zip) |
| 400 | Not one of the account’s own API keys (code not_an_account_key) |
| 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 account is suspended (code account_suspended); write to support@simple-host.app for a copy of the data |
| 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/me/identities
Own API key only (400 not_an_account_key otherwise).
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Responses:
| Status | Description |
|---|---|
| 200 | The linked sign-ins |
| 400 | Not an account key (code not_an_account_key) |
| 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). |
DELETE /v1/me/identities/{id}
That Google or GitHub account no longer signs in to yours. Own API key only.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | yes |
Responses:
| Status | Description |
|---|---|
| 204 | Unlinked |
| 400 | Not an account key (code not_an_account_key) |
| 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 | No such sign-in on this account |
GET /v1/me/keys
Every key on the account, newest first. current marks the key this request was made with. Keys issued before names existed have no name or last4 (shown as “Earlier key”). last_used_at is updated at most every 5 minutes. A key unused for 180 days stops working. idle_expires_at says when (KEY_IDLE_EXPIRY_DAYS); one minted with expires_in_days stops at expires_at. A key that has stopped stays listed with expired until revoked.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Responses:
| Status | Description |
|---|---|
| 200 | The account’s keys |
| 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). |
POST /v1/me/keys
Create an account key for a trusted CI client or another machine. A deploy-only key can publish the account’s permitted websites but cannot manage account settings or website storage. The key is returned once; keep it outside chat.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Request body:
| Name | Type | Required | Description |
|---|---|---|---|
| expires_in_days | integer | Optional fixed expiry, in days from now | |
| name | string | yes | Any label except the names Simple Host gives its own keys (dashboard sign-in, agent sign-in, event account, reviewer sign-in, replacement key; 400) |
| scope | string, one of full, deploy |
deploy: create, update, roll back and list sites and make preview links, nothing else |
Responses:
| Status | Description |
|---|---|
| 201 | Key created. api_key is shown only here. |
| 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). |
| 409 | The account already holds 50 keys (code key_limit); revoke one first. |
DELETE /v1/me/keys/{id}
The key stops working at once; the account’s other keys and connected apps are untouched. Revoking the key this request uses signs this caller out. Needs one of the account’s own keys.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | yes |
Responses:
| Status | Description |
|---|---|
| 204 | Revoked |
| 400 | Not one of the account’s own keys (code not_an_account_key) |
| 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 | No key with that id on this account |
POST /v1/me/password
Available only when PASSWORD_SIGNIN=on, for an account that already has a password (404 for one that does not). current_password is verified against the same limiters as sign-in (passwordLoginLimiter, keyed by the normalized username, and passwordIPLimiter); a wrong current password counts against both and refunds neither, and answers 403 (not 401, which the dashboard and Hack account screens read as an expired key and sign the browser out). new_password must be 8-256 characters and differ from current_password. Only a real account API key may call this; a connector’s OAuth access token, even one otherwise valid for the REST API, is refused. Does not revoke keys, sessions or connector tokens; every other sign-in stays valid.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Request body:
| Name | Type | Required | Description |
|---|---|---|---|
| current_password | string | yes | |
| new_password | string | yes |
Responses:
| Status | Description |
|---|---|
| 204 | Password changed |
| 400 | invalid_password (too short, or same as current_password) |
| 401 | Missing or invalid API key |
| 403 | Wrong current password (code bad_credentials), or a connector access token (code connector_not_allowed): sign in with an account API key instead. |
| 404 | not found: PASSWORD_SIGNIN is off, or this account has no password |
| 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/me/sign-out
Deletes the API key sent with this request and cascades to its apex SSO passes and every visitor session minted from them, then clears the apex cookie; the account’s other keys and connected apps are untouched. The dashboard’s Sign out calls this before it clears the key from the browser. Needs one of the account’s own keys (the admin env key or a connected app gets 400 not_an_account_key).
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Responses:
| Status | Description |
|---|---|
| 204 | Signed out; the key no longer works |
| 400 | Not one of the account’s own keys (code not_an_account_key) |
| 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). |