Polpo API v1 (Reader)

Polpo is the internal API used by the Volpe reader. It handles reader session initialization, user notes/highlights, in-reader search, and AI-powered integrations (translate, listen, dictionary, explain/expand/summarize).

Key characteristics:

• Reader session authentication via encrypted reader-token header
• Content encryption for text payloads (two-layer validation: encrypted then decrypted)
• Format-aware responses (PDF, EPUB, Audiobook)
• AI integrations for translate, text-to-speech, dictionary, and text analysis

Export all API v2 documentation (5 sections) as a single Markdown file.

---

Base URL

https://{store_final_domain}/api/v1/

All routes are prefixed with /api/v1/ and handled by the api middleware group.

---

Authentication

Most endpoints require a valid reader session token passed via the reader-token header.

reader-token: {encrypted_session_token}

The token is obtained by calling POST /api/v1/sessions (the only unauthenticated endpoint alongside GET /api/v1/issue-text-content/{id}).

The readerSessionMiddleware decrypts the token, loads the ReaderSession, sets the tenant context, and authenticates the user. Returns 403 if the token is missing, invalid, or expired.

---

Content Encryption

Integration endpoints (translate, listen, dictionary, AI) use two-layer validation:

1. Layer 1: Validates the encrypted payload size (larger limit due to encryption overhead)
2. Layer 2: Decrypts the content, then validates the plaintext size (smaller limit)

Encryption is enabled for manifest versions >= 2.0.0 using ContentEncryptionService with tenant_id, issue_id, and an IV seed. Older clients send plaintext and are handled transparently.

---

Endpoint Summary

Sessions

Method	Endpoint	Auth	Description
POST	/sessions	None	Initialize reader session, get content URLs
GET	/sessions/{id}	None	Retrieve session details
DELETE	/sessions/{id}	None	Delete session

Notes

Method	Endpoint	Auth	Description
GET	/notes	reader-token	List user's notes for current issue
POST	/notes	reader-token	Create a highlight/annotation
GET	/notes/{id}	reader-token	Get a single note
PATCH	/notes/{id}	reader-token	Update note color or annotation
DELETE	/notes/{id}	reader-token	Delete a note

Search

Method	Endpoint	Auth	Description
GET	/issue-text-content?search=...	reader-token	Full-text search within issue
GET	/issue-text-content/{id}?issue_id=...	None	Get all indexed text content

Integrations

Method	Endpoint	Auth	Description
POST	/integrations/translate	reader-token	Translate selected text
POST	/integrations/listen	reader-token	Text-to-speech
POST	/integrations/dictionary	reader-token	Define a word or phrase
GET	/integrations/ai-integrations	reader-token	List available AI actions
POST	/integrations/ai-integrations	reader-token	Perform AI action (explain/expand/summarize)
PUT	/integrations/ai-integrations	reader-token	Rate AI response

---

Next Steps

• Sessions - Reader session initialization and content URL generation
• Notes - Highlights and annotations
• Search - Full-text search within issues
• Integrations - Translate, listen, dictionary, and AI features