Notes

Endpoints for managing user highlights and annotations within the reader. All endpoints use single-tenant mode (require X-Farfalla-Tenant-Id) and require the reader-token header.

Notes are scoped to the current tenant, user, and issue (determined by the reader session).

---

List Notes

GET /api/v2/reader/notes

Returns all notes for the current user on the current issue.

Request:

curl https://app.publica.la/api/v2/reader/notes \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Farfalla-Tenant-Id: 42" \
  -H "reader-token: {session_token}" \
  -H "Accept: application/json"

Response: 200 OK

[
  {
    "id": 1,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "color": "yellow",
    "totalLength": 42,
    "totalText": "encrypted_highlighted_text",
    "annotationText": "User's note on this passage",
    "startPage": 5,
    "startPageStartOffset": 120,
    "startPageLength": 42,
    "endPage": 5,
    "endPageLength": 42,
    "epubLocationStartCfi": null,
    "epubLocationEndCfi": null,
    "epubChapter": null,
    "epubLocationStartChar": null,
    "epubLocation": null,
    "createdAt": "2026-04-02T10:30:00Z",
    "updatedAt": "2026-04-02T10:30:00Z"
  }
]

info

Response fields use camelCase (not snake_case). The totalText field is encrypted before being returned.

---

Create Note

POST /api/v2/reader/notes

Creates a new highlight or annotation. The request fields vary by content format (PDF or EPUB).

Request:

curl -X POST https://app.publica.la/api/v2/reader/notes \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Farfalla-Tenant-Id: 42" \
  -H "reader-token: {session_token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "color": "yellow",
    "totalLength": 42,
    "totalText": "The highlighted text passage",
    "annotationText": "My note on this",
    "startPage": 5,
    "startPageStartOffset": 120,
    "startPageLength": 42,
    "endPage": 5,
    "endPageLength": 42
  }'

Common Fields

Field	Type	Required	Description
uuid	string	Yes	Client-generated UUID
color	string	Yes	Highlight color name
totalLength	integer	Yes	Character count of highlighted text (min: 1)
totalText	string	Yes	The highlighted text (plaintext, encrypted on storage)
annotationText	string	No	User's annotation/comment

PDF-Specific Fields

Field	Type	Description
startPage	integer	Starting page number
startPageStartOffset	integer	Character offset on start page
startPageLength	integer	Highlight length on start page
endPage	integer	Ending page number
endPageLength	integer	Highlight length on end page

EPUB-Specific Fields

Field	Type	Description
epubLocationStartCfi	string	CFI start position
epubLocationEndCfi	string	CFI end position
epubChapter	string	Chapter identifier
epubLocationStartChar	string	Start character position
epubLocation	array	General EPUB location

Response: 201 Created — the created note with encrypted totalText.

---

Update Note

PUT /api/v2/reader/notes/{note_id}

Updates a note's color or annotation. The highlighted text and position are immutable.

Request:

curl -X PUT https://app.publica.la/api/v2/reader/notes/1 \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Farfalla-Tenant-Id: 42" \
  -H "reader-token: {session_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "color": "blue",
    "annotationText": "Updated annotation"
  }'

Field	Type	Required	Description
color	string	Yes	New highlight color
annotationText	string	No	New annotation (null to clear)

Response: 200 OK — the updated note.

Error Responses

Code	Cause
403	Note does not belong to the current user

---

Delete Note

DELETE /api/v2/reader/notes/{note_id}

Deletes a note. Returns the deleted note object with encrypted text.

Request:

curl -X DELETE https://app.publica.la/api/v2/reader/notes/1 \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Farfalla-Tenant-Id: 42" \
  -H "reader-token: {session_token}" \
  -H "Accept: application/json"

Response: 200 OK — the deleted note object.

Error Responses

Code	Cause
403	Note does not belong to the current user

---

See Also

• Reader - Reader sessions, settings, and content download
• Integrations - AI, translate, dictionary, text-to-speech