797.cx API Version 1 · base URL https://app.797.cx/api/v1 · openapi.json (download ) · m2m-spec.json (download )
Auth Errors Rate limits Idempotency Paging Webhook guide Identity Links Link settings Aliases Targeting Analytics QR codes Folders Tags Domains Webhooks API keys
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.
Plan API RPM Links / hr Monthly Links Monthly Clicks Monthly API Req Webhooks Seats
Free 60 200 1,000 5,000 50,000 2 1 Hobby 120 500 5,000 25,000 200,000 5 2 Pro 600 2000 25,000 150,000 1,000,000 20 5 Team 1200 10000 100,000 500,000 5,000,000 50 20 Enterprise 3000 50000 ∞ ∞ ∞ 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
Links
GET
/linksList links — filter, sort, offset or cursor paging
Scope links:read
Query
hoststringExact short-link host to list, including an optional subdomain. qstringSearch code, destination, title, subdomain, tags. status"all" | "active" | "expired" | "paused" | "disabled" | "flagged"kind"link" | "bundle"folderstringteamstringtagstringsort"created" | "clicks" | "code"dir"asc" | "desc"limitinteger Max 100. offsetintegercursorstringnext_cursor from the previous page. Ignores offset.
POST
/linksCreate a short link
Scope links:write · write role
Body (JSON)
url required stringDestination URL (http/https). aliasstringCustom code. Omit for a random one. subdomainstringVanity subdomain label or multi-level subdomain (e.g. ss22 or sub.sub.sub) under the primary or custom domain. domainstringFull host (custom domain apex or <label>.domain). titlestringfallback_urlstringredirect_status"301" | "302" | "307" | "308"previewboolean
POST
/minipagesCreate a MyMiniPage (link-in-bio bundle) in one step
Scope links:write · write role
Body (JSON)
title required stringTitle shown at the top of the MyMiniPage descriptionstringBio, tagline or page description (supports rich text formatting) aliasstringCustom slug code for the short URL domainstringCustomer domain apex or custom host subdomainstringSubdomain label or multi-level subdomain (e.g. ss22 or sub.sub.sub) under the domain theme"clean" | "dark" | "glass" | "sunset" | "forest" | "neon"button_style"rounded" | "pill" | "square" | "glass"items required object[]List of links and block items on the page
GET
/links/{id}Get one link
POST
/links/{id}/duplicateDuplicate a link with its rules, campaign and experiment
Scope links:write · write role
GET
/links/{id}/slug-suggestionsSuggest alternative codes
PATCH
/links/{id}Update a link (destination, code, subdomain, status, title, expiry …)
Scope links:write · write role
DELETE
/links/{id}Delete a link
Scope links:write · write role
POST
/links/importCSV-style import of up to 500 rows (dry_run validates without writing)
Scope links:write · write role
Body (JSON)
rows required object[] Max 5000 items. dry_runboolean
POST
/links/bulkCreate up to 100 links; per-item results, partial success allowed
Scope links:write · write role
Body (JSON)
links required object[] Max 100 items.
PATCH
/links/bulkUpdate up to 100 links (same fields as PATCH /links/{id})
Scope links:write · write role
Body (JSON)
links required object[] Max 100 items.
POST
/links/bulk/deleteDelete up to 100 links
Scope links:write · write role
Body (JSON)
ids required string[] Max 100 items.
Link settings
GET
/links/{id}/editorEverything the editor needs for one link
PUT
/links/{id}/settings/{section}Save one settings section (lifecycle, password, cloaking, social, tracking, general)
Scope links:write · write role
Path
id required stringsection required "lifecycle" | "password" | "cloaking" | "social" | "tracking" | "general"
Body (JSON)
starts_atstringScheduled activation start time (lifecycle section) expires_atstringLink expiration time (lifecycle section) max_clicksintegerMaximum clicks (lifecycle section) expired_urlstringFallback URL when expired (lifecycle section) delete_atstringAuto-deletion timestamp (lifecycle section) passwordstringPassword for protected access (password section) enabledbooleantitlestringDisplay title or OG title (cloaking/social/general section) descriptionstringDescription or OG description (cloaking/social section) imagestringOpen Graph preview image URL or saved /uploads image (social section) gastringGoogle Analytics 4 Measurement ID (tracking section) fbstringMeta Pixel ID (tracking section) adrollstringAdRoll Pixel ID (tracking section) tiktokstringTikTok Pixel ID (tracking section) gtmstringGoogle Tag Manager Container ID (tracking section) target_urlstringDestination URL (general section) fallback_urlstringFailover destination (general section) redirect_status"301" | "302" | "307" | "308"HTTP redirect code (general section) ci_codeboolean
PUT
/links/{id}/bundleSave / update the MyMiniPage content and design
Scope links:write · write role
Body (JSON)
enabledbooleantitlestringdescriptionstringtheme"clean" | "dark" | "glass" | "sunset" | "forest" | "neon"button_style"rounded" | "pill" | "square" | "glass"logo_urlstringbanner_urlstringsocialobjectitemsobject[]
GET
/links/{id}/permissionsPer-link editor/viewer grants
PUT
/links/{id}/permissionsReplace per-link grants
Scope links:write · write role
POST
/links/{id}/social/fetchFetch Open Graph data from the destination (throttled)
Scope links:write · write role
POST
/links/{id}/cloak-checkCheck whether the destination allows framing (throttled)
Scope links:write · write role
Aliases
GET
/links/{id}/aliasesList extra codes pointing at this link
POST
/links/{id}/aliasesAdd an alias code
Scope links:write · write role
Body (JSON)
code required stringsubdomainstringci_codeboolean
DELETE
/links/{id}/aliases/{aliasId}Remove an alias
Scope links:write · write role
Path
id required stringaliasId required string
Targeting
GET
/links/{id}/targetingDevice / geo rules, campaign and experiment
PUT
/links/{id}/rules/deviceReplace device rules
Scope links:write · write role
PUT
/links/{id}/rules/geoReplace geo rules (country: Hobby+, region: Pro+)
Scope links:write · write role
PUT
/links/{id}/campaignSet UTM campaign parameters
Scope links:write · write role
PUT
/links/{id}/experimentConfigure an A/B experiment
Scope links:write · write role
Analytics
GET
/links/{id}/statsClick analytics for one link
Scope analytics:read
Query
range"1" | "7" | "30" | "90" | "365" | "all"
GET
/links/{id}/clicks.csvRaw click log as CSV
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)
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
Query
format"png" | "svg" | "pdf"inline"0" | "1"
PUT
/links/{id}/qrSave the link's default QR design
Scope links:write · write role
POST
/links/{id}/qr/renderRender a QR design without saving
GET
/links/{id}/qr/publishedList published QR snapshots
POST
/links/{id}/qr/publishPublish a QR snapshot
Scope links:write · write role
PATCH
/links/{id}/qr/published/{pid}Update a published QR
Scope links:write · write role
Path
id required stringpid required string
DELETE
/links/{id}/qr/published/{pid}Revoke a published QR
Scope links:write · write role
Path
id required stringpid required string
GET
/links/{id}/qr/published/{pid}/previewImage preview of a published QR
Scope links:read
Path
id required stringpid required string
GET
/qr-codesList all published QR codes across the workspace
Scope links:read
Query
qstringstatus"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 required stringformat"png" | "svg" | "pdf"configobjectlogostring
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"urlstringtextstringfieldsobjecttitlestringnamestringaliasstringsubdomainstringdomainstringkind"unique" | "link"previewbooleanconfigobjectlogostring
PATCH
/links/{id}/qr-cardUpdate a dynamic QR card payload (Wi-Fi, vCard, Event, etc.)
Scope links:write · write role
Folders
GET
/foldersList folders
POST
/foldersCreate a folder
Scope folders:write · write role
Body (JSON)
name required stringcolorstring
PATCH
/folders/{id}Rename a folder
Scope folders:write · write role
DELETE
/folders/{id}Delete a folder (links are kept)
Scope folders:write · write role
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
POST
/domainsAdd a custom domain (workspace admin or platform admin)
Scope domains:write
Body (JSON)
host required stringDomain 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)
DELETE
/domains/{id}Remove or disable a custom domain (workspace admin or platform admin)
PUT
/domains/{id}/indexSet or clear what the bare apex custom domain root (https://domain/) serves
Scope domains:write
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
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
DELETE
/subdomain-requests/{id}Cancel a subdomain request
Scope domains:write · write role
PUT
/domains/{id}/subdomains/{subId}/indexSet what the bare subdomain root (https://label.domain/) serves
Scope domains:write · write role
Path
id required stringsubId required string
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 required stringsubId required string
Webhooks
GET
/webhooksList webhook endpoints (workspace owner/admin)
POST
/webhooksCreate a webhook endpoint — the signing secret is returned once
Scope webhooks:write · write role
Body (JSON)
url required stringevents"*" | "link.created" | "link.updated" | "link.deleted" | "link.flagged" | "link.clicked"[]descriptionstring
GET
/webhooks/{id}Get one webhook endpoint
PATCH
/webhooks/{id}Update URL, events, description or active flag
Scope webhooks:write · write role
Body (JSON)
urlstringevents"*" | "link.created" | "link.updated" | "link.deleted" | "link.flagged" | "link.clicked"[]descriptionstringactiveboolean
DELETE
/webhooks/{id}Delete a webhook endpoint
Scope webhooks:write · write role
POST
/webhooks/{id}/rotate-secretIssue a new signing secret (returned once)
Scope webhooks:write · write role
POST
/webhooks/{id}/pingQueue a test `ping` delivery
Scope webhooks:write · write role
GET
/webhooks/{id}/deliveriesDelivery log (30 days), newest first
Scope webhooks:read
Query
status"pending" | "success" | "failed"beforestringlimitinteger Max 100.
POST
/webhooks/{id}/deliveries/{deliveryId}/redeliverSend a past event again
Scope webhooks:write · write role
Path
id required stringdeliveryId required string
API keys
GET
/keysList API keys (owners/admins see all, members their own)
POST
/keysCreate an API key — the secret is returned once
Scope keys:write · write role
Body (JSON)
namestringscopes"*" | "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. expiresInDaysnumberallowedIpsanyAllowed 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)
DELETE
/keys/{id}Revoke an API key
Scope keys:write · write role