API reference

What v1 does

Update API-flagged link blocks on your space programmatically. Mark a link as “Available via API” in the editor, copy its block id, generate a token, and PATCH it from your pipeline.

Quickstart

Replace your-slug, <block-id>, and the token with your own values.

curl -X PATCH \
  https://www.cntct.space/api/v1/spaces/your-slug/blocks/<block-id> \
  -H "Authorization: Bearer cnt_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-new-link.example/","title":"Latest video"}'

Authentication

• Send your token as Authorization: Bearer cnt_live_….
• Generate tokens at /account-settings/api-tokens.
• Maximum 5 active tokens per user.
• Tokens auto-revoke on downgrade from Pro.

Endpoints

GET /api/v1/spaces

{
  "data": [
    {
      "id": "1a8e3f2c-...",
      "slug": "your-slug",
      "name": "My space",
      "is_published": true,
      "api_block_count": 1,
      "updated_at": "2026-05-22T14:08:11.000Z"
    }
  ]
}

GET /api/v1/spaces/:slug/blocks

{
  "data": [
    {
      "id": "9b1d72a4-...",
      "type": "link",
      "title": "Latest video",
      "url": "https://your-new-link.example/",
      "icon": "fa-link",
      "thumbnailUrl": "",
      "featured": false,
      "style": "compact",
      "description": "",
      "apiUpdatable": true
    }
  ],
  "meta": {
    "space_updated_at": "2026-05-22T14:08:11.000Z"
  }
}

GET /api/v1/spaces/:slug/blocks/:blockId

{
  "data": {
    "id": "9b1d72a4-...",
    "type": "link",
    "title": "Latest video",
    "url": "https://your-new-link.example/",
    "icon": "fa-link",
    "thumbnailUrl": "",
    "featured": false,
    "style": "compact",
    "description": "",
    "apiUpdatable": true
  },
  "meta": {
    "space_updated_at": "2026-05-22T14:08:11.000Z"
  }
}

PATCH /api/v1/spaces/:slug/blocks/:blockId

Accepts any subset of the link block's fields in the JSON body (e.g. url, title, description, thumbnailUrl, icon, badge, schedule). The type and apiUpdatable fields are immutable via the API. Pass If-Match: <space_updated_at> for optimistic concurrency — a mismatch returns 409 stale_write.

{
  "data": {
    "id": "9b1d72a4-...",
    "type": "link",
    "title": "Latest video",
    "url": "https://your-new-link.example/",
    "icon": "fa-link",
    "thumbnailUrl": "",
    "featured": false,
    "style": "compact",
    "description": "",
    "apiUpdatable": true
  },
  "meta": {
    "space_updated_at": "2026-05-22T14:12:47.000Z"
  }
}

Error envelope

Every error response uses this shape:

{
  "error": {
    "code": "validation_failed",
    "message": "Block did not validate.",
    "fields": { "url": "Must be an http(s) URL." }
  }
}

The apiUpdatable flag and the empty-slot workflow

1. Add a Link block in the editor.
2. Toggle “Available via API” on.
3. Copy the block id shown.
4. Generate an API token at /account-settings/api-tokens.
5. PATCH the block from your script.
6. (Optional) Leave the URL blank until your pipeline populates it — the block is hidden until then.

Errors

Rate limits

• 120 reads/min per token.
• 30 writes/min per token.
• 429 response has no Retry-After — wait ~60s and retry.

Versioning

• v1 stays backwards compatible.
• Future breaking changes ship as v2 with ≥6-month overlap.