Docs

Human sign-in. Emails a one-time link; redeeming it creates a session. No password exists. Rate limited to 10 requests per hour per client. Public.

email

string · required

Where the link is sent.

Returns

{"ok": true, "message": "..."} — and in local development with no email provider configured, a login_url to open directly.

curl https://golem.to/api/auth/magic-link \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'

Exchanges the token from the sign-in email for a session. Public.

token

string · required

The golem_login_... token from the emailed link.

Returns

token (a session token to send as Authorization: Bearer ...), user_id, email.

The user (or key) behind the request, the team it acts for, and its role. Call it first: every other endpoint is scoped to this one team.

Invalidates the current session token. API keys are revoked via DELETE /api/keys/<id>, not here.

Every key the team holds — label, creation, expiry — never the secret, which is shown once at creation. OAuth-connected assistants appear here too, labelled OAuth: ...; revoking the key disconnects them.

Creates a team-scoped key that authenticates both /api/* and POST /mcp. Its authority is capped by the role of whoever mints it. Requires a session — a key cannot mint keys, because a key that can mint keys defeats revocation.

label	string	What this key is for; shown in the list.
expires_in_days	int · 1–365	Days until the key stops working. Omitted: lives until revoked.

Returns

201 with the golem_key_... token. Store it now; it is not shown again.

curl https://golem.to/api/keys \
  -H "Authorization: Bearer $SESSION" \
  -H "Content-Type: application/json" \
  -d '{"label": "reporting script", "expires_in_days": 90}'

Immediate. Whatever holds the key — script, assistant, OAuth connection — loses access on its next request.

archived

true · false · all

Which slice: active (default), retired, or both.

Returns

Each link with its stats, short_url, and qr_url.

One link per place you promote. Point destination_url at a Golem form's public URL and every response traces back to this link; point it anywhere else and it still counts clicks.

destination_url	string · required	Where the short link sends people.
slug	string	The path after the host. Generated when omitted.
title	string	A name for your dashboard, not shown to visitors.
channel	string	The place this link lives: "newsletter", "linkedin", "flyer". This is what source comparison groups by.
domain_id	uuid	Serve from a branded domain instead of the primary host.
expires_at	RFC 3339	When the link stops redirecting.

Returns

201 with the link, its short_url, and a permanent qr_url.

curl https://golem.to/api/links \
  -H "Authorization: Bearer golem_key_..." \
  -H "Content-Type: application/json" \
  -d '{"destination_url": "https://golem.to/f/reg", "slug": "launch", "channel": "newsletter"}'

The link with stats, short_url, and qr_url.

Send only what changes. Editing the destination keeps the slug and the QR code — reprint nothing.

destination_url	string	New destination; the short URL does not change.
slug	string	Renames the public path. The old slug stops resolving.
title	string	Dashboard name.
channel	string	Reclassifies the link's place.
enabled	bool	false pauses the redirect without retiring it.
expires_at	RFC 3339 · null	null removes an expiry.

The URL answers 410 Gone; every recorded event is kept and the slug stays reserved. Nothing in Golem deletes. POST /api/links/<id>/restore undoes it.

The link's QR code as a PNG. Public and permanent — print it; editing the destination later does not invalidate it. Refused once the link is retired, for the same reason the URL is.

days

int · default 7

Reporting window.

Returns

Opens → form views → starts → responses for journeys that began at this link, with rates and their numerators and denominators.

archived

true · false · all

Which slice: active (default), retired, or both.

A form is a titled list of fields, published at /f/<slug>.

title	string	Shown to respondents.
fields	array	Field objects, in order — see below.
published	bool	true makes the public URL live. Default: draft.
slug	string	Public path. Generated when omitted.
description	string	Intro text under the title.
confirmation_message	string	Shown after submitting.
redirect_url	string	Send respondents somewhere after submitting instead.
logo_url · cover_image_url	string	The form's own branding.
notify_email	string	Emails each response as it arrives.
domain_id	uuid	Serve from a branded domain.

Each field

field_type	string · required	One of GET /api/form-field-types. Semantic types (email, phone, date, country...) carry their own validation.
label	string	The question.
key	string	Stable machine key. Derived from the label when omitted.
required	bool	Refuse submission without it.
options	string[]	For choice fields.
help · placeholder	string	Hint under the label · ghost text in the input.
hidden_value	string	For hidden fields: the value submitted.

curl https://golem.to/api/forms \
  -H "Authorization: Bearer golem_key_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Early access", "published": true, "fields": [
        {"field_type": "email", "label": "Work email", "required": true},
        {"field_type": "single_choice", "label": "Team size",
         "options": ["Just me", "2-10", "11+"]}]}'

The form with its fields and public URL. The respondent-facing contract lives at /f/<slug>/schema, which needs no auth.

Same fields as create; send only what changes. An empty string clears redirect_url, logo_url, cover_image_url, or notify_email. domain_id moves the form: null back to the primary host, an id onto that (active) branded domain. Sending fields replaces the field list — include id on fields you are keeping, so their answers stay attached.

The public form answers 410 Gone; every response is kept. POST /api/forms/<id>/restore undoes it.

The fourteen field types with their keys and what each validates. The form builder in the app is generated from this same list.

Responses with canonical answer values (a form answered in three languages is one dataset), arrival time, attribution to the link that brought each one, and location where known. /submissions.csv is the same data as a CSV export.

days

int · default 7

Reporting window.

Returns

Views → starts → responses, total and attributed submissions, and click-to-response computed only over clicks that could convert.

How many respondents picked each option, per choice field — the "what did people answer" view without downloading the CSV.

Countries and cities of the responses (not the traffic), plus a location object stating what the geolocation backend can actually know right now — so an empty list can say "no database loaded" instead of reading as "nobody, from nowhere".

The form's locales. PUT /api/forms/<id>/translations/<locale> adds or replaces one (labels, options, messages in that language); DELETE removes it. Respondents get the best match from ?lang=, then Accept-Language, then the default. Answers always store the canonical value.

days	int · default 7	Reporting window. Lifetime totals come separately, under all_time.
scope	all · links · forms	Which half of the product to report. Default: all.

Returns

Human opens, form views, starts, and responses for the period with change against the previous equal period; attributed_submissions and attributable_opens — the numerator and denominator of click_to_response_rate — reported alongside it, so "nobody converted" and "no link points at a form yet" stay distinguishable; and the top sources.

curl "https://golem.to/api/analytics/overview?days=30" \
  -H "Authorization: Bearer golem_key_..."

days	int · default 7	Reporting window.
form_id	uuid	Only journeys that ended at this form.

Returns

Per link: real filtered opens, responses produced, and the rate between them — not the share of attributed journeys, which would read 100% for every link that produced anything.

days	int · default 7	Reporting window.
scope	all · links · forms	Which half to chart.

Returns

Daily buckets, gap-filled — a day with nothing is a zero, so a chart cannot imply continuity that was not there.

days	int · default 7	Reporting window.
scope	all · links · forms	Which half to break down.

Returns

Request classification (human, agent, bot, preview, scanner), top referring hosts, channels, countries and cities, plus the location capability object.

days	int · default 7	Reporting window.
scope	all · links · forms	Which half to map.

Returns

Located clicks as city-centroid coordinates with counts, plus located and total so a map of three dots is never mistaken for the whole traffic.

Creates a revocable public page of one funnel — the thing you send a client or sponsor. The reporting window freezes at creation.

form_id	uuid · required	The form whose funnel the report shows.
link_id	uuid	Narrow to one link's journeys.
title	string	The heading the reader sees.
days	int	Days back from now.

Returns

201 with the public URL (/r/<token>). Append .json for the machine twin — every rate ships with its numerator and denominator.

curl https://golem.to/api/reports \
  -H "Authorization: Bearer golem_key_..." \
  -H "Content-Type: application/json" \
  -d '{"form_id": "...", "title": "March campaign", "days": 30}'

Every report the team has minted, with its URL and whether it is still live.

The public URL stops resolving for everyone, immediately. Idempotent.

The team's branded hostnames and their verification state.

hostname

string · required

e.g. go.company.com — a subdomain, since DNS cannot put a CNAME on an apex; apexes are refused. Golem serves only links and forms on it.

Returns

The two records to add: a CNAME for routing, and a TXT record (_golem.<hostname>) proving you control the DNS. The domain activates when a check sees both — a pointing CNAME alone is not proof of ownership.

Looks up the records as the world sees them and answers expected vs found, with concrete fix text when they disagree. Activation requires both the CNAME and the ownership TXT to verify. GET /api/domains/<id> reads the stored state without re-checking.

Nothing serves on the hostname any more and it becomes claimable again — removal is the one transition that releases a name rather than reserving it. Refused while unarchived links or forms still live on the domain: archive them, or move the forms first (PATCH /api/forms/<id> with domain_id). Recorded events are kept. Idempotent.