API Quick Start

Make your first Meldoc API call in under 5 minutes.

Prerequisites: An Integration Tokens and your project alias. To find the alias, open the project and use Copy project alias in the header menu — or check Project settings → Basic Information.

All examples below use these placeholder values:

Token:         mdc_your_token_here
Project alias: my-project
Base URL:      https://api.meldoc.io/api/v1

Get the document tree

The tree endpoint returns every document in your project with its metadata and content.

curl -H "X-Cli-Secret: mdc_your_token_here" \
     -H "X-Project-Alias: my-project" \
     https://api.meldoc.io/api/v1/tree

Response:

{
  "cursor": "2026-03-25T12:00:00Z",
  "docs": [
    {
      "id": "a1b2c3d4-...",
      "title": "Getting Started",
      "alias": "getting-started",
      "order": 0,
      "is_virtual": false,
      "workflow": "published",
      "visibility": "visible",
      "exposure": "inherit",
      "content": "# Getting Started\n\nWelcome to..."
    },
    {
      "id": "e5f6g7h8-...",
      "title": "API Guide",
      "alias": "api-guide",
      "parentAlias": "getting-started",
      "order": 1,
      "is_virtual": false,
      "workflow": "draft",
      "visibility": "visible",
      "exposure": "inherit",
      "content": "..."
    }
  ]
}

Read a single document

Fetch a document by its alias when you need one specific page.

curl -H "X-Cli-Secret: mdc_your_token_here" \
     -H "X-Project-Alias: my-project" \
     "https://api.meldoc.io/api/v1/doc?alias=getting-started"

Response:

{
  "id": "a1b2c3d4-...",
  "alias": "getting-started",
  "title": "Getting Started",
  "hash": "abc123def456...",
  "updated_at": "2026-03-25T10:30:00Z",
  "content": "# Getting Started\n\nWelcome to...",
  "order": 0,
  "workflow": "published",
  "visibility": "visible",
  "exposure": "inherit"
}

Add &include_content=false to fetch metadata only.

Push a document

Create or update a document by pushing it to the server. Pushing requires a token with the Write permission level or higher.

curl -X POST \
     -H "X-Cli-Secret: mdc_your_token_here" \
     -H "X-Project-Alias: my-project" \
     -H "Content-Type: application/json" \
     -d '{
       "files": [
         {
           "path": "docs/hello.meldoc.md",
           "alias": "hello",
           "title": "Hello World",
           "content": "This is my first document.",
           "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
         }
       ]
     }' \
     https://api.meldoc.io/api/v1/push

Response:

{
  "results": [
    {
      "alias": "hello",
      "path": "docs/hello.meldoc.md",
      "id": "f9a8b7c6-...",
      "title": "Hello World",
      "order": 0,
      "status": "created"
    }
  ],
  "server_version": "1.0.1"
}

Note: The sha256 field is a SHA-256 hash of the file content, used for conflict detection.

Use other HTTP clients

The API works with any HTTP client. Here are examples in Python and JavaScript.

Python

import requests

headers = {
    "X-Cli-Secret": "mdc_your_token_here",
    "X-Project-Alias": "my-project",
}

response = requests.get(
    "https://api.meldoc.io/api/v1/tree",
    headers=headers,
)
docs = response.json()["docs"]

for doc in docs:
    print(f"{doc['alias']}: {doc['title']}")

JavaScript

const headers = {
  "X-Cli-Secret": "mdc_your_token_here",
  "X-Project-Alias": "my-project",
};

const response = await fetch("https://api.meldoc.io/api/v1/tree", { headers });
const { docs } = await response.json();

docs.forEach((doc) => {
  console.log(`${doc.alias}: ${doc.title}`);
});

What’s next?

Endpoint Reference — Complete endpoint reference with all parameters and response fields.

Integration Tokens — Create and manage tokens.