API Overview - SimpleHost

Base URL

https://simplehost.dev

All API endpoints are prefixed with /api/v1/ or /api/auth/.

Authentication

Authenticated endpoints require a Bearer token in the Authorization header:

Authorization: Bearer sh_live_your_api_key_here

API keys have the format sh_live_ followed by 32 hex characters. See Authentication for how to get one. Some endpoints work without authentication (anonymous publishing), but with limitations.

Content Type

All request bodies must be JSON:

Content-Type: application/json

Response Format

All responses return JSON. Successful responses include the relevant data. Error responses follow a consistent format:

{
  "error": "Description of what went wrong",
  "code": "ERROR_CODE",
  "status": 400
}

See Errors for all error codes.

Rate Limiting

Every API response includes rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1711050000

See Rate Limits for limits per plan.

Endpoints

Publishing

Method	Endpoint	Description
`POST`	`/api/v1/publish`	Create a new site
`PUT`	`/api/v1/_upload/:key`	Upload a file
`POST`	`/api/v1/publish/:slug/finalize`	Finalize and go live
`PUT`	`/api/v1/publish/:slug`	Update an existing site

Management

Method	Endpoint	Description
`GET`	`/api/v1/publishes`	List all sites
`GET`	`/api/v1/publish/:slug`	Get site details
`DELETE`	`/api/v1/publish/:slug`	Delete a site
`POST`	`/api/v1/publish/:slug/duplicate`	Duplicate a site
`PATCH`	`/api/v1/publish/:slug/metadata`	Update metadata
`GET`	`/api/v1/publish/:slug/variables`	List site variables
`PUT`	`/api/v1/publish/:slug/variables`	Store site variables
`DELETE`	`/api/v1/publish/:slug/variables/:name`	Delete a site variable
`GET`	`/api/v1/publish/:slug/proxy-hosts`	List approved proxy hosts
`PUT`	`/api/v1/publish/:slug/proxy-hosts`	Add approved proxy hosts
`DELETE`	`/api/v1/publish/:slug/proxy-hosts/:hostname`	Remove an approved proxy host
`POST`	`/api/v1/publish/:slug/claim`	Claim anonymous site

Secure Browser Requests

Method	Endpoint	Description
`POST`	`/api/v1/proxy/:slug`	Send a secure proxied request for a site

Account

Method	Endpoint	Description
`GET`	`/api/v1/account`	Get account info and usage

Handle

Method	Endpoint	Description
`GET`	`/api/v1/handle`	Get current handle
`PUT`	`/api/v1/handle`	Claim or change handle
`DELETE`	`/api/v1/handle`	Release handle

Billing

Method	Endpoint	Description
`POST`	`/api/billing/checkout`	Create checkout session
`POST`	`/api/billing/portal`	Manage subscription

Authentication

Method	Endpoint	Description
`POST`	`/api/auth/agent/request-code`	Request verification code
`POST`	`/api/auth/agent/verify-code`	Verify code and get API key

​Base URL

​Authentication

​Content Type

​Response Format

​Rate Limiting

​Endpoints

​Publishing

​Management

​Secure Browser Requests

​Account

​Handle

​Billing

​Authentication

Base URL

Authentication

Content Type

Response Format

Rate Limiting

Endpoints

Publishing

Management

Secure Browser Requests

Account

Handle

Billing

Authentication