Quickstart

This guide gets a developer from a new workspace to the first useful API reads. The base URL for all examples is https://app.gtmclarity.ai/api/v1.

Get an API key

There is no dashboard UI for API keys yet. Keys are managed through the API itself. Your first admin key is provisioned by GTM Clarity; contact support to obtain one.

Use that admin key to mint additional keys:

curl https://app.gtmclarity.ai/api/v1/keys \
  -X POST \
  -H 'Authorization: Bearer gtmc_admin_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "ci-reader",
    "tier": "read",
    "scope": "agency"
  }'

Use scope: "agency" for a key that can access every customer in your organization. Use scope: "customer" only when the key should be bound to one customer; customer-scoped keys also require customerId in the request body.

The response includes the plaintext key exactly once. Store it immediately. GTM Clarity stores only a hash after creation.

Make the first usage call

Call the usage endpoint with an agency-scope key:

curl https://app.gtmclarity.ai/api/v1/usage \
  -H 'Authorization: Bearer gtmc_your_key_here'

The response shape is:

{
  "billingStatus": "active",
  "customers": [
    {
      "customerId": 42
    }
  ],
  "totals": {
    "conversions": 12,
    "spentCents": 25800,
    "resolutions": 40,
    "resolutionSpentCents": 8000
  }
}

Usage is org-level. Customer-scoped keys are denied for this endpoint, so use an agency-scope key.

Read conversations

First list customers. Customer listing is cursor paginated and returns data plus has_more.

curl 'https://app.gtmclarity.ai/api/v1/customers' \
  -H 'Authorization: Bearer gtmc_your_key_here'

The response shape is:

{
  "data": [
    {
      "id": 42
    }
  ],
  "has_more": false
}

Then read conversations for one customer:

curl https://app.gtmclarity.ai/api/v1/customers/42/conversations \
  -H 'Authorization: Bearer gtmc_your_key_here'