Let an agent organize your Litlas library

Quick start

All endpoints use JSON and are rooted at the following base path.

In an interactive Bash shell, keep the one-time key in a non-exported variable and pass it to curl only through a private configuration file descriptor. This prevents the key from entering shell history, child-process environments, or curl arguments:

unset LITLAS_API_KEYbuiltin printf 'Litlas API key: ' >&2IFS= read -r -s LITLAS_API_KEYbuiltin printf '\n' >&2litlas_curl() {  if [[ ! ${LITLAS_API_KEY-} =~ ^litlas_sk_[A-Za-z0-9_-]{43}$ ]]; then    builtin printf 'Invalid Litlas API key.\n' >&2    return 64  fi  command curl --config <(    builtin printf 'header = "Authorization: Bearer %s"\n' "$LITLAS_API_KEY"  ) "$@"}

Authentication and API keys

Send your Litlas API key in the Authorization header on every request.

Authorization: Bearer <YOUR_LITLAS_API_KEY>

Treat the key like a password. Do not put it in a URL, source code, chat transcript, log, shell history, or repository. Never type the complete value directly into a shell command. After pasting it into the intended secret store, overwrite your clipboard and hide the key in Settings.

When finished, clear the key and helper function from the current shell:

unset LITLAS_API_KEYunset -f litlas_curl

Identifiers and note behavior

const paperId = 'SOURCE/ID';encodeURIComponent(paperId); // 'SOURCE%2FID'

Input limits

• Board name: 1–120 characters, counted before whitespace is normalized. Litlas then trims surrounding whitespace, collapses internal whitespace, and rejects a case-insensitive duplicate name in the same account with 400.
• paper_id: 1–120 characters after surrounding whitespace is removed. Internal whitespace is preserved, not collapsed; do not case-fold or otherwise normalize this opaque identifier.
• note: at most 2000 characters. In mode "replace" an empty string clears the note; in mode "append" a blank note is rejected with 422 instead of silently doing nothing. When appending makes the stored note exceed the limit the request fails with 422 note_too_long and nothing is written; the note is never truncated.
• expected_updated_at: 1–64 characters and cannot be blank.
• mode: one of append, replace. Defaults to append.
• permanent: a boolean query parameter on the library delete. Defaults to false, which moves the paper to the trash.
• Unknown fields in a JSON request body are rejected with 422.
• Unknown query parameters are rejected with 422, so a misspelled parameter cannot silently run with its default.

Update notes without overwriting another agent

expected_updated_at is required. Use optimistic concurrency for every note edit:

1. GET the note and retain its updated_at value.
2. PATCH with that exact value as expected_updated_at. Send only the new text to append it, or the complete new note with mode "replace" to overwrite.
3. On 409 note_conflict, do not overwrite or silently merge. Read current_note and current_updated_at from the conflict, reconcile explicitly, then send a new PATCH.
4. Never reuse a version that already succeeded: because a version is consumed once, a blindly repeated append cannot double-write.

{  "detail": {    "code": "note_conflict",    "paper_id": "P43NTWMNFA70",    "current_note": "The note saved by another client.",    "current_updated_at": "2026-09-03T12:34:00Z"  }}

Endpoints

Commands with a JSON body pass the displayed example to curl on standard input instead of an argument. If the real body contains sensitive content, do not replace the example inside an interactive shell command or history; have the agent generate the JSON on standard input without logging it.

litlas_curl --fail-with-body --silent --show-error \  --request POST \  --form 'pdf=@paper.pdf;type=application/pdf' \  --form-string 'board_ids=["board_01JABCDEF"]' \  'https://litlas.ai/api/v1/agent/library/upload-pdf'

{  "ok": true,  "created": true,  "pdf_uploaded": true,  "paper": {    "id": "browser_import:example",    "title": "Example paper title"  },  "item": {    "paper_id": "browser_import:example",    "board_ids": [      "board_01JABCDEF"    ]  }}

litlas_curl --fail-with-body --silent --show-error \  --request POST \  --form 'bib=@papers.bib;type=application/x-bibtex' \  --form-string 'board_ids=["board_01JABCDEF"]' \  'https://litlas.ai/api/v1/agent/library/import-bibtex'

{  "total_entries": 1,  "imported_count": 1,  "matched_count": 0,  "captured_count": 1,  "unmatched_count": 0,  "note_conflict_count": 0,  "imported_paper_ids": [    "browser_import:example"  ],  "target_board_ids": [    "board_01JABCDEF"  ]}

litlas_curl --fail-with-body --silent --show-error \  --request GET \  'https://litlas.ai/api/v1/agent/boards'

{  "boards": [    {      "board_id": "board_01JABCDEF",      "name": "Reading list",      "item_count": 0,      "created_at": "2026-09-03T12:30:00Z",      "updated_at": "2026-09-03T12:30:00Z"    }  ]}

{  "name": "Reading list"}

litlas_curl --fail-with-body --silent --show-error \  --request POST \  --header 'Content-Type: application/json' \  --data-binary @- \  'https://litlas.ai/api/v1/agent/boards' <<'JSON'{"name":"Reading list"}JSON

{  "board": {    "board_id": "board_01JABCDEF",    "name": "Reading list",    "item_count": 0,    "created_at": "2026-09-03T12:30:00Z",    "updated_at": "2026-09-03T12:30:00Z"  }}

litlas_curl --fail-with-body --silent --show-error \  --request DELETE \  'https://litlas.ai/api/v1/agent/boards/board_01JABCDEF'

{  "board_id": "board_01JABCDEF",  "deleted": true}

litlas_curl --fail-with-body --silent --show-error \  --request GET \  'https://litlas.ai/api/v1/agent/boards/board_01JABCDEF/papers'

{  "board_id": "board_01JABCDEF",  "papers": [    {      "paper_id": "P43NTWMNFA70",      "title": "Example paper title",      "authors": [        "Ada Lovelace",        "Alan Turing"      ],      "year": 2026    }  ]}

{  "paper_id": "P43NTWMNFA70"}

litlas_curl --fail-with-body --silent --show-error \  --request POST \  --header 'Content-Type: application/json' \  --data-binary @- \  'https://litlas.ai/api/v1/agent/boards/board_01JABCDEF/papers' <<'JSON'{"paper_id":"P43NTWMNFA70"}JSON

{  "board_id": "board_01JABCDEF",  "paper_id": "P43NTWMNFA70",  "added": true}

litlas_curl --fail-with-body --silent --show-error \  --request DELETE \  'https://litlas.ai/api/v1/agent/boards/board_01JABCDEF/papers/P43NTWMNFA70'

{  "board_id": "board_01JABCDEF",  "paper_id": "P43NTWMNFA70",  "removed": true}

litlas_curl --fail-with-body --silent --show-error \  --request GET \  'https://litlas.ai/api/v1/agent/papers/P43NTWMNFA70/note'

{  "paper_id": "P43NTWMNFA70",  "note": "Initial note.",  "updated_at": "2026-09-03T12:31:00Z"}

{  "note": "Key finding and follow-up questions.",  "expected_updated_at": "2026-09-03T12:31:00Z",  "mode": "append"}

litlas_curl --fail-with-body --silent --show-error \  --request PATCH \  --header 'Content-Type: application/json' \  --data-binary @- \  'https://litlas.ai/api/v1/agent/papers/P43NTWMNFA70/note' <<'JSON'{"note":"Key finding and follow-up questions.","expected_updated_at":"2026-09-03T12:31:00Z","mode":"append"}JSON

{  "paper_id": "P43NTWMNFA70",  "note": "Initial note.\n\nKey finding and follow-up questions.",  "updated_at": "2026-09-03T12:35:00Z"}

litlas_curl --fail-with-body --silent --show-error \  --request DELETE \  'https://litlas.ai/api/v1/agent/papers/P43NTWMNFA70?permanent=false'

{  "paper_id": "P43NTWMNFA70",  "permanent": false,  "deleted": true}

Errors

A request succeeds only with a 2xx response. Do not treat an error body as a successful result.

Error response schema

Every error has a top-level detail field. Depending on the error, detail is a string, a machine-readable object, or the standard validation array. Branch on the HTTP status first and, when detail is an object, on detail.code. Never assume one detail shape for every non-2xx response.

{  "detail": "Board not found"}

{  "detail": {    "code": "free_capacity_exceeded",    "kind": "items",    "limit": 100,    "used": 100  }}

{  "detail": {    "code": "library_identity_changed",    "message": "The library changed concurrently. Retry the request.",    "retryable": true  }}

{  "detail": {    "code": "library_identity_ambiguous",    "message": "Stored library identities cannot be resolved unambiguously. No changes were applied.",    "retryable": false  }}

{  "detail": {    "code": "note_conflict",    "paper_id": "P43NTWMNFA70",    "current_note": "The note saved by another client.",    "current_updated_at": "2026-09-03T12:34:00Z"  }}

{  "detail": {    "code": "note_too_long",    "paper_id": "P43NTWMNFA70",    "limit": 2000,    "length": 2064  }}

{  "detail": {    "code": "paper_metadata_unavailable",    "paper_id": "P43NTWMNFA70"  }}

Safe retries for library identity conflicts

Requests that resolve stored paper identities can return one of these 409 responses after a concurrent identity change or when stored identities cannot be resolved safely. Use retryable as an explicit instruction:

• library_identity_changed with retryable: true: start the same request again from the beginning so Litlas re-resolves current identity. Retry at most once; if it repeats, stop and surface the error.
• library_identity_ambiguous with retryable: false: do not guess, modify stored data, or retry automatically. No mutation was confirmed; stop and surface the error. Ask the account owner or Litlas support to repair the stored identity conflict, and retry only after they explicitly confirm that it is resolved.
• Other 409 responses have their own recovery rules. In particular, reconcile note_conflict explicitly and do not retry free_capacity_exceeded unchanged.

The examples use curl --fail-with-body so HTTP errors produce a non-zero exit status while preserving the response body for diagnosis.

Request conventions

• Send Content-Type: application/json when a request has a JSON body.
• Path identifiers must be URL-encoded if they are inserted programmatically.
• Only the query parameters documented for an endpoint are accepted. Anything else is a 422, so a typo cannot quietly fall back to a default.
• Every Agent API response, including errors, sends Cache-Control: private, no-store and Pragma: no-cache. Do not persist account data in an intermediary cache.
• Never guess that a timed-out write succeeded or failed. Read the resource before deciding whether to retry.