Hermetica API

Everything the Hermetica dashboard does goes through the same HTTP API, so anything you can click you can also script. The endpoints are listed by area under Endpoints, generated from the live OpenAPI document.

Base URL

https://hermetica.15.204.158.166.sslip.io

Most endpoints live under /v1. Public endpoints used by browsers and recipients (tracking, unsubscribe, forms, hub) live under their own prefixes and need no key.

Authentication

Create a key under Settings → API keys and send it as a bearer token:

curl https://hermetica.15.204.158.166.sslip.io/v1/me \
  -H "Authorization: Bearer hm_sk_..."

• A secret key (hm_sk_) is for servers only. Give it the narrowest scopes it needs, for example profiles:write and messages:send.

• A publishable key is for the browser and mobile SDKs and can only send events and identify visitors.

• A key belongs to one workspace. Keys can be limited to IP addresses and given a per-minute rate limit.

See API keys for the details.

Errors

Errors are JSON with a stable code (invalid, not_found, conflict, forbidden, precondition_failed, unauthenticated, rate_limited) and a human-readable message. A 422 names each field that failed validation.

Idempotency

Send an Idempotency-Key header on any POST that sends a message or creates something you do not want twice. A retry with the same key returns the first result.

Consent is enforced

Marketing and prospecting messages are only sent to people with consent on record and who are not suppressed. The API never bypasses this; a blocked send is reported as blocked, not as an error. See Consent.

SDKs

Official SDKs for Node, Python, Go, Ruby, PHP, Java, .NET, browser, React Native, Flutter, iOS and Android are listed in SDKs.