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

Method	Path	Auth	Description
POST	`/api/materialize`	Session or Bearer	Create a List, a Document, or both from a source object. Subscriber only.

POST /api/materialize

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

Request body

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

Field	Type	Required	Description
`target`	string	yes	`list`, `doc`, or `both` — what to create.
`source`	object	yes	An id-only source reference (see the source kinds below). The server re-fetches and authorizes every id.
`listConfig`	object	no	Column/schema configuration when `target` includes a list.
`docConfig`	object	no	Title/path/style configuration when `target` includes a document.

Source kinds (source.kind)

`kind`	Fields	Materializes
`messages`	`messageIds: string[]`	One or more messages.
`lists`	`listIds: string[]`	One or more whole lists (schema + rows).
`rows`	`listId: string`, `rowIds: string[]`	Selected rows from one list.
`document`	`documentId: string`	A whole document.
`docElements`	`documentId: string`, `markdown: string`	A selection of a document, identified by the document id plus the selected markdown.

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

listConfig (used when target is list or both)

Field	Type	Description
`title`	string	New list title.
`description`	string	Optional list description.
`isPublic`	boolean	Public visibility of the new list.
`fields`	array	Column definitions. Each has `propertyKey`, `propertyName`, `propertyType`, optional `isRequired`/`options`, and a `sourceKey` mapping the column to a source attribute (`null` for a user-added empty column). The server re-derives values from the source via `sourceKey` — it does not accept client cell values.
`includeData`	boolean	Seed the list with rows derived from the source (default `true`). Set `false` to create an empty, columns-only list.

docConfig (used when target is doc or both)

Field	Type	Description
`title`	string	New document title.
`relativePath`	string	Optional folder path for the new document.
`isPublic`	boolean	Public visibility of the new document.
`listStyle`	string	`numbered` or `bulleted` — how list/row sources render as a document.
`rowDataStyle`	string	`inline` or `sub-items` — how each row's fields are laid out.

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.

Error responses

Status	Condition
401	Not authenticated.
403	Authenticated but not a subscriber.
400	Missing `source`, or an invalid request (bad field config, unsupported source shape).
404	A referenced id (message, list, row, or document) is not found or not owned by you.
500	Unexpected server error.

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.

Help

Help

Create from… (Materialize)

Endpoint

POST /api/materialize

Related