---
title: "Append by filename, creating the note on first touch"
method: POST
path: "/notes/by-filename/{filename}/append"
tags: ["notes"]
---

# Append by filename, creating the note on first touch

`POST /notes/by-filename/{filename}/append`

## Request

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

The stream primitive: the first call creates the note (append-only by default), every later call appends. 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

- `filename` string, required

## Headers

- `Idempotency-Key` string

## Request body

- NamedAppendBody
  - `text` string, required
  - `append_only` boolean: First touch only: lock the new note append-only.
  - `client_encrypted` boolean: First touch only: mark the new note client-encrypted (personal notes only).

## Response `200`

Appended to the existing note.

- NamedAppendResult
  - `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
  - `filename` string, required
  - `created` boolean, required
  - `client_encrypted` boolean, required

## Other responses

- `201`: Created the note with this text as its first line.
- `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`: `filename_conflict`: a team note or a trashed note holds this name; or `idempotency_key_conflict`.
- `413`: Over the per-note byte cap and no roll-over possible (`content_too_large`).
- `422`: Bad input, or the plan's note cap is reached (`cap_exceeded`).
- `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)