> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contactbutton.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API quickstart

> Get started with the Contact Button API by onboarding, creating a workspace and page, publishing it, and inspecting the resulting agent manifest.

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](/authentication#agent-first-signup), or have the represented human [create a scoped API key](/authentication#create-a-key-in-the-portal).

## 2. Create a workspace

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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.