API reference

Overview

A JSON API over the workspace: contacts, signals, queue and connections. Everything the agents write is readable, and most of it is writable.

Base URL

text

https://api.trygtm.com/v1

The version is in the path and will not change under you. A breaking change ships as /v2; /v1 keeps its contract.

Authentication

A workspace API token in an Authorization header. Tokens are scoped — a token that can read contacts cannot enqueue a send unless it was issued with that scope. Every endpoint page lists the scopes it requires.

curl https://api.trygtm.com/v1/contacts \
  -H "Authorization: Bearer $TRYGTM_API_TOKEN"

Errors

Errors return the HTTP status plus a stable machine-readable code. Branch on code, never on the message — messages are written for people and get rewritten.

Code	Status	Meaning
`invalid_request`	400	A parameter is missing or malformed.
`unauthorized`	401	No token, or the token is not valid.
`insufficient_scope`	403	The token is valid but lacks the scope this endpoint requires.
`not_found`	404	No such resource in this workspace.
`suppressed`	409	The address or domain is on a suppression list and cannot be written.
`quota_exhausted`	402	The credit allowance is spent and overage is not enabled.
`rate_limited`	429	Too many requests. Retry after the header says.

Error shape

json

{
  "error": {
    "code": "insufficient_scope",
    "message": "This token cannot write contacts.",
    "required_scope": "contacts:write"
  }
}

Pagination

Cursor-based. A list response carries next_cursor, which is opaque and either a string or null. Do not construct one, and do not assume offsets — contacts are written continuously by the sweep, so an offset walk would skip and repeat rows.

Rate limits

Per token. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 carries Retry-After in seconds; honour it rather than backing off on a schedule of your own.