Reading
Generated reading operations.
GET/v1/reading/continueList the viewer's unfinished reading publicationsread
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the read scope, or a signed-in session
- OpenAPI operation ID
get_reading_continue
Parameters
| Name | In | Type | Description |
|---|---|---|---|
libraryId | query | string | |
cursor | query | string | |
limit | query | integer | ""1–100 |
Responses
200Successapplication/json
{
"items": [
{
"conversion": {
"converter": "libmobi:85dcfe803fc2a21020ddcf15c3eb66b93d388add",
"inputSHA256": "string",
"options": "portico-epub-v1;unencrypted-only;no-replica;default-kf8",
"originalFormat": "mobi",
"originalRevision": "r12",
"originalSize": 1,
"originalSourceId": "id_8h2k4q",
"outputSHA256": "string",
"outputSize": 1,
"revision": "r12",
"workerSHA256": "string"
},
"item": {
"author": {
"source": "owner",
"value": "string"
},
"coverUrl": "https://example.com/…",
"format": "epub",
"id": "id_8h2k4q",
"inventoryAvailable": true,
"libraryId": "id_8h2k4q",
"publicationType": {
"source": "owner",
"value": "book"
},
"readingMark": {
"itemId": "id_8h2k4q",
"read": true,
"revision": 0
},
"series": {
"id": "id_8h2k4q",
"name": "Fargo",
"number": 0,
"source": "owner"
},
"sourceId": "id_8h2k4q",
"title": "Fargo"
},
"progress": {
"location": {
"cfi": "string",
"format": "epub",
"pageIndex": 0,
"progression": 0,
"section": "string"
},
"observedAt": 0,
"revision": 0,
"sourceId": "id_8h2k4q",
"sourceRevision": "r12",
"stale": true
}
}
],
"nextCursor": "eyJvIjoyMH0"
}itemsarray of objectrequired
conversionobject
- converterstringrequiredone of "libmobi:85dcfe803fc2a21020ddcf15c3eb66b93d388add"
- inputSHA256stringrequiredlength 64–64pattern ^[a-f0-9]{64}$
- optionsstringrequiredone of "portico-epub-v1;unencrypted-only;no-replica;default-kf8"
- originalFormatstringrequiredone of "mobi", "azw3"
- originalRevisionstringrequiredlength 64–64pattern ^[a-f0-9]{64}$
- originalSizeintegerrequired1–67108864
- originalSourceIdstringrequiredlength 1–256
- outputSHA256stringrequiredlength 64–64pattern ^[a-f0-9]{64}$
- outputSizeintegerrequired1–134217728
- revisionstringrequiredlength 64–64pattern ^[a-f0-9]{64}$
- workerSHA256stringrequiredlength 64–64pattern ^[a-f0-9]{64}$
itemobjectrequired
authorobject
- sourcestringrequiredone of "owner", "file-metadata", "file-name", "folder"
- valuestringrequiredlength 1–4096
- coverUrlstring
- formatstringrequiredone of "epub", "pdf", "cbz", "mobi", "azw3", "cb7", "cbr"
- idstringrequired
- inventoryAvailablebooleanrequired
- libraryIdstringrequired
publicationTypeobject
- sourcestringrequiredone of "owner", "file-metadata"
- valuestringrequiredone of "book", "magazine", "newspaper"
readingMarkobject
- itemIdstringrequiredlength 1–64pattern ^[A-Za-z0-9_-]{1,64}$
- readbooleanrequired
- revisionintegerrequired≥ 0
seriesobject
- idstringrequiredlength 1–∞
- namestringrequiredlength 1–4096
- numbernumber≥ 0
- sourcestringrequiredone of "owner", "file-metadata", "file-name", "folder"
- sourceIdstringrequired
- titlestringrequired
progressobjectrequired
locationobjectrequired
- cfistring
- formatstringrequiredone of "epub", "pdf", "cbz", "cb7", "cbr"
- pageIndexinteger
- progressionnumberrequired
- sectionstring
- observedAtintegerrequired
- revisionintegerrequired
- sourceIdstringrequired
- sourceRevisionstringrequired
- stalebooleanrequired
- nextCursorstring
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternaldatabase_busy
Example request
curl -X GET "http://127.0.0.1:32500/v1/reading/continue" \
-H "Authorization: Bearer $PORTICO_API_KEY"GET/v1/reading/discoverRead the server-composed Discover rowsread
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the read scope, or a signed-in session
- OpenAPI operation ID
get_reading_discover
Parameters
| Name | In | Type | Description |
|---|---|---|---|
libraryId | query | string | |
limit | query | integer1–100 | |
seriesLimit | query | string | |
shortReadsLimit | query | string | |
newIssuesLimit | query | string | |
newspaperLimit | query | string | |
row | query | string | |
cursor | query | string |
Responses
200Successapplication/json
{
"rows": [
{
"items": [
{
"author": {},
"coverUrl": "https://example.com/…",
"format": "epub",
"id": "id_8h2k4q",
"inventoryAvailable": true,
"libraryId": "id_8h2k4q",
"publicationType": {},
"readingMark": {},
"series": {},
"sourceId": "id_8h2k4q",
"title": "Fargo"
}
],
"key": "string",
"newIssues": [
{
"issueDate": "string",
"item": {}
}
],
"newspaper": {
"id": "id_8h2k4q",
"issueCount": 1,
"latest": {
"issueDate": "string",
"item": {}
},
"name": "Fargo"
},
"nextCursor": "eyJvIjoyMH0",
"series": [
{
"count": 1,
"id": "id_8h2k4q",
"libraryId": "id_8h2k4q",
"name": "Fargo",
"preview": [],
"readCount": 0
}
],
"shortReads": [
{
"estimatedSeconds": 1,
"item": {},
"wordCount": 1
}
]
}
]
}rowsarray of objectrequired
itemsarray of objectrequired
authorobject
- sourcestringrequiredone of "owner", "file-metadata", "file-name", "folder"
- valuestringrequiredlength 1–4096
- coverUrlstring
- formatstringrequiredone of "epub", "pdf", "cbz", "mobi", "azw3", "cb7", "cbr"
- idstringrequired
- inventoryAvailablebooleanrequired
- libraryIdstringrequired
publicationTypeobject
- sourcestringrequiredone of "owner", "file-metadata"
- valuestringrequiredone of "book", "magazine", "newspaper"
readingMarkobject
- itemIdstringrequiredlength 1–64pattern ^[A-Za-z0-9_-]{1,64}$
- readbooleanrequired
- revisionintegerrequired≥ 0
seriesobject
- idstringrequiredlength 1–∞
- namestringrequiredlength 1–4096
- numbernumber≥ 0
- sourcestringrequiredone of "owner", "file-metadata", "file-name", "folder"
- sourceIdstringrequired
- titlestringrequired
- keystringrequired
newIssuesarray of object
- issueDatestringrequiredlength 7–10pattern ^[0-9]{4}-[0-9]{2}(-[0-9]{2})?$
itemobjectrequired
authorobject
- sourcestringrequiredone of "owner", "file-metadata", "file-name", "folder"
- valuestringrequiredlength 1–4096
- coverUrlstring
- formatstringrequiredone of "epub", "pdf", "cbz", "mobi", "azw3", "cb7", "cbr"
- idstringrequired
- inventoryAvailablebooleanrequired
- libraryIdstringrequired
publicationTypeobject
- sourcestringrequiredone of "owner", "file-metadata"
- valuestringrequiredone of "book", "magazine", "newspaper"
readingMarkobject
- itemIdstringrequiredlength 1–64pattern ^[A-Za-z0-9_-]{1,64}$
- readbooleanrequired
- revisionintegerrequired≥ 0
seriesobject
- idstringrequiredlength 1–∞
- namestringrequiredlength 1–4096
- numbernumber≥ 0
- sourcestringrequiredone of "owner", "file-metadata", "file-name", "folder"
- sourceIdstringrequired
- titlestringrequired
newspaperobject
- idstringrequiredpattern ^[A-Za-z0-9_-]{43}$
- issueCountintegerrequired≥ 1
latestobjectrequired
- issueDatestringrequiredlength 7–10pattern ^[0-9]{4}-[0-9]{2}(-[0-9]{2})?$
itemobjectrequired
authorobject
- sourcestringrequiredone of "owner", "file-metadata", "file-name", "folder"
- valuestringrequiredlength 1–4096
- coverUrlstring
- formatstringrequiredone of "epub", "pdf", "cbz", "mobi", "azw3", "cb7", "cbr"
- idstringrequired
- inventoryAvailablebooleanrequired
- libraryIdstringrequired
publicationTypeobject
- sourcestringrequiredone of "owner", "file-metadata"
- valuestringrequiredone of "book", "magazine", "newspaper"
readingMarkobject
- itemIdstringrequiredlength 1–64pattern ^[A-Za-z0-9_-]{1,64}$
- readbooleanrequired
- revisionintegerrequired≥ 0
seriesobject
- idstringrequiredlength 1–∞
- namestringrequiredlength 1–4096
- numbernumber≥ 0
- sourcestringrequiredone of "owner", "file-metadata", "file-name", "folder"
- sourceIdstringrequired
- titlestringrequired
- namestringrequiredlength 1–4096
- nextCursorstring
seriesarray of object
- countintegerrequired≥ 1
- idstringrequiredpattern ^[A-Za-z0-9_-]{43}$
- libraryIdstringrequiredlength 1–∞
- namestringrequiredlength 1–4096
previewarray of objectrequired1–3 items
authorobject
- sourcestringrequiredone of "owner", "file-metadata", "file-name", "folder"
- valuestringrequiredlength 1–4096
- coverUrlstring
- formatstringrequiredone of "epub", "pdf", "cbz", "mobi", "azw3", "cb7", "cbr"
- idstringrequired
- inventoryAvailablebooleanrequired
- libraryIdstringrequired
publicationTypeobject
- sourcestringrequiredone of "owner", "file-metadata"
- valuestringrequiredone of "book", "magazine", "newspaper"
readingMarkobject
- itemIdstringrequiredlength 1–64pattern ^[A-Za-z0-9_-]{1,64}$
- readbooleanrequired
- revisionintegerrequired≥ 0
seriesobject
- idstringrequiredlength 1–∞
- namestringrequiredlength 1–4096
- numbernumber≥ 0
- sourcestringrequiredone of "owner", "file-metadata", "file-name", "folder"
- sourceIdstringrequired
- titlestringrequired
- readCountintegerrequired≥ 0
shortReadsarray of object
- estimatedSecondsintegerrequired1–10800
itemobjectrequired
authorobject
- sourcestringrequiredone of "owner", "file-metadata", "file-name", "folder"
- valuestringrequiredlength 1–4096
- coverUrlstring
- formatstringrequiredone of "epub", "pdf", "cbz", "mobi", "azw3", "cb7", "cbr"
- idstringrequired
- inventoryAvailablebooleanrequired
- libraryIdstringrequired
publicationTypeobject
- sourcestringrequiredone of "owner", "file-metadata"
- valuestringrequiredone of "book", "magazine", "newspaper"
readingMarkobject
- itemIdstringrequiredlength 1–64pattern ^[A-Za-z0-9_-]{1,64}$
- readbooleanrequired
- revisionintegerrequired≥ 0
seriesobject
- idstringrequiredlength 1–∞
- namestringrequiredlength 1–4096
- numbernumber≥ 0
- sourcestringrequiredone of "owner", "file-metadata", "file-name", "folder"
- sourceIdstringrequired
- titlestringrequired
- wordCountintegerrequired1–44999
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternaldatabase_busy
Example request
curl -X GET "http://127.0.0.1:32500/v1/reading/discover" \
-H "Authorization: Bearer $PORTICO_API_KEY"GET/v1/reading/itemsList visible reading publicationsread
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the read scope, or a signed-in session
- OpenAPI operation ID
get_reading_items
Parameters
| Name | In | Type | Description |
|---|---|---|---|
libraryId | query | string | |
cursor | query | string | |
limit | query | integer | ""1–100 |
Responses
200Successapplication/json
{
"items": [
{
"author": {
"source": "owner",
"value": "string"
},
"coverUrl": "https://example.com/…",
"format": "epub",
"id": "id_8h2k4q",
"inventoryAvailable": true,
"libraryId": "id_8h2k4q",
"publicationType": {
"source": "owner",
"value": "book"
},
"readingMark": {
"itemId": "id_8h2k4q",
"read": true,
"revision": 0
},
"series": {
"id": "id_8h2k4q",
"name": "Fargo",
"number": 0,
"source": "owner"
},
"sourceId": "id_8h2k4q",
"title": "Fargo"
}
],
"nextCursor": "eyJvIjoyMH0"
}itemsarray of objectrequired
authorobject
- sourcestringrequiredone of "owner", "file-metadata", "file-name", "folder"
- valuestringrequiredlength 1–4096
- coverUrlstring
- formatstringrequiredone of "epub", "pdf", "cbz", "mobi", "azw3", "cb7", "cbr"
- idstringrequired
- inventoryAvailablebooleanrequired
- libraryIdstringrequired
publicationTypeobject
- sourcestringrequiredone of "owner", "file-metadata"
- valuestringrequiredone of "book", "magazine", "newspaper"
readingMarkobject
- itemIdstringrequiredlength 1–64pattern ^[A-Za-z0-9_-]{1,64}$
- readbooleanrequired
- revisionintegerrequired≥ 0
seriesobject
- idstringrequiredlength 1–∞
- namestringrequiredlength 1–4096
- numbernumber≥ 0
- sourcestringrequiredone of "owner", "file-metadata", "file-name", "folder"
- sourceIdstringrequired
- titlestringrequired
- nextCursorstring
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternaldatabase_busy
Example request
curl -X GET "http://127.0.0.1:32500/v1/reading/items" \
-H "Authorization: Bearer $PORTICO_API_KEY"POST/v1/reading/offline/progressReconcile an observed location from this viewer's signed offline publicationplayback
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the playback scope, or a signed-in session
- OpenAPI operation ID
post_reading_offline_progress- Max body
- 32 KiB
Request body application/json · required
{
"expectedRevision": 0,
"location": {
"cfi": "string",
"format": "epub",
"progression": 0,
"section": "string"
},
"observationReceipt": {
"algorithm": "string",
"claims": {
"artifact": {
"bytes": 0,
"sha256": "string"
},
"expiresAt": "2026-10-18T19:30:00Z",
"issuedAt": "2026-10-18T19:30:00Z",
"itemId": "id_8h2k4q",
"keyId": "id_8h2k4q",
"kind": "string",
"preparationId": "id_8h2k4q",
"publication": {
"documentSha256": "string",
"format": "epub",
"revision": "r12",
"sourceId": "id_8h2k4q"
},
"quality": "string",
"qualityLabel": "string",
"receiptId": "id_8h2k4q",
"version": "string",
"viewer": {
"accountId": "id_8h2k4q",
"authority": "string",
"profileId": "id_8h2k4q",
"serverId": "id_8h2k4q"
}
},
"keyId": "id_8h2k4q",
"payload": "string",
"receiptId": "id_8h2k4q",
"revision": 0,
"signature": "string"
},
"observedAt": 1,
"receipt": {
"algorithm": "string",
"claims": {
"artifact": {
"bytes": 0,
"sha256": "string"
},
"expiresAt": "2026-10-18T19:30:00Z",
"issuedAt": "2026-10-18T19:30:00Z",
"itemId": "id_8h2k4q",
"keyId": "id_8h2k4q",
"kind": "string",
"preparationId": "id_8h2k4q",
"publication": {
"documentSha256": "string",
"format": "epub",
"revision": "r12",
"sourceId": "id_8h2k4q"
},
"quality": "string",
"qualityLabel": "string",
"receiptId": "id_8h2k4q",
"version": "string",
"viewer": {
"accountId": "id_8h2k4q",
"authority": "string",
"profileId": "id_8h2k4q",
"serverId": "id_8h2k4q"
}
},
"keyId": "id_8h2k4q",
"payload": "string",
"receiptId": "id_8h2k4q",
"revision": 0,
"signature": "string"
},
"startedAt": 1
}- expectedRevisionintegerrequired≥ 0
locationobjectrequired
- cfistringrequiredlength 10–4096pattern ^epubcfi\(/.*\)$
- format"epub"required
- progressionnumberrequired0–1
- sectionstringlength 0–1024
observationReceiptobject
- algorithmstringrequired
claimsobjectrequired
artifactobjectrequired
- bytesintegerrequired
- sha256stringrequired
- expiresAtstringrequired
- issuedAtstringrequired
- itemIdstringrequired
- keyIdstringrequired
- kindstringrequired
- preparationIdstringrequired
publicationobject
- documentSha256stringrequiredpattern ^[0-9a-f]{64}$
- formatstringrequiredone of "epub", "pdf", "cbz", "cb7", "cbr"
- revisionstringrequiredpattern ^[0-9a-f]{64}$
- sourceIdstringrequiredlength 1–128pattern ^[A-Za-z0-9_-]+$
- qualitystringrequired
- qualityLabelstringrequired
- receiptIdstringrequired
- versionstringrequired
viewerobjectrequired
- accountIdstringrequired
- authoritystringrequired
- profileIdstringrequired
- serverIdstringrequired
- keyIdstringrequired
- payloadstringrequired
- receiptIdstringrequired
- revisionintegerrequired
- signaturestringrequired
- observedAtintegerrequired≥ 1
receiptobjectrequired
- algorithmstringrequired
claimsobjectrequired
artifactobjectrequired
- bytesintegerrequired
- sha256stringrequired
- expiresAtstringrequired
- issuedAtstringrequired
- itemIdstringrequired
- keyIdstringrequired
- kindstringrequired
- preparationIdstringrequired
publicationobject
- documentSha256stringrequiredpattern ^[0-9a-f]{64}$
- formatstringrequiredone of "epub", "pdf", "cbz", "cb7", "cbr"
- revisionstringrequiredpattern ^[0-9a-f]{64}$
- sourceIdstringrequiredlength 1–128pattern ^[A-Za-z0-9_-]+$
- qualitystringrequired
- qualityLabelstringrequired
- receiptIdstringrequired
- versionstringrequired
viewerobjectrequired
- accountIdstringrequired
- authoritystringrequired
- profileIdstringrequired
- serverIdstringrequired
- keyIdstringrequired
- payloadstringrequired
- receiptIdstringrequired
- revisionintegerrequired
- signaturestringrequired
- startedAtintegerrequired≥ 1
Responses
200Successapplication/json
{
"outcome": "applied",
"progress": {
"location": {
"cfi": "string",
"format": "epub",
"progression": 0,
"section": "string"
},
"observedAt": 1,
"revision": 0,
"sourceId": "id_8h2k4q",
"sourceRevision": "r12",
"stale": true
},
"saved": true
}- outcomestringrequiredone of "applied", "history_paused", "stale_observation", "superseded_online"
progressobject | any | nullrequired
locationobjectrequired
- cfistringrequiredlength 10–4096pattern ^epubcfi\(/.*\)$
- format"epub"required
- progressionnumberrequired0–1
- sectionstringlength 0–1024
- observedAtintegerrequired≥ 1
- revisionintegerrequired≥ 0
- sourceIdstringrequiredlength 1–128pattern ^[A-Za-z0-9_-]+$
- sourceRevisionstringrequiredpattern ^[0-9a-f]{64}$
- stalebooleanrequired
- savedbooleanrequired
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternaldatabase_busywriter_capacity
Example request
curl -X POST "http://127.0.0.1:32500/v1/reading/offline/progress" \
-H "Authorization: Bearer $PORTICO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"expectedRevision": 0,
"location": {
"cfi": "string",
"format": "epub",
"progression": 0,
"section": "string"
},
"observationReceipt": {
"algorithm": "string",
"claims": {
"artifact": {
"bytes": 0,
"sha256": "string"
},
"expiresAt": "2026-10-18T19:30:00Z",
"issuedAt": "2026-10-18T19:30:00Z",
"itemId": "id_8h2k4q",
"keyId": "id_8h2k4q",
"kind": "string",
"preparationId": "id_8h2k4q",
"publication": {
"documentSha256": "string",
"format": "epub",
"revision": "r12",
"sourceId": "id_8h2k4q"
},
"quality": "string",
"qualityLabel": "string",
"receiptId": "id_8h2k4q",
"version": "string",
"viewer": {
"accountId": "id_8h2k4q",
"authority": "string",
"profileId": "id_8h2k4q",
"serverId": "id_8h2k4q"
}
},
"keyId": "id_8h2k4q",
"payload": "string",
"receiptId": "id_8h2k4q",
"revision": 0,
"signature": "string"
},
"observedAt": 1,
"receipt": {
"algorithm": "string",
"claims": {
"artifact": {
"bytes": 0,
"sha256": "string"
},
"expiresAt": "2026-10-18T19:30:00Z",
"issuedAt": "2026-10-18T19:30:00Z",
"itemId": "id_8h2k4q",
"keyId": "id_8h2k4q",
"kind": "string",
"preparationId": "id_8h2k4q",
"publication": {
"documentSha256": "string",
"format": "epub",
"revision": "r12",
"sourceId": "id_8h2k4q"
},
"quality": "string",
"qualityLabel": "string",
"receiptId": "id_8h2k4q",
"version": "string",
"viewer": {
"accountId": "id_8h2k4q",
"authority": "string",
"profileId": "id_8h2k4q",
"serverId": "id_8h2k4q"
}
},
"keyId": "id_8h2k4q",
"payload": "string",
"receiptId": "id_8h2k4q",
"revision": 0,
"signature": "string"
},
"startedAt": 1
}'POST/v1/reading/offline/progress/readRead this viewer's saved positions for signed offline publicationsplayback
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the playback scope, or a signed-in session
- OpenAPI operation ID
post_reading_offline_progress_read- Max body
- 512 KiB
Request body application/json · required
{
"receipts": [
{
"algorithm": "string",
"claims": {
"artifact": {
"bytes": 0,
"sha256": "string"
},
"expiresAt": "2026-10-18T19:30:00Z",
"issuedAt": "2026-10-18T19:30:00Z",
"itemId": "id_8h2k4q",
"keyId": "id_8h2k4q",
"kind": "string",
"preparationId": "id_8h2k4q",
"publication": {
"documentSha256": "string",
"format": "epub",
"revision": "r12",
"sourceId": "id_8h2k4q"
},
"quality": "string",
"qualityLabel": "string",
"receiptId": "id_8h2k4q",
"version": "string",
"viewer": {
"accountId": "id_8h2k4q",
"authority": "string",
"profileId": "id_8h2k4q",
"serverId": "id_8h2k4q"
}
},
"keyId": "id_8h2k4q",
"payload": "string",
"receiptId": "id_8h2k4q",
"revision": 0,
"signature": "string"
}
]
}receiptsarray of objectrequired1–50 items
- algorithmstringrequired
claimsobjectrequired
artifactobjectrequired
- bytesintegerrequired
- sha256stringrequired
- expiresAtstringrequired
- issuedAtstringrequired
- itemIdstringrequired
- keyIdstringrequired
- kindstringrequired
- preparationIdstringrequired
publicationobject
- documentSha256stringrequiredpattern ^[0-9a-f]{64}$
- formatstringrequiredone of "epub", "pdf", "cbz", "cb7", "cbr"
- revisionstringrequiredpattern ^[0-9a-f]{64}$
- sourceIdstringrequiredlength 1–128pattern ^[A-Za-z0-9_-]+$
- qualitystringrequired
- qualityLabelstringrequired
- receiptIdstringrequired
- versionstringrequired
viewerobjectrequired
- accountIdstringrequired
- authoritystringrequired
- profileIdstringrequired
- serverIdstringrequired
- keyIdstringrequired
- payloadstringrequired
- receiptIdstringrequired
- revisionintegerrequired
- signaturestringrequired
Responses
200Successapplication/json
{
"results": [
{
"itemId": "id_8h2k4q",
"outcome": "current",
"progress": {
"location": {
"cfi": "string",
"format": "epub",
"progression": 0,
"section": "string"
},
"observedAt": 1,
"revision": 0,
"sourceId": "id_8h2k4q",
"sourceRevision": "r12",
"stale": true
},
"receiptId": "id_8h2k4q",
"sourceId": "id_8h2k4q",
"sourceRevision": "r12"
}
]
}resultsarray of objectrequired0–50 items
- itemIdstringrequiredlength 1–128
- outcome"current"required
progressobject | any | nullrequired
locationobjectrequired
- cfistringrequiredlength 10–4096pattern ^epubcfi\(/.*\)$
- format"epub"required
- progressionnumberrequired0–1
- sectionstringlength 0–1024
- observedAtintegerrequired≥ 1
- revisionintegerrequired≥ 0
- sourceIdstringrequiredlength 1–128pattern ^[A-Za-z0-9_-]+$
- sourceRevisionstringrequiredpattern ^[0-9a-f]{64}$
- stalebooleanrequired
- receiptIdstringrequiredlength 1–128
- sourceIdstringrequiredlength 1–128pattern ^[A-Za-z0-9_-]+$
- sourceRevisionstringrequiredpattern ^[0-9a-f]{64}$
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternaldatabase_busywriter_capacity
Example request
curl -X POST "http://127.0.0.1:32500/v1/reading/offline/progress/read" \
-H "Authorization: Bearer $PORTICO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"receipts": [
{
"algorithm": "string",
"claims": {
"artifact": {
"bytes": 0,
"sha256": "string"
},
"expiresAt": "2026-10-18T19:30:00Z",
"issuedAt": "2026-10-18T19:30:00Z",
"itemId": "id_8h2k4q",
"keyId": "id_8h2k4q",
"kind": "string",
"preparationId": "id_8h2k4q",
"publication": {
"documentSha256": "string",
"format": "epub",
"revision": "r12",
"sourceId": "id_8h2k4q"
},
"quality": "string",
"qualityLabel": "string",
"receiptId": "id_8h2k4q",
"version": "string",
"viewer": {
"accountId": "id_8h2k4q",
"authority": "string",
"profileId": "id_8h2k4q",
"serverId": "id_8h2k4q"
}
},
"keyId": "id_8h2k4q",
"payload": "string",
"receiptId": "id_8h2k4q",
"revision": 0,
"signature": "string"
}
]
}'DELETE/v1/reading/saved-groups/{referenceId}Remove only this profile's exact private Saved reference without resolving its targetplayback
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the playback scope, or a signed-in session
- OpenAPI operation ID
delete_reading_saved_group_reference- Max body
- 4 KiB
Parameters
| Name | In | Type | Description |
|---|---|---|---|
referenceIdrequired | path | string | |
Idempotency-Key | header | string | |
Portico-Mutation-Root | header | string |
Request body application/json · required
{
"expectedRevision": 1,
"operationId": "id_8h2k4q"
}- expectedRevisionintegerrequired≥ 1
- operationIdstringrequiredlength 1–128pattern ^[A-Za-z0-9_-]{1,128}$
Responses
200Successapplication/json
{
"operationId": "id_8h2k4q",
"referenceId": "id_8h2k4q",
"removed": true,
"revision": 1,
"serverId": "id_8h2k4q"
}- operationIdstringrequiredlength 1–128
- referenceIdstringrequiredlength 1–128
- removedbooleanrequiredone of true
- revisionintegerrequired≥ 1
- serverIdstringrequiredlength 1–128
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_mismatchstale_continuationinternalrate_limitedpersonal_state_conflictidempotency_key_reusedoperation_expiredidempotency_conflictreceipt_expiredinvalid_mutation_keydatabase_busywriter_capacity
Example request
curl -X DELETE "http://127.0.0.1:32500/v1/reading/saved-groups/{referenceId}" \
-H "Authorization: Bearer $PORTICO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":1,"operationId":"id_8h2k4q"}'GET/v1/reading/searchSearch the persisted Reading index across the viewer's ready librariesread
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the read scope, or a signed-in session
- OpenAPI operation ID
get_reading_search
Parameters
| Name | In | Type | Description |
|---|---|---|---|
q | query | string | |
cursor | query | string | |
limit | query | integer | ""1–50 | |
libraryId | query | string |
Responses
200Successapplication/json
{
"anchor": {
"matchUnit": "utf16",
"normalization": "xhtml-body-blockspace-fields-v1",
"offsetUnit": "utf16"
},
"hits": [
{
"coverUrl": "https://example.com/…",
"excerpt": "string",
"itemId": "id_8h2k4q",
"libraryId": "id_8h2k4q",
"matchLength": 1,
"matchStart": 0,
"sectionIndex": 0,
"sectionPath": "string",
"sourceId": "id_8h2k4q",
"sourceRevision": "r12",
"title": "Fargo",
"utf16Offset": 0
}
],
"indexRevision": 0,
"indexedOnly": true,
"next": "string"
}anchorobjectrequired
- matchUnitstringrequiredone of "utf16"
- normalizationstringrequiredone of "xhtml-body-blockspace-fields-v1"
- offsetUnitstringrequiredone of "utf16"
hitsarray of objectrequired0–50 items
- coverUrlstringlength 0–2048
- excerptstringrequiredlength 0–8192
- itemIdstringrequiredlength 1–128
- libraryIdstringrequiredlength 1–128
- matchLengthintegerrequired≥ 1
- matchStartintegerrequired≥ 0
- sectionIndexintegerrequired0–4095
- sectionPathstringrequiredlength 1–1024
- sourceIdstringrequiredlength 1–128
- sourceRevisionstringrequiredlength 1–128
- titlestringlength 0–4096
- utf16Offsetintegerrequired≥ 0
- indexRevisionintegerrequired≥ 0
- indexedOnlybooleanrequiredone of true
- nextstringlength 0–512
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternalsearch_busydatabase_busy
Example request
curl -X GET "http://127.0.0.1:32500/v1/reading/search" \
-H "Authorization: Bearer $PORTICO_API_KEY"POST/v1/reading/sessionsOpen an authorized reading publicationplayback
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the playback scope, or a signed-in session
- OpenAPI operation ID
post_reading_sessions- Max body
- 4 KiB
Request body application/json · required
{
"itemId": "id_8h2k4q",
"sourceId": "id_8h2k4q"
}- itemIdstringrequired
- sourceIdstringrequired
Responses
200Successapplication/json
{
"canAnnotate": true,
"canSaveFile": true,
"contents": [
{
"depth": 0,
"fragment": "string",
"section": "string",
"title": "Fargo"
}
],
"conversion": {
"converter": "libmobi:85dcfe803fc2a21020ddcf15c3eb66b93d388add",
"inputSHA256": "string",
"options": "portico-epub-v1;unencrypted-only;no-replica;default-kf8",
"originalFormat": "mobi",
"originalRevision": "r12",
"originalSize": 1,
"originalSourceId": "id_8h2k4q",
"outputSHA256": "string",
"outputSize": 1,
"revision": "r12",
"workerSHA256": "string"
},
"format": "epub",
"itemId": "id_8h2k4q",
"metadata": {
"author": "string",
"coverUrl": "https://example.com/…",
"direction": "ltr",
"estimatedSeconds": 0,
"language": "en",
"openingLines": "string",
"pageCount": 1,
"publicationType": {
"source": "owner",
"value": "book"
},
"series": {
"id": "id_8h2k4q",
"libraryId": "id_8h2k4q",
"name": "Fargo",
"number": 0,
"source": "owner"
},
"title": "Fargo",
"wordCount": 0
},
"pageNames": [
"Fargo"
],
"resources": [
{
"mime": "string",
"path": "string",
"size": 0
}
],
"revision": "r12",
"sequential": true,
"sessionId": "id_8h2k4q",
"size": 0,
"sourceId": "id_8h2k4q",
"spine": [
"string"
]
}- canAnnotateboolean
- canSaveFileboolean
contentsarray of object0–512 items
- depthintegerrequired0–16
- fragmentstringlength 0–1024
- sectionstringrequiredlength 1–4096
- titlestringrequiredlength 1–1024
conversionobject
- converterstringrequiredone of "libmobi:85dcfe803fc2a21020ddcf15c3eb66b93d388add"
- inputSHA256stringrequiredlength 64–64pattern ^[a-f0-9]{64}$
- optionsstringrequiredone of "portico-epub-v1;unencrypted-only;no-replica;default-kf8"
- originalFormatstringrequiredone of "mobi", "azw3"
- originalRevisionstringrequiredlength 64–64pattern ^[a-f0-9]{64}$
- originalSizeintegerrequired1–67108864
- originalSourceIdstringrequiredlength 1–256
- outputSHA256stringrequiredlength 64–64pattern ^[a-f0-9]{64}$
- outputSizeintegerrequired1–134217728
- revisionstringrequiredlength 64–64pattern ^[a-f0-9]{64}$
- workerSHA256stringrequiredlength 64–64pattern ^[a-f0-9]{64}$
- formatstringrequiredone of "epub", "pdf", "cbz", "cb7", "cbr"
- itemIdstringrequired
metadataobjectrequired
- authorstring
- coverUrlstring
- directionstringone of "ltr", "rtl", "vertical"
- estimatedSecondsinteger0–16106128
- languagestring
- openingLinesstringlength 1–4096
- pageCountinteger1–4096
publicationTypeobject
- sourcestringrequiredone of "owner", "file-metadata"
- valuestringrequiredone of "book", "magazine", "newspaper"
seriesobject
- idstringrequiredlength 43–43pattern ^[A-Za-z0-9_-]{43}$
- libraryIdstringrequiredlength 1–256
- namestringrequiredlength 1–4096
- numbernumber≥ 0
- sourcestringrequiredone of "owner", "file-metadata", "file-name", "folder"
- titlestring
- wordCountinteger0–67108864
- pageNamesarray of string
resourcesarray of object
- mimestringrequired
- pathstringrequired
- sizeintegerrequired
- revisionstringrequired
- sequentialboolean
- sessionIdstringrequired
- sizeintegerrequired
- sourceIdstringrequired
- spinearray of string
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternaldatabase_busywriter_capacity
Example request
curl -X POST "http://127.0.0.1:32500/v1/reading/sessions" \
-H "Authorization: Bearer $PORTICO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"itemId":"id_8h2k4q","sourceId":"id_8h2k4q"}'DELETE/v1/reading/sessions/{sessionId}Close this caller's reading sessionplayback
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the playback scope, or a signed-in session
- OpenAPI operation ID
delete_reading_sessions_sessionId
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sessionIdrequired | path | string |
Responses
204Success
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternaldatabase_busywriter_capacity
Example request
curl -X DELETE "http://127.0.0.1:32500/v1/reading/sessions/{sessionId}" \
-H "Authorization: Bearer $PORTICO_API_KEY"GET/v1/reading/sessions/{sessionId}/annotationsRead the current profile's annotations for this exact publication versionread
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the read scope, or a signed-in session
- OpenAPI operation ID
get_reading_sessions_sessionId_annotations
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sessionIdrequired | path | string | |
cursor | query | string | |
revision | query | string | |
If-Match | header | string |
Responses
200Successapplication/json
{
"entries": [
{
"colour": "",
"createdAt": 0,
"id": "id_8h2k4q",
"kind": "bookmark",
"location": {
"cfi": "string",
"format": "epub",
"progression": 0,
"section": "string"
},
"note": "string",
"rects": [
{
"height": 0,
"width": 0,
"x": 0,
"y": 0
}
],
"text": "string",
"updatedAt": 0
}
],
"nextCursor": "eyJvIjoyMH0",
"revision": 0,
"sourceId": "id_8h2k4q",
"sourceRevision": "r12"
}entriesarray of objectrequired0–50 items
- colourstringrequiredone of "", "yellow", "green", "blue", "pink"
- createdAtintegerrequired≥ 0
- idstringrequiredlength 1–64pattern ^[A-Za-z0-9_-]{1,64}$
- kindstringrequiredone of "bookmark", "highlight"
locationobjectrequired
- cfistringrequiredlength 10–4096
- formatstringrequiredone of "epub"
- progressionnumberrequired0–1
- sectionstringlength 0–1024
- notestringrequiredlength 0–4096
rectsarray of object0–128 items
- heightnumberrequired0–1
- widthnumberrequired0–1
- xnumberrequired0–1
- ynumberrequired0–1
- textstringrequiredlength 0–8192
- updatedAtintegerrequired≥ 0
- nextCursorstringrequiredlength 0–64pattern ^([A-Za-z0-9_-]{1,64})?$
- revisionintegerrequired≥ 0
- sourceIdstringrequiredlength 1–256
- sourceRevisionstringrequiredlength 1–256
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternaldatabase_busy
Example request
curl -X GET "http://127.0.0.1:32500/v1/reading/sessions/{sessionId}/annotations" \
-H "Authorization: Bearer $PORTICO_API_KEY"PUT/v1/reading/sessions/{sessionId}/annotationsChange an annotation under current profile, source version and collection CASplayback
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the playback scope, or a signed-in session
- OpenAPI operation ID
put_reading_sessions_sessionId_annotations- Max body
- 32 KiB
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sessionIdrequired | path | string | |
If-Match | header | string |
Request body application/json · required
{
"expectedRevision": 0,
"id": "id_8h2k4q",
"operation": "delete"
}- expectedRevisionintegerrequired0–9007199254740990
- idstringrequiredlength 1–64pattern ^[A-Za-z0-9_-]{1,64}$
- operationstringrequiredone of "delete"
Responses
200Successapplication/json
{
"revision": 1
}- revisionintegerrequired≥ 1
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternaldatabase_busywriter_capacity
Example request
curl -X PUT "http://127.0.0.1:32500/v1/reading/sessions/{sessionId}/annotations" \
-H "Authorization: Bearer $PORTICO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":0,"id":"id_8h2k4q","operation":"delete"}'GET/v1/reading/sessions/{sessionId}/assetsRead one enumerated original EPUB assetplayback
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the playback scope, or a signed-in session
- OpenAPI operation ID
get_reading_sessions_sessionId_assets
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sessionIdrequired | path | string | |
path | query | string | |
If-Match | header | string | |
If-None-Match | header | string |
Responses
200Successapplication/octet-stream
"string"string (binary)
304Successapplication/octet-stream
"string"string (binary)
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternaldatabase_busy
Example request
curl -X GET "http://127.0.0.1:32500/v1/reading/sessions/{sessionId}/assets" \
-H "Authorization: Bearer $PORTICO_API_KEY"POST/v1/reading/sessions/{sessionId}/file-saveSave the selected original file through its live authenticated Reader sessionplayback
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the playback scope, or a signed-in session
- OpenAPI operation ID
post_reading_sessions_sessionId_file_save- Max body
- 4 KiB
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sessionIdrequired | path | string | |
If-Match | header | string |
Request body application/json · required
{
"operationId": "id_8h2k4q"
}- operationIdstringrequiredpattern ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$
Responses
200Successapplication/octet-stream
"string"string (binary)
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternaldatabase_busywriter_capacity
Example request
curl -X POST "http://127.0.0.1:32500/v1/reading/sessions/{sessionId}/file-save" \
-H "Authorization: Bearer $PORTICO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"operationId":"id_8h2k4q"}'GET/v1/reading/sessions/{sessionId}/pages/{pageIndex}Read one bounded comic page imageplayback
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the playback scope, or a signed-in session
- OpenAPI operation ID
get_reading_sessions_sessionId_pages_pageIndex
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sessionIdrequired | path | string | |
pageIndexrequired | path | string | |
width | query | string | |
If-Match | header | string | |
If-None-Match | header | string |
Responses
200Successapplication/octet-stream
"string"string (binary)
304Successapplication/octet-stream
"string"string (binary)
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternaldatabase_busy
Example request
curl -X GET "http://127.0.0.1:32500/v1/reading/sessions/{sessionId}/pages/{pageIndex}" \
-H "Authorization: Bearer $PORTICO_API_KEY"GET/v1/reading/sessions/{sessionId}/progressRead the selected publication's saved locationread
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the read scope, or a signed-in session
- OpenAPI operation ID
get_reading_sessions_sessionId_progress
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sessionIdrequired | path | string | |
If-Match | header | string |
Responses
200Successapplication/json
{
"progress": {
"location": {
"cfi": "string",
"format": "epub",
"pageIndex": 0,
"progression": 0,
"section": "string"
},
"observedAt": 0,
"revision": 0,
"sourceId": "id_8h2k4q",
"sourceRevision": "r12",
"stale": true
}
}progressobject | any | nullrequired
locationobjectrequired
- cfistring
- formatstringrequiredone of "epub", "pdf", "cbz", "cb7", "cbr"
- pageIndexinteger
- progressionnumberrequired
- sectionstring
- observedAtintegerrequired
- revisionintegerrequired
- sourceIdstringrequired
- sourceRevisionstringrequired
- stalebooleanrequired
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternaldatabase_busy
Example request
curl -X GET "http://127.0.0.1:32500/v1/reading/sessions/{sessionId}/progress" \
-H "Authorization: Bearer $PORTICO_API_KEY"PUT/v1/reading/sessions/{sessionId}/progressSave the selected publication's location with compare and swapplayback
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the playback scope, or a signed-in session
- OpenAPI operation ID
put_reading_sessions_sessionId_progress- Max body
- 8 KiB
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sessionIdrequired | path | string | |
If-Match | header | string |
Request body application/json · required
{
"expectedRevision": 0,
"location": {
"cfi": "string",
"format": "epub",
"pageIndex": 0,
"progression": 0,
"section": "string"
}
}- expectedRevisionintegerrequired
locationobjectrequired
- cfistring
- formatstringrequiredone of "epub", "pdf", "cbz", "cb7", "cbr"
- pageIndexinteger
- progressionnumberrequired
- sectionstring
Responses
200Successapplication/json
{
"progress": {
"location": {
"cfi": "string",
"format": "epub",
"pageIndex": 0,
"progression": 0,
"section": "string"
},
"observedAt": 0,
"revision": 0,
"sourceId": "id_8h2k4q",
"sourceRevision": "r12",
"stale": true
},
"saved": true
}progressobject | any | nullrequired
locationobjectrequired
- cfistring
- formatstringrequiredone of "epub", "pdf", "cbz", "cb7", "cbr"
- pageIndexinteger
- progressionnumberrequired
- sectionstring
- observedAtintegerrequired
- revisionintegerrequired
- sourceIdstringrequired
- sourceRevisionstringrequired
- stalebooleanrequired
- savedbooleanrequired
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternaldatabase_busywriter_capacity
Example request
curl -X PUT "http://127.0.0.1:32500/v1/reading/sessions/{sessionId}/progress" \
-H "Authorization: Bearer $PORTICO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":0,"location":{"cfi":"string","format":"epub","pageIndex":0,"progression":0,"section":"string"}}'GET/v1/reading/sessions/{sessionId}/searchSearch the selected publication's persisted text indexread
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the read scope, or a signed-in session
- OpenAPI operation ID
get_reading_sessions_sessionId_search
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sessionIdrequired | path | string | |
q | query | string | |
cursor | query | string | |
limit | query | integer | ""1–50 |
Responses
200Successapplication/json
{
"coverage": {
"reason": "string",
"status": "indexed"
},
"hits": [
{
"excerpt": "string",
"matchLength": 1,
"matchStart": 0,
"sectionIndex": 0,
"sectionPath": "string",
"utf16Offset": 0
}
],
"indexRevision": 0,
"next": "string",
"sessionId": "id_8h2k4q",
"sourceId": "id_8h2k4q",
"sourceRevision": "r12"
}coverageobjectrequired
- reasonstringlength 0–64
- statusstringrequiredone of "indexed", "pending", "unsupported", "evicted", "excluded"
hitsarray of objectrequired0–50 items
- excerptstringrequiredlength 0–8192
- matchLengthintegerrequired≥ 1
- matchStartintegerrequired≥ 0
- sectionIndexintegerrequired0–4095
- sectionPathstringrequiredlength 1–1024
- utf16Offsetintegerrequired≥ 0
- indexRevisionintegerrequired≥ 0
- nextstringlength 0–512
- sessionIdstringrequiredlength 1–128
- sourceIdstringrequiredlength 1–128
- sourceRevisionstringrequiredlength 1–128
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternalsearch_busydatabase_busy
Example request
curl -X GET "http://127.0.0.1:32500/v1/reading/sessions/{sessionId}/search" \
-H "Authorization: Bearer $PORTICO_API_KEY"GET/v1/reading/sessions/{sessionId}/sourceRead the selected PDF's exact byte rangeplayback
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the playback scope, or a signed-in session
- OpenAPI operation ID
get_reading_sessions_sessionId_source
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sessionIdrequired | path | string | |
If-Match | header | string | |
Range | header | string |
Responses
200Successapplication/pdf
"string"string (binary)
206Successapplication/pdf
"string"string (binary)
416Successapplication/pdf
"string"string (binary)
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternaldatabase_busy
Example request
curl -X GET "http://127.0.0.1:32500/v1/reading/sessions/{sessionId}/source" \
-H "Authorization: Bearer $PORTICO_API_KEY"HEAD/v1/reading/sessions/{sessionId}/sourceRead the selected PDF's exact byte rangeplayback
- Audience
- Clients · Native API
- Authorization
- API key or personal access token with the playback scope, or a signed-in session
- OpenAPI operation ID
head_reading_sessions_sessionId_source
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sessionIdrequired | path | string | |
If-Match | header | string | |
Range | header | string |
Responses
200Successapplication/pdf
"string"string (binary)
416Successapplication/pdf
"string"string (binary)
defaultRequest refused or unavailableapplication/json
{
"error": {
"code": "string",
"message": "string"
}
}errorobjectrequired
- codestringrequired
- messagestringrequired
Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_requiredrevision_mismatchrequest_in_progressbody_too_largeinternaldatabase_busy
Example request
curl -X HEAD "http://127.0.0.1:32500/v1/reading/sessions/{sessionId}/source" \
-H "Authorization: Bearer $PORTICO_API_KEY"No operations match that filter.