課題 API リファレンス
課題(issue)の作成・更新・一覧、カンバンボード、コメント、課題設定(種別・状態・カテゴリ)、添付、保存済みフィルタ、マイ課題、プロフィールの API です。CI や AI エージェントから課題を操作する用途を想定しています。
認証・エラー形式・ページング・ロールと権限は REST API リファレンスの共通仕様 を参照してください。このページの auth 列は共通仕様の「ロールと権限」の行に対応します(読む = 全ロール、書く = owner / admin / member、admin = owner / admin)。
前提
- project で課題機能が有効で、project key(例:
NOLTO)が設定されていること。無効な project への呼び出しは404です。 - 課題はキー
NOLTO-12で表示されますが、API のパスは番号12を使います(/issues/12)。 {projectId}は project の UUID です。
課題
/api/projects/{projectId}/issues読むproject の課題を絞り込み、50 件ずつ返します。不正な query 値は無視して既定値を使います。
| query | 値 |
|---|---|
status | 状態 UUID。繰り返しまたはカンマ区切りで複数指定できます |
closed | exclude(既定)/ include / only |
assignee | member UUID / me / none |
type | 種別 UUID |
priority | high / normal / low |
category | カテゴリ UUID |
parent | 親の課題番号(その子課題)/ none(親なし) |
q | 件名・本文の部分一致(100 文字まで) |
sort | updated(既定)/ due / priority / number / created |
order | asc / desc。既定は due のとき asc、それ以外は desc |
page | 1 始まり。不正値は 1 |
{
"issues": [
{
"id": "0aa00000-0000-4000-8000-000000000012",
"number": 12,
"key": "NOLTO-12",
"subject": "ログイン画面の文言",
"priority": "normal",
"type": { "id": "uuid", "name": "タスク", "color": "#2563eb" },
"status": { "id": "uuid", "name": "処理中", "color": "#ca8a04", "isClosed": false },
"assignee": { "id": "uuid", "email": "dev@example.com", "name": "山田" },
"createdBy": { "id": "uuid", "email": "pm@example.com", "name": null },
"categories": [],
"dueDate": "2026-09-01",
"closedAt": null,
"createdAt": "2026-08-29T01:23:45.678Z",
"updatedAt": "2026-08-29T02:00:00.000Z",
"commentCount": 2,
"parent": null,
"childCount": 0
}
],
"total": 1,
"page": 1,
"pageSize": 50
}
| status | 意味 |
|---|---|
200 | 課題一覧 |
404 | project が見つからない、または課題機能が無効 |
/api/projects/{projectId}/issues書く課題を作成します。種別と状態を省略すると project の既定値を使います。
{
"subject": "ログイン画面の文言",
"body": "## 背景\n\n表示を更新します。",
"priority": "normal",
"assigneeId": "member-uuid",
"dueDate": "2026-09-01",
"categoryIds": ["category-uuid"],
"parentId": null,
"attachmentIds": []
}
| field | 条件 |
|---|---|
subject | 必須、1〜255 文字 |
body | 任意、100,000 文字まで |
typeId / statusId | 種別 / 状態 UUID。省略時は既定値 |
priority | high / normal / low。既定は normal |
assigneeId | member UUID または null。member 以外は 400 |
dueDate | YYYY-MM-DD または null |
categoryIds | カテゴリ UUID、20 件まで |
parentId | 親課題 UUID または null |
attachmentIds | 添付 UUID、20 件まで |
{
"issue": {
"id": "0aa00000-0000-4000-8000-000000000012",
"number": 12,
"key": "NOLTO-12",
"subject": "ログイン画面の文言",
"body": "## 背景\n\n表示を更新します。"
}
}
| status | 意味 |
|---|---|
201 | 作成した IssueDetail |
400 | 入力、member、マスタ、親課題、添付が不正 |
402 | Free の project ごとの課題数上限(100 件)を超過 |
/api/projects/{projectId}/issues/{number}読む課題の詳細、コメント、本文の添付、子課題をまとめて返します。number は project 内の課題番号です。
{
"issue": { "id": "uuid", "number": 12, "key": "NOLTO-12", "subject": "ログイン画面の文言", "body": "Markdown" },
"comments": [],
"attachments": [],
"children": []
}
| status | 意味 |
|---|---|
200 | 詳細と関連データ |
400 | 課題番号が不正 |
404 | 課題が見つからない |
/api/projects/{projectId}/issues/{number}書く課題を更新します。作成時のフィールドを 1 つ以上指定し、任意で変更履歴と同じ行に残すコメントを付けられます。
{
"statusId": "status-uuid",
"comment": "対応しました"
}
attachmentIds は comment があればコメントに、無ければ本文に紐付きます。変更とコメントの両方が無い場合、レスポンスの comment は null です。
{
"issue": { "id": "uuid", "number": 12, "key": "NOLTO-12", "status": { "id": "status-uuid", "name": "完了", "color": "#16a34a", "isClosed": true } },
"comment": { "id": "comment-uuid", "body": "対応しました", "changes": [{ "field": "status", "from": "old-uuid", "to": "status-uuid", "fromLabel": "処理中", "toLabel": "完了" }] }
}
| status | 意味 |
|---|---|
200 | 更新した課題と履歴 / コメント行 |
400 | 入力不正。親が別 project、親自身が子、自分自身、または子を持つ課題への親設定は parent_invalid |
404 | 課題が見つからない |
/api/projects/{projectId}/issues/{number}admin課題を削除します。コメントは削除され、添付は解放されて 24 時間後の自動削除対象になります。子課題の親は未設定になります。
| status | 意味 |
|---|---|
204 | 削除済み |
403 | owner / admin ではない |
404 | 課題が見つからない |
親子課題
親子は 1 階層のみです。parentId には同じ project にある、親を持たない課題を指定します。子を持つ課題には親を設定できません。一覧では parent=12 で 12 番の子課題、parent=none で親を持たない課題を取得できます。
ボード
/api/projects/{projectId}/issues/board読む全状態を列にしたカンバンボード用データを返します。一覧と同じ query を使えますが、status / closed / page は無視します。
{
"columns": [
{
"status": { "id": "status-uuid", "name": "処理中", "color": "#ca8a04", "isClosed": false },
"issues": [{ "id": "issue-uuid", "number": 12, "key": "NOLTO-12", "subject": "ログイン画面の文言" }]
}
],
"total": 1,
"truncated": false
}
| status | 意味 |
|---|---|
200 | 状態列と課題。500 件で打ち切り、超過時は truncated: true |
404 | project が見つからない、または課題機能が無効 |
コメント
/api/projects/{projectId}/issues/{number}/comments書く課題へコメントを追加します。
{
"body": "確認しました。",
"attachmentIds": ["attachment-uuid"]
}
body は必須で 1〜100,000 文字、attachmentIds は 20 件までです。
| status | 意味 |
|---|---|
201 | { "comment": IssueComment } |
400 | 本文または添付が不正 |
404 | 課題が見つからない |
/api/projects/{projectId}/issues/{number}/comments/{commentId}自分 / admin自分のコメント本文を更新します。owner / admin は他の member のコメントも更新できます。
{
"body": "確認して対応しました。"
}
| status | 意味 |
|---|---|
200 | { "comment": IssueComment } |
403 | 他人のコメントを変更する権限がない |
404 | コメントが見つからない |
/api/projects/{projectId}/issues/{number}/comments/{commentId}自分 / admin自分のコメントを削除します。owner / admin は他の member のコメントも削除できます。
フィールド変更を伴う行は本文だけを削除して履歴を残します。通常のコメントは行ごと削除します。本文がなく履歴だけの行は削除できません。コメントの添付は解放されます。
| status | 意味 |
|---|---|
204 | コメントまたは本文を削除 |
403 | 削除権限がない |
404 | コメントが見つからない |
409 | 履歴のみの行で削除できない |
本文やコメントに [@表示名](mention:<userId>) と書くと、同じ project の member へメールで通知します。member ではない利用者と操作した本人は通知対象外です。編集時は新たに追加したメンションだけを通知します。
課題設定
kind は types / statuses / categories のいずれかです。
/api/projects/{projectId}/issue-settings読むproject の種別、状態、カテゴリを表示順で返します。
{
"types": [{ "id": "uuid", "name": "タスク", "color": "#2563eb", "sortOrder": 0, "isDefault": true }],
"statuses": [{ "id": "uuid", "name": "未対応", "color": "#64748b", "sortOrder": 0, "isDefault": true, "isClosed": false }],
"categories": [{ "id": "uuid", "name": "UI", "sortOrder": 0 }]
}
| status | 意味 |
|---|---|
200 | 課題設定 |
404 | project が見つからない、または課題機能が無効 |
/api/projects/{projectId}/issue-settings/{kind}admin種別、状態、カテゴリの項目を追加します。
| kind | body |
|---|---|
types | name(1〜50)、任意の color(小文字 #rrggbb)/ isDefault |
statuses | types と同じフィールド + 任意の isClosed |
categories | name(1〜50) |
{
"name": "レビュー中",
"color": "#ca8a04",
"isClosed": false
}
| status | 意味 |
|---|---|
201 | 作成した item(種別・状態・カテゴリのいずれか) |
400 | kind または入力が不正 |
409 | 同じ名前の項目がある |
/api/projects/{projectId}/issue-settings/{kind}/{id}admin項目を更新します。作成時のフィールドか sortOrder を 1 つ以上指定します。
{
"name": "確認中",
"sortOrder": 20
}
sortOrder は 0〜1000 です。
| status | 意味 |
|---|---|
200 | 更新した item(種別・状態・カテゴリのいずれか) |
400 | kind、ID、入力が不正 |
409 | 既定の項目を isDefault: false にしようとした |
/api/projects/{projectId}/issue-settings/{kind}/{id}?replaceWithId={id}admin項目を削除します。使用中の項目には付け替え先の replaceWithId が必要です。
| status | 意味 |
|---|---|
204 | 削除済み |
400 | 付け替え先が未指定、自分自身、または存在しない |
409 | 既定の項目、または kind の最後の項目で削除できない |
添付
添付はクライアントから S3 へ直接アップロードします。
- 添付メタデータを
POSTし、15 分有効のuploadUrlを取得します。 uploadUrlへファイル本体をPUTします。- complete API を呼び、
readyにします。 - 課題やコメントの
attachmentIdsに渡すか、Markdown から attachment ID を参照します。
/api/projects/{projectId}/attachments書くpending 状態の添付と presigned upload URL を発行します。
{
"filename": "screenshot.png",
"size": 248120,
"mime": "image/png"
}
filename は 1〜255 文字でパス区切りを含められません。size は bytes です。
{
"attachment": { "id": "attachment-uuid", "filename": "screenshot.png", "size": 248120, "mime": "image/png", "status": "pending" },
"uploadUrl": "https://storage.example.com/presigned-url",
"expiresAt": "2026-08-29T03:15:00.000Z"
}
| status | 意味 |
|---|---|
200 | pending 添付と upload URL |
400 | 入力不正。実行ファイルなどは禁止形式 blocked_type |
402 | Free の project ごとの添付容量上限(100 MB)を超過 |
413 | 1 ファイル 50 MB を超過 |
503 | ストレージが未設定 |
{uploadUrl}なし発行された URL へファイル本体を送ります。Authorization ヘッダは付けません。
| status | 意味 |
|---|---|
200 | S3 へのアップロード成功 |
/api/projects/{projectId}/attachments/{attachmentId}/completeアップロード本人S3 のオブジェクト到達とサイズを確認し、添付を ready にします。
| status | 意味 |
|---|---|
200 | { "attachment": PublicAttachment } |
403 | アップロードした本人ではない |
409 | upload_missing、または size_mismatch。サイズ不一致時は行とオブジェクトを削除 |
/api/projects/{projectId}/attachments/{attachmentId}/url読むready な添付の 5 分有効 URL を返します。画像は inline、それ以外は attachment で配信します。
redirect=1 を query に付けると URL の JSON ではなく 302 で転送します。
| status | 意味 |
|---|---|
200 | { "url": "...", "expiresAt": "..." } |
302 | redirect=1 の転送 |
404 | 添付が見つからない、または ready ではない |
/api/projects/{projectId}/attachments/{attachmentId}自分 / admin自分がアップロードした添付を削除します。owner / admin は他の member の添付も削除できます。
| status | 意味 |
|---|---|
204 | 削除済み |
403 | 削除権限がない |
502 | ストレージから削除できない |
complete 後の ID は、自分がアップロードした ready かつ未紐付けの添付だけを attachmentIds に渡せます。本文では画像を 、その他を [name](attachment:<attachmentId>) と書きます。24 時間以内に紐付けなかった添付は自動削除されます。
保存済みフィルタ
/api/projects/{projectId}/issue-filters読む自分のフィルタと、他の member が共有したフィルタを名前順で返します。
{
"mine": [],
"shared": []
}
| status | 意味 |
|---|---|
200 | mine と shared のフィルタ一覧 |
/api/projects/{projectId}/issue-filters書く一覧の絞り込み条件を保存します。
{
"name": "自分の期限超過",
"query": {
"statusIds": [],
"closed": "exclude",
"assignee": "me",
"typeId": null,
"priority": null,
"categoryId": null,
"parent": null,
"q": "",
"sort": "due",
"order": "asc"
},
"isShared": false
}
name は 1〜40 文字、isShared の既定は false です。query の未知のキーは 400 です。
| status | 意味 |
|---|---|
201 | { "filter": IssueFilter } |
409 | 同じ作成者に同名のフィルタがある |
/api/projects/{projectId}/issue-filters/{filterId}作成者 / admin名前、query、共有設定のいずれかを更新します。共有フィルタは owner / admin も更新できます。
{
"name": "今週の担当課題",
"isShared": true
}
| status | 意味 |
|---|---|
200 | { "filter": IssueFilter } |
403 | 更新権限がない |
404 | フィルタが見つからない。他人の非共有フィルタも 404 |
/api/projects/{projectId}/issue-filters/{filterId}作成者 / adminフィルタを削除します。共有フィルタは owner / admin も削除できます。
| status | 意味 |
|---|---|
204 | 削除済み |
403 | 削除権限がない |
404 | フィルタが見つからない。他人の非共有フィルタも 404 |
SavedIssueQuery は課題一覧 query から page を除いた JSON です。statusIds は UUID を20件まで、assignee は UUID / me / none / null、parent は課題番号 / none / null を指定できます。assignee: "me" は見る人ごとに解決します。
マイ課題
/api/me/issuesBearer Token / Cookieログインユーザーが参加する課題機能 ON かつ key 設定済みの project を横断し、担当・登録した課題を返します。対象 project が無ければ空配列です。
| query | 値 |
|---|---|
role | assignee(既定)/ reporter / any |
due | any(既定)/ overdue / week |
closed | exclude(既定)/ include / only |
sort | due(既定)/ updated |
order | asc / desc。既定は due が asc、updated が desc |
page | 1 始まり |
overdue は期限超過かつ未完了だけを返し、closed の指定に関わらず完了課題を除きます。week はサーバーの JST で今日から 7 日後までです。
{
"issues": [
{
"id": "issue-uuid",
"number": 12,
"key": "NOLTO-12",
"subject": "ログイン画面の文言",
"project": { "id": "project-uuid", "name": "Web アプリ", "key": "NOLTO" }
}
],
"total": 1,
"page": 1,
"pageSize": 50
}
| status | 意味 |
|---|---|
200 | project 情報付きの課題一覧 |
401 | ログインが必要 |
プロフィール
/api/me/profileBearer Token / Cookieログインユーザーのプロフィールを返します。
{
"profile": {
"id": "user-uuid",
"email": "dev@example.com",
"displayName": "山田"
}
}
| status | 意味 |
|---|---|
200 | プロフィール |
401 | ログインが必要 |
/api/me/profileBearer Token / Cookie表示名を更新します。空文字は null として保存されます。
{
"displayName": "山田"
}
displayName は null または 1〜50 文字です。
| status | 意味 |
|---|---|
200 | { "profile": { "id": "...", "email": "...", "displayName": "山田" } } |
400 | 表示名が不正 |
401 | ログインが必要 |
型
各エンドポイントのレスポンスで使う主な型です。
{
"id": "issue-uuid",
"number": 12,
"key": "NOLTO-12",
"subject": "ログイン画面の文言",
"priority": "normal",
"type": { "id": "type-uuid", "name": "タスク", "color": "#2563eb" },
"status": { "id": "status-uuid", "name": "処理中", "color": "#ca8a04", "isClosed": false },
"assignee": { "id": "user-uuid", "email": "dev@example.com", "name": "山田" },
"createdBy": { "id": "user-uuid", "email": "pm@example.com", "name": null },
"categories": [{ "id": "category-uuid", "name": "UI" }],
"dueDate": "2026-09-01",
"closedAt": null,
"createdAt": "2026-08-29T01:23:45.678Z",
"updatedAt": "2026-08-29T02:00:00.000Z",
"commentCount": 2,
"parent": {
"id": "parent-uuid",
"number": 3,
"key": "NOLTO-3",
"subject": "認証まわり",
"status": { "id": "status-uuid", "name": "処理中", "color": "#ca8a04", "isClosed": false }
},
"childCount": 0
}
上は IssueSummary です。IssueDetail はこれに Markdown の body を加えます。
| 型 | フィールド |
|---|---|
IssueComment | id、author、body、changes、attachments、createdAt、updatedAt |
IssueChange | field、from、to、fromLabel、toLabel |
IssueType | id、name、color、sortOrder、isDefault |
IssueStatus | IssueType のフィールド + isClosed |
IssueCategory | id、name、sortOrder |
IssueFilter | id、name、query、isShared、createdBy、updatedAt |
SavedIssueQuery | statusIds、closed、assignee、typeId、priority、categoryId、parent、q、sort、order |
PublicAttachment | id、filename、size、mime、status、entityType、entityId、createdAt、completedAt |
PublicAttachment.status は pending / ready / deleted、entityType は issue / issue_comment / null です。IssueChange.field は subject / body / type / status / priority / assignee / due_date / categories / parent です。