# 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:

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

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

## Create jots

Create a draft:

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

Create and publish immediately:

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

Create from stdin:

```bash
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:

```bash
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:

```bash
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:

```json
{
  "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:

```bash
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:

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

Publish or unpublish while editing:

```bash
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:

```bash
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:

```bash
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:

```bash
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