Getting started

The Hyperstatic APIs are REST APIs over HTTPS. All APIs share one authentication model, one response envelope, and one error format. This consistency aims to makes development and integration easier since every endpoint behaves predictably.

Authentication

Every non-public request is authenticated using a bearer token, referred to as an access token.

Access tokens can be acquired in two ways:

1. User-scoped access tokens are generated through the standard API authentication flow.
2. Permission-scoped access tokens are generated through the Console.

User-scoped access tokens

User-scoped access tokens are obtained through the standard passwordless login flow. Start by sending a login email through the authentication API. The email contains a single-use login link that passes through the authentication service, validates the link, and generates the login token used to complete the flow on the client.

The steps to obtain an access token are detailed below.

{ "email": "henry.case@hyperstatic.com", "url": "https://hyperstatic.com" }

After you click the single-use link in the login email, the authentication service redirects to your authorized callback URL with either a token or an error parameter. If the token parameter is present, it is your login token.

// https://hyperstatic.com?token=MuMg5zTZhG...gOSPtxL33I const loginToken = new URLSearchParams( window.location.search ) ?.get( 'token' ) { "token": "MuMg5zTZhG...gOSPtxL33I" }

The login endpoint returns the standard response envelope. Its data property contains both a Credentials object and a User object.

{ "data": { "credentials": { "accessToken": "eyJhbGciOi...V_adQssw5c", "expires": 1784580042, "refreshToken": "AMf-vBy5W8...Q4mN2vhI9j", "scope": "backend", "sessionId": "ses_3HSp6P80ZGLbD9p8F63NuK63jku" }, "user": { "anonymous": false, "details": { "name": "Henry Case", "preferred": "Henry" }, "disabled": false, "email": "henry.case@hyperstatic.com", "id": "usr_3HSnjv59UEytfIvAOlbAWsHaJMj", "meta": { "created": 1559703925, "updated": 1713717876 }, "type": "user" } } }

Maintain a session by refreshing the user's credentials with the provided refresh token. A new refresh token is included in the returned credentials only when required for session maintenance.

{ "refreshToken": "AMf-vBy5W8...Q4mN2vhI9j" }

The refresh response largely mirrors the login response: the standard response envelope's data property contains both a Credentials object and a User object.

{ "data": { "credentials": { "accessToken": "eyJhbGciOi...V_adQssw5c", "expires": 1784580042, "scope": "backend", "sessionId": "ses_3HSp6P80ZGLbD9p8F63NuK63jku" }, "user": { "anonymous": false, "details": { "name": "Henry Case", "preferred": "Henry" }, "disabled": false, "email": "henry.case@hyperstatic.com", "id": "usr_3HSnjv59UEytfIvAOlbAWsHaJMj", "meta": { "created": 1559703925, "updated": 1713717876 }, "type": "user" } } }

Permission-scoped access tokens

Permission-scoped access tokens can be created via the Console.

Unlike user-scoped access tokens, permission-scoped access tokens carry assigned permission roles. The available roles are listed below.

organization.read

View an organization's profile, settings, and metadata.

organization.write

Create organizations and update their profile and settings.

organization.delete

Permanently delete an organization.

organization.billing

View and manage billing, subscriptions, and payment methods.

organization.members

Invite, remove, and change the roles of members in an organization.

organization.domains.read

View the custom domains attached to an organization.

organization.domains.write

Add and update custom domains.

organization.domains.delete

Remove custom domains from an organization.

organization.domains.verify

Trigger and complete domain ownership verification.

commerce.read

View commerce instances and their configuration.

commerce.write

Create and update commerce instances.

commerce.delete

Permanently delete a commerce instance.

commerce.orders.read

View orders and their details.

commerce.orders.write

Update orders, including status and fulfilment changes.

commerce.orders.refund

Issue refunds against an order.

forms.read

View form instances and their configuration.

forms.write

Create and update form instances.

forms.delete

Permanently delete a form instance.

forms.configuration.read

View a form's resolved configuration for an environment.

forms.settings.read

View a form's environment settings.

forms.settings.write

Update a form's environment settings.

forms.submissions.read

View submissions made to a form.

forms.submissions.write

Create submissions (typically the public submit action).

forms.submissions.delete

Delete submissions from a form.

sites.read

View site instances and their configuration.

sites.write

Create and update site instances.

sites.delete

Permanently delete a site instance.

sites.builds.read

View a site's build history and status.

sites.builds.write

Trigger new builds for a site.

sites.publish

Promote a build to live / publish a site.

instances.read

List all instances across products that the caller can access.

user.read

View the authenticated user's own profile.

user.write

Update the authenticated user's own profile.

user.sessions.read

List the authenticated user's active sessions.

user.sessions.revoke

Revoke one of the authenticated user's sessions.

status.read

View the operational status of an application.

status.write

Update the operational status of an application.

utility.currency.read

Perform currency conversions.

utility.ip.read

Perform IP address lookups.

*

Unrestricted superuser access to all resources and actions.

Making requests

Send JSON, receive JSON. Unless otherwise noted, write operations (POST, PATCH, and PUT) expect an application/json request body. Read operations use the path and query parameters specified on their operation detail pages. Here is a complete write request in JavaScript.

const response = await fetch( 'https://api.hyperstatic.com/commerce/com_3HSriS5micF2IzoSe2Z8OXaTbf4/orders/ord_3HSsl2Bwl2jSQqNXfutYmPUDNIF', { method: 'POST', headers: { 'Authorization': 'Bearer eyJhbGciOi...V_adQssw5c', 'Content-Type': 'application/json', }, body: JSON.stringify( { status: 'shipped', } ), } );

The request envelope

Unless the operation details state otherwise, requests that act on a particular resource should not use a wrapping property. For example, when updating the status of an order, the payload is:

{ "status": "shipped" }

The response envelope

Success

Successful responses always wrap their payload in a top-level data property. Most responses also include a top-level meta property with request information and, for lists, pagination details for retrieving additional records.

{ "data": ..., "meta": { "pagination": { "limit": 12, "more": true, "offset": 0, "page": 1, "pages": 18, "total": 215 }, "requestId": "req_3HSugWUAHmYdzj6nfCTOF2d2NFy" } }

Pagination

Unless otherwise noted, list endpoints return up to limit records (default: 20; maximum: 100).

# Get the first 50 orders GET https://api.hyperstatic.com/commerce/com_3HSriS5micF2IzoSe2Z8OXaTbf4/orders?limit=50 # Get 25 orders, starting at page 5 GET https://api.hyperstatic.com/commerce/com_3HSriS5micF2IzoSe2Z8OXaTbf4/orders?limit=25&page=5

Error

Error responses follow RFC 9457: Problem Details for HTTP APIs. They use the application/problem+json media type, and their bodies are JSON objects with at least some of the members detailed below.

HTTP/1.1 403 Forbidden Content-Type: application/problem+json { "detail": "Your current balance is USD 3.25, but a quota increase costs USD 10.00", "instance": "https://console.hyperstatic.com/events/evt_3HSw1QQ3MNG4eZ7CFtH9Ib7Q0r1", "status": 403, "title": "Not enough credit", "type": "https://reference.hyperstatic.com/errors/organization/insufficient-funds" }

Rate limits

The default limit is 1,000 requests per minute per token. If a request exceeds the rate limit, the API returns 429 until the quota resets.