Concepts
Much of the Capacities API is also available through Markdown. You send or receive a string of Markdown instead of building blocks and text tokens by hand.
Markdown is a compressed, reduced representation of page content. It does not cover every layout and property the full API can express, but it matches how many tools and models already think about text — which makes it especially useful for AI assistants, scripts, and quick integrations.
| Area | Endpoint | Direction |
|---|---|---|
| Object body | GET /object/markdown | Read — export an object as Markdown |
| Object body | POST /object/markdown | Write — create an object from Markdown |
| Object body | POST /blocks/markdown/append | Write — append Markdown to an existing object |
| Daily notes | POST /blocks/markdown/daily-note | Write — append to a daily note |
| Weblink notes | POST /object/url (optional markdown field) | Write — notes on a new link object |
Conversion follows the same rules as Markdown in the Capacities app (headings, lists, links, tags where supported). Markdown is converted to blocks when writing, and blocks to Markdown when exporting.
These still use the full JSON models:
PATCH /object (see Properties)Typical pattern: create or update properties with POST /object or PATCH /object, and use Markdown only for the main body content.
| Markdown | Blocks + text tokens | |
|---|---|---|
| Best for | LLM output, .md files, quick capture | Exact structure, embeds, fine-grained edits |
| Payload size | Small string | Larger JSON trees |
| Expressiveness | Subset of Capacities formatting | Full block types and inline tokens |
| Round-trip | Good for prose; some details may differ | Lossless for supported block types |
For AI workflows, prefer Markdown endpoints when the model produces text. Drop to block JSON only when you need a specific block type, layout, or per-block patch.
See the API Reference for request bodies and SDK samples on each Markdown route.
Create a ticket on our feedback board. - Let us know if you have an idea for a feature, improvement or think there is something missing.
Request additions to the documentation. - If your questions are not getting answered, let us know and we will extend the documentation.