797.cx API

Version 1 · base URL https://app.797.cx/api/v1 · openapi.json (download) · m2m-spec.json (download)

Authentication

Create a key under Settings → API keys and send it as a bearer token. Keys are scoped (see each endpoint) and act as their owner inside one workspace.

curl https://app.797.cx/api/v1/links -H "Authorization: Bearer cx_live_…" \
  -H "content-type: application/json" -d '{"url":"https://example.com"}'

Errors

Every error has the same shape. Branch on code, not on the message. Quote request_id (also in the X-Request-Id header) when reporting a problem.

{ "error": "body.url must NOT have fewer than 1 characters", "code": "validation_failed",
  "details": [{ "field": "body.url", "message": "must NOT have fewer than 1 characters" }],
  "request_id": "req_4f2a…" }

Common codes: validation_failed, unauthorized, insufficient_scope, forbidden, not_found, conflict, plan_required, rate_limited, idempotency_key_reused, invalid_cursor, internal_error.

Plan Quotas & Rate Limits

Requests per minute and link-creation quotas depend on the workspace plan. All API keys in a workspace share one unified budget. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (unix seconds); over the limit you get 429 with Retry-After.

PlanAPI RPMLinks / hrMonthly LinksMonthly ClicksMonthly API ReqWebhooksSeats
Free602001,0005,00050,00021
Hobby1205005,00025,000200,00052
Pro600200025,000150,0001,000,000205
Team120010000100,000500,0005,000,0005020
Enterprise300050000∞∞∞100∞

Idempotency

Send Idempotency-Key: <unique string> on any POST or PATCH. For 24 hours a retry with the same key and body returns the original response (header Idempotent-Replayed: true) instead of creating a second link. The same key with a different body is rejected with 422 idempotency_key_reused.

Paging

GET /links returns { links, total, limit, next_cursor }. Pass cursor=<next_cursor> (with the same sort/dir) for the next page; it stays correct while links are being added. offset still works for jumping to a page.

Webhooks

Events: link.created, link.updated, link.deleted, link.flagged, link.clicked (plus ping from the test button). link.clicked is batched: data.clicks holds every click from one flush (sub-second). Each delivery is a POST with X-797-Event, X-797-Delivery and X-797-Signature: t=<unix>,v1=<hex>, where v1 = HMAC-SHA256(secret, t + "." + rawBody). Answer 2xx within 10 s. Failures retry 8 times over about 11 hours; 50 failures in a row switch the endpoint off.

// Node.js — verify a delivery
const [t, v1] = sig.split(',').map((p) => p.split('=')[1]);
const ok = Math.abs(Date.now() / 1000 - t) < 300 && crypto.timingSafeEqual(
  Buffer.from(v1, 'hex'),
  crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest());

Live clicks are also available as Server-Sent Events: GET /api/v1/stream (scope analytics:read).

Identity

GET /meWho is calling: user, workspace, auth type and key scopes

Any valid key

Aliases

GET /links/{id}/aliasesList extra codes pointing at this link

Scope links:read

Path
id requiredstring
POST /links/{id}/aliasesAdd an alias code

Scope links:write · write role

Path
id requiredstring
Body (JSON)
code requiredstring
subdomainstring
ci_codeboolean
DELETE /links/{id}/aliases/{aliasId}Remove an alias

Scope links:write · write role

Path
id requiredstring
aliasId requiredstring

Targeting

GET /links/{id}/targetingDevice / geo rules, campaign and experiment

Scope links:read

Path
id requiredstring
PUT /links/{id}/rules/deviceReplace device rules

Scope links:write · write role

Path
id requiredstring
Body (JSON)
rulesarray
PUT /links/{id}/rules/geoReplace geo rules (country: Hobby+, region: Pro+)

Scope links:write · write role

Path
id requiredstring
Body (JSON)
rulesarray
PUT /links/{id}/campaignSet UTM campaign parameters

Scope links:write · write role

Path
id requiredstring
PUT /links/{id}/experimentConfigure an A/B experiment

Scope links:write · write role

Path
id requiredstring

Analytics

GET /links/{id}/statsClick analytics for one link

Scope analytics:read

Path
id requiredstring
Query
range"1" | "7" | "30" | "90" | "365" | "all"
GET /links/{id}/clicks.csvRaw click log as CSV

Scope analytics:read

Path
id requiredstring
GET /analyticsWorkspace-wide breakdowns

Scope analytics:read

Query
range"1" | "7" | "30" | "90" | "365" | "all"
hoststringExact short-link host to include, including an optional subdomain.
fromstringInclusive custom window start date (YYYY-MM-DD).
tostringInclusive custom window end date (YYYY-MM-DD).
GET /overviewTotals, 30-day trend and top links

Scope analytics:read

Query
hoststringExact short-link host to include, including an optional subdomain.
GET /streamLive clicks as Server-Sent Events (event: click)

Scope analytics:read

Query
link_idstring

QR codes

POST /uploadUpload an image (logo, social card) as a data URL

Scope links:write · write role

GET /links/{id}/qrQR for a link: png/svg/pdf file, or JSON data URL when no format

Scope links:read

Path
id requiredstring
Query
format"png" | "svg" | "pdf"
inline"0" | "1"
PUT /links/{id}/qrSave the link's default QR design

Scope links:write · write role

Path
id requiredstring
POST /links/{id}/qr/renderRender a QR design without saving

Scope links:read

Path
id requiredstring
GET /links/{id}/qr/publishedList published QR snapshots

Scope links:read

Path
id requiredstring
POST /links/{id}/qr/publishPublish a QR snapshot

Scope links:write · write role

Path
id requiredstring
PATCH /links/{id}/qr/published/{pid}Update a published QR

Scope links:write · write role

Path
id requiredstring
pid requiredstring
DELETE /links/{id}/qr/published/{pid}Revoke a published QR

Scope links:write · write role

Path
id requiredstring
pid requiredstring
GET /links/{id}/qr/published/{pid}/previewImage preview of a published QR

Scope links:read

Path
id requiredstring
pid requiredstring
GET /qr-codesList all published QR codes across the workspace

Scope links:read

Query
qstring
status"all" | "on" | "off" | "revoked"
limitinteger Max 200.
POST /qr/renderRender a styled static QR image without saving

Scope links:read

Query
format"png" | "svg" | "pdf"
Body (JSON)
text requiredstring
format"png" | "svg" | "pdf"
configobject
logostring
POST /qr/dynamicCreate a dynamic short link + styled QR snapshot in one call

Scope links:write · write role

Body (JSON)
type"url" | "wifi" | "vcard" | "whatsapp" | "text" | "email" | "sms" | "phone" | "location" | "event" | "social" | "crypto"
urlstring
textstring
fieldsobject
titlestring
namestring
aliasstring
subdomainstring
domainstring
kind"unique" | "link"
previewboolean
configobject
logostring
PATCH /links/{id}/qr-cardUpdate a dynamic QR card payload (Wi-Fi, vCard, Event, etc.)

Scope links:write · write role

Path
id requiredstring

Folders

GET /foldersList folders

Scope folders:read

POST /foldersCreate a folder

Scope folders:write · write role

Body (JSON)
name requiredstring
colorstring
PATCH /folders/{id}Rename a folder

Scope folders:write · write role

Path
id requiredstring
Body (JSON)
name requiredstring
DELETE /folders/{id}Delete a folder (links are kept)

Scope folders:write · write role

Path
id requiredstring

Tags

GET /tagsList tags

Scope tags:read

PUT /links/{id}/tagsReplace a link's tags

Scope tags:write · write role

Path
id requiredstring
Body (JSON)
tagsstring[] Max 50 items.

Domains

GET /subdomains/checkCheck if a subdomain or host exists and whether the client has access

Scope domains:read | links:read | links:write

Query
hoststringFull hostname to check (e.g. dev.797.cx or mybrand.com)
subdomainstringSubdomain label or multi-level label (e.g. dev or api.dev)
domainstringParent domain name (defaults to 797.cx)
GET /domains/checkCheck if a subdomain or host exists and whether the client has access

Scope domains:read | links:read | links:write

Query
hoststringFull hostname to check (e.g. dev.797.cx or mybrand.com)
subdomainstringSubdomain label or multi-level label (e.g. dev or api.dev)
domainstringParent domain name (defaults to 797.cx)
GET /domainsDomains and subdomains available to the workspace

Scope domains:read

POST /domainsAdd a custom domain (workspace admin or platform admin)

Scope domains:write

Body (JSON)
host requiredstringDomain name (e.g. 787.cc)
kind"platform" | "byo"platform: platform-wide (platform admin only). byo: workspace customer domain.
workspace_idstringCustomer workspace ID (platform admin override; defaults to active workspace).
POST /domains/{id}/verifyVerify a custom domain DNS configuration (workspace admin or platform admin)

Scope domains:write

Path
id requiredstring
DELETE /domains/{id}Remove or disable a custom domain (workspace admin or platform admin)

Scope domains:write

Path
id requiredstring
PUT /domains/{id}/indexSet or clear what the bare apex custom domain root (https://domain/) serves

Scope domains:write

Path
id requiredstring
Body (JSON)
link_idanyLink ID/UUID, or null to clear.
POST /domains/{id}/subdomainsCreate a subdomain on custom domain (self-service) or request on primary domain

Scope domains:write · write role

Path
id requiredstring
Body (JSON)
labelstringSubdomain label or multi-level subdomain (e.g. ss22 or sub.sub.sub)
namestringSubdomain name alias for label
notestringOptional request note for platform domain requests
GET /subdomain-requestsMy pending subdomain requests

Scope domains:read

DELETE /subdomain-requests/{id}Cancel a subdomain request

Scope domains:write · write role

Path
id requiredstring
PUT /domains/{id}/subdomains/{subId}/indexSet what the bare subdomain root (https://label.domain/) serves

Scope domains:write · write role

Path
id requiredstring
subId requiredstring
Body (JSON)
link_idanyLink ID/UUID, or null to clear.
DELETE /domains/{id}/subdomains/{subId}Remove a subdomain

Scope domains:write · write role

Path
id requiredstring
subId requiredstring

Webhooks

GET /webhooksList webhook endpoints (workspace owner/admin)

Scope webhooks:read

POST /webhooksCreate a webhook endpoint — the signing secret is returned once

Scope webhooks:write · write role

Body (JSON)
url requiredstring
events"*" | "link.created" | "link.updated" | "link.deleted" | "link.flagged" | "link.clicked"[]
descriptionstring
GET /webhooks/{id}Get one webhook endpoint

Scope webhooks:read

Path
id requiredstring
PATCH /webhooks/{id}Update URL, events, description or active flag

Scope webhooks:write · write role

Path
id requiredstring
Body (JSON)
urlstring
events"*" | "link.created" | "link.updated" | "link.deleted" | "link.flagged" | "link.clicked"[]
descriptionstring
activeboolean
DELETE /webhooks/{id}Delete a webhook endpoint

Scope webhooks:write · write role

Path
id requiredstring
POST /webhooks/{id}/rotate-secretIssue a new signing secret (returned once)

Scope webhooks:write · write role

Path
id requiredstring
POST /webhooks/{id}/pingQueue a test `ping` delivery

Scope webhooks:write · write role

Path
id requiredstring
GET /webhooks/{id}/deliveriesDelivery log (30 days), newest first

Scope webhooks:read

Path
id requiredstring
Query
status"pending" | "success" | "failed"
beforestring
limitinteger Max 100.
POST /webhooks/{id}/deliveries/{deliveryId}/redeliverSend a past event again

Scope webhooks:write · write role

Path
id requiredstring
deliveryId requiredstring

API keys

GET /keysList API keys (owners/admins see all, members their own)

Scope keys:read

POST /keysCreate an API key — the secret is returned once

Scope keys:write · write role

Body (JSON)
namestring
scopes"*" | "links:read" | "links:write" | "analytics:read" | "domains:read" | "domains:write" | "folders:read" | "folders:write" | "tags:read" | "tags:write" | "keys:read" | "keys:write" | "webhooks:read" | "webhooks:write"[] Max 14 items.
expiresInDaysnumber
allowedIpsanyAllowed client machine IP addresses or CIDR blocks for this key
boundMachineNamestringOptional machine identifier/label (e.g. prod-worker-01)
GET /keys/{id}/usageDaily request / error / rate-limited counts for a key (up to 35 days)

Scope keys:read

Path
id requiredstring
Query
daysinteger Max 35.
DELETE /keys/{id}Revoke an API key

Scope keys:write · write role

Path
id requiredstring