# Golem.to

> Short links and simple forms with attribution: when a Golem link points at
> a Golem form, every response is traced back to the link that produced it.
> Bots, previews and scanners are counted separately, never in your totals.

Everything the dashboard can do, the API and MCP can do.

## Authentication
- API key: `Authorization: Bearer golem_key_...` on /api/* and POST /mcp.
  Keys are minted in the dashboard (/app, API tab), are team-scoped, and may
  carry an expiry. Revoking a key disconnects whatever holds it.
- MCP clients can instead connect by OAuth: point the client at https://golem.to/mcp and
  it will discover https://golem.to/.well-known/oauth-protected-resource and walk the
  sign-in flow. The token it receives is an ordinary API key.

## MCP
- Endpoint: POST https://golem.to/mcp (streamable HTTP, JSON-RPC, one request per POST)
- Tools cover: account/team reads, links (create/update/list/archive/restore,
  QR), forms (create/update/list/archive/restore, submissions, CSV export,
  translations, machine-readable schema), analytics (overview, timeseries,
  breakdown, map, per-link and per-form funnels, source comparison), shared
  reports (create/list/revoke), domains.

## Machine-readable forms
- https://golem.to/f/{slug} with `Accept: application/json` (or /f/{slug}/schema):
  the form as JSON with stable field keys, types, and submit instructions.
- Submit: POST https://golem.to/f/{slug} as JSON; send `X-Golem-Agent: <name>` so your
  traffic is classified as agent, not bot.

## Shared reports
- https://golem.to/r/{token} — a public funnel report; append .json for the machine
  twin. Every rate carries its numerator and denominator; methodology fields
  state that bots are excluded and that opens are requests, not people.

## Reading the numbers
- Classifications: filtered_open (human), agent, bot, preview, scanner.
  Totals count only filtered_open.
- click_to_response divides responses attributed to a link by link opens
  that landed on a form. view_to_response divides responses by human form
  views. A zero denominator means "nothing to measure", not "0%".

## More
- Human documentation: https://golem.to/docs
- REST API base: https://golem.to/api (same nouns as the MCP tools)
- Health: https://golem.to/healthz