Bio Pages API

Programmatically create and manage link-in-bio pages with custom themes, content blocks, and analytics tracking. Each bio page belongs to a workspace and is served on a custom or default domain.

The bio page object

A bio page is a landing page containing content blocks (links, text, images, embeds). Pages can be themed, published or drafted, and tracked for view analytics.

Field	Type	Description
id	string	Unique bio page identifier (e.g. `bp_abc123`)
title	string	Page title displayed at the top
slug	string	URL slug for the bio page
description	string \| null	Short bio description
avatar_url	string \| null	URL to the avatar image
theme	object	Theme configuration (colors, fonts, button style)
blocks	Block[]	Array of content blocks
domain	string	The domain serving this bio page
views	number	Total page views
published	boolean	Whether the page is publicly visible
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last update timestamp

Block types

Each block has a type, a position integer, and a type-specific data object.

Type	Description
link	A clickable link button with title and URL
header	A section header or divider text
text	A paragraph of rich text content
image	An image with optional link and caption
video	An embedded video from YouTube or Vimeo
social	Social media profile icons row
email	Email signup or contact form
spotify	Spotify track or playlist embed
product	Product card with image, price, and buy link

List bio pages

Retrieve all bio pages in the workspace. Supports cursor-based pagination.

GET/api/v1/bio-pages

Request

curl "https://mask.pk/api/v1/bio-pages?limit=10" \
  -H "Authorization: Bearer mk_live_abc123def456"

Response

{
  "data": [
    {
      "id": "bp_abc123",
      "title": "Jane Smith",
      "slug": "jane",
      "description": "Designer & Content Creator",
      "domain": "bio.yourbrand.com",
      "views": 1420,
      "published": true,
      "created_at": "2026-03-13T10:00:00Z",
      "updated_at": "2026-03-13T10:00:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "cursor": null
  }
}

Create a bio page

Create a new bio page with a title, description, theme, and optional initial blocks. The page is created in draft mode unless published is set to true.

POST/api/v1/bio-pages

Request

curl -X POST https://mask.pk/api/v1/bio-pages \
  -H "Authorization: Bearer mk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Jane Smith",
    "slug": "jane",
    "description": "Designer & Content Creator",
    "domain": "bio.yourbrand.com",
    "theme": {
      "bg_color": "#ffffff",
      "text_color": "#000000",
      "button_style": "rounded",
      "font": "inter"
    },
    "blocks": [
      {
        "type": "link",
        "position": 0,
        "data": {
          "title": "My Portfolio",
          "url": "https://janesmith.com"
        }
      }
    ],
    "published": true
  }'

Response — 201 Created

{
  "id": "bp_abc123",
  "title": "Jane Smith",
  "slug": "jane",
  "description": "Designer & Content Creator",
  "avatar_url": null,
  "domain": "bio.yourbrand.com",
  "theme": {
    "bg_color": "#ffffff",
    "text_color": "#000000",
    "button_style": "rounded",
    "font": "inter"
  },
  "blocks": [
    {
      "id": "blk_001",
      "type": "link",
      "position": 0,
      "data": {
        "title": "My Portfolio",
        "url": "https://janesmith.com"
      }
    }
  ],
  "views": 0,
  "published": true,
  "created_at": "2026-03-13T10:00:00Z",
  "updated_at": "2026-03-13T10:00:00Z"
}

Get a bio page

Retrieve a single bio page by ID, including all blocks and theme configuration.

GET/api/v1/bio-pages/:id

Request

curl https://mask.pk/api/v1/bio-pages/bp_abc123 \
  -H "Authorization: Bearer mk_live_abc123def456"

Response

{
  "id": "bp_abc123",
  "title": "Jane Smith",
  "slug": "jane",
  "description": "Designer & Content Creator",
  "avatar_url": "https://cdn.mask.pk/avatars/jane.jpg",
  "domain": "bio.yourbrand.com",
  "theme": {
    "bg_color": "#ffffff",
    "text_color": "#000000",
    "button_style": "rounded",
    "font": "inter"
  },
  "blocks": [
    {
      "id": "blk_001",
      "type": "link",
      "position": 0,
      "data": {
        "title": "My Portfolio",
        "url": "https://janesmith.com"
      }
    },
    {
      "id": "blk_002",
      "type": "social",
      "position": 1,
      "data": {
        "platforms": {
          "twitter": "https://twitter.com/janesmith",
          "instagram": "https://instagram.com/janesmith"
        }
      }
    }
  ],
  "views": 1420,
  "published": true,
  "created_at": "2026-03-13T10:00:00Z",
  "updated_at": "2026-03-15T08:30:00Z"
}

Update a bio page

Update bio page fields. Only include the fields you want to change. To update blocks, pass the full blocks array — it replaces the existing blocks entirely.

PATCH/api/v1/bio-pages/:id

Request

curl -X PATCH https://mask.pk/api/v1/bio-pages/bp_abc123 \
  -H "Authorization: Bearer mk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Jane Smith - Updated",
    "description": "Designer, Creator & Speaker",
    "theme": {
      "bg_color": "#f9fafb",
      "text_color": "#111827",
      "button_style": "pill",
      "font": "inter"
    }
  }'

Response

{
  "id": "bp_abc123",
  "title": "Jane Smith - Updated",
  "slug": "jane",
  "description": "Designer, Creator & Speaker",
  "avatar_url": "https://cdn.mask.pk/avatars/jane.jpg",
  "domain": "bio.yourbrand.com",
  "theme": {
    "bg_color": "#f9fafb",
    "text_color": "#111827",
    "button_style": "pill",
    "font": "inter"
  },
  "blocks": [
    {
      "id": "blk_001",
      "type": "link",
      "position": 0,
      "data": {
        "title": "My Portfolio",
        "url": "https://janesmith.com"
      }
    }
  ],
  "views": 1420,
  "published": true,
  "created_at": "2026-03-13T10:00:00Z",
  "updated_at": "2026-03-16T14:00:00Z"
}

Delete a bio page

Permanently delete a bio page and all its blocks. The URL returns a 404 immediately. This action cannot be undone.

DELETE/api/v1/bio-pages/:id

Request

curl -X DELETE https://mask.pk/api/v1/bio-pages/bp_abc123 \
  -H "Authorization: Bearer mk_live_abc123def456"

Response — 200 OK

{
  "deleted": true,
  "id": "bp_abc123"
}