Create from… (Materialize)

The materialize endpoint turns an existing object — one or more messages, one or more lists, a set of list rows, a document, or a selection of document elements — into a new List, a new Document, or both. It backs the "Create from…" feature in the web app. This is a Subscriber-only endpoint, mirroring the list/document create gates.

The request sends id-only references, never content. The server re-fetches and authorizes every referenced id under the calling user, then derives the new list/document from that authoritative data. Client-supplied cell values or body text are not trusted.

Endpoint

POST /api/materialize

Auth required: yes (Session or Bearer) Subscriber only: yes

Request body

{
  "target": "list | doc | both | message",
  "source": { "kind": "messages", "messageIds": ["clx…"] },
  "listConfig": { "…": "optional; see below" },
  "docConfig": { "…": "optional; see below" }
}

Source kinds (source.kind)

Every id in a source is ownership-checked; referencing something you do not own returns 404.

listConfig (used when target is list or both)

docConfig (used when target is doc or both)

Response 201 Created

{
  "list": { "id": "clx…", "title": "From my messages" },
  "document": { "id": "clx…", "title": "From my messages" }
}

list is present when a list was created, document when a document was created; a both target returns both.

target: "message" — the one that does not create

This target completes the conversion matrix: structured work becomes a post. It returns a draft and writes nothing.

{
  "message": {
    "content": "Books to Read\n\nMy reading backlog.\n\n• The Dream Machine\n\n340 items in total.",
    "thread": ["Books to Read\n\nMy reading backlog.\n\n• The Dream Machine\n\n340 items in total."],
    "isThread": false,
    "charLimit": 300
  }
}

Publish it with POST /api/messages, sending content. That endpoint is where every posting gate lives — account status, verified email, the subscriber checks for media, cross-posting and scheduling, probation rate limits, and your own maxMessageLength. Re-implementing them here would duplicate the most safety-critical write path in the product and let them drift apart, so this endpoint deliberately stops at the draft. A prefill must never bypass a rule the composer enforces.

messageConfig

charLimit is the smaller of your maxMessageLength (from GET /api/user) and the tightest limit among crossPostTargets. Sizing to your own limit alone would show one post and then silently send a three-part thread to Bluesky.

A messages source is accepted (several messages combine into one draft), but message → message is not offered in the UI — use Quote or Push for a single message.

Error responses

Related

• Lists and List Schema DSL: the shape a materialized list takes.
• Documents: the shape a materialized document takes.
• Create from… (Help Center): the end-user walkthrough of this feature.