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_KEY
builtin printf 'Litlas API key: ' >&2
IFS= read -r -s LITLAS_API_KEY
builtin printf '\n' >&2
litlas_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>

Open Settings to issue or rotate an 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_KEY
unset -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. An empty string clears the note.
• expected_updated_at: 1–64 characters and cannot be blank.
• Unknown fields in a JSON request body are rejected with 422.

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 the edited note with that exact value as expected_updated_at.
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.

{
  "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 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"
}

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"}
JSON

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

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": "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.
• 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.