Skip to content
Docs

Deploy

Publish inline JSON files or a tar.gz/zip archive.

POST /v1/sites/{sitename}

Upload a .tar.gz or .zip (for framework builds, binary assets, large sites). Max 25 MB. 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. Choose access: specific at creation for only the owner and named viewers from the first request; omitted or anyone keeps the default (anyone with the address). Optional viewers emails require specific, are normalized and deduplicated, and respect SITE_VIEWERS_MAX. Named viewers require sign-in and the site’s own address and are unavailable on Simple Hack. Archive options use query parameters access and viewers (comma-separated or repeated).

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
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.
author query string Who made this version: free text, trimmed, control characters removed, at most 80 characters. Stored on the version and returned as author by GET /v1/sites/{sitename}/versions.
access query string, one of anyone, specific Creation only. Default anyone; specific allows only the owner and named viewers from the first request. Simple Hack refuses specific.
viewers query array of string Optional creation viewer emails, only with access specific. Comma-separated or repeated viewers parameters; SITE_VIEWERS_MAX applies. Not added to existing sites.

Request body: application/gzip

Responses:

Status Description
201 Site created
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 site_exists, access_differs (create-or-update), named_viewers_unavailable, sign_in_unavailable, named_viewers_need_own_address, or idempotency_key_reused
413 The request or deployment exceeds its applicable size limit.

PUT /v1/sites/{sitename}

Upload a new version of an existing site you own. Creates a new version and activates it; with ?publish=false the version is only stored (visitors keep seeing the live one) and the answer adds unpublished_version, preview_url and preview_expires_at. With ?create=1 a missing site is created instead (201, with the same checks as POST): one call from CI, e.g. curl -X PUT ".../v1/sites/<name>?create=1" -H "X-API-Key: $KEY" --data-binary @site.tar.gz. 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. Choose access: specific at creation for only the owner and named viewers from the first request; omitted or anyone keeps the default (anyone with the address). Optional viewers emails require specific, are normalized and deduplicated, and respect SITE_VIEWERS_MAX. Named viewers require sign-in and the site’s own address and are unavailable on Simple Hack. With create=1, access/viewers apply when creating. On an existing site, specific refuses 409 access_differs unless it is already specific; viewers are not added. anyone never changes an existing site’s access. Without create=1, access/viewers are 400 invalid_request; later use set_site_access / grant_site_viewer. Archive options use query parameters access and viewers (comma-separated or repeated).

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
publish query boolean false stores the new version without making it live (updates only; a new site’s first version always goes live: 400)
create query string, one of 1, 0, true, false 1 creates the site when you have none of that name (reserved names, the site quota and publish=false are refused as on POST), so one PUT deploys from CI whether or not the site exists
author query string Who made this version: free text, trimmed, control characters removed, at most 80 characters. Stored on the version and returned as author by GET /v1/sites/{sitename}/versions.
access query string, one of anyone, specific Creation only. Default anyone; specific allows only the owner and named viewers from the first request. Simple Hack refuses specific.
viewers query array of string Optional creation viewer emails, only with access specific. Comma-separated or repeated viewers parameters; SITE_VIEWERS_MAX applies. Not added to existing sites.

Request body: application/gzip

Responses:

Status Description
200 Site updated
201 Site created (?create=1 and no site of that name)
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).
404 Not found
409 site_exists, access_differs (create-or-update), named_viewers_unavailable, sign_in_unavailable, named_viewers_need_own_address, or idempotency_key_reused
413 The request or deployment exceeds its applicable size limit.

POST /v1/sites/{sitename}/files

The LLM-friendly deploy path — send every file inline in one request, no archiving. Text goes in files; base64-encoded binary goes in files_base64. index.html is required. Relative paths only (../absolute are rejected); secret files (.env, .git/*, id_rsa) are dropped and script extensions (.sh .py .php …) are rejected. Use PUT to update an existing site (409 site_exists says so); PUT with ?create=1 creates or updates in one call. 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. Choose access: specific at creation for only the owner and named viewers from the first request; omitted or anyone keeps the default (anyone with the address). Optional viewers emails require specific, are normalized and deduplicated, and respect SITE_VIEWERS_MAX. Named viewers require sign-in and the site’s own address and are unavailable on Simple Hack. JSON body fields: access and viewers.

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
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.
author query string Who made this version: free text, trimmed, control characters removed, at most 80 characters. Stored on the version and returned as author by GET /v1/sites/{sitename}/versions.

Request body:

Name Type Required Description
access string, one of anyone, specific Creation only (POST or PUT create=1). Default anyone; specific allows only the owner and named viewers from the first request. No access change on existing sites.
files object yes relative path -> file contents (text). index.html required unless PUT uses keep=1.
files_base64 object relative path -> base64-encoded binary contents. A path cannot also appear in files.
remove_files array of string Paths to drop from the live version; only with PUT keep=1.
viewers array of string Optional emails, only with access specific; normalized, deduplicated, limited by SITE_VIEWERS_MAX. Added only when the site is created.

Responses:

Status Description
201 Site created
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 site_exists, access_differs (create-or-update), named_viewers_unavailable, sign_in_unavailable, named_viewers_need_own_address, or idempotency_key_reused

PUT /v1/sites/{sitename}/files

Same as POST, but for an existing site you own. Creates a new version and activates it; with ?publish=false the version is only stored (visitors keep seeing the live one) and the answer adds unpublished_version, preview_url and preview_expires_at. With ?create=1 a missing site is created instead (201, with the same checks as POST), so CI deploys in one call; without it a missing site is 404. With ?keep=1, send only changed files: other files in the live version are retained byte-for-byte, and remove_files drops listed relative paths. remove_files requires keep=1; index.html is not required in a patch. The merged version meets the ordinary file and storage caps. 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. Choose access: specific at creation for only the owner and named viewers from the first request; omitted or anyone keeps the default (anyone with the address). Optional viewers emails require specific, are normalized and deduplicated, and respect SITE_VIEWERS_MAX. Named viewers require sign-in and the site’s own address and are unavailable on Simple Hack. With create=1, access/viewers apply when creating. On an existing site, specific refuses 409 access_differs unless it is already specific; viewers are not added. anyone never changes an existing site’s access. Without create=1, access/viewers are 400 invalid_request; later use set_site_access / grant_site_viewer. JSON body fields: access and viewers.

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
publish query boolean false stores the new version without making it live (updates only; a new site’s first version always goes live: 400)
create query string, one of 1, 0, true, false 1 creates the site when you have none of that name (reserved names, the site quota and publish=false are refused as on POST), so one PUT deploys from CI whether or not the site exists
author query string Who made this version: free text, trimmed, control characters removed, at most 80 characters. Stored on the version and returned as author by GET /v1/sites/{sitename}/versions.
keep query integer, one of 1 Keep unchanged files from the live version; merged files use ordinary unpacked-file caps

Request body:

Name Type Required Description
access string, one of anyone, specific Creation only (POST or PUT create=1). Default anyone; specific allows only the owner and named viewers from the first request. No access change on existing sites.
files object yes relative path -> file contents (text). index.html required unless PUT uses keep=1.
files_base64 object relative path -> base64-encoded binary contents. A path cannot also appear in files.
remove_files array of string Paths to drop from the live version; only with PUT keep=1.
viewers array of string Optional emails, only with access specific; normalized, deduplicated, limited by SITE_VIEWERS_MAX. Added only when the site is created.

Responses:

Status Description
200 Site updated
201 Site created (?create=1 and no site of that name)
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).
404 Not found
409 site_exists, access_differs (create-or-update), named_viewers_unavailable, sign_in_unavailable, named_viewers_need_own_address, or idempotency_key_reused

POST /v1/uploads/{token}

Use the private link returned by create_upload_link with archive true from a shell (the default on Simple Hack). Works once for one site for 15 minutes, including failed uploads. Sign-in is checked again at upload. Links stop working when the person signs out, disconnects the app or their sign-in expires. Creates the site if missing, else publishes a new version, public at its address on success. Never share the link or put it in a web page. Usual deploy and scope checks apply.

No authentication required.

Parameters:

Name In Type Required Description
token path string yes

Request body: application/gzip

Responses:

Status Description
200 Site updated
201 Site created
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 Sign-in ended, or deploy scope or team rules refused the upload
404 Unknown, used or expired link
409 Conflict: the code says which (site_exists, domain_taken, append_only, custom_domain_required, not_an_object)
413 The request or deployment exceeds its applicable size limit.
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).

PUT /v1/uploads/{token}

Use the private link returned by create_upload_link with archive true from a shell (the default on Simple Hack). Works once for one site for 15 minutes, including failed uploads. Sign-in is checked again at upload. Links stop working when the person signs out, disconnects the app or their sign-in expires. Creates the site if missing, else publishes a new version, public at its address on success. Never share the link or put it in a web page. Usual deploy and scope checks apply.

No authentication required.

Parameters:

Name In Type Required Description
token path string yes

Request body: application/gzip

Responses:

Status Description
200 Site updated
201 Site created
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 Sign-in ended, or deploy scope or team rules refused the upload
404 Unknown, used or expired link
409 Conflict: the code says which (site_exists, domain_taken, append_only, custom_domain_required, not_an_object)
413 The request or deployment exceeds its applicable size limit.
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).