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 /links List links with filters and a cursor

Requires links:read. Stable order by creation time and ID unless another supported sort is chosen (API-05). 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, which are a random seven-character slug, no metadata, no schedule, no password, the primary domain and no query forwarding (API-10).

{
    "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 and never partially (LNK-11). Requires the scope of the operation. `create` items take the fields of Create one link; `pause`, `activate` and `archive` items take `id` and `expected_version`; `tag` items also take `tags` and `mode` (add, remove or replace).

{
    "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.

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 with the current version (API-07). Omitted fields are kept, null clears a nullable field and arrays replace the whole array. The slug and short URL never change.

{
    "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 (LNK-05).

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 (LNK-10). 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 (ANA-08), 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 same figures as the Analytics page for equal filters (ANA-09). Without from and to it covers 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 (ANA-10). 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 (EVT-02).

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 (IO-02). 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 (IO-03). 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 (IO-01). 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 (IO-01).

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 (TEN-04); 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 sessions and delegated access end on their next request. The last owner cannot be removed (409), and keys cannot remove owners.

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; an owner can grant more on the Integrations page. At most four live keys per organization. Audience rest makes a REST key, audience 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.