API docs

Authentication

Generate a personal token in /settings/api_tokens. Tokens are shown once on creation and stored as a one-way hash — copy to your password manager or shell profile immediately.

Authorization: Bearer mn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Missing or invalid token returns 401 unauthenticated. Token holder lacks API access (Free / Personal tier) returns 403 forbidden.

Team tokens

Workspaces on the Team tier mint tokens at /team/api_tokens (owner / admin only). Same bearer-token wire format, same endpoints, same error envelope — but every read and write resolves to the team's notes, folders, and storage pool rather than the actor's personal pool.

• GET /notes lists only the team's notes; the actor's personal notes never appear.
• POST /notes creates with team_id set; the row's user_id records the actor (who wrote it) for the audit log at /team/audit_events.
• /folders/*, /notes/bulk, and /notes/:id/move are scope-aware — a team token only sees the team's folders, never personal ones, and refuses cross-pool placement with 404 not_found.
• Storage, rate limits, and per-tier caps come from the team's subscription, not the actor's. Bulk is enabled on every team token — the team subscription is the entitlement.

A team's token-active cap is 30 active tokens at once. Revoking lives at the same panel — revoked tokens stay listed for audit but stop authenticating immediately.

Endpoints

Rate limits

• Pro: 600 reads / 60 writes / 300 appends per minute. 3 active tokens. 15 GB storage. Bulk endpoint enabled.
• Team: per-token rate limits track the Pro ladder. 30 active tokens per team. 50 GB workspace storage. Bulk endpoint enabled. 50,000 plain notes / 1,000 rich notes team-wide.

Throttled requests return 429 rate_limited with Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

The full per-tier breakdown — including per-note size caps, browser-surface throttles, pagination ceilings, token-expiry policy, and the export window — is on the Service limits page.

Error envelope

All error responses share the same shape:

{ "error": { "code": "validation_failed", "message": "Title can't be blank", "details": ["Title can't be blank"] } }

Stable error codes:

• unauthenticated — missing / invalid token (401)
• forbidden — token lacks API access or account unconfirmed (403)
• not_found — record absent or owned by another user (404)
• validation_failed — bad input or schema violation (422)
• cap_exceeded — note count over your tier's cap (422)
• storage_cap_exceeded — total bytes would exceed your storage cap (422)
• content_too_large — single note over per-format byte cap (413)
• content_type_mismatch — attempted rich-note write via API (422)
• rate_limited — throttle window exceeded (429)

Watchdog & webhooks

Two per-note knobs for turning a stream into a monitoring substrate. Both are configured via PATCH /notes/:id (or PATCH /notes/by-filename/:filename) and can also be set from the per-note Settings page in the web UI. Both require the note to be append-only; the underlying flag is set at create time ({"append_only": true}) or via the browser-side lock toggle.

Dead-man's-switch alerts

Set append_deadline_hours on an append-only note (1–720) and Fresh Jots emails you when no append has landed in that window. The next append clears the alert; if the script recovers and then fails again, you get a fresh email — no manual reset. Optional alert_email overrides the destination (defaults to your account email).

curl -X PATCH https://freshjots.com/api/v1/notes/by-filename/cron-jobs-prod \
  -H "Authorization: Bearer $FRESHJOTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"note":{"append_deadline_hours":2,"alert_email":"oncall@example.com"}}'

Outbound webhooks

Set webhook_url on an append-only note and every successful append POSTs the new content to your endpoint. The body is signed with HMAC-SHA256 in the X-FreshJots-Signature header (format: sha256=<hex>) using the webhook_secret you configure; a blank secret signs with the empty string, and the secret is never read back via the API.

Ten consecutive non-2xx responses (or transport failures) auto-disables the webhook so a dead receiver doesn't drain the job queue. Updating the URL re-arms it. webhook_failure_count and webhook_disabled_at are exposed on GET /notes/:id for monitoring.

curl -X PATCH https://freshjots.com/api/v1/notes/by-filename/payments-prod \
  -H "Authorization: Bearer $FRESHJOTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"note":{"webhook_url":"https://hooks.example.com/x","webhook_secret":"sk_..."}}'

Payload shape:

{
  "event": "note.appended",
  "delivered_at": "2026-05-02T12:34:56Z",
  "delivery_id": "<uuid>",
  "note": {
    "id": 123, "filename": "payments-prod", "title": "payments-prod",
    "byte_size": 4096, "last_appended_at": "2026-05-02T12:34:55Z"
  },
  "appended_text": "...new chunk (capped at 8 KB)...",
  "appended_bytes": 42,
  "appended_truncated": false
}

Live browser updates