Integrations
AI-powered reader features: translate, text-to-speech, dictionary, and text analysis (explain/expand/summarize). All endpoints require the reader-token header.
All integration endpoints support content encryption (two-layer validation). See Overview for details.
Translate
POST /api/v1/integrations/translate
Translates selected text. Also available at /api/v1/integrations/google-translate for backward compatibility.
Request:
curl -X POST https://store.publica.la/api/v1/integrations/translate \
-H "reader-token: {session_token}" \
-H "Content-Type: application/json" \
-d '{
"text": "El gato se sentó en la alfombra",
"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/v1/integrations/listen
Converts text to speech audio using AWS Polly. Also available at /api/v1/integrations/amazon-polly for backward compatibility.
Request:
curl -X POST https://store.publica.la/api/v1/integrations/listen \
-H "reader-token: {session_token}" \
-H "Content-Type: application/json" \
-d '{
"text": "The cat sat on the rug",
"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 (defaults to Penelope) |
Response: 200 OK
Content-Type: audio/mpeg
Body: MP3 audio stream
The reader splits long text into ~500 character chunks client-side (total limit: 10,000 characters). Each chunk is sent as a separate request. Results are cached server-side for 30 minutes.
Dictionary
POST /api/v1/integrations/dictionary
Looks up the definition of a word or short phrase.
Request:
curl -X POST https://store.publica.la/api/v1/integrations/dictionary \
-H "reader-token: {session_token}" \
-H "Content-Type: application/json" \
-d '{
"text": "ephemeral",
"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/v1/integrations/ai-integrations
Returns the available AI actions with localized labels.
Response: 200 OK
{
"explain": "Explain this text",
"expand": "Expand this text",
"summarize": "Summarize this text"
}
Perform AI Action
POST /api/v1/integrations/ai-integrations
Performs an AI action on selected text.
Request:
curl -X POST https://store.publica.la/api/v1/integrations/ai-integrations \
-H "reader-token: {session_token}" \
-H "Content-Type: application/json" \
-d '{
"action": "explain",
"text": "Quantum entanglement is a phenomenon where particles become interconnected...",
"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/v1/integrations/ai-integrations
Submits feedback on an AI response. Each response can only be rated once.
Request:
curl -X PUT https://store.publica.la/api/v1/integrations/ai-integrations \
-H "reader-token: {session_token}" \
-H "Content-Type: application/json" \
-d '{
"uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"score": 1
}'
| Parameter | Type | Required | Description |
|---|---|---|---|
uuid | string | Yes | UUID from the AI action response |
score | integer | Yes | Rating value |
Response: 200 OK with empty body.