MuseCanto

POST a new document into an owned knowledge base from Markdown, HTML, or ProseMirror JSON.

Create a new document in a knowledge base you own. The server parses the body from Markdown, HTML, or ProseMirror JSON, creates the document, and initializes collaboration state (collabVersion starts at 0).

For authentication and the Open API prefix, see the developer documentation home. To list existing documents, use Export knowledge base documents.

Endpoint

POST /api/v1/open/books/{bookSlug}/docs/import
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Item	Value
Method	`POST`
Auth	`Authorization: Bearer` + full API key
Path parameter	`bookSlug` — target knowledge base slug
Content-Type	`application/json`
Ownership	Key must belong to the knowledge base owner

Request body

Field	Type	Required	Description
`title`	string	Yes	Document title, 1–150 characters after trimming
`format`	`"markdown"` \| `"html"` \| `"json"`	Yes	Body format
`content`	string \| object	Yes	Body. Must be a non-empty string for `markdown` / `html`; for `json` it can be a string or a ProseMirror doc object (`type: "doc"`)
`description`	string	No	Summary, max 150 characters
`parentId`	string	No	Parent node ID; placed at the library root when omitted. Must be a valid node in the same knowledge base

Format notes

`format`	`content` expectation
`markdown`	Non-empty Markdown string
`html`	Non-empty HTML string
`json`	ProseMirror document JSON (`{ "type": "doc", "content": [...] }`) or a JSON string of the same

Example request

Replace YOUR_API_KEY and BOOK_SLUG with your values. Use your deployment origin instead of https://your-domain.com when not running locally.

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "title": "Imported Doc",
        "format": "markdown",
        "content": "# Title\n\nBody paragraph."
      }' \
  "https://your-domain.com/api/v1/open/books/BOOK_SLUG/docs/import"

$headers = @{ Authorization = "Bearer YOUR_API_KEY" }
$body = @{
  title   = "Imported Doc"
  format  = "markdown"
  content = "# Title`n`nBody paragraph."
} | ConvertTo-Json
Invoke-RestMethod -Method Post `
  -Uri "https://your-domain.com/api/v1/open/books/BOOK_SLUG/docs/import" `
  -Headers $headers -ContentType "application/json" -Body $body

Success response

Status: 201 Created

{
  "success": true,
  "doc": {
    "id": "…",
    "slug": "doc-slug",
    "name": "Imported Doc",
    "type": "document",
    "collabVersion": 0
  },
  "links": {
    "editor": "/app/books/BOOK_SLUG/doc-slug"
  }
}

Response fields

Field	Type	Description
`doc.id`	string	New document ID
`doc.slug`	string	New document slug
`doc.name`	string	Title
`doc.type`	string	Always `document`
`doc.collabVersion`	number	Collaboration version; `0` for a new document
`links.editor`	string	Relative path to the in-browser editor

Error responses

All errors use a flat envelope:

{ "success": false, "code": "<MACHINE_CODE>", "message": "<human readable>" }

HTTP	`code`	When
`400`	`INVALID_CONTENT`	Empty body, or body cannot be parsed into a valid document for the given `format`
`400`	`INVALID_PARENT`	`parentId` is unknown or not part of this knowledge base
`401`	`INVALID_API_KEY`	Missing header, invalid, expired, or revoked key
`404`	`BOOK_NOT_FOUND`	Unknown slug, or library not owned by the key user
`500`	`IMPORT_FAILED`	Unexpected server error (cause is logged server-side, not echoed)

404 vs 403

Non-owned slugs return 404 instead of 403 to avoid leaking whether a slug exists.

Limitations (current version)

Create-only: does not update or delete existing documents.
No per-key knowledge base allowlist (any owned slug works).
Does not import into public or password-protected libraries you do not own.

Import a document