API overview

API6 min read

The SiteHut REST API is the same HTTPS API the web app uses. Use it for scripts and integrations. Connect Xero, QuickBooks, or Stripe in Integrations, not here.

Workspace settings → Integrations → API keys

desktop

When this area is the right place

Use this page when you are writing a script against SiteHut.

Do not use it to turn on accounting sync or card payments. Do not use it to change your password: that is Account settings.

Before you start

• HTTPS access to the API host for your environment.
• A SiteHut login (email verified). If a workspace requires 2FA, have an authenticator ready.
• For workspace-scoped routes: the workspace id and slug.
• To mint a workspace key: Integrations access (typically Owner or Admin).

Base URL

All application routes sit under /api/ on the API host. There is no /v1 segment.

Production:

https://api.sitehut.app/api/

Self-hosted or custom environments use a different host. Paths stay the same.

First request

1

Get an access token

POST /api/auth/token/ with your login email and password (the same fields the app sends).

POST /api/auth/token/
Content-Type: application/json

{"email":"you@company.com","password":"your-password"}

A successful response includes access and refresh. Send the access token on later requests:

Authorization: Bearer <access>

Refresh with POST /api/auth/token/refresh/ and body {"refresh":"<refresh>"} when the access token expires.

2

Send workspace context

The web app sends both headers on workspace-scoped calls. Scripts should too:

X-Workspace-Id: <numeric id>
X-Workspace-Slug: <slug>

Some routes also include the workspace slug in the URL (for example under /api/workspaces/ plus the slug).

3

Call a route

Example: who you are.

curl -sS -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "X-Workspace-Slug: $WORKSPACE_SLUG" \
  "https://api.sitehut.app/api/auth/me/"

A health check needs no auth: GET /api/healthz/.

Keys in the app

Create keys in the product, then copy the secret once.

Where	Labels
Workspace settings → Integrations	Expand API keys. Card Workspace API keys. Generate key opens Generate new API key (Key name, Expires, Access permissions). Copy the secret on New API key. Later: Edit, Regenerate, Revoke.
Account settings → API Keys	Card Personal API Keys. Generate Key opens Generate New API Key. That key authenticates as you, across workspaces you belong to.

Workspace keys are for company scripts. Personal keys are for tools that must act as your user. Least privilege: tick only the scopes the job needs.

Warning

You will not see the secret again. Store it outside source control. If it leaks, Regenerate or Revoke.

The live schema is the source of truth for which authentication the server accepts on each route.

What done looks like

• GET /api/healthz/ returns a JSON status.
• GET /api/auth/me/ returns your user with a Bearer token.
• A new key appears in the table with a Prefix. The full secret is gone from the screen.

Common mistakes

• Calling https://api.sitehut.app/ with no /api/ prefix.
• Omitting X-Workspace-Id / X-Workspace-Slug on workspace routes.
• Using a Personal API Keys secret for a company exporter. Use Workspace API keys.
• Looking for a Create button. Workspace keys use Generate key.

OpenAPI, 2FA login, and rate limits

Resource	Path
OpenAPI schema	GET /api/schema/
Swagger UI	GET /api/docs/

On production, /api/docs/ is limited to staff. Prefer /api/schema/ when you can fetch it. Endpoint names change with releases; do not hard-code a private catalogue from this page.

If POST /api/auth/token/ returns requires_2fa and pre_auth_token, complete login with POST /api/auth/token/2fa/ (pre_auth_token plus code or backup_code). Same as Verify and sign in in the app.

The API may respond 429 Too Many Requests. Back off and retry. Email support@sitehut.app if a server integration needs a higher limit.