Build on the Hermida platform.

Quickstart

From a token to your first integration.

Three steps. No SDK required — the API is plain HTTPS and JSON, so it works from a script, a server, or a spreadsheet automation.

1. 01

   Issue a personal access token

   Open your workspace settings, then Secrets → Personal access tokens, and create a token for the integration. It is shown once. Revoke it there the moment a machine stops using it.

   headerCopy

   Authorization: Bearer hmd_live_…

2. 02

   Call a function

   Every endpoint is a POST to /functions/<name> with a JSON body. The action in the body selects the behaviour of that function.

   curlCopy

   curl -X POST "$HERMIDA_API/functions/clientProjects" \
     -H "Authorization: Bearer $HERMIDA_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"action":"list","slug":"acme-co"}'

3. 03

   Read the scoped response

   Responses are JSON with an ok flag. A failure returns ok: false plus a code you can branch on — never a partial payload.

   javascriptCopy

   const res = await fetch(`${BASE}/functions/clientProjects`, {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${process.env.HERMIDA_TOKEN}`,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({ action: 'list', slug: 'acme-co' }),
   });
   
   const { ok, projects, code } = await res.json();
   if (!ok) throw new Error(code);

Authentication

A bearer token, and the permissions already attached to it.

Hermida has no separate permission model for integrations. The token inherits the member, the member inherits their memberships, and the API enforces both on every request.

curl -X POST "$HERMIDA_API/functions/clientProjects" \
  -H "Authorization: Bearer $HERMIDA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"billing","slug":"acme-co"}'

const res = await fetch(`${BASE}/functions/clientProjects`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HERMIDA_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ action: 'billing', slug: 'acme-co' }),
});

const { ok, billing } = await res.json();
if (!ok) throw new Error('request_failed');

Errors and limits

One shape for every failure.

A failed request returns a JSON body with ok: false and a stable code, plus an HTTP status you can branch on. Nothing partial is ever written.

{
  "ok": false,
  "code": "access_denied"
}