Skip to main content
POST
Create a list

Authorizations

Authorization
string
header
required

A workspace API key, created in workspace settings and sent as Authorization: Bearer op_live_…. Session cookies are not accepted. Scopes: signals:read, accounts:read, listeners:read, listeners:analyse, pipeline:read, pipeline:write, collections:write, export:read.

Body

application/json

What to call the list.

name
string
required

What to call it. Trimmed on write.

Required string length: 1 - 80
description
string

What it is for.

Maximum string length: 280

Response

The list, as created, with itemCount at 0.

A named list of signals, shared across the workspace. Saved is a list: the workspace gets one system collection with kind: "saved", created the first time anyone saves anything, so starring and adding to "Q1 outreach" are one mechanism rather than two.

id
string
required

Stable identifier.

orgId
string
required

The workspace this belongs to (org_…).

name
string
required

What it is called.

kind
enum<string>
required

saved is the system collection, one per workspace, and never counts against the plan's list cap. list is one somebody made.

Available options:
saved,
list
createdBy
string
required

Clerk user id of whoever made it: attribution, not access control.

itemCount
integer
required

How many signals are in it, denormalised so a list renders without counting.

createdAt
string<date-time>
required

When it was made.

updatedAt
string<date-time>
required

When it or its contents last changed. The pagination sort key.

description
string

What it is for, when somebody said.