Tertian GraphQL — API Reference

Endpoint and authentication

The Tertian GraphQL API is served at https://api.tertian.example/graphql over HTTPS only; cleartext HTTP requests return 426 Upgrade Required. All requests require a Bearer token in the Authorization header. Tokens are scoped (read, write, admin) and are issued from the workspace's Settings → API Keys page. Service-account tokens may not exceed read+write scope; admin operations require an interactive user login token.

Rate limits

The API enforces both per-token and per-IP limits. The default per-token limit is 600 query points per minute, where a typical 'project with first 50 issues' query consumes approximately 12 points. Per-IP limit is 6,000 points per minute aggregated across all tokens. Both limits return HTTP 429 with a Retry-After header when exceeded; the body is a GraphQL `errors` payload with the extension `code: RATE_LIMITED`.

Pagination

All list fields use Relay-style cursor pagination with `first`, `after`, `last`, and `before` arguments. The maximum value of `first` or `last` is 100; requesting more returns a validation error. There is no offset-based pagination. Cursors are opaque, base64-encoded strings; their structure is not part of the public API and is subject to change without notice between minor releases.

Mutations and idempotency

All mutations support the optional `clientMutationId` argument for idempotency: the API caches responses keyed on (token, clientMutationId) for 24 hours. Replaying the same mutation within the cache window returns the original response without re-executing. The `deleteProject` mutation is the only mutation that requires admin scope; it is not soft-delete and recovery requires opening a support ticket within 14 days of deletion.

Key facts

• The Tertian GraphQL API is served at https://api.tertian.example/graphql over HTTPS only.
• All requests require a Bearer token issued from Settings → API Keys.
• Pagination is Relay-style cursor pagination with no offset-based fallback.
• The default per-token rate limit is 600 query points per minute.
• Maximum value of `first` or `last` is 100; larger values return a validation error.
• Mutations support `clientMutationId` for 24-hour idempotency caching.
• Service-account tokens may not exceed read+write scope; admin requires interactive user login.
• Per-IP rate limit is 6,000 query points per minute aggregated across tokens.
• `deleteProject` is hard delete; recovery requires a support ticket within 14 days.

Details

product

Tertian

doc_type

api_reference

version

2025-11