jotbird-publish

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

JotBird Publish

JotBird 发布

Publish Markdown content to JotBird and get back a shareable URL, via the JotBird HTTP API. Base URL:

https://www.jotbird.com

通过JotBird HTTP API将Markdown内容发布到JotBird，并获取可分享的URL。基础URL：

https://www.jotbird.com

。

Auth

身份验证

Requires a Bearer API key. Set it as an env var before running any commands:

bash

export JOTBIRD_API_KEY="jb_c57e765852df55f32daa0f8c745b3241552a052ddfbe1907f73a4d67d107fe4b"

Never hardcode the key in commands shown to the user or in output files — always reference

$JOTBIRD_API_KEY

需要Bearer API密钥。在运行任何命令前，将其设置为环境变量：

bash

export JOTBIRD_API_KEY="jb_c57e765852df55f32daa0f8c745b3241552a052ddfbe1907f73a4d67d107fe4b"

切勿在展示给用户的命令或输出文件中硬编码密钥——始终引用

$JOTBIRD_API_KEY

。

Publish a document

发布文档

bash

curl -s -X POST https://www.jotbird.com/api/v1/publish \
  -H "Authorization: Bearer $JOTBIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Hello World\n\nContent here."
  }'

Optional fields in the JSON body:

```
title
```
— overrides the title extracted from the first
```
# H1
```
.
```
slug
```
— the slug of an existing document to update in place. Only works if that slug already belongs to the account; otherwise it's ignored and a new auto-generated slug is used.
```
namespaced: true
```
— publish at
```
share.jotbird.com/@username/slug
```
instead of a flat slug. Requires Pro + username set in Account Settings, and
```
slug
```
becomes required (not auto-generated).

Response (

new /

update):

json

{
  "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
}

Always read

slug

url

from the response — don't assume the slug you sent was used. Free accounts: 90-day expiry, 10 active docs, 10 publishes/hour. Pro: permanent links, unlimited docs, 100/hour.

To update a doc later, re-send with its known

slug

bash

curl -s -X POST https://www.jotbird.com/api/v1/publish \
  -H "Authorization: Bearer $JOTBIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Updated\n\nNew content.", "slug": "bright-calm-meadow"}'

Note: image uploads aren't supported — only externally-hosted image URLs render.

bash

curl -s -X POST https://www.jotbird.com/api/v1/publish \
  -H "Authorization: Bearer $JOTBIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Hello World\n\nContent here."
  }'

JSON请求体中的可选字段：

```
title
```
—— 覆盖从第一个
```
# H1
```
提取的标题。
```
slug
```
—— 用于原地更新现有文档的slug。仅当该slug已属于当前账户时生效；否则会被忽略，并使用自动生成的新slug。
```
namespaced: true
```
—— 在
```
share.jotbird.com/@username/slug
```
路径下发布，而非扁平slug。需要Pro版且已在账户设置中设置用户名，同时
```
slug
```
为必填项（不会自动生成）。

响应（

表示新建 /

表示更新）：

json

{
  "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
}

务必从响应中读取

slug

url

——不要假设你发送的slug被采用。免费账户：链接有效期90天，最多10个活跃文档，每小时最多发布10次。Pro版：永久链接，无文档数量限制，每小时最多发布100次。

后续更新文档时，重新发送请求并带上已知的

slug

：

bash

curl -s -X POST https://www.jotbird.com/api/v1/publish \
  -H "Authorization: Bearer $JOTBIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Updated\n\nNew content.", "slug": "bright-calm-meadow"}'

注意：不支持图片上传——仅渲染外部托管的图片URL。

List documents

列出文档

bash

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

Returns all active documents with

slug

username

title

url

source

(

cli

web

api

updatedAt

expiresAt

, plus current page settings (

theme

hideBranding

visibility

tags

bash

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

返回所有活跃文档的信息，包括

slug

、

username

、

title

、

url

、

source

（

cli

web

api

）、

updatedAt

、

expiresAt

，以及当前页面设置（

theme

、

hideBranding

、

visibility

、

tags

）。

Page settings (theme / visibility / password)

页面设置（主题 / 可见性 / 密码）

Read:

bash

curl -s https://www.jotbird.com/api/v1/documents/<slug>/settings \
  -H "Authorization: Bearer $JOTBIRD_API_KEY"

Update (send only fields to change):

bash

curl -s -X PATCH https://www.jotbird.com/api/v1/documents/<slug>/settings \
  -H "Authorization: Bearer $JOTBIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"theme": "essay", "visibility": "public"}'

```
theme
```
:
```
default
```
|
```
minimal
```
|
```
essay
```
|
```
terminal
```
(non-default requires Pro)
```
hideBranding
```
: bool (enabling requires Pro)
```
visibility
```
:
```
unlisted
```
|
```
public
```
|
```
password
```
(
```
password
```
requires Pro; must include
```
password
```
field when setting this)
For
```
@username/slug
```
docs, add
```
?namespaced=true
```
to the URL.
Turning password protection on applies immediately; relaxing it (
```
public
```
/
```
unlisted
```
) can take up to ~1 minute to reach the live page (the API/GET response is authoritative immediately).

读取设置：

bash

curl -s https://www.jotbird.com/api/v1/documents/<slug>/settings \
  -H "Authorization: Bearer $JOTBIRD_API_KEY"

更新设置（仅发送需要修改的字段）：

bash

curl -s -X PATCH https://www.jotbird.com/api/v1/documents/<slug>/settings \
  -H "Authorization: Bearer $JOTBIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"theme": "essay", "visibility": "public"}'

```
theme
```
:
```
default
```
|
```
minimal
```
|
```
essay
```
|
```
terminal
```
（非默认主题需要Pro版）
```
hideBranding
```
: 布尔值（启用该功能需要Pro版）
```
visibility
```
:
```
unlisted
```
|
```
public
```
|
```
password
```
（
```
password
```
选项需要Pro版；设置为该值时必须包含
```
password
```
字段）
对于
```
@username/slug
```
格式的文档，需在URL后添加
```
?namespaced=true
```
。
开启密码保护会立即生效；放宽限制（改为
```
public
```
/
```
unlisted
```
）可能需要约1分钟才能同步到在线页面（API/GET响应会立即更新为最新状态）。

Remove a document

删除文档

bash

curl -s -X DELETE "https://www.jotbird.com/api/v1/documents?slug=<slug>" \
  -H "Authorization: Bearer $JOTBIRD_API_KEY"

Add

&namespaced=true

for

@username/slug

docs. This is permanent — confirm with the user before running it.

bash

curl -s -X DELETE "https://www.jotbird.com/api/v1/documents?slug=<slug>" \
  -H "Authorization: Bearer $JOTBIRD_API_KEY"

对于

@username/slug

格式的文档，需添加

&namespaced=true

。此操作不可恢复——执行前请与用户确认。

Errors to watch for

需要注意的错误

Code	Meaning	Typical cause
400	Bad Request	missing `markdown` , bad slug format
401	Unauthorized	missing/invalid API key
403	Forbidden	not your document, or free-tier 10-doc cap reached
429	Rate limited	check `Retry-After` header
413	Payload too large	rendered HTML > 512 KB
503	Service unavailable	retry later

状态码	含义	常见原因
400	请求错误	缺少 `markdown` 字段，slug格式无效
401	未授权	API密钥缺失或无效
403	禁止访问	文档不属于你，或免费账户已达到10个文档的上限
429	请求受限	查看 `Retry-After` 响应头
413	请求体过大	渲染后的HTML超过512 KB
503	服务不可用	稍后重试

Workflow

工作流程

Confirm the Markdown content/file to publish.
Check if this is a first-time publish or an update to a known
```
slug
```
(ask the user if unclear, or check prior conversation for a saved slug/URL).
Run the
```
curl
```
command with
```
$JOTBIRD_API_KEY
```
set.
Report back the returned
```
url
```
(and
```
slug
```
— worth saving if they'll want to update it later) plus expiry info if on a free account.
If the user wants a custom look, offer page settings (theme/visibility/password) as a follow-up, not by default.

确认要发布的Markdown内容/文件。
判断是首次发布还是更新已知
```
slug
```
的文档（如果不确定，询问用户，或查看之前的对话记录中保存的slug/URL）。
在
```
$JOTBIRD_API_KEY
```
已设置的情况下运行
```
curl
```
命令。
返回获取到的
```
url
```
（以及
```
slug
```
——如果用户后续需要更新文档，建议保存），如果是免费账户，还需告知有效期信息。
如果用户需要自定义外观，可以后续提供页面设置（主题/可见性/密码）选项，无需默认启用。