JotBird API

The JotBird API allows you to publish, manage, and remove Markdown using scripts, CI pipelines, or any HTTP client. 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: Visit jotbird.com/account/api-key while signed in to generate a key.

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 the API keys panel 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."
  }'

Response

Returns 201 for new documents, 200 for updates.

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

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": "bright-calm-meadow",
      "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"
    }
  ]
}

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"

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