API Reference

Authentication

Every request carries a bearer token. Create one under API tokens; it is shown once and stored only as a hash, so it cannot be recovered later.

curl https://lynkarr.com/api/v1/me \
  -H "Authorization: Bearer lyn1_your_token_here"

Plans & Allowances

API access starts on Starter; the free plan has none. The monthly allowance resets on the 1st and is counted per company, not per token, so issuing more tokens does not raise it. Exhausting it returns 402 with a quota_exceeded code.

Scopes

A token holds exactly the scopes it was given. A write scope does not imply the matching read scope — being explicit means a token's permissions are what the list says, with nothing inferred.

Endpoints

Base URL: https://lynkarr.com/api/v1. All requests and responses use JSON. The full list, with every parameter, is in the OpenAPI 3.1 specification.

A code comes back with these fields:

Repointing a code

The request most integrations exist to make.

curl -X PATCH https://lynkarr.com/api/v1/codes/code_abc123 \
  -H "Authorization: Bearer lyn1_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/recall-notice"}'

The short link and the scan history are unchanged. Only the destination moves. A static code refuses this with 400, because its destination is encoded in the printed symbol and genuinely cannot change.

Creating a code

curl -X POST https://lynkarr.com/api/v1/codes \
  -H "Authorization: Bearer lyn1_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Batch 4471", "url": "https://example.com/batch/4471"}'

The response includes encode — the value to render into the QR symbol. Rendering happens on your side or in our designer; the API stores the definition and owns the redirect.

Reading scans

curl "https://lynkarr.com/api/v1/analytics/codes/code_abc123?days=30" \
  -H "Authorization: Bearer lyn1_your_token_here"

Aggregated rather than raw: totals, unique visitors, a daily series and a country breakdown. Individual scan records are never returned, and no IP address is stored to return.

Errors

Every failure returns the same shape. Match on code, never on the sentence — the wording will be improved, the code will not change.

{
  "error": {
    "code": "forbidden",
    "message": "This token does not have the `codes:write` scope.",
    "docs": "https://lynkarr.com/docs/api"
  }
}

A revoked token, an unknown token and one belonging to a suspended company all return the same 401. Distinguishing them would make this endpoint a way to test whether a guessed token exists.

Rate limit and quota

Two separate ceilings, because they fail for different reasons and are fixed in different ways.

The per-minute limit, per token. Exceeding it returns 429 with Retry-After in seconds. This protects the platform rather than metering you — wait a moment and continue.

The monthly allowance above, per company. Exhausting it returns 402 and quota_exceeded; waiting will not help until the month turns over.

Every response carries both, so an integration can pace itself rather than discovering a ceiling by hitting it: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and — on metered plans — Quota-Limit and Quota-Remaining.

Versioning

The version is in the path. /api/v1 will not change shape beneath you: fields may be added, but nothing that exists today will be removed or repurposed. A breaking change would arrive as /api/v2.

Create a token