CompactSaaS Links API Reference

Complete API reference for the CompactSaaS Links service. The Links API provides URL redirect management, short link generation, and custom domain configuration with managed TLS.

Base URL

The Links API is available through the CompactSaaS External API, the same endpoint used for analytics tracking.

All endpoints are under the /v1/links/ prefix. The team is identified automatically from your API key — no team ID in the URL.

Authentication

All endpoints require an API key in the x-api-key header.

x-api-key: pk_live_<32 random characters>

API keys can be created from the CompactSaaS dashboard under API Keys in the sidebar. Each key is bound to a team — all operations are scoped to that team automatically.

Error Responses

Error Format

The API returns errors in two formats depending on the error type:

Validation Errors (request schema violations)

{
  "errors": [
    { "param": "sourceDomain", "type": "String must contain at least 1 character(s)" },
    { "param": "targetUrl", "type": "Invalid url" }
  ]
}

Business Logic Errors

{
  "errors": "validation_error"
}

Common error codes:

Timestamps

All timestamp fields (createdAt, updatedAt, verifiedAt) are Unix epoch milliseconds (e.g., 1772970450599).

Redirects

Redirects map a source domain + path to a target URL. When a request hits the CloudFront edge network matching {sourceDomain}{sourcePath}, it returns an HTTP redirect (301 or 302) to the targetUrl.

Redirects are served at the edge via CloudFront Functions backed by a Key-Value Store (KVS), so they execute in under 1ms with no origin round-trip.

Create Redirect

Creates a new redirect rule and immediately syncs it to the edge network.

POST /v1/links/redirects

Request Body

Example Request

curl -X POST https://api.compactsaas.com/v1/links/redirects \
  -H "x-api-key: pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceDomain": "links.genairumors.com",
    "sourcePath": "/hello",
    "targetUrl": "https://compactsaas.com",
    "statusCode": 301,
    "ttl": 86400
  }'

Response — 201 Created

{
  "redirect": {
    "id": "01KK6MC7N71NTJ7XHJKRMR119V",
    "sourceDomain": "links.compactsaasstaging.click",
    "sourcePath": "/doc-test",
    "targetUrl": "https://example.com/doc-test",
    "statusCode": 302,
    "ttl": 3600,
    "enabled": true,
    "analyticsEnabled": false,
    "analyticsWebsiteId": null,
    "createdAt": 1772970450599,
    "updatedAt": 1772970450599
  }
}

Errors

List Redirects

Returns all redirects for the team.

GET /v1/links/redirects

Example Request

curl https://api.compactsaas.com/v1/links/redirects \
  -H "x-api-key: pk_live_your_key_here"

Response — 200 OK

{
  "redirects": [
    {
      "id": "01KK6E10671WWMNV9RWA2ZKGQE",
      "sourceDomain": "links.genairumors.com",
      "sourcePath": "/hello",
      "targetUrl": "https://compactsaas.com",
      "statusCode": 301,
      "ttl": 86400,
      "enabled": true,
      "analyticsEnabled": false,
      "analyticsWebsiteId": null,
      "createdAt": 1772963791047,
      "updatedAt": 1772963791047
    }
  ]
}

Returns an empty array if no redirects exist: {"redirects": []}.

Update Redirect

Updates an existing redirect. Only the fields provided in the request body are changed. The edge KVS entry is re-synced immediately.

PUT /v1/links/redirects/{redirectId}

Path Parameters

Request Body

All fields are optional. Only provided fields are updated.

Example Request

curl -X PUT https://api.compactsaas.com/v1/links/redirects/01KK6MC7N71NTJ7XHJKRMR119V \
  -H "x-api-key: pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"targetUrl": "https://example.com/updated", "statusCode": 301}'

Response — 200 OK

{
  "redirect": {
    "id": "01KK6MC7N71NTJ7XHJKRMR119V",
    "sourceDomain": "links.compactsaasstaging.click",
    "sourcePath": "/doc-test",
    "targetUrl": "https://example.com/updated",
    "statusCode": 301,
    "ttl": 3600,
    "enabled": true,
    "analyticsEnabled": false,
    "analyticsWebsiteId": null,
    "createdAt": 1772970450599,
    "updatedAt": 1772970467719
  }
}

Errors

Delete Redirect

Permanently deletes a redirect and removes it from the edge KVS.

DELETE /v1/links/redirects/{redirectId}

Example Request

curl -X DELETE https://api.compactsaas.com/v1/links/redirects/01KK6MC7N71NTJ7XHJKRMR119V \
  -H "x-api-key: pk_live_your_key_here"

Response — 204 No Content

Empty response body.

Errors

Short Links

Short links generate a compact URL on the platform's short domain (e.g., staging.urlz.zip in staging, urlz.zip in production). Each short link gets a unique 7-character base62 code, or you can specify a custom code.

Short links are served at the edge identically to redirects — via CloudFront Functions and KVS.

Create Short Link

Creates a new short link with either an auto-generated or custom short code.

POST /v1/links/shorten

Request Body

Example Request — Auto-generated Code

curl -X POST https://api.compactsaas.com/v1/links/shorten \
  -H "x-api-key: pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"targetUrl": "https://example.com/my-long-page"}'

Response — 201 Created

{
  "link": {
    "id": "01KK6MCSFTTM0GPJB3XEBWJACY",
    "shortCode": "oTmGvkP",
    "shortUrl": "https://staging.urlz.zip/oTmGvkP",
    "targetUrl": "https://example.com/short-test",
    "domain": "staging.urlz.zip",
    "enabled": true,
    "analyticsEnabled": false,
    "analyticsWebsiteId": null,
    "hasClicks": false,
    "createdAt": 1772970468859,
    "updatedAt": 1772970468859
  }
}

Example Request — Custom Code

curl -X POST https://api.compactsaas.com/v1/links/shorten \
  -H "x-api-key: pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"targetUrl": "https://example.com/promo", "customCode": "summer-sale"}'

Response — 201 Created

{
  "link": {
    "id": "01KK6MCT06Q29ZSQAXT4RSK3P4",
    "shortCode": "summer-sale",
    "shortUrl": "https://staging.urlz.zip/summer-sale",
    "targetUrl": "https://example.com/promo",
    "domain": "staging.urlz.zip",
    "enabled": true,
    "analyticsEnabled": false,
    "analyticsWebsiteId": null,
    "hasClicks": false,
    "createdAt": 1772970469382,
    "updatedAt": 1772970469382
  }
}

Errors

List Short Links

Returns all short links for the team.

GET /v1/links/short

Example Request

curl https://api.compactsaas.com/v1/links/short \
  -H "x-api-key: pk_live_your_key_here"

Response — 200 OK

{
  "links": [
    {
      "id": "01KK6MCSFTTM0GPJB3XEBWJACY",
      "shortCode": "oTmGvkP",
      "shortUrl": "https://staging.urlz.zip/oTmGvkP",
      "targetUrl": "https://example.com/short-test",
      "domain": "staging.urlz.zip",
      "enabled": true,
      "analyticsEnabled": false,
      "analyticsWebsiteId": null,
      "hasClicks": false,
      "createdAt": 1772970468859,
      "updatedAt": 1772970468859
    }
  ]
}

Returns an empty array if no short links exist: {"links": []}.

Get Short Link

Returns a single short link by ID.

GET /v1/links/short/{linkId}

Path Parameters

Example Request

curl https://api.compactsaas.com/v1/links/short/01KK6MCSFTTM0GPJB3XEBWJACY \
  -H "x-api-key: pk_live_your_key_here"

Response — 200 OK

{
  "link": {
    "id": "01KK6MCSFTTM0GPJB3XEBWJACY",
    "shortCode": "oTmGvkP",
    "shortUrl": "https://staging.urlz.zip/oTmGvkP",
    "targetUrl": "https://example.com/short-test",
    "domain": "staging.urlz.zip",
    "enabled": true,
    "analyticsEnabled": false,
    "analyticsWebsiteId": null,
    "hasClicks": false,
    "createdAt": 1772970468859,
    "updatedAt": 1772970468859
  }
}

Returns 404 NOT_FOUND if the link does not exist.

Get Short Link Stats

Returns daily click timeseries data for a short link. Data comes from analytics rollups which are preserved permanently, regardless of the raw event retention policy. Requires analyticsEnabled on the link.

GET /v1/links/short/{linkId}/stats

Path Parameters

Query Parameters

Example Request

curl "https://api.compactsaas.com/v1/links/short/01KK6MCSFTTM0GPJB3XEBWJACY/stats?days=14" \
  -H "x-api-key: pk_live_your_key_here"

Response — 200 OK

{
  "linkId": "01KK6MCSFTTM0GPJB3XEBWJACY",
  "totalClicks": 42,
  "days": 14,
  "timeseries": [
    { "date": "2026-03-08", "clicks": 3 },
    { "date": "2026-03-09", "clicks": 5 },
    { "date": "2026-03-15", "clicks": 10 },
    { "date": "2026-03-16", "clicks": 24 }
  ]
}

Returns 404 NOT_FOUND if the link does not exist. Returns totalClicks: 0 and empty timeseries if analytics is not enabled on the link or the analytics table is unavailable.

Update Short Link

Updates an existing short link. Only the fields provided in the request body are changed. If targetUrl is changed, the edge KVS entry is re-synced immediately.

PUT /v1/links/short/{linkId}

Path Parameters

Request Body

All fields are optional. Only provided fields are updated.

Example Request

curl -X PUT https://api.compactsaas.com/v1/links/short/01KK6MCSFTTM0GPJB3XEBWJACY \
  -H "x-api-key: pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"analyticsEnabled": true}'

Response — 200 OK

{
  "link": {
    "id": "01KK6MCSFTTM0GPJB3XEBWJACY",
    "shortCode": "oTmGvkP",
    "shortUrl": "https://staging.urlz.zip/oTmGvkP",
    "targetUrl": "https://example.com/short-test",
    "domain": "staging.urlz.zip",
    "enabled": true,
    "analyticsEnabled": true,
    "analyticsWebsiteId": "01KK6MD0A1B2C3D4E5F6G7H8J9",
    "hasClicks": true,
    "createdAt": 1772970468859,
    "updatedAt": 1772970512000
  }
}

Errors

Delete Short Link

Permanently deletes a short link and removes it from the edge KVS.

DELETE /v1/links/short/{linkId}

Path Parameters

Example Request

curl -X DELETE https://api.compactsaas.com/v1/links/short/01KK6MCSFTTM0GPJB3XEBWJACY \
  -H "x-api-key: pk_live_your_key_here"

Response — 204 No Content

Empty response body.

Get QR Code

Generate a QR code for a short link. Returns the QR code image directly (not JSON). The response is cacheable — identical requests return the same image.

Every short link automatically has a QR code endpoint. No creation limits, no branding restrictions.

GET /v1/links/short/{linkId}/qr

Path Parameters

Query Parameters

All query parameters are optional.

Example Request — Default SVG

curl https://api.compactsaas.com/v1/links/short/01KK6MCSFTTM0GPJB3XEBWJACY/qr \
  -H "x-api-key: pk_live_your_key_here" \
  -o qr-code.svg

Example Request — Custom Branded PNG

curl "https://api.compactsaas.com/v1/links/short/01KK6MCSFTTM0GPJB3XEBWJACY/qr?format=png&size=500&color=%23FF6600&bgColor=%23FFFFFF" \
  -H "x-api-key: pk_live_your_key_here" \
  -o qr-code.png

Response

Returns the image directly with appropriate Content-Type header:

• SVG: Content-Type: image/svg+xml
• PNG: Content-Type: image/png

Response includes Cache-Control: public, max-age=86400 for edge caching.

QR Code Analytics

When a short link has analyticsEnabled: true, every QR code scan is automatically tracked in your analytics dashboard. QR scans appear as "Direct / QR" traffic — distinguishable from regular link clicks which show the referring page.

No additional setup required. Create a short link with analytics enabled, download the QR code, and every scan shows up alongside your website traffic.

Errors

Custom Domains

Custom domains allow your team to serve redirects from your own domain (e.g., links.yourcompany.com) with fully managed TLS certificates.

Domain setup (verification, activation, TLS provisioning) is done through the CompactSaaS dashboard. Once a domain is active, you can manage it programmatically via this API:

• List domains — see all your custom domains and their status
• Set fallback URL — configure where unmatched paths redirect to (instead of 403)

Domain Lifecycle

Dashboard: Verify → Check DNS → Activate → Wait for TLS → Active
API:       List domains (read-only) | Set fallback URL (active domains only)

Set Domain Fallback URL

Configures a fallback redirect URL for a custom domain. When a request arrives at your custom domain for a path that has no matching redirect rule, the fallback URL is used instead of returning a raw 403 error from the origin.

The fallback is served as a 302 Found redirect at the edge.

The domain must have tenantStatus: "active".

POST /v1/links/domains/fallback

Request Body

Example Request — Set Fallback

curl -X POST https://api.compactsaas.com/v1/links/domains/fallback \
  -H "x-api-key: pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain": "links.yourcompany.com", "fallbackUrl": "https://yourcompany.com"}'

Response — 200 OK

{
  "domain": {
    "domain": "links.yourcompany.com",
    "status": "verified",
    "tenantStatus": "active",
    "fallbackUrl": "https://yourcompany.com",
    "verifiedAt": 1772836089453,
    "createdAt": 1772836027575
  }
}

Example Request — Clear Fallback

curl -X POST https://api.compactsaas.com/v1/links/domains/fallback \
  -H "x-api-key: pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain": "links.yourcompany.com", "fallbackUrl": ""}'

Errors

List Domain Verifications

Returns all domain verification records for the team, including their current status and tenant information.

GET /v1/links/domains

Example Request

curl https://api.compactsaas.com/v1/links/domains \
  -H "x-api-key: pk_live_your_key_here"

Response — 200 OK

{
  "domains": [
    {
      "domain": "links.genairumors.com",
      "status": "verified",
      "tenantStatus": "active",
      "fallbackUrl": "https://genairumors.com",
      "verifiedAt": 1772836089453,
      "createdAt": 1772836027575
    }
  ]
}

Returns an empty array if no domains are configured: {"domains": []}.

Domain Object

API Endpoint Summary

Domain setup (verification, activation, TLS provisioning) is managed through the CompactSaaS dashboard.

Dashboard API — Unified Links

These endpoints are used by the CompactSaaS dashboard (Cognito JWT auth, not API key auth). They provide a unified view across both redirects and short links.

List All Links

GET /:teamId/links/all

Returns both redirects and short links in a single array. Each item has a type field ("redirect" or "shortlink") and a sourceUrl field.

Query Parameters:

Get Link Detail

GET /:teamId/links/detail/:linkId

Returns a single link by ID. Tries short link first, then redirect (two point Gets, no scan). Returns 404 if neither exists.

Response includes all fields for the link type plus type and sourceUrl.

List All Links (External API)

GET /v1/links

Same as the dashboard GET /:teamId/links/all but uses API key auth. Team is determined from the API key.

Query Parameters: Same as dashboard — type, search, sort, order.

Get Link Detail (External API)

GET /v1/links/:linkId

Same as the dashboard GET /:teamId/links/detail/:linkId but uses API key auth. Returns 404 if neither a short link nor redirect exists with the given ID.