Skip to main content

Developer API beta

The SiteHut developer API is a support-approved beta for workspace integrations. It uses a versioned contract at https://api.sitehut.app/api/v1/. Service accounts are always free and never consume paid workspace seats. Usage limits and existing workspace feature entitlements still apply.

Request access​

Open Workspace settings → Integrations → API keys and choose Request API access. Your email composer opens with the workspace details filled in. Explain your integration and expected request volume, then send the email to support. API access remains disabled until support enables your workspace.

You can read this documentation before access is enabled. The full internal application API is separate and is not an external integration contract.

Set up an integration​

  1. An authorised workspace manager creates a service account with a name and description.
  2. Choose a workspace role. Start read-only and add only the permissions needed.
  3. Review job access. All current jobs are selected initially; clear any that the integration should not access. New jobs are not automatically assigned.
  4. Create a named workspace key for the service account, set an expiry, and optionally restrict the key further. All available key scopes are selected initially; the service account’s role and job access still limit every request. The default is 90 days.
  5. Copy the secret once into your integration's secret store. It is not shown again.

Personal API-key integrations are unavailable in this beta. Service accounts have no interactive login and remain independent of the employee who created them.

First request​

Workspace IDs and project IDs are UUIDs. Copy the workspace ID from the access-request email or your workspace information. The workspace in the URL must match the key. No workspace headers are required.

export SITEHUT_WORKSPACE_ID="your-workspace-uuid"
# Set SITEHUT_API_KEY using your secret manager or local environment.
curl --fail-with-body \
  -H "Authorization: Api-Key $SITEHUT_API_KEY" \
  "https://api.sitehut.app/api/v1/workspaces/$SITEHUT_WORKSPACE_ID/projects/"

This requires projects:read on both the service account and key. The response contains only explicitly assigned projects and uses count, next, previous, and results.

Create a customer​

With customers:write and a unique idempotency key:

curl --fail-with-body -X POST \
  -H "Authorization: Api-Key $SITEHUT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: customer-acme-2026-001" \
  --data '{"name":"Acme Construction","contact_email":"accounts@example.com"}' \
  "https://api.sitehut.app/api/v1/workspaces/$SITEHUT_WORKSPACE_ID/customers/"

Reuse that idempotency key only when retrying the identical request. Do not reuse it for another customer.

Explore​

The Postman collection contains no credentials. Set its variables locally, complete request bodies using the reference, and preserve the same Idempotency-Key when retrying a POST. The collection's generated GUID is for a new operation.