JotSpot CLI

(Updated 27/05/26)

JotSpot exposes a small HTTP API that works well from curl, shell scripts, editors, and other terminal tools.

Rules

• Account required for new CLI posts
• POST /api/v1/jots/text is limited to 10 creates per hour per account
• Admin accounts are exempt from that create limit
• Legacy token-based edits still work for older token-owned jots

Auth

For account-owned CLI use, generate an API key in account settings and send it as a bearer token:

curl -H "Authorization: Bearer <api_key>" ...

You can also use an authenticated browser session cookie for manual local testing.

Create jots

Create a draft:

curl -H "Authorization: Bearer <api_key>" \
  -X POST https://jotspot.io/api/v1/jots/text \
  --data-binary @note.md

Create and publish immediately:

curl -H "Authorization: Bearer <api_key>" \
  -X POST "https://jotspot.io/api/v1/jots/text?visibility=public" \
  --data-binary @note.md

Create from stdin:

cat README.md | curl -H "Authorization: Bearer <api_key>" \
  -X POST https://jotspot.io/api/v1/jots/text \
  --data-binary @-

Preserve raw terminal output instead of rendering Markdown:

uptime | curl -H "Authorization: Bearer <api_key>" \
  -X POST "https://jotspot.io/api/v1/jots/text?render=text" \
  --data-binary @-

Return plain text instead of JSON:

curl -s -H "Authorization: Bearer <api_key>" \
  -X POST "https://jotspot.io/api/v1/jots/text?format=text" \
  -d "Hello world"

format=text changes the response format only. If you also want the jot page to default to plain text, add render=text.

Create response

Typical JSON response:

{
  "success": true,
  "jot_id": "x93dst55",
  "url": "https://jotspot.io/j/x93dst55",
  "raw_url": "https://jotspot.io/j/x93dst55.txt",
  "manage_url": "/manage/x93dst55/<token>",
  "visibility": "draft"
}

Field notes:

• jot_id: the jot slug
• url: normal jot page
• raw_url: raw markdown/text route
• manage_url: private handoff URL for legacy token-based ownership
• visibility: initial jot state

Edit jots

Edit an account-owned jot with bearer auth:

curl -H "Authorization: Bearer <api_key>" \
  -X PATCH https://jotspot.io/api/v1/jots/abc123/text \
  --data-binary @note.md

Edit a legacy token-owned jot with its owner token:

curl -X PATCH \
  "https://jotspot.io/api/v1/jots/abc123/text?token=<owner_token>" \
  --data-binary @note.md

Publish or unpublish while editing:

curl -X PATCH \
  "https://jotspot.io/api/v1/jots/abc123/text?token=<owner_token>&visibility=public" \
  --data-binary @note.md

curl -X PATCH \
  "https://jotspot.io/api/v1/jots/abc123/text?token=<owner_token>&visibility=draft" \
  --data-binary @note.md

Update title, description, and tags:

curl -X PATCH "https://jotspot.io/api/v1/jots/abc123/title?token=<owner_token>" -d "New title"
curl -X PATCH "https://jotspot.io/api/v1/jots/abc123/desc?token=<owner_token>" --data-binary "Short summary"
curl -X PATCH "https://jotspot.io/api/v1/jots/abc123/tags?token=<owner_token>" -d "cli,notes,python"

Read jots

Fetch raw body:

curl https://jotspot.io/j/abc123.txt
curl https://jotspot.io/j/abc123.md
curl -H "Accept: text/plain" https://jotspot.io/j/abc123

Fetch individual fields:

curl https://jotspot.io/api/v1/jots/abc123/title
curl https://jotspot.io/api/v1/jots/abc123/desc
curl https://jotspot.io/api/v1/jots/abc123/tags
curl https://jotspot.io/api/v1/jots/abc123/text

Ownership model

• New CLI creates are account-owned
• Existing token-owned jots can still be edited with their manage_url or ?token=...
• CLI text endpoints create drafts by default unless you pass visibility=public

Notes

• API key auth respects account bans
• Session-authenticated API requests also respect bans
• Banned API requests return the ban reason message
• Suspicious nested/proxy-style links may be blocked at render time even if they already exist in older posts