REST API リファレンス

Nolto の REST API は 2 ページに分かれています。このページは全 API に共通する仕様と、project・roadmap 同期・member・token の API です。課題・コメント・添付・保存済みフィルタ・マイ課題は 課題 API を参照してください。

共通仕様

Base URL

https://nolto.app

認証

CLI と外部クライアントは Personal API Token（nolto_user_ で始まる）を Bearer token として送ります。token は 設定 > アプリと API トークン で発行します（認証）。

Authorization: Bearer nolto_user_xxxxxx

トークン発行時に「制限付き」を選ぶと機能と対象プロジェクトを絞れます。スコープは issues:read / issues:write / wiki:read / wiki:write / files:read / files:write / roadmap:read / roadmap:sync。write / sync は同機能の read を含みます。機能 API の GET / HEAD は read、他のメソッドは write（roadmap は sync）を要求し、メンバー管理・設定・組織 API は全権限が必要です。GET /api/projects、GET /api/me/profile、GET /api/me/token はスコープ不問、My issues は issues:read です。対象プロジェクトの指定は projects / My issues の一覧にも反映します。

権限不足は 403 { error: "token_scope", message, requiredScope, tokenScopes }、別プロジェクトへのアクセスは 403 { error: "token_project", message, tokenScopes }。requiredScope は必要なスコープまたは "full" です。既存トークンと nolto login の発行は全権限のままです。

ブラウザからは Cookie セッションでも呼び出せますが、Cookie 認証の変更系リクエストは同一 origin の Origin ヘッダを要求します（CSRF 対策）。外部クライアントは Bearer token を使ってください。

リクエストとレスポンス

• ボディは JSON（Content-Type: application/json）。JSON として読めないボディは 400 です。
• 課題 API のボディは 未知のキーを拒否します（400）。
• 日付のみの項目（dueDate）は YYYY-MM-DD、日時は ISO 8601（UTC）です。
• 一覧は page（1 始まり）でページングし、{ ..., "total": 123, "page": 1, "pageSize": 50 } を返します。

エラー

エラーは { "error": "..." } の JSON です。error は利用者向けメッセージ（日本語）か、機械可読なコードのどちらかで、コードの場合は message に説明が付きます。

Zod の検証では最初のエラーを返します。未知のキーは 不明な項目があります: 'foo' の形式で示し、Zod 既定の英語メッセージは各 API の日本語 fallback に置き換えます。schema が定義した日本語メッセージはそのまま返します。

ロールと権限

project のロールは owner / admin / member / viewer です。organization の admin は所属 project の暗黙 owner として扱われます。organization の member は、その project の project_members 行がある場合のみアクセスできます（自動加入はありません）。

機能スコープ

project member の featureScope は null（全機能）または roadmap / issues / wiki / files / git_links / settings の配列です。非 null は外部メンバーを表し、配列にない機能の API は404を返します。外部メンバーの標準設定は ["issues", "wiki", "files"] です。外部メンバーへ admin / owner は設定できません。

互換性

このリファレンスに載っているパスは公開契約です。レスポンスにはフィールドを追加することがありますが、既存フィールドの削除や意味の変更は行いません。廃止する場合はこのドキュメントで告知し、互換性のない変更は別のパスで提供します。

Projects

{
  "projects": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "my-app",
      "description": "Web application",
      "repository_url": "https://github.com/example/my-app",
      "role": "owner",
      "archivedAt": null,
      "featureScope": null
    }
  ]
}

{
  "name": "my-app",
  "description": "Web application",
  "repositoryUrl": "https://github.com/example/my-app",
  "orgId": "00000000-0000-4000-8000-000000000001"
}

name は必須（trim 後 1〜80 文字）です。description（400 文字まで、空文字 / 空白のみは null）、repositoryUrl（有効な URL または null、空文字 / 空白のみは null）は省略できます。orgId は必須です。未指定・空の場合は 400 org_required を返します。

Owner / Admin が利用できます。{ "name"?: string, "description"?: string | null, "icon"?: { "kind": "text", "text"?: string, "color": string } | { "kind": "emoji", "emoji": string, "color": string } | null }（少なくとも 1 つ）。name は 1〜80 文字、description は 400 文字まで（空文字は null）。 icon.text は NFC 正規化・前後空白除去後に 1〜2 コードポイント（空は名前由来の既定文字）。icon.emoji は絵文字 1 つ（ZWJ・肌色対応、8 コードポイント以内。国旗・keycap は対象外）。color は red, orange, yellow, lime, green, teal, cyan, blue, indigo, violet, pink, gray のいずれか。icon: null で名前先頭 2 文字と id ハッシュ色の既定に戻します。

レスポンス: 200 { project: { id, name, description, icon, updated_at } } / 400 入力不正（アイコン不正は { code: "project_icon_invalid", error }）/ 403 権限なし。

JSON PATCH の icon は text / emoji / null のみです。指定時は既存の画像を削除します。image の直接指定は 400 project_icon_invalid。レスポンスの icon は { kind: "image", version, color } を含む場合があります。

成功時は 200 { icon: { kind: "image", version, color } }。version は保存バイト列の SHA-256 先頭16桁、color は現在の色（未設定なら既定色）を保持します。UI は元画像を中央から 256 px の正方形 PNG に変換して送信します。400 project_icon_image_invalid / 413 サイズ超過 / 415 MIME 不正 / 429 rate_limited（ユーザーごと 30 回 / 15 分、Retry-After 付き）/ 409 project_archived。

?v=version が現在の version と一致する場合は Cache-Control: private, max-age=31536000, immutable、それ以外は private, no-store。Content-Type は image/png、Content-Disposition は inline、X-Content-Type-Options は nosniff です。

成功時は 200 { project: { id, archivedAt } } を返します。以後の書き込みは 409 project_archived です。GET・project の DELETE・unarchive は利用できます。repo binding は保持され、Free の件数、通知、期限リマインダー、My issues の対象から外れます。自動招待受諾は解除まで保留します。

成功時は 200 { project: { id, archivedAt: null } } です。Free のアクティブなプロジェクト数が上限に達している場合は 402 { error: "plan_limit", message, upgradeUrl }、未アーカイブなら 409 project_not_archived を返します。GET /api/projects はアーカイブ済みを含み、各項目の archivedAt は日時文字列または null です。

Roadmap sync

{
  "repoIdentity": {
    "kind": "remote",
    "value": "github.com/example/my-app"
  },
  "roadmap": {
    "schemaVersion": 2,
    "project": {
      "id": "my-app",
      "name": "My App",
      "repository": "https://github.com/example/my-app"
    },
    "updatedAt": "2026-08-04T10:00:00Z",
    "currentTaskId": "auth-2",
    "summary": "認証機能を更新中",
    "phases": []
  },
  "planDocuments": [
    {
      "path": "docs/plans/auth.md",
      "taskId": "auth-2",
      "content": "# Authentication plan",
      "contentHash": "sha256:..."
    }
  ]
}

成功時:

{
  "roadmapId": "uuid",
  "slug": "my-app",
  "stats": { "total": 8, "done": 3, "blocked": 1 },
  "documents": { "upserted": 1, "unchanged": 0, "deleted": 0 },
  "issues": { "linked": 0, "skipped": 0 },
  "warnings": []
}

task の issues は同一 project の live 課題だけを解決し、リンクを全置換します。未知番号・他 project・キー未設定・課題機能 OFF は警告してスキップします。成功応答は常に issues 件数と warnings を返します。警告は task 順・配列順で最大 50 件と超過件数を返し、同期を失敗させません。

repo_mismatch はクライアントが自己申告した識別子による、意図しない複数リポジトリ利用の防止策です。認可境界ではなく、実際のアクセス制御は project membership と plan gate が担います。

repoIdentity は必須です。kind は remote または local、value は CLI が解決した正規化済みリポジトリ識別子です。

{
  "repoIdentity": {
    "kind": "remote",
    "value": "github.com/example/my-app"
  }
}

成功時は現在の repoIdentity と紐付け日時を返します。クールダウン中は 429 rebind_cooldown と再試行可能になるまでの時間を返します。

同期時の phase / task の状態変更と plan path の新規登録・変更は、roadmap スコープを持つメンバーに設定に応じて通知されます（同期者は除外）。blocked は最大5件の単独通知、それ以外と超過分は既存の5分ダイジェストです。既定の「ブロックのみ」はアプリ内・メール共通で、ダイジェストは「すべて」で受信します。状態変更があった同期は活動記録にも残り、plan 登録だけでは活動記録を作りません。初回・空スタブ・タイトルのみの変更では発火せず、PUT の応答形式は変わりません。

Git links

{"links":[{"kind":"pr","ref":"123","title":"NOLTO-50 対応 (#123)","author":"Developer","committedAt":"2026-09-06T00:00:00Z","issueKeys":["NOLTO-50"]}]}

PATCH /api/projects/{projectId} の gitLinkDetail: "summary" | "full" は owner / admin が表示粒度を変更します。既定は summary。不正値は400です。

Members and invitations

Project groups

実効ロールは個人参加・グループ参加・組織管理者の最大値です。機能スコープは全経路の和集合で、一つでも null があれば無制限になります。

Organizations

組織（organization）はプロジェクトをまとめて所有する単位です。組織の管理者は組織のすべてのプロジェクトに入れます。管理者でないメンバーが入れるのは、追加されたプロジェクトだけです。誰でも作成でき、Free の組織はメンバー 3 名（招待中を含む）・アクティブなプロジェクト 3 件まで、Pro・Pro+ の組織は無制限です（レート制限・Tier）。組織の Pro 契約は組織ごとに行います。

{
  "orgs": [
    {
      "id": "c0000000-0000-4000-8000-000000000001",
      "name": "uruca",
      "role": "admin",
      "plan": "free",
      "planSource": "none",
      "memberCount": 1,
      "pendingInvitationCount": 0,
      "projectCount": 0,
      "limits": { "maxOrgMembers": 3, "maxProjects": 3 },
      "createdAt": "2026-08-29T01:23:45.678Z"
    }
  ]
}

planSource は stripe（Stripe 契約）/ owner（運営による付与）/ none。limits の null は無制限です。

{ "name": "uruca" }

name は 1〜80 文字。レスポンスは 201 { "org": ... }（上と同じ形）。

{ "orgs": [{ "id", "name", "role", "plan", "planSource", "projectCount", "limits" }] }。

プロジェクトは必ず組織に属します。POST /api/projects には orgId が必須です。Free の組織でアクティブなプロジェクトが 4 件目になる場合は 402 です。

組織の Pro 契約: POST /api/billing/checkout に { "plan": "pro", "scope": "org", "orgId": "..." }（組織の管理者のみ。運営付与中は 409 org_owner_granted、契約中は 409 org_active_team）。お支払いの管理は POST /api/billing/portal に { "scope": "org", "orgId": "..." }。

Organization groups

対象なしは404 group_not_found です。グループだけで参加する人は個人招待の人数上限に算入せず、組織席は一人一席です。

活動記録の API 経由表示

GET /api/projects/{projectId}/activity の events は、API トークンで操作した場合に payload.via: { kind: "api_token", tokenName }、OAuth で接続したアプリから操作した場合に payload.via: { kind: "oauth_app", tokenName } を含みます。tokenName は操作時のトークン名、またはアプリ名です。アプリ名には (MCP) の接尾辞は付きません。Cookie／システム操作では既存 payload をそのまま返し、従来の文字列 via も保持します。Web の活動記録は型が一致する場合だけバッジを表示し、API トークンは「API 経由」（title は「API トークン: （トークン名）」）、OAuth アプリは「Claude 経由」のようにアプリ名を表示します（title は「接続中のアプリ: （アプリ名）」）。活動記録の詳細も参照してください。

Personal API Tokens

一覧・発行・失効の token record は scopes、projectId、projectName も返します。

{
  "name": "github-actions",
  "expiresAt": "2026-12-31T23:59:59Z",
  "scopes": ["issues:write", "roadmap:sync"],
  "projectId": null
}

name は 1〜120 文字、expiresAt は ISO 8601 の未来の日時（省略または null で無期限）。過去または現在の時刻は 400 { "code": "expires_at_past" }、ISO 8601 形式が不正な場合は 400 { "code": "expires_at_invalid" }。アクティブ token（失効済み・期限切れを除く）が 20 件に達すると 409 です。

scopes は上記語彙の配列（省略・null は全権限）。空・未知値・非配列は400 scopes_invalid、重複は除去されます。projectId は参加できるプロジェクトの UUID（省略・null は全プロジェクト）。非メンバー・不在は404 project_not_found、形式不正は400 project_id_invalid です。