Sign in

v1

latestOpenAPI 3.0.22026-07-261040577.4 KB
Docs

Create doc

Create a new doc in your Dovetail workspace. Docs are rich-text documents used to write up research reports, share findings, and publish deliverables.

You can provide the initial content as HTML, Markdown, or plain text via the content and content_type fields. Markdown support enables importing content from Confluence, Notion, and other wiki or document stores.

HTML content may include inline Dovetail nodes using the data-dovetail-type attribute — see the mention shape below for an example.

A doc can be placed inside a project (via project_id) or a folder (via folder_id), but not both. If neither is specified, the doc is created at the workspace root level.

Returns the doc object without the content body.

Inline mentions: to reference a Dovetail user, include a span with data-dovetail-type="mn" and data-dovetail-attrs='{"id":"<user-uuid>"}'. The span's inner text is used as the fallback label if the user cannot be resolved. When the id resolves to a live workspace user, the span is replaced with a live mention node on import. Unresolved ids degrade gracefully to plain text — the import does not fail.

🚧 Permissions

Please check you have the relevant permissions required to access this resource. This may include specific permissions on the object itself or its parent, or having the correct user role if you're making updates.

post/v1/docs

Request body

titlestring

The doc's title.

contentstring

The initial content of the doc. Interpreted according to the content_type field (defaults to HTML).

content_type'html' | 'markdown' | 'text'

The format of the content field. Defaults to "html". Use "markdown" for Markdown-formatted content (supports headings, lists, bold, italic, code blocks, tables, task lists, links, and blockquotes). Use "text" for plain text.

project_idstring nullable

Unique identifier of the project that the doc is associated with. Cannot be used together with folder_id.

folder_idstring nullable

Unique identifier of the folder to place the doc in. Cannot be used together with project_id.

author_idstring

Unique identifier of the user to set as the author. Only workspace admins can use this field. If omitted, defaults to the authenticated user. Can only be set at creation time. When an admin sets this field, the author change is recorded in workspace audit logs with the API user as the actor, so overrides remain traceable.

cover_image_file_idstring nullable

Unique identifier of a file to use as the doc's cover image.

created_atstring date-time

ISO 8601 datetime to set as the doc's creation date. Only workspace admins can use this field. If omitted, defaults to the current time. Can only be set at creation time.

Example request

{
  "title": "My First Doc",
  "content": "This is my new doc from the key learnings of the interview.",
  "created_at": "2024-01-15T10:30:00Z"
}

Response

201