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.
| Tier | Can call |
|---|---|
read | Every GET endpoint except GET /keys |
write | Also: create and update customers, update widget config, create, update and rotate webhook endpoints |
admin | Also: 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,visitorIdandresolvedPersonId, 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 inZ. - Boolean query parameters take the strings
trueorfalse. - Every response carries an
X-Request-Idheader. 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_afterdefaults to0andlimitto 50. - Webhook deliveries return
nextCursorinstead ofhas_more. Pass it back ascursor; it isnullon 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"
}
}
| Status | type | When |
|---|---|---|
400 | invalid_request_error | Invalid body, query or pagination parameters (code: invalid_request), or an update to a deactivated customer (customer_deactivated) |
401 | authentication_error | Missing, malformed, invalid, revoked or expired key |
403 | permission_error | The key's tier or scope does not allow the request (forbidden), or the account is suspended (account_stopped) |
404 | not_found_error | The resource does not exist, or this key cannot see it |
409 | idempotency_error | An Idempotency-Key was reused for a different request (key_reused) |
429 | rate_limit_error | Rate 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 windowX-RateLimit-Remaining: requests left in the current windowX-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
| Method | Path | Tier | Page |
|---|---|---|---|
GET | /customers | read | Customers & conversations |
POST | /customers | write | Customers & conversations |
GET | /customers/{id} | read | Customers & conversations |
PATCH | /customers/{id} | write | Customers & conversations |
DELETE | /customers/{id} | admin | Customers & conversations |
GET | /customers/{id}/widget-config | read | Customers & conversations |
PATCH | /customers/{id}/widget-config | write | Customers & conversations |
GET | /customers/{id}/conversations | read | Customers & conversations |
GET | /customers/{id}/conversations/{conversationId} | read | Customers & conversations |
GET | /customers/{id}/conversations/{conversationId}/messages | read | Customers & conversations |
GET | /customers/{id}/identities | read | Identities & resolutions |
GET | /resolutions | read | Identities & resolutions |
GET | /resolutions/{id} | read | Identities & resolutions |
GET | /conversions | read | Events & webhooks |
GET | /conversions/{id} | read | Events & webhooks |
GET | /customers/{id}/webhook-endpoints | read | Events & webhooks |
POST | /customers/{id}/webhook-endpoints | write | Events & webhooks |
GET | /customers/{id}/webhook-endpoints/{endpointId} | read | Events & webhooks |
PATCH | /customers/{id}/webhook-endpoints/{endpointId} | write | Events & webhooks |
DELETE | /customers/{id}/webhook-endpoints/{endpointId} | admin | Events & webhooks |
POST | /customers/{id}/webhook-endpoints/{endpointId}/rotate-secret | write | Events & webhooks |
GET | /customers/{id}/webhook-endpoints/{endpointId}/deliveries | read | Events & webhooks |
GET | /usage | read | below |
GET | /usage/timeseries | read | below |
GET | /keys | admin | below |
POST | /keys | admin | below |
DELETE | /keys/{id} | admin | below |
POST | /keys/{id}/rotate | admin | below |
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
| Parameter | Type | Notes |
|---|---|---|
bucket | day or week | Default day |
from | date-time | Default: 30 days (or 12 weeks) before to |
to | date-time | Default: 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"
}
| Field | Type | Notes |
|---|---|---|
name | string | Required, 1 to 100 characters |
tier | read, write or admin | Required |
scope | agency or customer | Required |
customerId | integer | Required for customer scope, not allowed for agency |
expiresAt | date-time | Optional |
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.