Selected Documents
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.
Recommended Usage
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.
Development Tips
- Start with
GET /documentsto discover available documents and their IDs - Use the
idparameter inGET /blockswith a document's ID to fetch that document's content - When inserting blocks, use
pageIdin the position object to specify the target document/block - Use
GET /documents/searchto search across all documents with relevance-based ranking - Collections can span multiple documents - use
GET /collectionsto 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 (
GETrequests), 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
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 markdown formatted output may include structural tags like <page></page>, etc. When displaying content, consider rendering markdown as formatted text or cleaning up the syntax for plain text display.
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
The ID of the page block to fetch. Required for multi-document operations. Accepts IDs for documents, pages and blocks.
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.
-1Whether to fetch metadata (comments, createdBy, lastModifiedBy, lastModifiedAt, createdAt) for the blocks. Default is false.
Response Body
Successfully retrieved data
"text"h1-h4, body, caption for text blocks. card/page for page blocks with visual styling.
"card" | "page" | "h1" | "h2" | "h3" | "h4" | "caption" | "body"default is left
"left" | "center" | "right" | "justify""system" | "serif" | "rounded" | "mono"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.
"small" | "square" | "regular" | "large"The markdown content of the block.
The indentation level of the block.
0 <= value <= 5"none" | "bullet" | "numbered" | "toggle" | "task"7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.
^#[0-9a-fA-F]{6}$only interpreted, if listStyle is 'task'
"page"The title of the page block.
The indentation level of the block.
0 <= value <= 5"none" | "bullet" | "numbered" | "toggle" | "task"7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.
^#[0-9a-fA-F]{6}$only interpreted, if listStyle is 'task'
h1-h4, body, caption for text blocks. card/page for page blocks with visual styling.
"card" | "page" | "h1" | "h2" | "h3" | "h4" | "caption" | "body"default is left
"left" | "center" | "right" | "justify""system" | "serif" | "rounded" | "mono"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.
"small" | "square" | "regular" | "large"Content of the page block. Array of blocks. Follows the same block schema.
"collectionItem"The title of the block.
The properties of the block.
Empty Object
The title of the collection item
Content of the collection item block's page. Array of blocks. Follows the same block schema.
"image""fit" | "fill""auto" | "fullWidth"The markdown content of the block.
The indentation level of the block.
0 <= value <= 5"none" | "bullet" | "numbered" | "toggle" | "task"7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.
^#[0-9a-fA-F]{6}$only interpreted, if listStyle is 'task'
"video""fit" | "fill""auto" | "fullWidth"The markdown content of the block.
The indentation level of the block.
0 <= value <= 5"none" | "bullet" | "numbered" | "toggle" | "task"7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.
^#[0-9a-fA-F]{6}$only interpreted, if listStyle is 'task'
"file"The name of the file.
"small" | "regular" | "card"The markdown content of the block.
The indentation level of the block.
0 <= value <= 5"none" | "bullet" | "numbered" | "toggle" | "task"7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.
^#[0-9a-fA-F]{6}$only interpreted, if listStyle is 'task'
"drawing"The markdown content of the block.
The indentation level of the block.
0 <= value <= 5"none" | "bullet" | "numbered" | "toggle" | "task"7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.
^#[0-9a-fA-F]{6}$only interpreted, if listStyle is 'task'
"whiteboard"The markdown content of the block.
The indentation level of the block.
0 <= value <= 5"none" | "bullet" | "numbered" | "toggle" | "task"7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.
^#[0-9a-fA-F]{6}$only interpreted, if listStyle is 'task'
"table"The markdown content of the block.
The indentation level of the block.
0 <= value <= 5"none" | "bullet" | "numbered" | "toggle" | "task"7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.
^#[0-9a-fA-F]{6}$only interpreted, if listStyle is 'task'
"collection"The markdown content of the block.
The indentation level of the block.
0 <= value <= 5"none" | "bullet" | "numbered" | "toggle" | "task"7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.
^#[0-9a-fA-F]{6}$only interpreted, if listStyle is 'task'
"code"The raw code of the block.
"ada" | "bash" | "cpp" | "cs" | "css" | "dart" | "dockerfile" | "matlab" | "go" | "groovy" | "haskell" | "html" | "java" | "javascript" | "json" | "julia" | "kotlin" | "lua" | "markdown" | "objectivec" | "perl" | "php" | "prolog" | "plaintext" | "python" | "r" | "ruby" | "rust" | "scala" | "shell" | "sql" | "swift" | "typescript" | "vbnet" | "xml" | "yaml" | "math_formula" | "other"The markdown content of the block.
The indentation level of the block.
0 <= value <= 5"none" | "bullet" | "numbered" | "toggle" | "task"7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.
^#[0-9a-fA-F]{6}$only interpreted, if listStyle is 'task'
"richUrl""small" | "regular" | "card"The markdown content of the block.
The indentation level of the block.
0 <= value <= 5"none" | "bullet" | "numbered" | "toggle" | "task"7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.
^#[0-9a-fA-F]{6}$only interpreted, if listStyle is 'task'
"line"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.
"regular""strong" | "regular" | "light" | "extraLight" | "pageBreak"The markdown content of the block.
The indentation level of the block.
0 <= value <= 5"none" | "bullet" | "numbered" | "toggle" | "task"7-character hex code (e.g., #RRGGBB). Case-insensitive. Auto-adjusted for readability, with dark variant auto-generated.
^#[0-9a-fA-F]{6}$only interpreted, if listStyle is 'task'
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Insert 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
The blocks to insert, as JSON array
JSON object to insert the content at. Must specify either pageId or siblingId.
The position to insert the blocks at. 'start' inserts at the start of the page, 'end' inserts at the end of the page.
"start" | "end"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.
The position to insert the blocks at. 'before' inserts before the referenced block, 'after' inserts after the referenced block.
"before" | "after"ID of the block to insert blocks next to.
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.
JSON object to insert the content at. Must specify either pageId or siblingId.
The position to insert the blocks at. 'start' inserts at the start of the page, 'end' inserts at the end of the page.
"start" | "end"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.
The position to insert the blocks at. 'before' inserts before the referenced block, 'after' inserts after the referenced block.
"before" | "after"ID of the block to insert blocks next to.
Response Body
Successfully created resource
Array of blocks
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Delete Blocks
Summary
Delete content from documents in this multi-document connection. Removes specified blocks by their IDs.
Request Body
The IDs of the blocks to delete
Response Body
Successfully deleted resource
Array of deleted block IDs
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Update 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
The blocks to update, as JSON array. Only the fields that are provided will be updated.
Response Body
Successfully updated resource
Array of blocks
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Move Blocks
Summary
Move blocks to reorder them or move them between documents. Returns the moved block IDs.
Request Body
The IDs of the blocks to move
JSON object to move the content to. Must specify either pageId or siblingId.
The position to insert the blocks at. 'start' inserts at the start of the page, 'end' inserts at the end of the page.
"start" | "end"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.
The position to insert the blocks at. 'before' inserts before the referenced block, 'after' inserts after the referenced block.
"before" | "after"ID of the block to insert blocks next to.
Response Body
Successfully moved resource
Array of moved block IDs
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Search in Document
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
The document ID to search within.
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.
Whether the search should be case sensitive. Default is false.
The number of blocks to include before the matched block.
5The number of blocks to include after the matched block.
5Response Body
Successfully retrieved data
Array of search matches with structured context
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Search across Documents
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
Search terms to include in the search. Can be a single string or array of strings.
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.
The document IDs to filter. If not provided, all documents will be searched. Can be a single string or array of strings.
Whether to include or exclude the specified documents. Default is 'include'. Only used when documentIds is provided.
"include""include" | "exclude"Whether to include document metadata (lastModifiedAt, createdAt) in each search result. Default is false.
Response Body
Successfully retrieved data
Array of individual search matches across documents, ordered by document relevance
Create an API connection in the Imagine tab in Craft, and paste your API URL here
List Collections
Summary
List all collections across documents in this multi-document connection
Query Parameters
The document IDs to filter. If not provided, collections in all documents will be listed. Can be a single string or array of strings.
Whether to include or exclude the specified documents. Default is 'include'. Only used when documentIds is provided.
"include""include" | "exclude"Response Body
Success
Array of collections in the specified documents
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Get Collection Schema
Summary
Get collection schema in JSON Schema format
Path Parameters
Query Parameters
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
"json-schema-items""schema" | "json-schema-items"Response Body
Successfully retrieved data
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Get Collection Items
Summary
Get all items from a collection
Path Parameters
Query Parameters
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.
-1Response Body
Successfully retrieved data
Array of items in the collection.
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Add Collection 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
Request Body
Items to add to the collection. Each item should match the collection's schema (properties will be validated at runtime).
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
Successfully created resource
Array of successfully added items
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Delete Collection Items
Summary
Delete collection items (also deletes content inside items)
Path Parameters
Request Body
IDs of the items to delete from the collection.
Response Body
Successfully deleted resource
Array of successfully deleted item IDs
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Update Collection Items
Summary
Update collection items. Two-way relations are synced automatically in the background - only set one side for consistency.
Path Parameters
Request Body
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).
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
Successfully updated resource
Array of successfully updated items
Create an API connection in the Imagine tab in Craft, and paste your API URL here
List Documents
Summary
Retrieve all documents accessible through this multi-document connection. Returns document IDs, titles, and deletion status. The document ID is the same as its root block ID - use it with GET /blocks to fetch content.
Query Parameters
Whether to include metadata (lastModifiedAt, createdAt) in the response. Default is false.
Response Body
Success
Array of documents in this multi-document connection
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Upload File
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. This is an experimental API, expect breaking changes.
Query Parameters
Where to insert: 'start' or 'end' for page/date positions, 'before' or 'after' for sibling positions.
"start" | "end" | "before" | "after"Page block ID to insert into. Required when position is 'start' or 'end' (unless date is specified).
Daily note date. Accepts 'today', 'yesterday', 'tomorrow', or ISO date (YYYY-MM-DD). Use with position 'start' or 'end'.
Block ID to insert relative to. Required when position is 'before' or 'after'.
Request Body
binaryResponse Body
Success
The ID of the created block
The URL to access the uploaded asset
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Add comments
Summary
Add comments to blocks. This is an experimental endpoint, expect breaking changes.
Request Body
List of comments to add.
Response Body
Successfully created resource
The ID of the created comment
Create an API connection in the Imagine tab in Craft, and paste your API URL here
Get Connection Info
Summary
Returns connection metadata including space ID, timezone, current time, and URL templates for constructing deep links to blocks. This is an experimental API, expect breaking changes.
Response Body
Successfully retrieved data
Create an API connection in the Imagine tab in Craft, and paste your API URL here