エージェントから Litlas のライブラリを整理する

クイックスタート

すべてのエンドポイントは JSON を使い、次のベースパス以下にあります。

対話型の Bash では、一度だけ表示されたキーを非 export の変数へ画面表示なしで読み、非公開の設定用ファイルディスクリプタだけを通して curl へ渡します。キーをシェル履歴、子プロセスの環境変数、curl の引数へ残しません。

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"
  ) "$@"
}

認証と API キー

すべてのリクエストで Litlas API キーを Authorization ヘッダーに指定します。

Authorization: Bearer <YOUR_LITLAS_API_KEY>

設定を開いて API キーを発行・ローテートする

キーはパスワードと同様に扱ってください。URL、ソースコード、チャット記録、ログ、シェル履歴、リポジトリには記載しないでください。完全な値をシェルコマンドへ直接入力しないでください。意図したシークレットストアへ貼り付けたあとは、クリップボードを上書きし、設定画面でキーを隠してください。

使い終わったら、現在のシェルからキーと補助関数を消去します。

unset LITLAS_API_KEY
unset -f litlas_curl

識別子とメモの扱い

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

入力上限

• ボード名: 1〜120 文字で、空白を正規化する前の文字数で判定します。そのうえで前後の空白を除去し、連続する空白をまとめます。同じアカウント内の大文字・小文字だけが異なる同名ボードは 400 で拒否します。
• paper_id: 前後の空白を除去したあと 1〜120 文字です。内部の空白はまとめずそのまま保持します。不透明な識別子のため、大文字・小文字の変換やその他の正規化を行わないでください。
• note: 最大 2000 文字です。空文字列を送るとメモを消去します。
• expected_updated_at: 1〜64 文字で、空白だけの値は使えません。
• JSON リクエスト本文の未知フィールドは 422 で拒否します。

ほかのエージェントの編集を上書きせずにメモを更新する

expected_updated_at は必須です。すべてのメモ編集で楽観的排他制御を使います。

1. GET でメモを取得し、返された updated_at を保持します。
2. 編集した note と、その値を変更せず入れた expected_updated_at を PATCH で送ります。
3. 409 note_conflict のときは上書きや自動マージをしません。競合レスポンスの current_note と current_updated_at を読み、明示的に調整してから新しい PATCH を送ります。

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

エンドポイント

JSON 本文があるコマンドは、表示した例を引数ではなく標準入力から curl へ渡します。実際の本文に機密情報が含まれる場合は、対話シェルのコマンドや履歴内の例を実値へ置き換えず、エージェントからログへ出さずに標準入力へ生成してください。

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

エラー

2xx 応答だけが成功です。エラー本文を成功結果として扱わないでください。

エラーレスポンスの形式

すべてのエラーは最上位に detail フィールドを持ちます。エラーに応じて、detail は文字列、機械判定できるオブジェクト、または標準のバリデーション配列になります。最初に HTTP ステータスで分岐し、detail がオブジェクトの場合は detail.code でも分岐してください。すべての非 2xx 応答が同じ detail 形式だと仮定しないでください。

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

論文 ID の競合を安全に再試行する

保存済み論文 ID を解決するリクエストでは、論文 ID が並行して変わった場合や、保存済み ID を安全に解決できない場合に次の 409 を返すことがあります。retryable を明示的な指示として扱ってください。

• library_identity_changed かつ retryable: true: Litlas が現在の論文 ID を解決し直せるよう、同じリクエストを最初からやり直します。再試行は最大 1 回とし、繰り返す場合は中止してエラーを表面化させます。
• library_identity_ambiguous かつ retryable: false: 使用する保存済み ID を推測せず、保存データを変更せず、自動で再試行しません。変更の成功は確定していないため中止し、エラーを表面化させます。アカウント所有者または Litlas サポートに保存済み ID の競合修復を依頼し、明示的に解消されたと確認できたあとだけ、やり直します。
• その他の 409 には個別の回復手順があります。note_conflict は明示的に内容を調整し、free_capacity_exceeded は同じ内容のまま再試行しません。

例では curl --fail-with-body を使います。HTTP エラー時に終了コードを非ゼロにしつつ、調査用の応答本文を残せます。

リクエスト規約

• JSON 本文があるリクエストでは Content-Type: application/json を送信します。
• プログラムでパスへ識別子を埋め込む場合は、必ず URL エンコードします。
• エラーを含むすべての Agent API 応答には Cache-Control: private, no-store と Pragma: no-cache が付きます。中継キャッシュへアカウントデータを保存しないでください。
• タイムアウトした書き込みの成否を推測しないでください。再試行を決める前に対象リソースを読み直します。