---
title: "Append to a plain note"
method: POST
path: "/notes/{id}/append"
tags: ["notes"]
---

# Append to a plain note

`POST /notes/{id}/append`

## Request

- Base URL: `https://freshjots.com/api/v1`
- URL: `https://freshjots.com/api/v1/notes/{id}/append`
- Auth: HTTP bearer

Atomic: the text is added as a new entry (top or bottom per the note's direction). At the per-note byte cap an append-only note rolls over: the full note is renamed `<filename>.<n>`, a successor takes its name and settings, and `rolled_over_from` names the closed segment; an append addressed to a closed segment lands on the live note. Only a text that would not fit even an empty note, or a roll-over blocked by the note or storage cap, is refused with 413 `content_too_large`.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- AppendBody
  - `text` string, required: The entry to add; may contain newlines.

## Response `200`

The append landed.

- AppendResult
  - `id` integer, required: The note the text landed on (the successor after a roll-over).
  - `append_only` boolean, required
  - `byte_size` integer, required
  - `bytes_remaining` integer, required
  - `storage_used` integer, required
  - `storage_cap` integer, nullable
  - `updated_at` string, date-time, required
  - `rolled_over_from` object: Present when this append rolled the stream over or was redirected from a closed segment.
    - `id` integer, required
    - `filename` string, required

## Other responses

- `401`: Missing, invalid, revoked or expired bearer token (`unauthenticated`).
- `403`: The token's scope or plan does not allow this (`forbidden`).
- `404`: No such record in this token's scope (`not_found`).
- `409`: The Idempotency-Key was already used with a different body (`idempotency_key_conflict`).
- `413`: Over the per-note byte cap and no roll-over possible (`content_too_large`).
- `422`: Bad input (`validation_failed`, `note_locked`, `content_type_mismatch`, `storage_cap_exceeded`, `encrypted_team_unsupported`).
- `429`: Throttled (`rate_limited`); honour Retry-After.
- `503`: Backend temporarily unreachable; retry with backoff (`service_unavailable`).

---

[API](https://skmtc.dev/freshjots/apis/fresh-jots-api.md) · [All operations](https://skmtc.dev/freshjots/apis/fresh-jots-api/llms.txt) · [OpenAPI document](https://skmtc.dev/freshjots/apis/fresh-jots-api/revisions/2708284fa25a?raw)