Craft Document Management

Operate on a Craft space via the Craft Connect REST API. Full CRUD on documents,
blocks, folders, tasks, collections, and comments.

Requirements

• - curl — used for all API requests
• CRAFTAPIURL — your Craft Connect API base URL (contains embedded link token for authentication)

Setup

1. 1. Create a Craft Connect link in your Craft space (Settings → Connect → Create Link)
2. Copy the API base URL and store it in TOOLS.md under a Craft section:

CODEBLOCK0

1. 3. Read TOOLS.md before making any calls to retrieve the URL.

All calls use curl with -H "Content-Type: application/json" for writes and
-H "Accept: application/json" for reads.

Important: URL-encode non-ASCII characters (e.g. Chinese) in query params.

API Reference

Connection Info

CODEBLOCK1

Returns space ID, timezone, current time, and deep-link URL templates.

Discovery

CODEBLOCK2

Search

CODEBLOCK3

Documents

CODEBLOCK4

Reading Content

CODEBLOCK5

Writing Content

Two methods: markdown (recommended) and blocks JSON.

Method 1: Markdown (Recommended)

Best for most content. Craft parses markdown and auto-generates correct block
types, indentation levels, and list styles.

CODEBLOCK6

Method 2: Blocks JSON

Use when you need explicit control over color, font, textStyle, or other
properties not expressible in plain markdown.

CODEBLOCK7

Position Options

Updating & Deleting Blocks

CODEBLOCK8

Tasks

CODEBLOCK9

Folders

CODEBLOCK10

Collections (Structured Databases)

Collections are like Notion databases — structured tables with typed columns.

CODEBLOCK11

Comments

CODEBLOCK12

File Upload

CODEBLOCK13

Position params: position (start|end|before|after) + pageId/date/siblingId.

Block Types & Formatting

Headings

CODEBLOCK14

Inline Styles

CODEBLOCK15

Highlights (9 solid + 5 gradient)

CODEBLOCK16

Solid: yellow, blue, red, green, purple, pink, mint, cyan, gray
Gradient: gradient-blue, gradient-purple, gradient-red, gradient-yellow, INLINECODE28

Lists

CODEBLOCK17

Toggle (Collapsible) Lists — CRITICAL

Children MUST be indented 2 spaces to nest inside a toggle:

CODEBLOCK18

Use markdown mode only. indentationLevel in blocks JSON is silently
ignored on insert.

Blockquote

CODEBLOCK19

Produces block with decorations: ["quote"].

Dividers / Lines

Blocks JSON with lineStyle:

CODEBLOCK20

Markdown mode: --- produces extraLight by default.

Code Blocks

Markdown mode:

INLINECODE34

Blocks JSON (requires rawCode!):

CODEBLOCK23python\ndef hello():\n print('Hello')\n``"} CODEBLOCK24json {"type": "code", "language": "math_formula", "rawCode": "x = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}", "markdown": "`math_formula\nx = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}\n`"} CODEBLOCK25markdown | Col A | Col B | | --- | --- | | val 1 | val 2 | CODEBLOCK26json {"type": "image", "url": "https://example.com/photo.jpg", "markdown": "![Alt](https://example.com/photo.jpg)"} CODEBLOCK27json {"type": "richUrl", "url": "https://www.youtube.com/watch?v=..."} CODEBLOCK28json {"type": "page", "textStyle": "page", "markdown": "Sub-page Title"} {"type": "page", "textStyle": "card", "markdown": "Card Title"} CODEBLOCK29json {"type": "text", "color": "#00A3CB", "markdown": "<callout>💡 Info</callout>"} CODEBLOCK30json {"type": "text", "textStyle": "caption", "markdown": "<caption>Small annotation</caption>"} CODEBLOCK31json {"type": "text", "listStyle": "task", "taskInfo": {"state": "todo"}, "markdown": "- [ ] Task"} CODEBLOCK32json { "type": "text", "font": "rounded", "textStyle": "h3", "color": "#9862E8", "markdown": "<callout>### ✨ Purple rounded heading callout</callout>" } ` --- ## Choosing Insert Method | Need | Use | Why | |------|-----|-----| | Text, lists, headings | Markdown | Clean, auto-detects types | | Toggle lists with children | Markdown | Only way to get indentation right | | Code blocks, tables | Either | Markdown is simpler; JSON needs rawCode | | Colored callouts | Blocks JSON | Need color property | | Custom fonts | Blocks JSON | Need font property | | Captions | Blocks JSON | Need textStyle: "caption" | | Images, richUrl, pages | Blocks JSON | Need type field | | Line styles | Blocks JSON | Need lineStyle | | Math formulas | Blocks JSON | Need language: "mathformula" + rawCode | | Mixed content | Split calls | Combine markdown + blocks JSON | --- ## Gotchas & Lessons Learned 1. **Toggle indentation**: markdown mode with 2-space indent is the only way. indentationLevel in blocks JSON is silently ignored on insert. 2. **Task state values**: todo | done | canceled. NOT completed. 3. **Position after/before**: use siblingId (not blockId). 4. **Position end/start**: use pageId or date. 5. **Code blocks in JSON mode**: require rawCode field. Without it you get a validation error. 6. **Collection item keys**: the API docs say title but the real field name is the auto-generated contentProp key from the schema (e.g. 4). Always GET /collections//schema?format=json-schema-items first to discover the correct keys. 7. **URL-encode search terms**: Chinese and special characters in query params must be URL-encoded or curl returns 400. 8. **Accept header**: use application/json for reads. text/markdown may 502. 9. **Document delete is soft**: goes to trash, restorable via move. Block delete is permanent. 10. **Large inserts**: one POST can insert many blocks. Prefer fewer larger writes to avoid rate limits. 11. **Image re-hosting**: Craft downloads external images and re-hosts them at https://r.craft.do/`. Your original URL is replaced.

1. 12. Collections are experimental: the API may change. Always read the