Create Reader Session

POST /api/v2/reader/{issue_id}/sessions

Creates a reader session for the mobile app. Returns content URLs needed to render the publication, varying by format (PDF, EPUB, Audiobook). This replaces the API v1 encrypted-token flow by using JWT authentication directly.

Request:

curl -X POST https://app.publica.la/api/v2/reader/440317/sessions \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Farfalla-Tenant-Id: 42" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Optional Headers:

Header	Description
reader-token	Previously assigned reader session token (for resuming downloaded content)

Optional Query Parameters:

Parameter	Type	Description
preview	boolean	Enable 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 sent as the reader-token header for all subsequent reader 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.

Error Responses

Code	Cause
403	User does not have access to this issue
403	Invalid or corrupted reader-token header