REST API reference

GET /me Identity, organization, capabilities and quotas of the calling key

Answers for any valid key, whatever its scopes. A good first call to check a new key.

curl -sS "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/me" \
  -H "Authorization: Bearer $C1K_API_KEY"

Responses: 200 The calling key and its organization, 401 Missing, invalid, expired or revoked key, 429 Too many requests. Wait the number of seconds in Retry-After.

GET /entitlements Effective limits, what is used against them, and when they next change

Answers for any valid key and reports only the calling key's own organization. The slot figures are the ones admission enforces. next_change_at is the earliest boundary that can move capacity (a renewal, a grace window or a recovery hold's purge deadline), or null.

curl -sS "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/entitlements" \
  -H "Authorization: Bearer $C1K_API_KEY"

Responses: 200 The organization's entitlements, 401 Missing, invalid, expired or revoked key, 429 Too many requests. Wait the number of seconds in Retry-After.

GET /links List links with filters and a cursor

Requires links:read. Pass `meta.next_cursor` back as `cursor` for the next page.

curl -sS "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/links" \
  -H "Authorization: Bearer $C1K_API_KEY"

Responses: 200 One page of links, 400 Error envelope with a stable code, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 422 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

POST /links Create one link

Requires links:write. Only destination_url is required; omitted fields take their defaults, including a random seven-character slug.

{
    "destination_url": "https://venture.example/launch",
    "slug": "launch26",
    "title": "Launch page",
    "tags": [
        "launch"
    ],
    "utm": {
        "source": "newsletter",
        "medium": "email",
        "campaign": "launch26"
    }
}

curl -sS -X POST "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/links" \
  -H "Authorization: Bearer $C1K_API_KEY" \
  -H "Idempotency-Key: c1k-$(date +%s)-$RANDOM" \
  -H 'Content-Type: application/json' \
  -d '{"destination_url":"https://venture.example/launch","slug":"launch26","title":"Launch page","tags":["launch"],"utm":{"source":"newsletter","medium":"email","campaign":"launch26"}}'

Responses: 201 Created. Location names the new link and ETag carries its version, 400 Error envelope with a stable code, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 409 Error envelope with a stable code, 413 Error envelope with a stable code, 415 Error envelope with a stable code, 422 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After, 507 Error envelope with a stable code.

POST /links/bulk Create or change up to 25 links with a result per item

Each item is applied on its own, never partially, with the scope of its operation. `create` takes the fields of Create one link; `pause`, `activate` and `archive` take `id` and `expected_version`; `tag` also takes `tags` and `mode`.

{
    "operation": "pause",
    "items": [
        {
            "id": "lnk_4fQ2mVxT9kLpR7sA1b",
            "expected_version": 3
        },
        {
            "id": "lnk_9Hn3cZq8Wb2Ld5Rk7T",
            "expected_version": 1
        }
    ]
}

curl -sS -X POST "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/links/bulk" \
  -H "Authorization: Bearer $C1K_API_KEY" \
  -H "Idempotency-Key: c1k-$(date +%s)-$RANDOM" \
  -H 'Content-Type: application/json' \
  -d '{"operation":"pause","items":[{"id":"lnk_4fQ2mVxT9kLpR7sA1b","expected_version":3},{"id":"lnk_9Hn3cZq8Wb2Ld5Rk7T","expected_version":1}]}'

Responses: 200 Per-item results with stable indexes, 400 Error envelope with a stable code, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 409 Error envelope with a stable code, 413 Error envelope with a stable code, 415 Error envelope with a stable code, 422 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

POST /links/swap Pause one link and enable another, atomically

Pauses one link and activates another in one step, so a full limit needs no new capacity. Both apply or neither does. Requires links:write and the current version of both links.

{
    "pause_id": "lnk_4fQ2mVxT9kLpR7sA1b",
    "pause_expected_version": 3,
    "enable_id": "lnk_9Hn3cZq8Wb2Ld5Rk7T",
    "enable_expected_version": 1
}

curl -sS -X POST "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/links/swap" \
  -H "Authorization: Bearer $C1K_API_KEY" \
  -H "Idempotency-Key: c1k-$(date +%s)-$RANDOM" \
  -H 'Content-Type: application/json' \
  -d '{"pause_id":"lnk_4fQ2mVxT9kLpR7sA1b","pause_expected_version":3,"enable_id":"lnk_9Hn3cZq8Wb2Ld5Rk7T","enable_expected_version":1}'

Responses: 200 The paused link and the enabled link, each with its new version, 400 Error envelope with a stable code, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 404 Error envelope with a stable code, 409 Error envelope with a stable code, 412 Error envelope with a stable code, 413 Error envelope with a stable code, 415 Error envelope with a stable code, 422 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After, 507 Error envelope with a stable code.

GET /links/{id} Read one link

Requires links:read. Never includes the password or its hash; `password_protected` says whether one is set.

curl -sS "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/links/lnk_4fQ2mVxT9kLpR7sA1b" \
  -H "Authorization: Bearer $C1K_API_KEY"

Responses: 200 The link. ETag carries its version for If-Match, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 404 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

PATCH /links/{id} Edit mutable fields or the lifecycle state

Requires links:write and If-Match. Omitted fields are kept, null clears a field and arrays are replaced. The slug never changes.

{
    "destination_url": "https://venture.example/launch-v2",
    "title": "Launch page (v2)"
}

curl -sS -X PATCH "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/links/lnk_4fQ2mVxT9kLpR7sA1b" \
  -H "Authorization: Bearer $C1K_API_KEY" \
  -H 'If-Match: "1"' \
  -H 'Content-Type: application/json' \
  -d '{"destination_url":"https://venture.example/launch-v2","title":"Launch page (v2)"}'

Responses: 200 The updated link with its new version, 400 Error envelope with a stable code, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 404 Error envelope with a stable code, 412 Error envelope with a stable code, 413 Error envelope with a stable code, 415 Error envelope with a stable code, 422 Error envelope with a stable code, 428 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

DELETE /links/{id} Erase the link and keep its short key reserved

Requires links:delete and If-Match. The link and its analytics are erased; the slug can never be reused.

curl -sS -X DELETE "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/links/lnk_4fQ2mVxT9kLpR7sA1b" \
  -H "Authorization: Bearer $C1K_API_KEY" \
  -H 'If-Match: "1"'

Responses: 200 The erased link's identifiers, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 404 Error envelope with a stable code, 412 Error envelope with a stable code, 428 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

GET /links/{id}/qr SVG QR code of the short URL

Requires links:read. Error correction level M with a four-module quiet zone. The SVG contains only the code.

curl -sS "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/links/lnk_4fQ2mVxT9kLpR7sA1b/qr" \
  -H "Authorization: Bearer $C1K_API_KEY"

Responses: 200 SVG image, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 404 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

GET /links/{id}/analytics Daily and lifetime recorded requests of one link

Requires analytics:read. Link daily figures are kept for seven UTC days; lifetime totals until the analytics are purged or the link is deleted.

curl -sS "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/links/lnk_4fQ2mVxT9kLpR7sA1b/analytics" \
  -H "Authorization: Bearer $C1K_API_KEY"

Responses: 200 Link analytics with interval, retained interval, coverage and unique estimate labels, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 404 Error envelope with a stable code, 422 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After, 503 Error envelope with a stable code.

GET /analytics Organization daily totals and dimensions

Requires analytics:read. The Analytics page figures; without from and to, the last seven UTC days.

curl -sS "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/analytics" \
  -H "Authorization: Bearer $C1K_API_KEY"

Responses: 200 Organization analytics, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 422 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After, 503 Error envelope with a stable code.

DELETE /analytics Purge all or selected-link analytics

Requires analytics:delete. Cannot be undone. Removes counters, sketches and dimensions in bounded batches. When the answer has done false, send the same request with the returned started_at until done is true. Link IDs outside the organization answer 404.

{
    "confirm": true,
    "link_ids": [
        "lnk_4fQ2mVxT9kLpR7sA1b"
    ]
}

curl -sS -X DELETE "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/analytics" \
  -H "Authorization: Bearer $C1K_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"confirm":true,"link_ids":["lnk_4fQ2mVxT9kLpR7sA1b"]}'

Responses: 200 Progress of the purge, 400 Error envelope with a stable code, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 404 Error envelope with a stable code, 413 Error envelope with a stable code, 415 Error envelope with a stable code, 422 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After, 503 Error envelope with a stable code.

GET /events Poll the change feed after a cursor

Requires events:read. Events come in increasing ID order, at most 100 per page. The feed keeps at most 100 events per organization and seven days. A cursor older than the retained history answers 410 cursor_expired; take a fresh snapshot and poll again without a cursor. Deduplicate by event ID.

curl -sS "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/events" \
  -H "Authorization: Bearer $C1K_API_KEY"

Responses: 200 One page of events and the cursor to poll with next, 400 Error envelope with a stable code, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 410 Error envelope with a stable code, 422 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

POST /imports/validate Check one import chunk without writing anything

Requires links:write. At most 25 rows and 65,536 bytes. Returns every row as ok or with its error, and a receipt valid for ten minutes that is bound to the organization, the caller and the SHA-256 of the rows. Fields other than the listed ones, including password, fail their row.

{
    "rows": [
        {
            "row": 1,
            "destination_url": "https://venture.example/spring",
            "slug": "spring26",
            "tags": [
                "campaign"
            ]
        },
        {
            "row": 2,
            "destination_url": "https://venture.example/summer",
            "title": "Summer offer"
        }
    ]
}

curl -sS -X POST "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/imports/validate" \
  -H "Authorization: Bearer $C1K_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"rows":[{"row":1,"destination_url":"https://venture.example/spring","slug":"spring26","tags":["campaign"]},{"row":2,"destination_url":"https://venture.example/summer","title":"Summer offer"}]}'

Responses: 200 Row results and the receipt, 400 Error envelope with a stable code, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 413 Error envelope with a stable code, 415 Error envelope with a stable code, 422 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

POST /imports/apply Create the rows of a validated chunk

Requires links:write and an Idempotency-Key. Send the validated rows unchanged with their receipt. Each row is created in its own transaction with authorization, quota, capacity and slug checked again; existing links are never changed. A retry with the same key returns the first result. An expired or mismatched receipt answers 409; validate the chunk again.

{
    "rows": [
        {
            "row": 1,
            "destination_url": "https://venture.example/spring",
            "slug": "spring26",
            "tags": [
                "campaign"
            ]
        }
    ],
    "receipt": "eyJ2IjoxLCJvcmciOiJvcmdfLi4uIn0.SIGNATURE"
}

curl -sS -X POST "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/imports/apply" \
  -H "Authorization: Bearer $C1K_API_KEY" \
  -H "Idempotency-Key: c1k-$(date +%s)-$RANDOM" \
  -H 'Content-Type: application/json' \
  -d '{"rows":[{"row":1,"destination_url":"https://venture.example/spring","slug":"spring26","tags":["campaign"]}],"receipt":"eyJ2IjoxLCJvcmciOiJvcmdfLi4uIn0.SIGNATURE"}'

Responses: 200 Created and failed rows by row number, 400 Error envelope with a stable code, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 409 Error envelope with a stable code, 413 Error envelope with a stable code, 415 Error envelope with a stable code, 422 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

GET /exports/links Stream the link configuration as CSV or versioned JSON

Requires exports:read. Read in batches and streamed; no copy stays on the server and no password material is included. CSV cells that begin with =, +, -, @, a tab or a carriage return get one leading apostrophe, removed again on import. The last CSV record is "#end" with the record count.

curl -sS "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/exports/links" \
  -H "Authorization: Bearer $C1K_API_KEY"

Responses: 200 The export as a download named in Content-Disposition, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 422 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

GET /exports/analytics Stream retained analytics as CSV or versioned JSON

Requires exports:read and analytics:read. Daily totals, per-link days, dimension buckets, lifetime totals, collection gaps and coverage notes, streamed.

curl -sS "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/exports/analytics" \
  -H "Authorization: Bearer $C1K_API_KEY"

Responses: 200 The export as a download named in Content-Disposition, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 422 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After, 503 Error envelope with a stable code.

GET /members Active members, owners first, with pending invitations in meta

Requires members:manage. Invitation links are never listed again.

curl -sS "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/members" \
  -H "Authorization: Bearer $C1K_API_KEY"

Responses: 200 Members; meta.pending_invitations lists open invitations without their links, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

POST /members Create a single-use invitation link for a new member

Requires members:manage. People join only by opening an invitation link; C1K sends no mail. The link is returned once and works for 72 hours. A key acts as an administrator, so it cannot invite an owner. An optional email binds the invitation to that account.

{
    "role": "editor",
    "email": "new.colleague@venture.example"
}

curl -sS -X POST "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/members" \
  -H "Authorization: Bearer $C1K_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"role":"editor","email":"new.colleague@venture.example"}'

Responses: 201 The invitation with its link, shown only now, 400 Error envelope with a stable code, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 413 Error envelope with a stable code, 415 Error envelope with a stable code, 422 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

PATCH /members/{user_id} Change a member's role within the caller's authority

Requires members:manage. Administrators and keys cannot change owners or assign the owner role.

{
    "role": "admin"
}

curl -sS -X PATCH "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/members/usr_REPLACEWITHUSERID0" \
  -H "Authorization: Bearer $C1K_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"role":"admin"}'

Responses: 200 The member after the change, 400 Error envelope with a stable code, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 404 Error envelope with a stable code, 409 Error envelope with a stable code, 413 Error envelope with a stable code, 415 Error envelope with a stable code, 422 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

DELETE /members/{user_id} End a membership

Requires members:manage. The member's access ends on their next request. The last owner cannot be removed (409).

curl -sS -X DELETE "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/members/usr_REPLACEWITHUSERID0" \
  -H "Authorization: Bearer $C1K_API_KEY"

Responses: 200 The membership is revoked, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 404 Error envelope with a stable code, 409 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

GET /service-accounts Service accounts of the organization

Requires integrations:manage.

curl -sS "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/service-accounts" \
  -H "Authorization: Bearer $C1K_API_KEY"

Responses: 200 Service accounts, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

POST /service-accounts Create a service account

Requires integrations:manage. At most two active service accounts per organization.

{
    "name": "website backend"
}

curl -sS -X POST "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/service-accounts" \
  -H "Authorization: Bearer $C1K_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"website backend"}'

Responses: 201 Created, 400 Error envelope with a stable code, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 409 Error envelope with a stable code, 413 Error envelope with a stable code, 415 Error envelope with a stable code, 422 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

DELETE /service-accounts/{id} Revoke a service account and every key it holds

Requires integrations:manage. Its keys stop working on their next request.

curl -sS -X DELETE "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/service-accounts/sva_REPLACEWITHACCTID0" \
  -H "Authorization: Bearer $C1K_API_KEY"

Responses: 200 Revoked, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 404 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

GET /credentials Keys of the organization without their secrets

Requires integrations:manage.

curl -sS "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/credentials" \
  -H "Authorization: Bearer $C1K_API_KEY"

Responses: 200 Keys with name, audience, scopes, last use, expiry and status, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

POST /credentials Create a key; the secret is returned once

Requires integrations:manage. A key may create keys only with a subset of its own scopes. At most four live keys per organization. Audience rest makes a REST key, mcp an MCP token.

{
    "service_account_id": "sva_REPLACEWITHACCTID0",
    "name": "reporting job",
    "audience": "rest",
    "scopes": [
        "links:read",
        "analytics:read"
    ],
    "expires_in_days": 90
}

curl -sS -X POST "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/credentials" \
  -H "Authorization: Bearer $C1K_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"service_account_id":"sva_REPLACEWITHACCTID0","name":"reporting job","audience":"rest","scopes":["links:read","analytics:read"],"expires_in_days":90}'

Responses: 201 Created. `data.token` is shown only in this response, 400 Error envelope with a stable code, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 404 Error envelope with a stable code, 409 Error envelope with a stable code, 413 Error envelope with a stable code, 415 Error envelope with a stable code, 422 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.

DELETE /credentials/{id} Revoke a key immediately

Requires integrations:manage. The key stops working on its next request.

curl -sS -X DELETE "https://c1k.me/api/v1/orgs/$C1K_ORG_ID/credentials/crd_REPLACEWITHKEYID00" \
  -H "Authorization: Bearer $C1K_API_KEY"

Responses: 200 Revoked, 401 Missing, invalid, expired or revoked key, 403 Error envelope with a stable code, 404 Error envelope with a stable code, 429 Too many requests. Wait the number of seconds in Retry-After.