Blogs API

Create and manage blogs, API keys, and custom domains.

Create Blog

POST /blogs

Parameter	Type	Required	Description
`slug`	string	Yes	Blog subdomain (lowercase alphanumeric + hyphens, 1-63 chars)
`name`	string	Yes	Blog name (max 200 chars)
`description`	string	No	Blog description (max 1000 chars)

Blog limits per plan: Free 1, Starter 1, Creator 3, Scale 5, Enterprise unlimited.

curl -X POST https://api.postlark.ai/v1/blogs \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-tech-blog",
    "name": "My Tech Blog",
    "description": "Writing about AI, APIs, and developer tools."
  }'

{
  "id": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
  "slug": "my-tech-blog",
  "name": "My Tech Blog",
  "url": "https://my-tech-blog.postlark.ai",
  "created_at": "2026-03-24T10:00:00.000Z"
}

List Blogs

GET /blogs

Returns all blogs owned by the authenticated user, sorted by most recent first.

curl https://api.postlark.ai/v1/blogs \
  -H "Authorization: Bearer pk_live_your_key"

{
  "data": [
    {
      "id": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
      "slug": "my-tech-blog",
      "name": "My Tech Blog",
      "description": "Writing about AI, APIs, and developer tools.",
      "custom_domain": null,
      "created_at": "2026-03-24T10:00:00.000Z",
      "updated_at": "2026-03-24T10:00:00.000Z"
    }
  ]
}

Update Blog

PUT /blogs/:id

Parameter	Type	Required	Description
`name`	string	No	Blog name (max 200 chars)
`description`	string	No	Blog description (max 1000 chars)
`theme_config`	object	No	Theme customization (plan-gated)

Theme features by plan:

Starter+: customCss, adCode, cssUrl
Creator+: headerHtml, footerHtml

curl -X PUT https://api.postlark.ai/v1/blogs/b1c2d3e4-5678-90ab-cdef-1234567890ab \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Renamed Blog",
    "description": "Updated description for the blog.",
    "theme_config": {
      "customCss": "body { font-family: Georgia, serif; }",
      "headerHtml": "<nav>Custom navigation</nav>"
    }
  }'

{
  "id": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
  "slug": "my-tech-blog",
  "name": "My Renamed Blog",
  "description": "Updated description for the blog.",
  "custom_domain": null,
  "theme_config": {
    "customCss": "body { font-family: Georgia, serif; }",
    "headerHtml": "<nav>Custom navigation</nav>"
  },
  "updated_at": "2026-03-25T09:30:00.000Z"
}

Delete Blog

DELETE /blogs/:id

curl -X DELETE https://api.postlark.ai/v1/blogs/b1c2d3e4-5678-90ab-cdef-1234567890ab \
  -H "Authorization: Bearer pk_live_your_key"

{
  "deleted": true
}

API Keys

Generate Key

POST /blogs/:id/api-keys

Parameter	Type	Required	Description
`name`	string	No	Key name (default: “Default”, max 100 chars)

curl -X POST https://api.postlark.ai/v1/blogs/b1c2d3e4-5678-90ab-cdef-1234567890ab/api-keys \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "CI/CD Pipeline" }'

{
  "id": "k1l2m3n4-5678-90ab-cdef-1234567890ab",
  "name": "CI/CD Pipeline",
  "key": "pk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "prefix": "pk_live_a1b2",
  "created_at": "2026-03-25T10:00:00.000Z"
}

List Keys

GET /blogs/:id/api-keys

Returns key prefix and metadata only (not the full key). Only active (non-revoked) keys are shown.

curl https://api.postlark.ai/v1/blogs/b1c2d3e4-5678-90ab-cdef-1234567890ab/api-keys \
  -H "Authorization: Bearer pk_live_your_key"

{
  "data": [
    {
      "id": "k1l2m3n4-5678-90ab-cdef-1234567890ab",
      "name": "CI/CD Pipeline",
      "key_prefix": "pk_live_a1b2",
      "last_used_at": "2026-03-25T15:30:00.000Z",
      "created_at": "2026-03-25T10:00:00.000Z"
    }
  ]
}

Revoke Key

DELETE /blogs/:id/api-keys/:keyId

Soft-deletes the API key. The key immediately stops working.

curl -X DELETE https://api.postlark.ai/v1/blogs/b1c2d3e4-5678-90ab-cdef-1234567890ab/api-keys/k1l2m3n4-5678-90ab-cdef-1234567890ab \
  -H "Authorization: Bearer pk_live_your_key"

{
  "deleted": true
}

Custom Domain (Starter+)

Register

POST /blogs/:id/domain

Parameter	Type	Required	Description
`hostname`	string	Yes	Your custom domain (e.g. `blog.yourdomain.com`)

curl -X POST https://api.postlark.ai/v1/blogs/b1c2d3e4-5678-90ab-cdef-1234567890ab/domain \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "hostname": "blog.yourdomain.com" }'

{
  "hostname": "blog.yourdomain.com",
  "status": "pending_verification",
  "cname_target": "my-tech-blog.postlark.ai",
  "instructions": "Add a CNAME record: blog.yourdomain.com → my-tech-blog.postlark.ai"
}

Check Status

GET /blogs/:id/domain

curl https://api.postlark.ai/v1/blogs/b1c2d3e4-5678-90ab-cdef-1234567890ab/domain \
  -H "Authorization: Bearer pk_live_your_key"

{
  "hostname": "blog.yourdomain.com",
  "status": "active",
  "cname_target": "my-tech-blog.postlark.ai"
}

Remove

DELETE /blogs/:id/domain

curl -X DELETE https://api.postlark.ai/v1/blogs/b1c2d3e4-5678-90ab-cdef-1234567890ab/domain \
  -H "Authorization: Bearer pk_live_your_key"

{
  "deleted": true
}