The TRIMS
API Reference.
A predictable, resource-oriented REST API. JSON everywhere, bearer-token auth with granular scopes, and a machine-readable OpenAPI spec. Everything below maps one-to-one to a live endpoint under/api/v1.
Introduction
The TRIMS API lets you manage links, pull analytics, and generate QR codes programmatically. It follows REST conventions: resource-based URLs, standard HTTP verbs, JSON request and response bodies, and conventional status codes.
- All requests must be made over HTTPS.
- All requests are authenticated with a workspace-scoped bearer token.
- All responses are JSON, except binary endpoints like QR image export.
- Every request made with a token is logged on our side.
Base URL & versioning
All public API endpoints live under a single versioned base path on your TRIMS host:
https://api.trims.app/api/v1The version is pinned in the path (/v1). Backwards-incompatible changes ship under a new version; additive changes (new fields, new endpoints) may arrive within v1, so write clients that ignore unknown fields.
api.trims.app, including calls about links on your own domains.Authentication
Authenticate every request with a bearer token in the Authorization header. Create tokens in the dashboard under API Tokens, in the Developers section of the sidebar — you choose the workspace and the scopes each token carries.
Authorization: Bearer trims_9f8a7b6c5d4e3f2a1b0c8d7e6f5a4b3c| Field | Type | Description |
|---|---|---|
| Authorization (required) | header | Bearer <token>. Tokens begin with the trims_ prefix and are bound to one workspace. |
| Content-Type | header | application/json for POST/PATCH requests carrying a body. |
A token resolves to its workspace automatically — you never pass a workspace id. Requests with a missing, malformed, or revoked token return 401; a valid token lacking the required scope returns 403.
curl https://api.trims.app/api/v1/links \
-H "Authorization: Bearer $TRIMS_TOKEN"Scopes
Tokens are least-privilege by design. Each endpoint requires a specific scope; grant a token only the scopes its integration needs.
| Field | Type | Description |
|---|---|---|
| links.read | scope | List and read links; generate QR codes. |
| links.write | scope | Create, update, and delete links. |
| tags.read | scope | Read workspace tags. |
| domains.read | scope | Read verified custom domains. |
| folders.read | scope | Read folders. |
| analytics.read | scope | Read analytics summaries and breakdowns. |
403 with {"error":"Insufficient permissions. Required scope: <scope>"}.Rate limits
Two limits apply per workspace, across all of its tokens: a per-minute rate and a monthly request quota. Exceeding either returns 429 with a Retry-After header (in seconds) and a code saying which one you hit.
| Field | Type | Description |
|---|---|---|
| Pro | 600 / min · 100,000 / month | Standard developer throughput. |
| Business | 1,500 / min · 500,000 / month | For higher-volume automation (upcoming). |
| Premium | 3,000 / min · 2,000,000 / month | Higher ceilings are negotiated (upcoming). |
HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json
{
"error": "Too many requests. Slow down and retry shortly.",
"code": "rate_limit_exceeded",
"retryAfter": 12,
"limit": 600
}A spent monthly quota answers with code: "quota_exceeded" and a resetsAt timestamp instead. Retrying will not help until then.
Retry-After with exponential backoff rather than tight retry loops.Errors
TRIMS uses conventional HTTP status codes. 2xx means success, 4xx indicates a client problem (the JSON body explains it), and 5xx indicates a server error.
| Field | Type | Description |
|---|---|---|
| 200 / 201 | Success | The request succeeded (201 for resource creation). |
| 400 | Bad Request | Malformed JSON or failed validation. |
| 401 | Unauthorized | Missing, malformed, or revoked token. |
| 403 | Forbidden | Valid token, but missing scope or an upgrade-required plan gate. |
| 404 | Not Found | Resource doesn't exist or isn't in your workspace. |
| 409 | Conflict | Duplicate alias or domain. |
| 429 | Too Many Requests | Rate limit exceeded; retry after the given delay. |
| 500 | Server Error | Something went wrong on our end — safe to retry. |
Plan-gated errors
When an endpoint needs a higher plan, the response is a structured 403 your client can detect programmatically:
{
"error": "Advanced analytics require the Pro plan.",
"code": "upgrade_required",
"feature": "advanced_analytics",
"requiredPlan": "pro"
}Pagination
List endpoints are paginated with limit and offset query parameters (page works too, counted in steps of limit). limit defaults to 100 and is capped at 500. total is the full count after filters.
curl "https://api.trims.app/api/v1/links?limit=50&offset=50" \
-H "Authorization: Bearer $TRIMS_TOKEN"{
"links": [ /* … */ ],
"total": 3842
}OpenAPI spec
A machine-readable OpenAPI 3 document describes the entire public surface. Point Postman, Insomnia, or an OpenAPI code generator at it to scaffold a client in seconds.
/api/v1/openapi.jsoncurl https://api.trims.app/api/v1/openapi.json --output trims-openapi.jsonLinks
The core resource. List your workspace links or create new ones. Each link carries its rules and live click counters.
/api/v1/links links.read/api/v1/links links.writeThe link object
| Field | Type | Description |
|---|---|---|
| id | string | Unique identifier for the link. |
| shortCode | string | The alias / key after the domain (e.g. q4-launch). |
| shortUrl | string | The full short URL, including the domain. |
| url | string | The destination the link redirects to. |
| title | string | Human-readable title. |
| tags | string[] | Tag names attached to the link. |
| clickCount | integer | Total resolved clicks (after bot filtering). |
| createdAt | datetime | When the link was created (ISO 8601). |
List links
Supports search, tags (comma-separated), folder, domain, status, sort and order, and pagination.
curl "https://api.trims.app/api/v1/links?search=q4&tags=campaign&limit=50" \
-H "Authorization: Bearer $TRIMS_TOKEN"{
"links": [
{
"id": "lnk_8f2a",
"shortCode": "q4-launch",
"shortUrl": "https://go.northlight.co/q4-launch",
"url": "https://northlight.co/products/launch-2026",
"title": "Q4 Launch",
"tags": ["campaign", "q4"],
"clickCount": 12483,
"createdAt": "2026-02-01T10:22:00Z"
}
],
"total": 128
}Create a link
| Field | Type | Description |
|---|---|---|
| url (required) | string | Destination URL. Must be absolute and valid. |
| customCode | string | Custom alias. If omitted, a random code is generated. 409 if taken. |
| domainId | string | Id of the custom domain to mint on. Defaults to the platform domain. |
| title | string | Title for the dashboard and social previews. |
| tags | string[] | Tag names; unknown tags are auto-created. |
| utmSource… | string | Optional utmSource, utmMedium, utmCampaign, utmContent, utmTerm. |
| expiresAt | datetime | Optional expiry timestamp (ISO 8601). |
| password | string | Optional password to gate the destination. |
curl -X POST https://api.trims.app/api/v1/links \
-H "Authorization: Bearer $TRIMS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "url": "https://northlight.co/pricing", "customCode": "pricing", "tags": ["q4"] }'const res = await fetch("https://api.trims.app/api/v1/links", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TRIMS_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ url: "https://northlight.co/pricing", customCode: "pricing" }),
});
const link = await res.json();
console.log(link.shortUrl);Domains
List the verified custom domains available for minting links in this workspace.
/api/v1/domains domains.read{
"domains": [
{ "id": "dom_1", "domain": "go.northlight.co", "verified": true, "ssl_status": "active" }
]
}Folders
Folders group links for organization. Read them to power navigation or filtered creation.
/api/v1/folders folders.read{
"folders": [
{ "id": "fld_1", "name": "Campaigns", "linkCount": 42 }
]
}Analytics
Read analytics for a link or your workspace. Requires the analytics.read scope (advanced metrics require the Pro plan).
/api/v1/analytics analytics.readPass an alias for a single link, or omit it for workspace-wide aggregates. Control the window with period (24h, 7d, 30d, 90d, 12m) or days (1 to 365). Your plan caps how far back that reaches.
curl "https://api.trims.app/api/v1/analytics?alias=q4-launch&period=30d" \
-H "Authorization: Bearer $TRIMS_TOKEN"{
"summary": {
"total_clicks": 12483,
"unique_visitors": 8121,
"human_clicks": 11902,
"bot_clicks": 581,
"period_days": 30
},
"trends": { "daily_clicks": [ /* … */ ] },
"demographics": { "countries": [ /* … */ ], "devices": [ /* … */ ], "browsers": [ /* … */ ], "os": [ /* … */ ] },
"referrers": [ /* … */ ],
"timestamp": "2026-03-02T12:04:11Z"
}QR codes
Generate a QR code image for any URL, or pass code to render one of your links with its saved QR design. Requires links.read. This endpoint has its own limit of 30 requests per minute.
/api/v1/qr?url={url} links.read/api/v1/qr?code={shortCode} links.readcurl "https://api.trims.app/api/v1/qr?url=https://go.northlight.co/q4-launch" \
-H "Authorization: Bearer $TRIMS_TOKEN" --output qr.pngOAuth 2.0
Building an app that acts on behalf of other TRIMS users? Use the OAuth 2.0 authorization-code flow instead of a static token, so each user grants your app scoped access to their workspace.
/oauth/authorize/oauth/token- 1Redirect the user to /oauth/authorize with your client_id, redirect_uri, response_type=code, and requested scopes.
- 2The user reviews the scopes and approves; TRIMS redirects back to your redirect_uri with a short-lived authorization code.
- 3Your server exchanges the code at /oauth/token for an access token and a refresh token.
- 4Call /api/v1/* with the access token; use the refresh token to obtain a new one when it expires.
curl -X POST https://api.trims.app/oauth/token \
-d grant_type=authorization_code \
-d code=$AUTH_CODE \
-d client_id=$CLIENT_ID \
-d client_secret=$CLIENT_SECRET \
-d redirect_uri=$REDIRECT_URIWebhooks
Instead of polling, subscribe to events and TRIMS will POST a signed JSON payload to your endpoint whenever they occur. Manage webhook subscriptions under Webhooks, in the Developers section of the sidebar (API access / Pro required).
Events
link.created,link.updated,link.deleted
Clicks are not sent as webhooks; read them from /api/v1/analytics.
{
"id": "evt_2b9c6d1e",
"workspaceId": "ws_4f1a",
"timestamp": "2026-03-02T12:04:11Z",
"data": {
"link": "q4-launch",
"destination": "https://example.com/summer",
"shortCode": "q4-launch"
}
}Verifying signatures
Each delivery carries a Trims-Signature header of the form t=<unix seconds>,v1=<hex>. The v1 value is an HMAC-SHA256, keyed with your webhook secret, of the timestamp, a dot, and the raw request body. Recompute it, compare in constant time, and reject old timestamps so a captured delivery cannot be replayed.
import crypto from "node:crypto";
export function verify(rawBody, header, secret, toleranceSec = 300) {
const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
const t = Number(parts.t);
if (!t || !parts.v1 || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return expected.length === parts.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}SDKs & tooling
Use the raw REST API from any language, or generate a typed client from the OpenAPI spec.
- Point Postman or Insomnia at
https://api.trims.app/api/v1/openapi.jsonto import every endpoint. - Run openapi-generator to scaffold a client in your language of choice.
- Store your token in an environment variable (
TRIMS_TOKEN) — never in source control.
npx @openapitools/openapi-generator-cli generate \
-i https://api.trims.app/api/v1/openapi.json \
-g typescript-fetch \
-o ./trims-clientChangelog
Support
Stuck on an integration? We're happy to help.
Build something great
Create a scoped token under API Tokens in the dashboard and make your first API call in minutes.