Integrations

AI-powered reader features: translate, text-to-speech, dictionary, and text analysis (explain/expand/summarize). All endpoints use single-tenant mode (require X-Farfalla-Tenant-Id) and require the reader-token header.

All integration endpoints support content encryption via two-layer validation. The encrypted payload is validated first against size limits, then the decrypted content is validated against business rules.

---

Translate

POST /api/v2/reader/integrations/translate

Translates selected text to a target language.

Request:

curl -X POST https://app.publica.la/api/v2/reader/integrations/translate \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Farfalla-Tenant-Id: 42" \
  -H "reader-token: {session_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "encrypted_text_content",
    "target_lang": "en"
  }'

Parameter	Type	Required	Description
text	string	Yes	Text to translate (max 1000 chars plaintext, 1900 encrypted)
target_lang	string	No	Target language (ISO 639 code)

Response: 200 OK

{
  "data": {
    "translations": [
      {
        "translatedText": "The cat sat on the rug",
        "detectedSourceLanguage": "es"
      }
    ]
  },
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

---

Text-to-Speech (Listen)

POST /api/v2/reader/integrations/listen

Converts text to speech audio using AWS Polly.

Request:

curl -X POST https://app.publica.la/api/v2/reader/integrations/listen \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Farfalla-Tenant-Id: 42" \
  -H "reader-token: {session_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "encrypted_text_content",
    "voiceId": "Penelope"
  }'

Parameter	Type	Required	Description
text	string	Yes	Text to synthesize (max 500 chars plaintext, 750 encrypted)
voiceId	string	No	AWS Polly voice ID

Response: 200 OK

Content-Type: audio/mpeg
Body: MP3 audio stream

info

The reader splits long text into ~500 character chunks client-side (total limit: 10,000 characters). Each chunk is sent as a separate request.

---

Dictionary

POST /api/v2/reader/integrations/dictionary

Looks up the definition of a word or short phrase using AI.

Request:

curl -X POST https://app.publica.la/api/v2/reader/integrations/dictionary \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Farfalla-Tenant-Id: 42" \
  -H "reader-token: {session_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "encrypted_text_content",
    "lang": "en"
  }'

Parameter	Type	Required	Description
text	string	Yes	Word or short phrase (max 5 words, 150 chars encrypted)
lang	string	Yes	Language code for the definition

Response: 200 OK — AI-generated definition.

---

AI Actions

List Available Actions

GET /api/v2/reader/integrations/ai-integrations

Returns the available AI actions with localized labels.

Request:

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

Response: 200 OK

{
  "explain": "Explain this text",
  "expand": "Expand this text",
  "summarize": "Summarize this text"
}

Perform AI Action

POST /api/v2/reader/integrations/ai-integrations

Performs an AI action on selected text.

Request:

curl -X POST https://app.publica.la/api/v2/reader/integrations/ai-integrations \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Farfalla-Tenant-Id: 42" \
  -H "reader-token: {session_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "explain",
    "text": "encrypted_text_content",
    "lang": "en"
  }'

Parameter	Type	Required	Description
action	string	Yes	explain, expand, or summarize
text	string	Yes	Text to process (10-4000 chars plaintext, 7500 encrypted)
lang	string	No	Response language (defaults to tenant language)

Response: 200 OK

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "text": "This passage describes quantum entanglement, a key concept in quantum mechanics where...",
  "language": "en"
}

Rate AI Response

PUT /api/v2/reader/integrations/ai-integrations

Submits feedback on an AI response. Each response can only be rated once.

Request:

curl -X PUT https://app.publica.la/api/v2/reader/integrations/ai-integrations \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Farfalla-Tenant-Id: 42" \
  -H "reader-token: {session_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "score": true
  }'

Parameter	Type	Required	Description
uuid	string	Yes	UUID from the AI action response
score	boolean	Yes	Positive (true) or negative (false) feedback

Response: 200 OK with empty body.

Error Responses

Code	Cause
422	UUID not found
422	Feedback does not belong to user
422	Response already rated

---

Content Encryption

All integration endpoints that accept text use two-layer validation for content security:

1. Layer 1 (encrypted): Validates the raw encrypted payload against size limits. Limits are set higher than the plaintext maximum to account for ~50% encryption overhead.
2. Layer 2 (decrypted): Decrypts the content using the reader session key, then validates against business rules (character count, word count, etc.).

Endpoint	Plaintext Limit	Encrypted Limit
AI	10-4000 chars	7500 chars
Translate	max 1000 chars	1900 chars
Listen	max 500 chars	750 chars
Dictionary	max 5 words	150 chars

---

See Also

• Reader - Reader sessions, settings, and content download
• Notes - Highlights and annotations within the reader