List API

Notes

• Most write operations require the list owner role.
• Endpoints under /delivery and GET /lists/:list_id/channel require list cooperator role.

Create List

POST API_BASE/lists

Authorization Required

OAuth	APIKey
Yes	Yes

Request Body

{
  "slug": "my-channel",
  "title": "My Channel",
  "description": "...",
  "avatar_image_url": "https://...",
  "favicon_image_url": "https://...",
  "widget_custom_styles": "..."
}

Response

{
  "data": ChannelObject,
  "ts": 1723923923
}

Search Lists

POST API_BASE/lists/search

Request Body

{
  "q": "keyword",
  "offset": 0,
  "limit": 20
}

Response

{
  "data": {
    "pagination": {
      "offset": 0,
      "next_offset": 20,
      "limit": 20
    },
    "items": [ChannelObject, ...]
  },
  "ts": 1723923923
}

Get List

GET API_BASE/lists/:list_id

Parameters

Parameter	Type	Description
list_id	string	The slug or numeric ID of the list

Response

{
  "data": ChannelObject,
  "ts": 1723923923
}

Get List Metrics

GET API_BASE/lists/:list_id/metrics

Parameters

Parameter	Type	Description
list_id	string	The slug or numeric ID of the list

Response

{
  "data": ListMetricsObject,
  "ts": 1723923923
}

Get List By Domain

GET API_BASE/lists/domains/:domain

Parameters

Parameter	Type	Description
domain	string	The custom domain.

Response

{
  "data": ChannelObject,
  "ts": 1723923923
}

Update List

PUT API_BASE/lists/:list_id

Authorization Required

OAuth	APIKey
Yes	Yes

Parameters

Parameter	Type	Description
list_id	string	The slug or numeric ID of the list

Request Body

Same as Create List.

Response

{
  "data": ChannelObject,
  "ts": 1723923923
}

Update List Slug

PUT API_BASE/lists/:list_id/slug?slug=:slug

Authorization Required

OAuth	APIKey
Yes	Yes

Parameters

Parameter	Type	Description
list_id	string	The slug or numeric ID of the list
slug	string	New slug value.

Response

{
  "data": ChannelObject,
  "ts": 1723923923
}

Update List Options

PUT API_BASE/lists/:list_id/options

Authorization Required

OAuth	APIKey
Yes	Yes

Parameters

Parameter	Type	Description
list_id	string	The slug or numeric ID of the list

Request Body

{
  "options": {
    "comment_enabled": true,
    "comment_strategy": 0,
    "shorten_url_enabled": false
  }
}

Response

{
  "data": ChannelObject,
  "ts": 1723923923
}

Update List Channel Settings

PUT API_BASE/lists/:list_id/channel

Authorization Required

OAuth	APIKey
Yes	Yes

Parameters

Parameter	Type	Description
list_id	string	The slug or numeric ID of the list

Request Body

{
  "telegram_channel_enabled": false,
  "telegram_channel_id": "@channel",
  "discord_channel_enabled": false,
  "discord_channel_id": "123",
  "line_channel_enabled": false,
  "line_channel_id": "123",
  "twitter_channel_enabled": false,
  "bluesky_channel_enabled": false,
  "slack_channel_enabled": false
}

Response

{
  "data": ListChannelObject,
  "ts": 1723923923
}

Get List Channel Settings

GET API_BASE/lists/:list_id/channel

Authorization Required

OAuth	APIKey
Yes	Yes

Parameters

Parameter	Type	Description
list_id	string	The slug or numeric ID of the list

Response

{
  "data": ListChannelObject,
  "ts": 1723923923
}

Generate Line Keypair

POST API_BASE/lists/:list_id/channel/line/keys

Authorization Required

OAuth	APIKey
Yes	Yes

Parameters

Parameter	Type	Description
list_id	string	The slug or numeric ID of the list

Response

{
  "data": {
    "line_jwk_pub": "...",
    "line_jwk_pub_decoded": "..."
  },
  "ts": 1723923923
}

Update List Bulletin

PUT API_BASE/lists/:list_id/bulletin

Authorization Required

OAuth	APIKey
Yes	Yes

Request Body

{
  "bulletin": "..."
}

Response

{
  "data": ChannelObject,
  "ts": 1723923923
}

Update Text Templates

PUT API_BASE/lists/:list_id/text_templates

Authorization Required

OAuth	APIKey
Yes	Yes

Request Body

{
  "text_templates": {
    "email_signature": "..."
  }
}

Response

{
  "data": ChannelObject,
  "ts": 1723923923
}

Update Email Settings

PUT API_BASE/lists/:list_id/email_settings

Authorization Required

OAuth	APIKey
Yes	Yes

Request Body

{
  "email_channel_enabled": true,
  "email_deny_list": ["example.com"]
}

Response

{
  "data": ChannelObject,
  "ts": 1723923923
}

Update Analytics Settings

PUT API_BASE/lists/:list_id/analytics

Authorization Required

OAuth	APIKey
Yes	Yes

Request Body

{
  "a_umami_id": "...",
  "a_umami_base": "https://...",
  "a_ga_id": "G-XXXXXXXXXX",
  "shorten_url_enabled": false,
  "shorten_url_provider": "sink",
  "sink_site_base": "https://...",
  "sink_site_token": "..."
}

Response

{
  "data": ChannelObject,
  "ts": 1723923923
}

Update Domain Settings

PUT API_BASE/lists/:list_id/domain

Authorization Required

OAuth	APIKey
Yes	Yes

Request Body

{
  "custom_domain_enabled": true,
  "domain": "example.com",
  "canonical_base": "https://example.com"
}

Response

{
  "data": ChannelObject,
  "ts": 1723923923
}

Verify Domain

POST API_BASE/lists/:list_id/domain/verify

Authorization Required

OAuth	APIKey
Yes	Yes

Response

{
  "data": ChannelObject,
  "ts": 1723923923
}

Update Comment Settings

PUT API_BASE/lists/:list_id/comment

Authorization Required

OAuth	APIKey
Yes	Yes

Request Body

{
  "comment_enabled": true,
  "comment_strategy": 0
}

Response

{
  "data": ChannelObject,
  "ts": 1723923923
}

Update Tweet Settings

PUT API_BASE/lists/:list_id/tweets

Authorization Required

OAuth	APIKey
Yes	Yes

Request Body

{
  "tweets_enabled": true,
  "bulletin": "..."
}

Response

{
  "data": ChannelObject,
  "ts": 1723923923
}

Update Cooperators

PUT API_BASE/lists/:list_id/cooperators

Authorization Required

OAuth	APIKey
Yes	Yes

Request Body

{
  "cooperators": [1, 2, 3]
}

Response

{
  "data": ChannelObject,
  "ts": 1723923923
}

Request Deletion

DELETE API_BASE/lists/:list_id

Authorization Required

OAuth	APIKey
Yes	Yes

Response

{
  "data": {
    "id": 1
  },
  "ts": 1723923923
}

Export Data

POST API_BASE/lists/:list_id/export.zip

Authorization Required

OAuth	APIKey
Yes	Yes

Response

{
  "data": 0,
  "ts": 1723923923
}

Delivery Tasks (List Scope)

GET API_BASE/lists/:list_id/delivery?offset=:offset&limit=:limit

Authorization Required

OAuth	APIKey
Yes	Yes

list_id must be a numeric ID for delivery endpoints.

Query Parameters

Parameter	Type	Description
offset	number	Pagination offset.
limit	number	Pagination limit.

Response

{
  "data": {
    "pagination": {
      "total": 0,
      "offset": 0,
      "next_offset": 16,
      "limit": 16
    },
    "items": [DeliveryTaskObject, ...]
  },
  "ts": 1723923923
}

PUT API_BASE/lists/:list_id/delivery/:task_id

PUT API_BASE/lists/:list_id/delivery/:task_id/cancel

GET API_BASE/lists/:list_id/delivery/:task_id/report

All delivery task routes require list cooperator permission and return the matching task or report payload.