ログイン無料で始める

REST API リファレンス

Base URL

https://nolto.app

CLI と外部クライアントは Personal API Token を Bearer token として送ります。

Authorization: Bearer nolto_user_xxxxxx

エラーは原則として { "error": "..." } の JSON で返ります。

Projects

GET/api/projectsBearer Token / Cookie

利用者が project member または organization member として参加している project を返します。

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

project を作成し、作成者を owner にします。

{
  "name": "my-app",
  "description": "Web application",
  "repositoryUrl": "https://github.com/example/my-app",
  "orgId": null
}

name は必須です。description、repositoryUrl、orgId は省略できます。

PATCH/api/projects/{projectId}Owner

project の名前と説明を更新します。

オーナーのみ。{ "name"?: string, "description"?: string | null }（少なくとも 1 つ）。name は 1〜80 文字、description は 400 文字まで（空文字は null）。 レスポンス: 200 { project: { id, name, description, updated_at } } / 400 入力不正 / 403 オーナー以外。

Roadmap sync

PUT/api/projects/{projectId}/roadmaps/{slug}Write Access

roadmap と参照された Markdown 文書を冪等に同期します。通常は nolto sync がこの API を呼び出します。

{
  "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 }
}
status意味
400slug または JSON が不正
403project への write 権限がない
409保存済み roadmap の updatedAt の方が新しい、repo_mismatch（別リポジトリに紐付け済み）、または repo_unbound（オーナーによる初回紐付けが必要）
422roadmap schema または文書 path が不正
426必須の repoIdentity がない（0.8.0 より前の CLI）

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

ℹ️

同期 payload は全体スナップショットです。payload から消えた文書は、その roadmap の保存済み文書からも削除されます。

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

POST/api/projects/{projectId}/repo-bindingOwner

project を現在のリポジトリへ付け替えます。付け替えは 7 日に 1 回までです。

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

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

Members and invitations

POST/api/projects/{projectId}/membersOwner

既存ユーザーを追加するか、email invitation を作成します。

PATCH/api/projects/{projectId}/members/{memberId}Owner

member role を更新します。

DELETE/api/projects/{projectId}/members/{memberId}Owner

member を削除します。最後の owner は削除できません。

Personal API Tokens

GET/api/tokensCookie Session

ログインユーザーの token 一覧を返します。

POST/api/tokensCookie Session

Personal API Token を作成します。平文 token はこのレスポンスで一度だけ返ります。

{
  "name": "github-actions",
  "expiresAt": "2026-12-31T23:59:59Z"
}
POST/api/tokens/{tokenId}/revokeCookie Session

token を失効します。

REST API リファレンス | Nolto