Skip to main content

API overview

The GTM Clarity REST API lets you manage your agents (called customers in the API), read their conversations, messages, resolved identities, conversions and resolutions, read your usage, manage outbound webhook endpoints, and manage API keys.

Base URL: https://app.gtmclarity.ai/api/v1

api.gtmclarity.ai is reserved for a future host and is not live. Use the base URL above.

The machine-readable OpenAPI 3.1 description is published at https://app.gtmclarity.ai/api/v1/openapi.json. It needs no key, and is the source these pages follow.

Authentication​

Every request needs an API key, sent as a bearer token:

curl https://app.gtmclarity.ai/api/v1/customers \
-H "Authorization: Bearer $GTMC_API_KEY"

Keys start with gtmc_. Create one in the dashboard under Settings → API keys (your account Owner or an Admin can do this), or with POST /keys. A key is shown in full exactly once, when it is created; only its prefix is shown afterwards. Keys are secret: never put one in client-side code. The chat widget does not use an API key; it identifies itself with the customer's widgetKey.

A missing, malformed, revoked or expired key returns 401.

Tiers​

Each key has a tier. A higher tier can do everything a lower one can.

TierCan call
readEvery GET endpoint except GET /keys
writeAlso: create and update customers, update widget config, create, update and rotate webhook endpoints
adminAlso: delete customers, delete webhook endpoints, and every /keys endpoint

A write key can register a webhook endpoint, and webhook payloads include visitor details, so treat write keys as trusted.

Scopes​

A key is either agency scoped (every customer in your account) or customer scoped (one customer). Keys created in the dashboard are agency scoped. A customer-scoped key can only reach its own customer: it can use GET, PATCH and DELETE /customers/{id} and everything under /customers/{id}/ for that one id, plus /conversions and /resolutions (which it filters to that customer). It gets 403 on GET and POST /customers, /usage and /keys.

Conventions​

  • Request and response bodies are JSON. Field names are camelCase; query parameters are snake_case.
  • Ids are integers, except orgId, widgetKey, visitorId and resolvedPersonId, which are strings.
  • Timestamps are ISO 8601 in UTC, for example 2026-10-14T15:04:05.000Z. Date-time query parameters (started_after, created_after, from, to) take the same format and must end in Z.
  • Boolean query parameters take the strings true or false.
  • Every response carries an X-Request-Id header. Quote it when you contact support.

Pagination​

List endpoints return newest first, in pages:

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

Pass limit (1 to 100, default 20) and, to get the next page, starting_after set to the id of the last item you received. Keep going while has_more is true.

Two endpoints differ:

  • Conversation messages are returned oldest first; starting_after defaults to 0 and limit to 50.
  • Webhook deliveries return nextCursor instead of has_more. Pass it back as cursor; it is null on the last page.

GET /customers/{id}/webhook-endpoints and GET /keys are not paginated: they return every row in data.

Errors​

Errors use one envelope:

{
"error": {
"type": "not_found_error",
"code": "not_found",
"message": "Customer not found",
"request_id": "3f2c9a4e-6b1d-4e8a-9f0c-2a7d5e1b8c43"
}
}
StatustypeWhen
400invalid_request_errorInvalid body, query or pagination parameters (code: invalid_request), or an update to a deactivated customer (customer_deactivated)
401authentication_errorMissing, malformed, invalid, revoked or expired key
403permission_errorThe key's tier or scope does not allow the request (forbidden), or the account is suspended (account_stopped)
404not_found_errorThe resource does not exist, or this key cannot see it
409idempotency_errorAn Idempotency-Key was reused for a different request (key_reused)
429rate_limit_errorRate limit exceeded (rate_limited)

A resource that exists but is outside your key's reach returns 404, the same as one that does not exist.

Rate limits​

Limits are per key, per one-minute window: read keys 600 requests, write keys 120, admin keys 60. Responses carry:

  • X-RateLimit-Limit: requests allowed in the current window
  • X-RateLimit-Remaining: requests left in the current window
  • X-RateLimit-Reset: Unix time when the window resets

A 429 also carries Retry-After, in seconds.

Idempotency​

POST /customers accepts an optional Idempotency-Key header (1 to 255 characters). Repeating the same request with the same key within 24 hours returns the stored response, with the header Idempotent-Replay: true, instead of creating a second customer. Reusing the key for a different request returns 409.

Endpoints​

MethodPathTierPage
GET/customersreadCustomers & conversations
POST/customerswriteCustomers & conversations
GET/customers/{id}readCustomers & conversations
PATCH/customers/{id}writeCustomers & conversations
DELETE/customers/{id}adminCustomers & conversations
GET/customers/{id}/widget-configreadCustomers & conversations
PATCH/customers/{id}/widget-configwriteCustomers & conversations
GET/customers/{id}/conversationsreadCustomers & conversations
GET/customers/{id}/conversations/{conversationId}readCustomers & conversations
GET/customers/{id}/conversations/{conversationId}/messagesreadCustomers & conversations
GET/customers/{id}/identitiesreadIdentities & resolutions
GET/resolutionsreadIdentities & resolutions
GET/resolutions/{id}readIdentities & resolutions
GET/conversionsreadEvents & webhooks
GET/conversions/{id}readEvents & webhooks
GET/customers/{id}/webhook-endpointsreadEvents & webhooks
POST/customers/{id}/webhook-endpointswriteEvents & webhooks
GET/customers/{id}/webhook-endpoints/{endpointId}readEvents & webhooks
PATCH/customers/{id}/webhook-endpoints/{endpointId}writeEvents & webhooks
DELETE/customers/{id}/webhook-endpoints/{endpointId}adminEvents & webhooks
POST/customers/{id}/webhook-endpoints/{endpointId}/rotate-secretwriteEvents & webhooks
GET/customers/{id}/webhook-endpoints/{endpointId}/deliveriesreadEvents & webhooks
GET/usagereadbelow
GET/usage/timeseriesreadbelow
GET/keysadminbelow
POST/keysadminbelow
DELETE/keys/{id}adminbelow
POST/keys/{id}/rotateadminbelow

Usage​

Both usage endpoints cover the whole account, so they need an agency-scoped key.

Get account usage​

GET /api/v1/usage HTTP/1.1
Host: app.gtmclarity.ai
Authorization: Bearer gtmc_your_key_here
{
"billingStatus": "active",
"customers": [
{
"customerId": 42,
"name": "Acme website",
"conversionType": "booked_meeting",
"active": true,
"conversions": 18,
"billed": 16,
"unbilled": 2,
"spentCents": 200000,
"priceCents": 12500,
"spendCapCents": null,
"billResolutions": true,
"resolutions": 240,
"resolutionsBilled": 240,
"resolutionsUnbilled": 0,
"resolutionSpentCents": 2400,
"resolutionPriceCents": 10,
"resolutionHasOverride": false
}
],
"resolutionDefaultCents": 10,
"totals": {
"conversions": 18,
"spentCents": 200000,
"resolutions": 240,
"resolutionSpentCents": 2400
}
}

billingStatus is one of trialing, active, past_due, canceled. Money is in cents. spendCapCents and resolutionDefaultCents can be null. Responses: 200, 401, 403, 429.

Get a usage timeseries​

GET /api/v1/usage/timeseries?bucket=week&from=2026-07-01T00:00:00Z HTTP/1.1
Host: app.gtmclarity.ai
Authorization: Bearer gtmc_your_key_here
ParameterTypeNotes
bucketday or weekDefault day
fromdate-timeDefault: 30 days (or 12 weeks) before to
todate-timeDefault: now
{
"granularity": "week",
"from": "2026-07-01T00:00:00.000Z",
"to": "2026-10-14T15:04:05.000Z",
"buckets": [
{
"bucket": "2026-10-12T00:00:00.000Z",
"conversions": 4,
"resolutions": 51,
"conversionSpentCents": 50000,
"resolutionSpentCents": 510
}
]
}

Responses: 200, 400, 401, 403, 429.

API keys​

Every /keys endpoint needs an admin key with agency scope, and covers the keys in your own account.

List API keys​

GET /api/v1/keys HTTP/1.1
Host: app.gtmclarity.ai
Authorization: Bearer gtmc_your_key_here
{
"data": [
{
"id": 7,
"name": "Zapier integration",
"keyPrefix": "gtmc_Q2x9aB",
"tier": "read",
"scope": "agency",
"customerId": null,
"status": "active",
"lastUsedAt": "2026-10-13T09:12:44.000Z",
"expiresAt": null,
"createdAt": "2026-09-02T14:00:00.000Z"
}
]
}

scope is platform_admin, agency or customer; status is active or revoked. Responses: 200, 401, 403, 429.

Create an API key​

POST /api/v1/keys HTTP/1.1
Host: app.gtmclarity.ai
Authorization: Bearer gtmc_your_key_here
Content-Type: application/json

{
"name": "Reporting export",
"tier": "read",
"scope": "customer",
"customerId": 42,
"expiresAt": "2027-01-01T00:00:00Z"
}
FieldTypeNotes
namestringRequired, 1 to 100 characters
tierread, write or adminRequired
scopeagency or customerRequired
customerIdintegerRequired for customer scope, not allowed for agency
expiresAtdate-timeOptional

Returns 201 with the key's fields plus plaintext, the full key. Store it now: it is never shown again. Responses: 201, 400, 401, 403, 429.

Revoke an API key​

DELETE /api/v1/keys/7 HTTP/1.1
Host: app.gtmclarity.ai
Authorization: Bearer gtmc_your_key_here
{
"revoked": true,
"id": 7
}

self_revoked: true is added when the key you revoked is the one that made the request. Revoking an already revoked key succeeds. Responses: 200, 401, 403, 404, 429.

Rotate an API key​

POST /api/v1/keys/7/rotate HTTP/1.1
Host: app.gtmclarity.ai
Authorization: Bearer gtmc_your_key_here

Replaces the key's secret and keeps its id, name, tier and scope. The old secret stops working at once. Returns 200 with the same shape as create, including the new plaintext. A revoked key cannot be rotated (404). Responses: 200, 401, 403, 404, 429.