Getting started

The Hyperstatic APIs are organized REST over HTTPS. All APIs share one authentication model, one response envelope, and one error format. This consistency is ensured to ease development and integration, and so that every endpoint behaves the way you expect it to.

Authentication

Every non-public request is is authenticated with a bearer token. The token itself is referred to as an access token. Access tokens can be acquired in two ways:

• User-scoped access tokens can be generated by following the standard API-based authentication flow
• Permission-scoped access tokens can be generated via the Console

User-scoped access tokens

1. Send authentication email

   Send an email with an authentication link

2. Send authentication email

   Send an email with an authentication link

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

3. Grab the login token

   After clicking the one-time link in the login email, our servers will complete the authentication process and then redirect you to your authorized callback URL along with either a token or an error parameter. If a token parameter exists, this is a login token.

   const token = new URLSearchParams( window.location.search )?.get( 'token' )

4. Login with the provided token

   The provided token can be passed in to the login endpoint to create a new user session

   Request

   { "token": "MuMg5zTZhGp2xtHt88KR1TzOJDgvlItrj2weRF31ZVHwgOSPtxL33I" }

   Response

   { "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" } } }

5. Session maintenance

   An authentication session can be maintained by refreshing the user's credentials using the provided refresh token. Unless necessary for session maintenance, a new refresh token may not be included in the returned credentials.

   Request

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

   Response

   { "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. After logging in, navigate to Organization => Settings => Access => API Keys to generate your token.

Unlike user-scoped access tokens, permission-scoped access tokens rely on specific permission roles being attached to the token. Available permission 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.

resource.manage

Full access to every action on a resource (e.g. forms.manage covers read, write, delete, settings, and submissions).

*

Unrestricted superuser access to all resources and actions.

Making requests

Send JSON, get JSON. All write operations (POST, PATCH, and PUT- unless otherwise noted - expect an application/json body as a payload. All read operations take path and query parameters as specified on their operation detail pages. Here is a complete write call 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 otherwise noted in the operation's details, requests acting on a particular resource should not have any sort of wrapping property. To wit, when updating the status of an order, the payload should be: { "status": "shipped", }

The response envelope

Success

Successful responses will always wrap their payload in a top-level data property. Most requests will also provide a top-level meta property housing both information about the request itself as well as any relevant pagination details for retrieving additional records from a listing.

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

Pagination

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

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

Error

Error responses strictly follow the standard set out by RFC 9457: Problem Details for HTTP APIs. This means error responses will always use the application/problem+json media type, and the body will be a JSON object with at least some of the members detailed below.

HTTP/1.1 403 Forbidden Content-Type: application/problem+json { "detail": "Your current balance is 3.25USD, but a quota increase costs 10.00USD", "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. When exceeding the rate limit, a 429 will be returned until the quota resets.