API guide
API v3 is the recommended version for new integrations. V1 and v2 remain supported with their existing contracts. Use a separate v3 key when migrating; v3 keys cannot authenticate on legacy endpoints.
- Base URL:
https://links.t-api.de/v3 - Authentication:
Authorization: Bearer tl_YOUR_API_KEY - Create a key at https://dash.ternis.link/api-keys. Choose v3 and review the exact permissions. The secret is shown once.
- Send
Content-Type: application/jsonwith JSON bodies andAccept: application/json. - Complete v3 reference: fields, routes, permissions, filtering, pagination, analytics, targets, bulk and retries.
- OpenAPI 3.1 contract: schemas, executable examples and operation permissions.
First request
# Set API_KEY locally; never commit or log it.
curl --fail-with-body https://links.t-api.de/v3/me \
-H "Authorization: Bearer $API_KEY" -H 'Accept: application/json'
curl --fail-with-body https://links.t-api.de/v3/links \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: launch-example-001' \
-d '{"url":"https://example.com/launch"}'
/me reports data.permissions.granted, role-filtered effective permissions, default domain and enforced limits. An empty permission list can read these diagnostics. Profile name requires user:info; email independently requires user:email.
Creation returns 201 with Location and data.id, data.short_url, data.slug and data.domain.hostname. Use the ID for API operations. Omit domain to select the key preference, account default, then public fallback. An explicit unavailable domain fails validation.
Choose permissions
The default link_creator preset grants links:read, links:write, domains:read, qr:read. Link operations apply to links created by that key. To read every link in the same account, select user:links:read; analytics separately requires user:analytics:read. The account_read_only preset includes account links and QR codes plus domain discovery. Account grants never authorize other accounts. There are no wildcard grants. Key management, deletion and profile access require explicit permissions; see the permission matrix.
Quotas, errors and retries
Plan quotas and request throttles are shared across the account and its keys. A new key does not reset usage. /me reports limits.daily, limits.creation and limits.requests; null limits mean unlimited. Daily reset timestamps include the application timezone. Quota snapshots do not reserve capacity; concurrent daily creation accounting is not atomic.
JSON uses {data, error, meta}; failures include error.code, message, fields and retry_after_seconds. Keep X-Request-ID for support. Missing/invalid credentials return 401, insufficient permission 403, inaccessible resources 404, validation errors 422 and throttles/quotas 429 with Retry-After. QR responses may be SVG or PNG; key revocation returns empty 204.
Reuse the same Idempotency-Key and unchanged request for a retry of single or bulk POST creation within 24 hours. Changed payloads return 409. Unkeyed POST retries can create duplicates. Bulk creation and updates report individual outcomes, including 207 for partial success. See the retry contract before automating retries.
Existing integrations
- V2 guide and v2 OpenAPI: existing
destination_url/domain_idintegrations. - V1 guide and v1 OpenAPI: legacy API, guest creation, custom-domain registration, settings and account/privacy workflows.
- Authentication and browser auth API: key creation and short-lived session tokens.
V3 does not mirror every v1 route. Prefer v3 for scoped link workflows; keep explicit legacy credentials for features that still require v1. Test a replacement key before revoking its predecessor: token scope does not transfer the old key's links. Account permissions can provide access to those links when needed. Existing deployed v3 grants are renamed by the compatibility migration described in the v3 rollout instructions.