JotBird API

The JotBird API lets you turn Markdown into shareable web pages using scripts, CI pipelines, or any HTTP client. Send Markdown, get back a public URL. All you need is a free JotBird account and an API key.

All endpoints accept and return JSON. The base URL for all requests is:

https://www.jotbird.com

If you prefer a CLI, the jotbird command wraps these endpoints with file tracking and slug mapping. Install it from npm:

npm install -g jotbird

An OpenAPI spec is also available for code generation and tooling.

All API requests require a personal API key, passed as a Bearer token in the Authorization header:

Authorization: Bearer jb_your_api_key_here

Generating a key

Sign up for a free account at jotbird.com, then generate an API key in two ways:

• CLI: Run jotbird login to open the browser and generate a key automatically.
• Browser: Open Account Settings from the account menu in the web app and generate a key from the API Keys section.

Key limits

Each account can have up to 10 API keys. If you reach the limit, revoke an existing key before generating a new one.

Revoking a key

To revoke an API key, open Account Settings from your account menu in the web app. Each key shows its prefix, creation date, and last usage. Click Revoke to permanently delete a key. Revoked keys stop working immediately.

Publish requests are rate-limited per account on a rolling hourly window. Free accounts also have a cap on the number of active documents published via API. Active documents are documents with a live public URL that have not expired. Expired documents do not count toward the limit.

Response headers

Every publish response includes rate limit information:

Publish a new Markdown document or update an existing one. The server renders your Markdown to HTML and hosts it at a shareable URL. Free accounts get 90-day links. Pro makes links permanent.

Request body

curl -X POST https://www.jotbird.com/api/v1/publish \
  -H "Authorization: Bearer jb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Hello World\n\nThis is my document."
  }'

Updating an existing document

To update a document you've already published, include its slug in the request body. The content at that URL is replaced with the new Markdown.

curl -X POST https://www.jotbird.com/api/v1/publish \
  -H "Authorization: Bearer jb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Hello World\n\nUpdated content goes here.",
    "slug": "bright-calm-meadow"
  }'

The response returns 200 instead of 201, and "created": false.

Response

Returns 201 for new documents, 200 for updates.

{
  "slug": "bright-calm-meadow",
  "username": null,
  "url": "https://share.jotbird.com/bright-calm-meadow",
  "title": "Hello World",
  "expiresAt": "2026-05-10T12:00:00.000Z",
  "ttlDays": 90,
  "created": true
}

Pro users who have set a username can publish documents at permanent, human-readable URLs like share.jotbird.com/@username/my-page. Set your username in Account Settings.

Pass "namespaced": true in the publish request body to publish at your username. A slug is required — the API will not auto-generate one for namespaced documents. If a document with that slug already exists in your namespace, it is updated in place.

curl -X POST https://www.jotbird.com/api/v1/publish \
  -H "Authorization: Bearer jb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# My Page\n\nPublished at a custom URL.",
    "slug": "my-page",
    "namespaced": true
  }'

The response includes a username field and a namespaced URL:

{
  "slug": "my-page",
  "username": "clayton-myers",
  "url": "https://share.jotbird.com/@clayton-myers/my-page",
  "title": "My Page",
  "expiresAt": null,
  "ttlDays": null,
  "created": true
}

The list endpoint always returns the correct URL for each document and includes a username field ( null for documents without a username).

Retrieve all published documents for your account. Only documents with an active public URL are returned.

Request

No request body is required.

curl https://www.jotbird.com/api/v1/documents \
  -H "Authorization: Bearer jb_your_api_key_here"

Response

{
  "documents": [
    {
      "slug": "my-page",
      "username": "clayton-myers",
      "title": "My Page",
      "url": "https://share.jotbird.com/@clayton-myers/my-page",
      "source": "api",
      "updatedAt": "2026-04-20T10:00:00.000Z",
      "expiresAt": null
    },
    {
      "slug": "bright-calm-meadow",
      "username": null,
      "title": "Hello World",
      "url": "https://share.jotbird.com/bright-calm-meadow",
      "source": "cli",
      "updatedAt": "2026-02-09T14:30:00.000Z",
      "expiresAt": "2026-05-10T14:30:00.000Z",
      "theme": "default",
      "hideBranding": false,
      "visibility": "unlisted",
      "tags": []
    }
  ]
}

Each document also includes its current page settings — theme, hideBranding, visibility, and tags — see Page settings.

Read and change a published document's page settings — theme, branding, and visibility — without republishing. For documents at @username/slug URLs, add ?namespaced=true. You can also address a document by its stable id with ?documentId=<uuid> (returned by the publish endpoint) — it takes precedence over the path slug and survives slug changes.

Read settings

curl https://www.jotbird.com/api/v1/documents/bright-calm-meadow/settings \
  -H "Authorization: Bearer jb_your_api_key_here"

{
  "slug": "bright-calm-meadow",
  "username": null,
  "url": "https://share.jotbird.com/bright-calm-meadow",
  "title": "Hello World",
  "theme": "default",
  "hideBranding": false,
  "visibility": "unlisted",
  "tags": [],
  "expiresAt": "2026-05-10T14:30:00.000Z"
}

Update settings

Send only the settings you want to change — everything else is left as-is. The response is the full updated settings state.

curl -X PATCH https://www.jotbird.com/api/v1/documents/bright-calm-meadow/settings \
  -H "Authorization: Bearer jb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"theme": "essay", "visibility": "public"}'

To password-protect a page:

curl -X PATCH https://www.jotbird.com/api/v1/documents/bright-calm-meadow/settings \
  -H "Authorization: Bearer jb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"visibility": "password", "password": "correct-horse-battery"}'

Permanently delete a document. This removes the public URL, the stored content, and all associated image references. This action cannot be undone.

Query parameters

curl -X DELETE "https://www.jotbird.com/api/v1/documents?slug=bright-calm-meadow" \
  -H "Authorization: Bearer jb_your_api_key_here"

To remove a namespaced document:

curl -X DELETE "https://www.jotbird.com/api/v1/documents?slug=my-page&namespaced=true" \
  -H "Authorization: Bearer jb_your_api_key_here"

Response

{
  "ok": true
}

All error responses return a JSON object with an error field containing a human-readable message:

{
  "error": "Missing markdown field"
}

Status codes