Notes

Endpoints for managing user highlights and annotations within the reader. All endpoints require the reader-token header.

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

---

List Notes

GET /api/v1/notes

Returns all notes for the current user on the current issue, ordered by creation date.

Request:

curl https://store.publica.la/api/v1/notes \
  -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/v1/notes

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

Request:

curl -X POST https://store.publica.la/api/v1/notes \
  -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 unique ID
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	string	General EPUB location

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

---

Get Note

GET /api/v1/notes/{id}

Returns a single note. Returns 403 if the note does not belong to the current user.

Response: 200 OK — the note object.

---

Update Note

PATCH /api/v1/notes/{id}

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

Request:

curl -X PATCH https://store.publica.la/api/v1/notes/1 \
  -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.

---

Delete Note

DELETE /api/v1/notes/{id}

Deletes a note. Returns 403 if the note does not belong to the current user.

Response: 200 OK — the deleted note object.

---

See Also

• Sessions - How to obtain the reader-token
• Search - Full-text search within issues