Content Formats

When creating docs via POST /docs (or the deprecated POST /insights), you can specify the format of the content field using the optional content_type parameter. This is useful when importing content from tools like Confluence, Notion, or other wiki and document stores that export as Markdown.

Supported formats

Value	Description
`html`	HTML content (default). Tags like `<strong>`, `<em>`, `<h1>`, `<ul>`, `<table>`, etc. are converted to rich text.
`markdown`	Markdown content. Supports headings, bold, italic, links, lists, blockquotes, code blocks, tables, task lists, and horizontal rules.
`text`	Plain text. Line breaks are preserved as paragraphs.

If content_type is omitted, content is parsed as HTML.

Examples

Creating a doc with Markdown

POST https://dovetail.com/api/v1/docs
Authorization: Bearer <DOVETAIL_API_TOKEN>
Content-Type: application/json

{
  "title": "Sprint Retro Notes",
  "content": "# Key Findings\n\n- **Speed** improved by 20%\n- Need more [testing](https://example.com)\n\n## Action Items\n\n- [ ] Follow up with customers\n- [x] Update documentation",
  "content_type": "markdown",
  "project_id": "<PROJECT_ID>"
}

Creating a doc with HTML

POST https://dovetail.com/api/v1/docs
Authorization: Bearer <DOVETAIL_API_TOKEN>
Content-Type: application/json

{
  "title": "Interview Summary",
  "content": "<h1>Key Findings</h1><p>Speed improved by <strong>20%</strong></p>",
  "project_id": "<PROJECT_ID>"
}

Creating a doc with plain text

POST https://dovetail.com/api/v1/docs
Authorization: Bearer <DOVETAIL_API_TOKEN>
Content-Type: application/json

{
  "title": "Quick Note",
  "content": "First paragraph of notes.\n\nSecond paragraph with more detail.",
  "content_type": "text",
  "project_id": "<PROJECT_ID>"
}

Supported Markdown syntax

The following Markdown constructs are supported:

Headings: # H1 through ###### H6
Bold: **text**
Italic: *text*
Links: [text](url)
Unordered lists: - item or * item
Ordered lists: 1. item
Task lists: - [ ] todo and - [x] done
Blockquotes: > text
Code blocks: ```language with syntax highlighting
Inline code: `code`
Tables: pipe-delimited with header separator rows
Horizontal rules: ---