---
title: "Read a note by filename"
method: GET
path: "/notes/by-filename/{filename}"
tags: ["notes"]
---

# Read a note by filename

`GET /notes/by-filename/{filename}`

## Request

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

Exact filename first, then exact title as a fallback; a title shared by several notes is 422. Takes the same `tail` and `since` as GET /notes/{id}.

## Path parameters

- `filename` string, required

## Query parameters

- `tail` integer
- `since` integer

## Response `200`

The note, whole or sliced.

- Note
  - `id` integer, required
  - `hashid` string, required
  - `filename` string, required
  - `title` string, nullable
  - `format` 'plain' | 'rich', required
  - `folder_id` integer, nullable
  - `pinned` boolean
  - `append_only` boolean, required
  - `client_encrypted` boolean, required
  - `append_deadline_hours` integer, nullable
  - `alert_email` string, nullable
  - `match_pattern` string, nullable
  - `match_alerted_at` string, date-time, nullable
  - `last_appended_at` string, date-time, nullable
  - `alerted_at` string, date-time, nullable
  - `webhook_url` string, nullable
  - `webhook_format` 'generic' | 'slack' | 'discord' | 'google_chat' | 'mattermost' | 'rocket_chat'
  - `webhook_failure_count` integer
  - `webhook_disabled_at` string, date-time, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `plain_body` string, required: The body, or the requested slice of it; for rich notes the plain-text projection.
  - `byte_size` integer, required: Full body size in bytes, even when sliced.
  - `slice` Slice: Present only when the body was cut by tail, since or a size cap.
    - `since` integer, nullable
    - `tail` integer, nullable
    - `bytes` integer, required
    - `truncated` boolean, 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`).
- `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)