Work with the library

The library is the account’s private store: saved items, the standalone notes and highlights attached to them, reading history, and the original file bytes behind an upload. Three ideas carry the whole surface:

Items

A saved page, file, or supplied text. Addressed by a UUID.

Objects

Items, notes, and highlights under one search. Addressed by a stable ref.

Assets

The original bytes of an uploaded file, streamed back on demand.

Save something

POST /v1/library/items takes either a url for smry to fetch, or title plus content you supply yourself.

curl https://api.smry.ai/v1/library/items \
  --header "Authorization: Bearer $SMRY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://www.nasa.gov/news-release/nasa-sets-coverage-for-agency-crew-mission/",
    "tags": ["space", "launch"],
    "externalId": "crm-4821"
  }'

saved = smry.post("/v1/library/items", json={
    "url": "https://www.nasa.gov/news-release/nasa-sets-coverage-for-agency-crew-mission/",
    "tags": ["space", "launch"],
    "externalId": "crm-4821",
}).raise_for_status().json()

print(saved["item"]["id"], "already saved?", saved["alreadySaved"])

const saved = await smry("/v1/library/items", {
  url: "https://www.nasa.gov/news-release/nasa-sets-coverage-for-agency-crew-mission/",
  tags: ["space", "launch"],
  externalId: "crm-4821",
});

The response carries item, an extraction report, and alreadySaved. Saving the same url again returns the existing item with alreadySaved: true rather than creating a duplicate, which is what makes a retry after a timeout safe. externalId lets you carry your own identifier through — see Retries and idempotency.

Uploading a file

Two steps, in this order:

Admit the file

POST /v1/library/items with title and fileName — no bytes. Both are required; mimeType and format are optional. You get back an item id.

Send the bytes

PUT /v1/library/items/{id}/asset with the binary body, its Content-Type, and an X-Smry-File-Name header. The global ceiling is 100 MB, and audio gets all of it — but anything smry parses for text, a PDF or an EPUB included, is capped at 25 MB, so a 40 MB PDF is a 413. smry reads the extension from X-Smry-File-Name to pick the cap. Concurrent replacements of the same item are serialized, so a second write while one is in flight returns 409.

Read them back with GET /v1/library/items/{id}/asset, which streams the original with its stored MIME type and supports a single HTTP byte range — use it for audio, video, and large documents.

Find things

Two operations, two jobs.

Operation	Searches	Use when
`GET /v1/library/objects`	Items and notes and highlights	You are looking for knowledge and do not care which object holds it
`GET /v1/library/items`	Items only, with rich filters	You need a filtered list — by tag, status, kind, or date

Search everything

curl "https://api.smry.ai/v1/library/objects?query=attention+mechanism&types=note,highlight&limit=20" \
  --header "Authorization: Bearer $SMRY_API_KEY"

Each result carries a stable ref. Pass it to GET /v1/library/objects/{ref} to read the full object, whatever type it turned out to be. GET /v1/library/items filters on query, tag, status, starred, contentKind, captureMethod, format, externalId, savedAfter, and updatedAfter.

Reading history lives behind view=history. It is the only way to get it. GET /v1/library/items?view=history returns what the account has read, in reading order, rather than what it has saved.

savedAfter and updatedAfter are not interchangeable: savedAfter filters on when the item entered the library, updatedAfter on when it last changed. Use updatedAfter for polling, savedAfter for backfill.

Read one item

curl "https://api.smry.ai/v1/library/items/{id}?includeContent=true&contentMaxCharacters=4000" \
  --header "Authorization: Bearer $SMRY_API_KEY"

For anything long, don’t pull the whole body:

GET /v1/library/items/{id}/content returns a bounded window plus nextCursor, the same way article reading works.
POST /v1/library/items/{id}/search returns only the passages inside that one item that match a query, each with an anchor.

The second is almost always the right call inside an agent loop.

Change things

PATCH /v1/library/items/{id} moves, tags, stars, reclassifies, or marks an item read:

curl --request PATCH "https://api.smry.ai/v1/library/items/{id}" \
  --header "Authorization: Bearer $SMRY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"tags": ["space", "archive"], "markRead": true}'

tags is a complete replacement, not a merge. Read the item’s current tags first if you mean to add one. PATCH /v1/library/items (no id) applies one set of changes to up to 100 ids at once, and reports back updated and missing. DELETE /v1/library/items/{id} removes the item. Uploaded file bytes are permanently deleted from synced storage; notes and highlights are kept.

Sync into your own store

GET /v1/library/changes is the incremental feed of every mutation and deletion. The first call is the part people get wrong:

Take a checkpoint first

GET /v1/library/changes?cursor=latest. Keep the nextCursor it returns.

Then list the current library

Page GET /v1/library/items to load the state as it is now.

Then poll from the checkpoint

Continue from the stored nextCursor. Anything that changed during step 2 arrives as a change event, so nothing is lost and nothing is duplicated.

Doing it in the other order — list first, then checkpoint — drops every write that lands in between.

Python

checkpoint = smry.get("/v1/library/changes", params={"cursor": "latest"}).json()["nextCursor"]

cursor = None
while True:                                   # 1. load current state
    page = smry.get("/v1/library/items", params={"cursor": cursor, "limit": 100}).json()
    store.upsert(page["items"])
    cursor = page["nextCursor"]
    if cursor is None:
        break

while True:                                   # 2. stay current
    page = smry.get("/v1/library/changes", params={"cursor": checkpoint, "limit": 200}).json()
    for change in page["changes"]:
        store.apply(change)
    checkpoint = page["nextCursor"]
    if not page["hasMore"]:
        sleep(60)

GET /v1/library/counts gives the totals by status and content kind without paging anything — useful for a progress bar or a sanity check after a sync.

Saved article text is still source material written by someone else. Treat it as data, not instructions — see Content safety.

Cursors and paging

Library cursors are nextCursor; feed cursors are next_cursor. Don’t mix them.

Follow sources

Get new material into the library without asking for it.

Get started

Work with the API

Patterns

Reference

Work with the library

Items

Objects

Assets

Save something

Uploading a file

Find things

Read one item

Change things

Sync into your own store

Next

Cursors and paging

Follow sources

Items

Objects

Assets

​Save something

​Uploading a file

​Find things

​Read one item

​Change things

​Sync into your own store

​Next

Cursors and paging

Follow sources

Save something

Uploading a file

Find things

Read one item

Change things

Sync into your own store

Next