Selected Documents

Try it out?

Create an API connection in the Imagine tab in Craft, and paste your API URL here

Overview

The Craft Multi-Document API provides programmatic access to multiple Craft documents. Access documents, blocks, collections, and search across your document set with unified authentication.

Key Concepts

Document IDs: Each document is identified by an ID. Use GET /documents to discover available documents and their IDs.

Cross-Document Operations: Most operations require specifying which document to work with via block IDs. The API automatically resolves which document a block belongs to.

This API is ideal for building integrations that need to work with multiple related documents, such as project documentation sets, knowledge bases, or multi-document workflows.

Rate Limits

Rate limits apply at both public IP and Craft space scopes. The first limit reached returns HTTP 429.

LimitScopeAllowance
API requestsPublic source IP, shared across API links and MCP connections50 requests per 10 seconds
API requestsCraft space100 requests per 60 seconds
Blocks read or writtenCraft space20,000 blocks per 60 seconds

Clients behind the same public IP share the per-IP limit. Space limits are shared across all API links, MCP connections, and clients in that space; they are not allocated separately per link or session. Each paginated request and retry counts separately.

Application responses expose the Craft space request budget, when available, through X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Responses rejected at the public-IP limit may omit these headers.

REST block operations expose the corresponding X-BlockBudget-* headers after the space has recorded block usage in the current window; the first read in a new window may omit them. MCP responses do not expose the block budget as HTTP headers.

Application-generated HTTP 429 responses include Retry-After. MCP request-limit responses also repeat the retry delay in the error message because some MCP clients do not expose response headers. If Retry-After is absent, use exponential backoff with jitter.

Reminders

Block reminders are experimental. With a Craft OAuth connection, reminders belong to the signed-in user and are available in single-user and multi-user spaces. With an ordinary link, reminders belong to the link creator and require that creator to be the space's only active participant. Document scope always applies; custom (blockless) reminders are not exposed.

Unavailable reminder endpoints are omitted from this documentation. Direct requests return an explicit availability error. Task dates notify in-app; they are not a substitute for a requested timed reminder. A reminder can schedule a notification on any block, or save it for later without a notification. These operations are available only under the conditions above.

TypeFormatDescription
clickableLinkcraftdocs://open?spaceId={spaceId}&documentId={documentId}Returned in document metadata when fetchMetadata=true.
Web editorhttps://docs.craft.do/editor/d/{spaceId}/{documentId}Construct using the spaceId and documentId values from clickableLink.

Craft Markdown Extensions

The markdown field on blocks uses standard Markdown with the following Craft-specific extensions. These tags can appear in both input (when creating/updating blocks) and output (when reading blocks), unless noted otherwise.

Page Structure

TagDescription
<page>...<\/page>A nested page (sub-document). Optional attributes: textStyle (e.g. "card"), cardLayout, id.
<card>...<\/card>Shorthand for <page textStyle="card">.
<pageTitle>...<\/pageTitle>The title of a <page>. Always the first child inside <page>.
<content>...<\/content>The body content of a <page>, following <pageTitle>.

Block-Level Formatting

TagDescription
<callout>...<\/callout>Wraps blocks in a visually distinct callout box (similar to an admonition or aside).
<caption>...<\/caption>Renders text in a smaller, muted caption style.

Inline Formatting

TagDescription
<highlight color="...">...<\/highlight>Colored text highlight. Colors: yellow, green, mint, cyan, blue, purple, pink, red, gray, gradient-blue, gradient-purple, gradient-red, gradient-yellow, gradient-brown.
==text==Shorthand for <highlight color="yellow">.
<comment id="...">...<\/comment>Marks text that has a comment thread attached. The id references the comment thread.
$formula$ or $$formula$$LaTeX math formula, rendered inline or as a block.
SyntaxDescription
[text](block://blockId)Cross-reference to another block by ID. Appears as [text](invalid:out_of_scope) when the target block is outside the current API scope.
[text](date://YYYY-MM-DD)Link to a daily note for the given date.
2+ leading spacesNesting level. Every 2 spaces represents one level of indentation.

Collection Tags (output-only)

These tags appear only in responses, when the result contains collection data. They are not accepted as input.

TagDescription
<collection>...<\/collection>A collection (structured database). Contains <title>, <properties>, and either <content> (with items) or <itemsPreview>.
<title>...<\/title>The name of a collection or collection item.
<properties>...<\/properties>Comma-separated list of property (column) keys defined on the collection.
<collectionItem>...<\/collectionItem>A single row/item in a collection. Contains <property> tags, a <title>, and optionally <content> or <contentPreview>.
<property name="key">value<\/property>A property value on a collection item, where name is the property key.
<contentPreview>...<\/contentPreview>A truncated preview of nested content, included when the response depth limit is reached instead of the full <content>.
<itemsPreview>...<\/itemsPreview>A truncated preview of collection items, included when the response depth limit is reached instead of the full item list.

Development Tips

  • Start with GET /documents to discover available documents and their IDs
  • Use the id parameter in GET /blocks with a document's ID to fetch that document's content
  • When inserting blocks, use pageId in the position object to specify the target document/block
  • Use GET /documents/search to search across all documents with relevance-based ranking
  • Collections can span multiple documents - use GET /collections to discover them

Note for AI

When implementing functionality using this API, always make actual calls to these endpoints and verify the responses. Do not simulate or mock the API interactions or use hard-coded values on the client-side - use the real endpoints to ensure proper functionality and data handling.

IMPORTANT: This is a production server connected to real user data. Only perform testing operations that can be safely rolled back:

  • Safe: Reading data (GET requests), creating test content that you delete immediately after
  • Safe: Modifying content if you can restore it to its original state
  • Safe: Moving blocks if you can move them back to their original position
  • Unsafe: Permanent deletions, modifications without backup, or any changes you cannot reverse

Always verify rollback operations work before considering a test complete.

Fetch Blocks

GET
/blocks

Summary

Fetches content from documents in this multi-document connection. Use 'id' query parameter to specify which block to fetch.

Use Accept header application/json for structured data, text/markdown for rendered content.

Content Rendering: Text blocks contain markdown formatting and may include Craft-specific structural tags (e.g. <page>, <callout>, <highlight>). See the Craft Markdown Extensions section in the API description for the full list of tags.

Scope Filtering: Block links in markdown and collections, as well as relations are filtered to documents scope. Block links and date links are returned as block:// and date:// URLs.

Tip: Start by calling GET /documents to list available documents, then use their documentId values as the 'id' parameter to fetch each document's root content.

Query Parameters

idBlock ID

The ID of the page block to fetch. Required for multi-document operations. Accepts IDs for documents, pages and blocks.

maxDepth?Max Depth

The maximum depth of blocks to fetch. Default is -1 (all descendants). With a depth of 0, only the specified block is fetched. With a depth of 1, only direct children are returned.

Default-1
fetchMetadata?Fetch Metadata

Whether to fetch metadata (comments, createdBy, lastModifiedBy, lastModifiedAt, createdAt) for the blocks. Default is false.

Response Body

200

Successfully retrieved data

typeType
Allowed Values:"text"
idBlock ID
textStyle?string

h1-h4, body, caption for text blocks. card/page for page blocks with visual styling.

Allowed Values:"card" | "page" | "h1" | "h2" | "h3" | "h4" | "caption" | "body"
textAlignment?string

default is left

Allowed Values:"left" | "center" | "right" | "justify"
font?string
Allowed Values:"system" | "serif" | "rounded" | "mono"
cardLayout?string

Applies for 'card' textStyle. Small and square are for laying out in multi-column (2 or 3 depending on screen size, multi-column is only supported for certain block types, not for text). Regular and large are full width cards.

Allowed Values:"small" | "square" | "regular" | "large"
markdownMarkdown

The markdown content of the block. May include Craft-specific extensions such as structural tags and special link formats. See the Craft Markdown Extensions section in the API description for the full reference.

indentationLevel?Indentation Level

The indentation level of the block.

Range0 <= value <= 5
listStyle?string
Allowed Values:"none" | "bullet" | "numbered" | "toggle" | "task"
decorations?Decorations
color?Color

7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.

Match^#[0-9a-fA-F]{6}$
taskInfo?object

only interpreted, if listStyle is 'task'

metadata?Block Metadata
typeType
Allowed Values:"page"
idBlock ID
titleobject
markdownMarkdown

The title of the page block.

styling?Page Styling

Visual styling properties of the page (cover image, colors, fonts, etc.).

indentationLevel?Indentation Level

The indentation level of the block.

Range0 <= value <= 5
listStyle?string
Allowed Values:"none" | "bullet" | "numbered" | "toggle" | "task"
decorations?Decorations
color?Color

7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.

Match^#[0-9a-fA-F]{6}$
taskInfo?object

only interpreted, if listStyle is 'task'

metadata?Block Metadata
textStyle?string

h1-h4, body, caption for text blocks. card/page for page blocks with visual styling.

Allowed Values:"card" | "page" | "h1" | "h2" | "h3" | "h4" | "caption" | "body"
textAlignment?string

default is left

Allowed Values:"left" | "center" | "right" | "justify"
font?string
Allowed Values:"system" | "serif" | "rounded" | "mono"
cardLayout?string

Applies for 'card' textStyle. Small and square are for laying out in multi-column (2 or 3 depending on screen size, multi-column is only supported for certain block types, not for text). Regular and large are full width cards.

Allowed Values:"small" | "square" | "regular" | "large"
contentarray<unknown>

Content of the page block. Array of blocks. Follows the same block schema.

typeType
Allowed Values:"collectionItem"
idBlock ID
titleTitle

The title of the block.

propertiesProperties

The properties of the block.

Empty Object

markdownMarkdown

The title of the collection item

metadata?Block Metadata
contentarray<unknown>

Content of the collection item block's page. Array of blocks. Follows the same block schema.

typeType
Allowed Values:"image"
idBlock ID
urlstring
altText?string
size?string
Allowed Values:"fit" | "fill"
width?string
Allowed Values:"auto" | "fullWidth"
uploaded?boolean
fileSize?number
mimeType?string
aspectRatio?number
previewImageWidth?number
isPreviewImageUploaded?boolean
markdownMarkdown

The markdown content of the block. May include Craft-specific extensions such as structural tags and special link formats. See the Craft Markdown Extensions section in the API description for the full reference.

indentationLevel?Indentation Level

The indentation level of the block.

Range0 <= value <= 5
listStyle?string
Allowed Values:"none" | "bullet" | "numbered" | "toggle" | "task"
decorations?Decorations
color?Color

7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.

Match^#[0-9a-fA-F]{6}$
taskInfo?object

only interpreted, if listStyle is 'task'

metadata?Block Metadata
typeType
Allowed Values:"video"
idBlock ID
urlstring
altText?string
size?string
Allowed Values:"fit" | "fill"
width?string
Allowed Values:"auto" | "fullWidth"
uploaded?boolean
fileSize?number
mimeType?string
markdownMarkdown

The markdown content of the block. May include Craft-specific extensions such as structural tags and special link formats. See the Craft Markdown Extensions section in the API description for the full reference.

indentationLevel?Indentation Level

The indentation level of the block.

Range0 <= value <= 5
listStyle?string
Allowed Values:"none" | "bullet" | "numbered" | "toggle" | "task"
decorations?Decorations
color?Color

7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.

Match^#[0-9a-fA-F]{6}$
taskInfo?object

only interpreted, if listStyle is 'task'

metadata?Block Metadata
typeType
Allowed Values:"file"
idBlock ID
urlstring
fileName?File Name

The name of the file.

blockLayout?string
Allowed Values:"small" | "regular" | "card"
uploaded?boolean
mimeType?string
fileSize?number
markdownMarkdown

The markdown content of the block. May include Craft-specific extensions such as structural tags and special link formats. See the Craft Markdown Extensions section in the API description for the full reference.

indentationLevel?Indentation Level

The indentation level of the block.

Range0 <= value <= 5
listStyle?string
Allowed Values:"none" | "bullet" | "numbered" | "toggle" | "task"
decorations?Decorations
color?Color

7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.

Match^#[0-9a-fA-F]{6}$
taskInfo?object

only interpreted, if listStyle is 'task'

metadata?Block Metadata
typeType
Allowed Values:"drawing"
idBlock ID
urlstring
markdownMarkdown

The markdown content of the block. May include Craft-specific extensions such as structural tags and special link formats. See the Craft Markdown Extensions section in the API description for the full reference.

indentationLevel?Indentation Level

The indentation level of the block.

Range0 <= value <= 5
listStyle?string
Allowed Values:"none" | "bullet" | "numbered" | "toggle" | "task"
decorations?Decorations
color?Color

7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.

Match^#[0-9a-fA-F]{6}$
taskInfo?object

only interpreted, if listStyle is 'task'

metadata?Block Metadata
typeType
Allowed Values:"whiteboard"
idBlock ID
url?string
markdownMarkdown

The markdown content of the block. May include Craft-specific extensions such as structural tags and special link formats. See the Craft Markdown Extensions section in the API description for the full reference.

indentationLevel?Indentation Level

The indentation level of the block.

Range0 <= value <= 5
listStyle?string
Allowed Values:"none" | "bullet" | "numbered" | "toggle" | "task"
decorations?Decorations
color?Color

7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.

Match^#[0-9a-fA-F]{6}$
taskInfo?object

only interpreted, if listStyle is 'task'

metadata?Block Metadata
typeType
Allowed Values:"table"
idBlock ID
markdownMarkdown

The markdown content of the block. May include Craft-specific extensions such as structural tags and special link formats. See the Craft Markdown Extensions section in the API description for the full reference.

indentationLevel?Indentation Level

The indentation level of the block.

Range0 <= value <= 5
listStyle?string
Allowed Values:"none" | "bullet" | "numbered" | "toggle" | "task"
decorations?Decorations
color?Color

7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.

Match^#[0-9a-fA-F]{6}$
taskInfo?object

only interpreted, if listStyle is 'task'

metadata?Block Metadata
typeType
Allowed Values:"collection"
idBlock ID
markdownMarkdown

The markdown content of the block. May include Craft-specific extensions such as structural tags and special link formats. See the Craft Markdown Extensions section in the API description for the full reference.

indentationLevel?Indentation Level

The indentation level of the block.

Range0 <= value <= 5
listStyle?string
Allowed Values:"none" | "bullet" | "numbered" | "toggle" | "task"
decorations?Decorations
color?Color

7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.

Match^#[0-9a-fA-F]{6}$
taskInfo?object

only interpreted, if listStyle is 'task'

metadata?Block Metadata
typeType
Allowed Values:"code"
idBlock ID
rawCodeRaw Code

The raw code of the block.

language?string
Allowed Values:"ada" | "bash" | "cpp" | "cs" | "css" | "dart" | "dockerfile" | "matlab" | "go" | "groovy" | "haskell" | "html" | "java" | "javascript" | "json" | "julia" | "kotlin" | "lua" | "markdown" | "mermaid" | "objectivec" | "perl" | "php" | "prolog" | "plaintext" | "python" | "r" | "ruby" | "rust" | "scala" | "shell" | "sql" | "swift" | "typescript" | "vbnet" | "xml" | "yaml" | "math_formula" | "other"
markdownMarkdown

The markdown content of the block. May include Craft-specific extensions such as structural tags and special link formats. See the Craft Markdown Extensions section in the API description for the full reference.

indentationLevel?Indentation Level

The indentation level of the block.

Range0 <= value <= 5
listStyle?string
Allowed Values:"none" | "bullet" | "numbered" | "toggle" | "task"
decorations?Decorations
color?Color

7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.

Match^#[0-9a-fA-F]{6}$
taskInfo?object

only interpreted, if listStyle is 'task'

metadata?Block Metadata
typeType
Allowed Values:"richUrl"
idBlock ID
urlstring
title?string
description?string
layout?string
Allowed Values:"small" | "regular" | "card"
markdownMarkdown

The markdown content of the block. May include Craft-specific extensions such as structural tags and special link formats. See the Craft Markdown Extensions section in the API description for the full reference.

indentationLevel?Indentation Level

The indentation level of the block.

Range0 <= value <= 5
listStyle?string
Allowed Values:"none" | "bullet" | "numbered" | "toggle" | "task"
decorations?Decorations
color?Color

7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.

Match^#[0-9a-fA-F]{6}$
taskInfo?object

only interpreted, if listStyle is 'task'

metadata?Block Metadata
typeType
Allowed Values:"line"
idBlock ID
lineStylestring

pageBreak lineStyle is just a strong visual separator within a page (chunks to page-looking groups visually). It does not affect the page block hierarchy.

Default"regular"
Allowed Values:"strong" | "regular" | "light" | "extraLight" | "pageBreak"
separatorStyle?string

Separator style for the line block (washi tape pattern, doodle, or regular line).

markdownMarkdown

The markdown content of the block. May include Craft-specific extensions such as structural tags and special link formats. See the Craft Markdown Extensions section in the API description for the full reference.

indentationLevel?Indentation Level

The indentation level of the block.

Range0 <= value <= 5
listStyle?string
Allowed Values:"none" | "bullet" | "numbered" | "toggle" | "task"
decorations?Decorations
color?Color

7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.

Match^#[0-9a-fA-F]{6}$
taskInfo?object

only interpreted, if listStyle is 'task'

metadata?Block Metadata
Try it out?

Create an API connection in the Imagine tab in Craft, and paste your API URL here

Document with nested structure
Insert Blocks
POST
/blocks
Summary
Insert content into documents in this multi-document connection. Content can be provided as structured JSON blocks. Use position parameter to specify where to insert. Returns the inserted blocks with their assigned block IDs for later reference.
Request Body
application/json
blocksNew Blocks
The blocks to insert, as JSON array
positionPosition
JSON object to insert the content at. Must specify either pageId or siblingId.
positionPage Position
The position to insert the blocks at. 'start' inserts at the start of the page, 'end' inserts at the end of the page.
Allowed Values:"start" | "end"
pageIdPage ID
ID of the block to insert children into. Required for multi-document operations. Only page, text, and card type blocks can be parent blocks. Text blocks are auto-converted to page type when they receive children. Collection items are implicitly pages.
positionSibling Position
The position to insert the blocks at. 'before' inserts before the referenced block, 'after' inserts after the referenced block.
Allowed Values:"before" | "after"
siblingIdSibling ID
ID of the block to insert blocks next to.
markdownMarkdown
The Markdown content to insert. Separate each paragraph and heading with two newlines. Separate each list item with one newline. The first item in any list cannot be empty.
Craft-specific tokens are HTML tags.:


    

  • <callout></callout> for callouts. Can be used to wrap multiple paragraphs/images/etc.
    • 

  • 
<caption></caption> for caption text style. Can be used to wrap a paragraph.

    • 

  • <highlight color=''></highlight> for highlights - color is optional. Can only be used inline.
    • 

positionPosition
JSON object to insert the content at. Must specify either pageId or siblingId.
positionPage Position
The position to insert the blocks at. 'start' inserts at the start of the page, 'end' inserts at the end of the page.
Allowed Values:"start" | "end"
pageIdPage ID
ID of the block to insert children into. Required for multi-document operations. Only page, text, and card type blocks can be parent blocks. Text blocks are auto-converted to page type when they receive children. Collection items are implicitly pages.
positionSibling Position
The position to insert the blocks at. 'before' inserts before the referenced block, 'after' inserts after the referenced block.
Allowed Values:"before" | "after"
siblingIdSibling ID
ID of the block to insert blocks next to.
Response Body
200
Successfully created resource
itemsBlocks
Array of blocks
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Successfully inserted blocks with auto-assigned IDs
Delete Blocks
DELETE
/blocks
Summary
Delete content from documents in this multi-document connection. Removes specified blocks by their IDs.
Request Body
application/json
blockIdsBlock IDs
The IDs of the blocks to delete
Response Body
200
Successfully deleted resource
itemsDeleted Block IDs
Array of deleted block IDs
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Successfully deleted multiple blocks
Update Blocks
PUT
/blocks
Summary
Update content across documents in this multi-document connection. For text blocks, provide updated markdown content. Only the fields that are provided will be updated.
Request Body
application/json
blocksBlocks to Update
The blocks to update, as JSON array. Only the fields that are provided will be updated.
Response Body
200
Successfully updated resource
itemsBlocks
Array of blocks
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Successfully updated text blocks
Move Blocks
PUT
/blocks/move
Summary
Move blocks to reorder them or move them between documents. Returns the moved block IDs.
Request Body
application/json
blockIdsBlock IDs
The IDs of the blocks to move
positionPosition
JSON object to move the content to. Must specify either pageId or siblingId.
positionPage Position
The position to insert the blocks at. 'start' inserts at the start of the page, 'end' inserts at the end of the page.
Allowed Values:"start" | "end"
pageIdPage ID
ID of the block to insert children into. Required for multi-document operations. Only page, text, and card type blocks can be parent blocks. Text blocks are auto-converted to page type when they receive children. Collection items are implicitly pages.
positionSibling Position
The position to insert the blocks at. 'before' inserts before the referenced block, 'after' inserts after the referenced block.
Allowed Values:"before" | "after"
siblingIdSibling ID
ID of the block to insert blocks next to.
Response Body
200
Successfully moved resource
itemsMoved Block IDs
Array of moved block IDs
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Successfully moved blocks between documents
Get Collection Items
GET
/collections/{collectionId}/items
Summary
Get all items from a collection
Path Parameters
collectionIdstring
Query Parameters
maxDepth?Max Depth
The maximum depth of nested content to fetch for each collection item. Default is -1 (all descendants). With a depth of 0, only the item properties are fetched without nested content.
Default-1
Response Body
200
Successfully retrieved data
itemsCollection Items
Array of items in the collection.
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Collection items with properties and content
Add Collection Items
POST
/collections/{collectionId}/items
Summary
Add new items to a collection. Two-way relations are synced automatically in the background - only set one side for consistency.
Path Parameters
collectionIdstring
Request Body
application/json
itemsItems to Add
Items to add to the collection. Each item should match the collection's schema (properties will be validated at runtime).
allowNewSelectOptions?Allow New Select Options
Allow adding new options to select properties. When true, new values will be automatically added to the collection schema. Never add new option values without explicit user intent.
Response Body
200
Successfully created resource
itemsSuccessfully Added Items
Array of successfully added items
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Successfully added collection items
Delete Collection Items
DELETE
/collections/{collectionId}/items
Summary
Delete collection items (also deletes content inside items)
Path Parameters
collectionIdstring
Request Body
application/json
idsToDeleteIDs to Delete
IDs of the items to delete from the collection.
Response Body
200
Successfully deleted resource
itemsDeleted Item IDs
Array of successfully deleted item IDs
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Successfully deleted collection items
Update Collection Items
PUT
/collections/{collectionId}/items
Summary
Update collection items. Two-way relations are synced automatically in the background - only set one side for consistency.
Path Parameters
collectionIdstring
Request Body
application/json
itemsToUpdateItems to Update
Items to update in the collection. Each item should have an id and optionally properties matching the collection's schema (properties will be validated at runtime).
allowNewSelectOptions?Allow New Select Options
Allow adding new options to select properties. When true, new values will be automatically added to the collection schema. Never add new option values without explicit user intent.
Response Body
200
Successfully updated resource
itemsSuccessfully Updated Items
Array of successfully updated items
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Successfully updated collection items
Set Active Collection View
PUT
/collections/{collectionId}/active-view
Summary
Set the collection-level activeViewId to one existing collection view ID. This only changes which stored view is marked active; it does not execute the view or change collection items.
Path Parameters
collectionIdstring
Request Body
application/json
viewIdView ID
The existing collection view ID to store as the collection's activeViewId
Length1 <= length
Response Body
200
Success
idstring
Collection view ID. Use this ID for update, delete, and set-active operations.
namestring
typestring
Stored collection view layout type. table is the regular/default table layout; gallery and kanban include matching view-specific settings when configured.
filtersarray<object>
Filter rules stored in the view definition. These endpoints do not execute the filters or return filtered items.
sortByarray<object>
Sort rules stored in the view definition. These endpoints do not execute the sorts or return sorted items.
groupByarray<object>
Grouping rules stored in the view definition. Kanban views have exactly one group rule.
hiddenPropertiesarray<object>
customPropertyOrderarray<object>
columnWidthobject
Empty Object
calculationsobject
Empty Object
isCalculationsRowVisible?boolean
gallery?object
Gallery view settings. Present only for gallery views.
kanban?object
Kanban view settings. Present only for kanban views.
isActiveboolean
True when this view is the effective active view. The effective active view is activeViewId when valid; otherwise it is the first stored view.
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Successfully set active collection view
List Collection Views
GET
/collections/{collectionId}/views
Summary
List table, gallery, and kanban view definitions for a collection. This returns configuration only; it does not execute filters/sorts/groups or return collection items. If activeViewId is missing or invalid, the first stored view is treated as active.
Path Parameters
collectionIdstring
Response Body
200
Success
collectionBlockIdCollection Block ID
The collection block ID whose views were listed
activeViewId?Active View ID
The effective active collection view ID. If the stored activeViewId is missing or invalid, the first stored view is treated as active. Absent only when the collection has no stored views.
viewsCollection Views
Stored collection view definitions. These definitions do not include collection items and are not the result of executing filters, sorts, or groups.
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Collection view definitions
Returns stored view definitions only. activeViewId is the effective active view; if the stored activeViewId is missing or invalid, the first stored view is treated as active.
Create Collection View
POST
/collections/{collectionId}/views
Summary
Create a collection view definition. Use type table for the regular/default table layout, gallery for card layouts, or kanban for grouped boards. This creates configuration only; it does not create or return collection items. Kanban requires exactly one group rule.
Path Parameters
collectionIdstring
Request Body
application/json
viewCollection View
The view definition to create. This stores configuration only; it does not execute the view or return collection items. Use type table for the regular/default table layout. Gallery settings are only valid for gallery views. Kanban settings are only valid for kanban views, and kanban requires exactly one groupBy rule.
Response Body
200
Successfully created resource
idstring
Collection view ID. Use this ID for update, delete, and set-active operations.
namestring
typestring
Stored collection view layout type. table is the regular/default table layout; gallery and kanban include matching view-specific settings when configured.
filtersarray<object>
Filter rules stored in the view definition. These endpoints do not execute the filters or return filtered items.
sortByarray<object>
Sort rules stored in the view definition. These endpoints do not execute the sorts or return sorted items.
groupByarray<object>
Grouping rules stored in the view definition. Kanban views have exactly one group rule.
hiddenPropertiesarray<object>
customPropertyOrderarray<object>
columnWidthobject
Empty Object
calculationsobject
Empty Object
isCalculationsRowVisible?boolean
gallery?object
Gallery view settings. Present only for gallery views.
kanban?object
Kanban view settings. Present only for kanban views.
isActiveboolean
True when this view is the effective active view. The effective active view is activeViewId when valid; otherwise it is the first stored view.
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Successfully created collection view
Delete Collection View
DELETE
/collections/{collectionId}/views/{viewId}
Summary
Delete one collection view definition by view ID. Cannot delete the last stored view in a collection. If the active view is deleted, the first remaining stored view becomes active.
Path Parameters
collectionIdstring
viewIdstring
Response Body
200
Successfully deleted resource
deletedViewIdDeleted View ID
The ID of the deleted collection view
activeViewId?Active View ID
The effective active view ID after deletion. If the deleted view was active, the first remaining stored view becomes active.
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Successfully deleted collection view
Update Collection View
PUT
/collections/{collectionId}/views/{viewId}
Summary
Update one collection view definition by view ID. Omitted settings are preserved. Pass empty arrays or objects to clear list-like settings. Gallery settings are only valid for gallery views; kanban settings are only valid for kanban views.
Path Parameters
collectionIdstring
viewIdstring
Request Body
application/json
viewUpdated Collection View
The view definition fields to update. Omitted settings are preserved. Pass empty arrays or objects to clear list-like settings. Gallery settings are only valid for gallery views. Kanban settings are only valid for kanban views, and kanban requires exactly one groupBy rule.
Response Body
200
Successfully updated resource
idstring
Collection view ID. Use this ID for update, delete, and set-active operations.
namestring
typestring
Stored collection view layout type. table is the regular/default table layout; gallery and kanban include matching view-specific settings when configured.
filtersarray<object>
Filter rules stored in the view definition. These endpoints do not execute the filters or return filtered items.
sortByarray<object>
Sort rules stored in the view definition. These endpoints do not execute the sorts or return sorted items.
groupByarray<object>
Grouping rules stored in the view definition. Kanban views have exactly one group rule.
hiddenPropertiesarray<object>
customPropertyOrderarray<object>
columnWidthobject
Empty Object
calculationsobject
Empty Object
isCalculationsRowVisible?boolean
gallery?object
Gallery view settings. Present only for gallery views.
kanban?object
Kanban view settings. Present only for kanban views.
isActiveboolean
True when this view is the effective active view. The effective active view is activeViewId when valid; otherwise it is the first stored view.
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Successfully updated collection view
List Collections
GET
/collections
Summary
List all collections across documents in this multi-document connection
Query Parameters
documentIds?Document IDs
The document IDs to filter. If not provided, collections in all documents will be listed. Can be a single string or array of strings.
documentFilterMode?Document Filter Mode
Whether to include or exclude the specified documents. Default is 'include'. Only used when documentIds is provided.
Default"include"
Allowed Values:"include" | "exclude"
Response Body
200
Success
itemsCollections
Array of collections in the specified documents
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Collections list with document IDs
Create Collection
POST
/collections
Summary
Create a new collection (structured table) in a document within this multi-document connection. Define the schema with columns and their types.
Request Body
application/json
schemaCollection Schema
The schema definition for the new collection, including name, content property, and column definitions.
positionPosition
JSON object to insert the collection at. Must specify either pageId or siblingId.
positionPage Position
The position to insert the blocks at. 'start' inserts at the start of the page, 'end' inserts at the end of the page.
Allowed Values:"start" | "end"
pageIdPage ID
ID of the block to insert children into. Required for multi-document operations. Only page, text, and card type blocks can be parent blocks. Text blocks are auto-converted to page type when they receive children. Collection items are implicitly pages.
positionSibling Position
The position to insert the blocks at. 'before' inserts before the referenced block, 'after' inserts after the referenced block.
Allowed Values:"before" | "after"
siblingIdSibling ID
ID of the block to insert blocks next to.
Response Body
200
Successfully created resource
collectionBlockIdCollection Block ID
The block ID of the newly created collection
nameCollection Name
The name of the created collection
schemaCollection Schema
The schema of the created collection
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Successfully created collection
Get Collection Schema
GET
/collections/{collectionId}/schema
Summary
Get collection schema in JSON Schema format
Path Parameters
collectionIdstring
Query Parameters
format?Format
The format to return the schema in. Default: json-schema-items. - 'schema': Returns the collection schema structure that can be edited - 'json-schema-items': Returns JSON Schema for addCollectionItems/updateCollectionItems validation
Default"json-schema-items"
Allowed Values:"schema" | "json-schema-items"
Response Body
200
Successfully retrieved data
response?unknown
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Update Collection Schema
PUT
/collections/{collectionId}/schema
Summary
Update the collection schema. Replaces the existing schema entirely - include all fields you want to keep. Keep property keys stable for existing properties.
Path Parameters
collectionIdstring
Request Body
application/json
schemaUpdated Collection Schema
The updated schema definition. Replaces the existing schema entirely - include all fields you want to keep.
Response Body
200
Successfully updated resource
collectionBlockIdCollection Block ID
The block ID of the collection whose schema was updated
schemaUpdated Collection Schema
The updated collection schema
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Successfully updated collection schema
Add comments
POST
/comments
Summary
Add comments to blocks.
Request Body
application/json
commentsarray<object>
List of comments to add.
Response Body
200
Successfully created resource
commentIdstring
The ID of the created comment
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Comments successfully created
Get Connection Info
GET
/connection
Summary
Returns connection metadata including space ID, space name, timezone, current time, and URL templates for constructing deep links to blocks.
Response Body
200
Successfully retrieved data
spaceobject
utcobject
urlTemplatesobject
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
List Documents
GET
/documents
Summary
Retrieve all documents accessible through this multi-document connection. Returns rootBlockIds, titles, and deletion status. Use the rootBlockId with GET /blocks to fetch content.
Query Parameters
fetchMetadata?Fetch Metadata
Whether to include metadata (lastModifiedAt, createdAt, clickableLink) in the response. Default is false.
Response Body
200
Success
itemsDocuments
Array of documents in this multi-document connection
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
List Reminders
GET
/reminders
Summary
Experimental: list block reminders within this connection's document scope. See the Reminders section for availability and ownership.
Query Parameters
status?string
List filter. Defaults to incomplete, including Save for later and overdue reminders. Upcoming includes incomplete reminders with a future time or no time (Save for later). All includes incomplete and completed reminders within this connection's scope.
Allowed Values:"incomplete" | "completed" | "upcoming" | "all"
limit?integer
Page size, defaults to 50. Results are ordered by creation time, then ID.
Range1 <= value <= 200
cursor?string
Continuation cursor from the previous response; keep the same status filter. If the cursor becomes invalid, restart without it.
Lengthlength <= 256
Response Body
200
Success
itemsarray<object>
pagination?object
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Create Reminders
POST
/reminders
Summary
Experimental: set or replace reminders on blocks within this connection's document scope. Omit the time to Save for later.
Request Body
application/json
remindersarray<object>
Reminders to set or replace on blocks
Response Body
200
Successfully created resource
itemsarray<object>
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Delete Reminders
DELETE
/reminders
Summary
Experimental: delete block reminders within this connection's document scope. The blocks themselves are not deleted.
Request Body
application/json
idsToDeletearray<string>
Reminder IDs to delete
Response Body
200
Successfully deleted resource
itemsarray<string>
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Update Reminders
PUT
/reminders
Summary
Experimental: update block reminders within this connection's document scope. Only provided fields are changed.
Request Body
application/json
remindersToUpdatearray<object>
Reminders to update. Only provided fields are changed.
Response Body
200
Successfully updated resource
itemsarray<object>
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Search in Document
GET
/blocks/search
Summary
Search content in one single Craft document. This is a secondary search tool that complements documents_search by allowing you to search within a single document.
Query Parameters
documentIdDocument ID
The document ID to search within.
patternPattern
The search patterns to look for. Patterns must follow RE2-compatible syntax, which supports most common regular-expression features (literal text, character classes, grouping alternation, quantifiers, lookaheads, and fixed-width lookbehinds.
caseSensitive?Case Sensitive
Whether the search should be case sensitive. Default is false.
beforeBlockCount?Before Block Count
The number of blocks to include before the matched block.
Default5
afterBlockCount?After Block Count
The number of blocks to include after the matched block.
Default5
fetchBlocks?Fetch Blocks
Whether to include the full matched blocks with styling in the response. Default is false.
Response Body
200
Successfully retrieved data
itemsSearch Matches
Array of search matches with structured context
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Search across Documents
GET
/documents/search
Summary
Search content across multiple documents using relevance-based ranking. This endpoint uses FlexiSpaceSearch to find matches across the documents in your multi-document connection.


    

  • Search across all documents or filter to specific documents
    • 

  • Optional document filtering (include or exclude specific documents)
    • 

  • Relevance-based ranking (top 20 results)
    • 

  • Content snippets with match highlighting
    • 

  • Returns exposedDocumentId for each result
    • 



Example Use Cases:


    

  • Find all mentions of a topic across project documents
    • 

  • Search for specific content excluding certain documents
    • 

  • Locate references across a set of related documents
    • 

Query Parameters
include?Include
Search terms to include in the search. Can be a single string or array of strings.
regexps?Regular Expressions
Search terms to include in the search. Patterns must follow RE2-compatible syntax, which supports most common regular-expression features (literal text, character classes, grouping alternation, quantifiers, lookaheads, and fixed-width lookbehinds.
documentIds?Document IDs
The document IDs to filter. If not provided, all documents will be searched. Can be a single string or array of strings.
documentFilterMode?Document Filter Mode
Whether to include or exclude the specified documents. Default is 'include'. Only used when documentIds is provided.
Default"include"
Allowed Values:"include" | "exclude"
fetchBlocks?Fetch Blocks
Whether to include the full matched blocks with styling and block IDs in each search result. Default is false.
Response Body
200
Successfully retrieved data
itemsSearch Matches
Array of individual search matches across documents, ordered by document relevance
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Upload File
POST
/upload
Summary
Upload a file (image, video, or document) and insert it at the specified position. Requires explicit target (pageId or siblingId). Send raw binary data in request body with Content-Type header.
Query Parameters
fileName?File Name
Optional filename, including extension (for example, report.pdf), used as the file attachment title. Left empty when omitted. Does not change the file type determined by Content-Type; ignored for image and video blocks.
Length1 <= length
positionPosition
Where to insert: 'start' or 'end' for page/date positions, 'before' or 'after' for sibling positions.
Allowed Values:"start" | "end" | "before" | "after"
pageId?Page ID
Page block ID to insert into. Required when position is 'start' or 'end' (unless date is specified).
date?Date
Daily note date. Accepts 'today', 'yesterday', 'tomorrow', or ISO date (YYYY-MM-DD). Use with position 'start' or 'end'.
siblingId?Sibling ID
Block ID to insert relative to. Required when position is 'before' or 'after'.
Request Body
application/octet-stream
bodyfile
Formatbinary
Response Body
200
Success
blockIdstring
The ID of the created block
assetUrlstring
The URL to access the uploaded asset
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Create Whiteboard
POST
/whiteboards
Summary
Create a new empty whiteboard block at the specified position. Returns the whiteboard block ID. Use whiteboardElements_add to populate it.
Request Body
application/json
positionPosition in a parent page | Position next to a sibling block
positionPage Position
The position to insert the blocks at. 'start' inserts at the start of the page, 'end' inserts at the end of the page.
Allowed Values:"start" | "end"
pageIdPage ID
ID of the block to insert children into. Required for multi-document operations. Only page, text, and card type blocks can be parent blocks. Text blocks are auto-converted to page type when they receive children. Collection items are implicitly pages.
positionSibling Position
The position to insert the blocks at. 'before' inserts before the referenced block, 'after' inserts after the referenced block.
Allowed Values:"before" | "after"
siblingIdSibling ID
ID of the block to insert blocks next to.
Response Body
200
Successfully created resource
whiteboardBlockIdstring
The block ID of the created whiteboard
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Get Whiteboard Elements
GET
/whiteboards/{whiteboardBlockId}/elements
Summary
Get all Excalidraw elements and appState from a whiteboard block.
Path Parameters
whiteboardBlockIdstring
Response Body
200
Successfully retrieved data
elementsarray<object>
Excalidraw elements
assets?object
Excalidraw assets (optional).
Empty Object
appState?object
Excalidraw app state (optional).
Empty Object
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Add Whiteboard Elements
POST
/whiteboards/{whiteboardBlockId}/elements
Summary
Append elements to an existing whiteboard without removing existing ones.
Path Parameters
whiteboardBlockIdstring
Request Body
application/json
elementsElements
Excalidraw elements to append.
Itemsitems <= 500
Response Body
200
Successfully created resource
elementsarray<object>
Excalidraw elements
assets?object
Excalidraw assets (optional).
Empty Object
appState?object
Excalidraw app state (optional).
Empty Object
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Delete Whiteboard Elements
DELETE
/whiteboards/{whiteboardBlockId}/elements
Summary
Remove elements from a whiteboard by their Excalidraw element IDs.
Path Parameters
whiteboardBlockIdstring
Request Body
application/json
elementIdsElement IDs
Excalidraw element IDs to remove.
Itemsitems <= 500
Response Body
200
Successfully deleted resource
deletedCountnumber
Number of elements deleted
remainingCountnumber
Number of elements remaining
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Update Whiteboard Elements
PUT
/whiteboards/{whiteboardBlockId}/elements
Summary
Update specific elements in a whiteboard by their ID. Elements not included in the request remain unchanged.
Path Parameters
whiteboardBlockIdstring
Request Body
application/json
elementsElements
Excalidraw elements to update. Each must include an id matching an existing element. Only provided properties are changed.
Itemsitems <= 500
Response Body
200
Successfully updated resource
elementsarray<object>
Excalidraw elements
assets?object
Excalidraw assets (optional).
Empty Object
appState?object
Excalidraw app state (optional).
Empty Object
Try it out?
Create an API connection in the Imagine tab in Craft, and paste your API URL here