Skip to main content
  • Send to AI

Sessions

Reader session management. The POST /sessions endpoint is the entry point for the reader — it initializes the session and returns all the content URLs needed to render the publication.

Create Session​

POST /api/v1/sessions

Initializes a reader session and returns content URLs specific to the publication format (PDF, EPUB, or Audiobook).

Authentication: None (this endpoint creates the session token)

Request:

curl -X POST https://store.publica.la/api/v1/sessions \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "token": "encrypted_reader_session_token",
    "reader": "volpe",
    "volpe_host": "farfalla"
  }'
ParameterTypeRequiredDescription
tokenstringYesEncrypted reader session token
readerstringNoReader identifier (volpe)
volpe_hoststringNoHost context (farfalla or fenice)
previewbooleanNoEnable preview mode (restricted content)

Response: 200 OK

The response varies by content type:

EPUB Response​

{
  "token": "encrypted_session_token",
  "cover": "https://cdn.publica.la/issues/cover_thumb.jpg",
  "table_of_contents": [],
  "file_url": "https://signed-url.publica.la/epub/content.epub",
  "custom_preview": false,
  "spine": [{ "href": "chapter1.xhtml", "idref": "ch1" }],
  "total_words": 45000,
  "tracks": null,
  "files_urls": null,
  "files_info": null,
  "articles": null
}

PDF Response​

{
  "token": "encrypted_session_token",
  "cover": "https://cdn.publica.la/issues/cover_thumb.jpg",
  "table_of_contents": [{ "title": "Chapter 1", "page": 1 }],
  "files_urls": [
    "https://signed-url.publica.la/pdf/page_1.jpg",
    "https://signed-url.publica.la/pdf/page_2.jpg"
  ],
  "files_info": [{ "width": 800, "height": 1200 }],
  "articles": [],
  "custom_preview": false,
  "file_url": null,
  "spine": null,
  "total_words": null,
  "tracks": null
}

Audiobook Response​

{
  "token": "encrypted_session_token",
  "cover": "https://cdn.publica.la/issues/cover_thumb.jpg",
  "tracks": [
    {
      "title": "Track 1",
      "url": "https://cdn.publica.la/audio/track1.mp3",
      "duration": 360
    }
  ],
  "table_of_contents": [],
  "file_url": null,
  "files_urls": null,
  "files_info": null,
  "articles": null,
  "spine": null,
  "total_words": null,
  "custom_preview": false
}
info

The returned token must be used as the reader-token header for all subsequent authenticated requests (notes, search, integrations).

warning

In preview mode, content is restricted based on the tenant's preview percentage configuration. PDF returns only a subset of pages, EPUB may limit chapters.

Get Session​

GET /api/v1/sessions/{id}

Retrieves a reader session record.

Response: 200 OK — the ReaderSession object.

Delete Session​

DELETE /api/v1/sessions/{id}

Deletes a reader session.

Response: 200 OK — the deleted ReaderSession object.

See Also​

  • Notes - Highlights and annotations within the reader
  • Search - Full-text search within issues
  • Integrations - Translate, listen, dictionary, AI
X

Graph View