API quickstart - Contact Button

This workflow creates an HTML-first page at button.contact/{slug} and makes the same profile discoverable to agents.

1. Get a token

Use the agent signup flow, or have the represented human create a scoped API key.

2. Create a workspace

curl -X POST https://api.contactbutton.com/v1/workspaces \
  -H "Authorization: Bearer $CONTACTBUTTON_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: workspace-acme-01' \
  -d '{"name":"Acme","website_url":"https://acme.example"}'

Keep the returned workspace UUID. API v1 never requires a session-selected tenant.

3. Create and publish a page

curl -X POST https://api.contactbutton.com/v1/workspaces/$WORKSPACE_ID/pages \
  -H "Authorization: Bearer $CONTACTBUTTON_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: page-acme-01' \
  -d '{
    "name":"Acme Support",
    "slug":"acme-support",
    "bio":"Book a demo, request a callback, or read our support articles.",
    "agent_instructions":"Use published knowledge first. Ask before requesting a material action."
  }'

curl -X POST https://api.contactbutton.com/v1/workspaces/$WORKSPACE_ID/pages/$PAGE_ID/publish \
  -H "Authorization: Bearer $CONTACTBUTTON_TOKEN" \
  -H 'Idempotency-Key: publish-acme-01'

4. Verify human and agent views

Open https://button.contact/acme-support for the canonical HTML page, then inspect:

curl https://button.contact/acme-support/manifest.json
curl https://button.contact/acme-support/index.md
curl https://button.contact/acme-support/.well-known/agent-card.json

5. Add a custom domain

Create the domain through API v1, publish the returned CNAME target, and call the verification endpoint. The button.contact URL stays as a stable platform identity; the verified custom domain becomes canonical.