REST API · v1

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.

Overview

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.
Availability
The developer API (tokens and webhooks) is available on the . Free plans use the dashboard.
Overview

Base URL & versioning

All public API endpoints live under a single versioned base path on your TRIMS host:

Base URL
https://api.trims.app/api/v1

The 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.

Custom domains
API calls always go to api.trims.app, including calls about links on your own domains.
Overview

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 header
Authorization: Bearer trims_9f8a7b6c5d4e3f2a1b0c8d7e6f5a4b3c
FieldTypeDescription
Authorization (required)headerBearer <token>. Tokens begin with the trims_ prefix and are bound to one workspace.
Content-Typeheaderapplication/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.

Verify your token
curl https://api.trims.app/api/v1/links \
  -H "Authorization: Bearer $TRIMS_TOKEN"
Keep tokens server-side
Tokens are shown only once at creation and grant full scope-level access to a workspace. Never embed a live token in browser or mobile code. Rotate immediately if one leaks.
Overview

Scopes

Tokens are least-privilege by design. Each endpoint requires a specific scope; grant a token only the scopes its integration needs.

FieldTypeDescription
links.readscopeList and read links; generate QR codes.
links.writescopeCreate, update, and delete links.
tags.readscopeRead workspace tags.
domains.readscopeRead verified custom domains.
folders.readscopeRead folders.
analytics.readscopeRead analytics summaries and breakdowns.
Insufficient scope
Calling an endpoint without its scope returns 403 with {"error":"Insufficient permissions. Required scope: <scope>"}.
Overview

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.

FieldTypeDescription
Pro600 / min · 100,000 / monthStandard developer throughput.
Business1,500 / min · 500,000 / monthFor higher-volume automation (upcoming).
Premium3,000 / min · 2,000,000 / monthHigher ceilings are negotiated (upcoming).
429 response
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.

Be a good client
Batch where possible, cache reads, and honor Retry-After with exponential backoff rather than tight retry loops.
Overview

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.

FieldTypeDescription
200 / 201SuccessThe request succeeded (201 for resource creation).
400Bad RequestMalformed JSON or failed validation.
401UnauthorizedMissing, malformed, or revoked token.
403ForbiddenValid token, but missing scope or an upgrade-required plan gate.
404Not FoundResource doesn't exist or isn't in your workspace.
409ConflictDuplicate alias or domain.
429Too Many RequestsRate limit exceeded; retry after the given delay.
500Server ErrorSomething 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:

upgrade_required
{
  "error": "Advanced analytics require the Pro plan.",
  "code": "upgrade_required",
  "feature": "advanced_analytics",
  "requiredPlan": "pro"
}
Overview

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.

Paginated list
curl "https://api.trims.app/api/v1/links?limit=50&offset=50" \
  -H "Authorization: Bearer $TRIMS_TOKEN"
Paginated response shape
{
  "links": [ /* … */ ],
  "total": 3842
}
Overview

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.

GET/api/v1/openapi.json
Download the spec
curl https://api.trims.app/api/v1/openapi.json --output trims-openapi.json
Resources

Tags

Read the tags in your workspace to build filters or dashboards.

GET/api/v1/tags tags.read
200 response
{
  "tags": [
    { "id": "tag_1", "name": "campaign", "color": "#F3F1EC" },
    { "id": "tag_2", "name": "q4", "color": "#12B886" }
  ]
}
Resources

Domains

List the verified custom domains available for minting links in this workspace.

GET/api/v1/domains domains.read
200 response
{
  "domains": [
    { "id": "dom_1", "domain": "go.northlight.co", "verified": true, "ssl_status": "active" }
  ]
}
Resources

Folders

Folders group links for organization. Read them to power navigation or filtered creation.

GET/api/v1/folders folders.read
200 response
{
  "folders": [
    { "id": "fld_1", "name": "Campaigns", "linkCount": 42 }
  ]
}
Resources

Analytics

Read analytics for a link or your workspace. Requires the analytics.read scope (advanced metrics require the Pro plan).

GET/api/v1/analytics analytics.read

Pass 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
curl "https://api.trims.app/api/v1/analytics?alias=q4-launch&period=30d" \
  -H "Authorization: Bearer $TRIMS_TOKEN"
Example summary
{
  "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"
}
Deeper reports
Funnels, cohorts, retention, and ML insights are available in the dashboard analytics area. Raw click export is available via the analytics export in-app and to Pro tokens.
Resources

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.

GET/api/v1/qr?url={url} links.read
GET/api/v1/qr?code={shortCode} links.read
Fetch a QR image
curl "https://api.trims.app/api/v1/qr?url=https://go.northlight.co/q4-launch" \
  -H "Authorization: Bearer $TRIMS_TOKEN" --output qr.png
Dynamic QR
For a link's dynamic QR (whose destination you can change later), generate the code for the link's short URL — scans are tracked as clicks automatically.
Advanced

OAuth 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.

GET/oauth/authorize
POST/oauth/token
  1. 1Redirect the user to /oauth/authorize with your client_id, redirect_uri, response_type=code, and requested scopes.
  2. 2The user reviews the scopes and approves; TRIMS redirects back to your redirect_uri with a short-lived authorization code.
  3. 3Your server exchanges the code at /oauth/token for an access token and a refresh token.
  4. 4Call /api/v1/* with the access token; use the refresh token to obtain a new one when it expires.
Exchange the code
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_URI
Advanced

Webhooks

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.

Example delivery
{
  "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.

Verify (Node.js)
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));
}
Respond fast
Return a 2xx within a few seconds. Do heavy work asynchronously — TRIMS retries failed deliveries with backoff and records every attempt.
Advanced

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.json to 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.
Generate a typed client
npx @openapitools/openapi-generator-cli generate \
  -i https://api.trims.app/api/v1/openapi.json \
  -g typescript-fetch \
  -o ./trims-client
Advanced

Changelog

v1 · current
Links, tags, domains, folders, analytics, QR, OpenAPI spec, OAuth 2.0, and webhooks.
Compatibility
Additive changes (new fields/endpoints) ship within v1. Breaking changes will be released under a new version path.
Advanced

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.