REST API reference

Base URL

https://api.hee.la

All endpoints are versioned under /v1.

Authentication

Send your project token as a bearer header:

Authorization: Bearer hee_…

Issue tokens from the portal or POST /v1/portal/projects/{slug}/tokens.

Content type

All request/response bodies are JSON. Send Content-Type: application/json on every POST.

Rate limits

Per-IP limits apply to unauthenticated and auth endpoints. Authenticated control-plane calls are currently uncapped — fair-use applies.

Endpoints at a glance

Domains Register, list, remove, and resolve customer hostnames.

Auth (portal) Magic-link session endpoints backing the portal UI.

Portal (session-scoped) Project, token, and domain management via session cookies.

Health Liveness and internal hostname validation.

Domains

POST /v1/edge/domains

Register a customer’s hostname. Idempotent — re-registering the same hostname in the same project returns the existing record with merged metadata.

Body parameters

Field	Type	Required	Description
hostname	string	yes	Fully-qualified domain name to route through Hee.
metadata	object	no	Opaque JSON blob returned verbatim from /resolve.

Request

cURL

curl -X POST https://api.hee.la/v1/edge/domains \
  -H "Authorization: Bearer $HEE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "docs.customer.com",
    "metadata": { "workspaceId": "ws_abc123" }
  }'

TypeScript

import { HeeClient } from "@heela/sdk";

const hee = new HeeClient({ token: process.env.HEE_TOKEN! });

await hee.domains.register({
  hostname: "docs.customer.com",
  metadata: { workspaceId: "ws_abc123" },
});

fetch

await fetch("https://api.hee.la/v1/edge/domains", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HEE_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    hostname: "docs.customer.com",
    metadata: { workspaceId: "ws_abc123" },
  }),
});

Response 200 OK

{
  "hostname": "docs.customer.com",
  "projectSlug": "acme-saas",
  "verified": false,
  "verifiedAt": null,
  "createdAt": "2026-04-20T21:47:38.000Z",
  "metadata": { "workspaceId": "ws_abc123" }
}

Errors

Status	Meaning
400	hostname fails FQDN validation
402	project is over its plan limit
409	hostname is claimed by another project

GET /v1/edge/domains

List every domain owned by the token’s project.

Request

cURL

curl https://api.hee.la/v1/edge/domains \
  -H "Authorization: Bearer $HEE_TOKEN"

TypeScript

const domains = await hee.domains.list();

Response 200 OK

[
  {
    "hostname": "docs.customer.com",
    "projectSlug": "acme-saas",
    "verified": true,
    "verifiedAt": "2026-04-20T21:50:12.000Z",
    "createdAt": "2026-04-20T21:47:38.000Z",
    "metadata": { "workspaceId": "ws_abc123" }
  },
  {
    "hostname": "app.customer.com",
    "projectSlug": "acme-saas",
    "verified": false,
    "verifiedAt": null,
    "createdAt": "2026-04-20T22:10:05.000Z",
    "metadata": {}
  }
]

DELETE /v1/edge/domains/{hostname}

Soft-delete a domain. Certificate and config are retained briefly so a re-add doesn’t re-trigger issuance rate limits.

Path parameters

Field	Type	Required	Description
hostname	string	yes	URL-encoded FQDN to remove.

Request

cURL

curl -X DELETE https://api.hee.la/v1/edge/domains/docs.customer.com \
  -H "Authorization: Bearer $HEE_TOKEN"

TypeScript

await hee.domains.remove("docs.customer.com");

Response 204 No Content

Errors

Status	Meaning
404	hostname is not owned by this project

GET /v1/edge/resolve

Look up routing metadata for a hostname. Used by upstream apps that need to know which project (and which workspace, tenant, etc.) a request belongs to.

Query parameters

Field	Type	Required	Description
hostname	string	yes	FQDN to resolve, unencoded in the query.

Request

cURL

curl "https://api.hee.la/v1/edge/resolve?hostname=docs.customer.com" \
  -H "Authorization: Bearer $HEE_TOKEN"

Response 200 OK

{
  "hostname": "docs.customer.com",
  "projectSlug": "acme-saas",
  "upstreamUrl": "https://acme.pages.dev",
  "metadata": { "workspaceId": "ws_abc123" }
}

Auth (portal)

You probably don't need these

The portal handles magic-link request, callback, and session cookies end-to-end. These endpoints are documented for SSR integrations and custom auth flows only.

POST/v1/auth/request-magic-link

Email a signed magic-link to the user.

POST/v1/auth/callback

Exchange a magic-link token for a session cookie.

GET/v1/auth/me

Return the current session’s user record.

POST/v1/auth/sign-out

Invalidate the session cookie.

Request/response shapes live in the auth-user module.

Portal (session-scoped)

Session cookie required

These endpoints expect a browser session cookie obtained via magic-link login — not an API token. Use them from the portal UI or server-rendered pages that proxy the session.

POST/v1/portal/projects

Create a project.

GET/v1/portal/projects/{slug}

Get project details.

POST/v1/portal/projects/{slug}/tokens

Issue an API token. Returns the raw token once — store it immediately.

GET/v1/portal/projects/{slug}/tokens

List tokens (hashed preview only — raw values are never replayed).

DELETE/v1/portal/projects/{slug}/tokens/{tokenId}

Revoke a token.

POST/v1/portal/projects/{slug}/domains

Register a domain via the portal (mirrors the API-token path).

GET/v1/portal/projects/{slug}/domains

List domains for the project.

DELETE/v1/portal/projects/{slug}/domains/{hostname}

Remove a domain.

Health

GET /healthz

Unauthenticated liveness probe.

Response 200 OK

{ "status": "ok" }

GET /_check-hostname

Internal

Called by Caddy’s on_demand_tls hook to decide whether to issue a certificate. Returns 200 if the domain is registered, a 4xx otherwise. Not intended for external use and subject to change without notice.

Query parameters

Field	Type	Required	Description
domain	string	yes	FQDN to check.

OpenAPI spec

A machine-readable OpenAPI 3.0 document is coming in Phase 2. Until then, this page and the TypeScript SDK types are the canonical reference.