ログイン無料で始める

課題 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 です。

課題

GET/api/projects/{projectId}/issues読む

project の課題を絞り込み、50 件ずつ返します。不正な query 値は無視して既定値を使います。

query
status状態 UUID。繰り返しまたはカンマ区切りで複数指定できます
closedexclude(既定)/ include / only
assigneemember UUID / me / none
type種別 UUID
priorityhigh / normal / low
categoryカテゴリ UUID
parent親の課題番号(その子課題)/ none(親なし)
q件名・本文の部分一致(100 文字まで)
sortupdated(既定)/ due / priority / number / created
orderasc / desc。既定は due のとき asc、それ以外は desc
page1 始まり。不正値は 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課題一覧
404project が見つからない、または課題機能が無効
POST/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。省略時は既定値
priorityhigh / normal / low。既定は normal
assigneeIdmember UUID または null。member 以外は 400
dueDateYYYY-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、マスタ、親課題、添付が不正
402Free の project ごとの課題数上限(100 件)を超過
GET/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課題が見つからない
PATCH/api/projects/{projectId}/issues/{number}書く

課題を更新します。作成時のフィールドを 1 つ以上指定し、任意で変更履歴と同じ行に残すコメントを付けられます。

{
  "statusId": "status-uuid",
  "comment": "対応しました"
}

attachmentIdscomment があればコメントに、無ければ本文に紐付きます。変更とコメントの両方が無い場合、レスポンスの commentnull です。

{
  "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課題が見つからない
DELETE/api/projects/{projectId}/issues/{number}admin

課題を削除します。コメントは削除され、添付は解放されて 24 時間後の自動削除対象になります。子課題の親は未設定になります。

status意味
204削除済み
403owner / admin ではない
404課題が見つからない

親子課題

親子は 1 階層のみです。parentId には同じ project にある、親を持たない課題を指定します。子を持つ課題には親を設定できません。一覧では parent=12 で 12 番の子課題、parent=none で親を持たない課題を取得できます。

ボード

GET/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
404project が見つからない、または課題機能が無効

コメント

POST/api/projects/{projectId}/issues/{number}/comments書く

課題へコメントを追加します。

{
  "body": "確認しました。",
  "attachmentIds": ["attachment-uuid"]
}

body は必須で 1〜100,000 文字、attachmentIds は 20 件までです。

status意味
201{ "comment": IssueComment }
400本文または添付が不正
404課題が見つからない
PATCH/api/projects/{projectId}/issues/{number}/comments/{commentId}自分 / admin

自分のコメント本文を更新します。owner / admin は他の member のコメントも更新できます。

{
  "body": "確認して対応しました。"
}
status意味
200{ "comment": IssueComment }
403他人のコメントを変更する権限がない
404コメントが見つからない
DELETE/api/projects/{projectId}/issues/{number}/comments/{commentId}自分 / admin

自分のコメントを削除します。owner / admin は他の member のコメントも削除できます。

フィールド変更を伴う行は本文だけを削除して履歴を残します。通常のコメントは行ごと削除します。本文がなく履歴だけの行は削除できません。コメントの添付は解放されます。

status意味
204コメントまたは本文を削除
403削除権限がない
404コメントが見つからない
409履歴のみの行で削除できない

本文やコメントに [@表示名](mention:<userId>) と書くと、同じ project の member へメールで通知します。member ではない利用者と操作した本人は通知対象外です。編集時は新たに追加したメンションだけを通知します。

課題設定

kindtypes / statuses / categories のいずれかです。

GET/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課題設定
404project が見つからない、または課題機能が無効
POST/api/projects/{projectId}/issue-settings/{kind}admin

種別、状態、カテゴリの項目を追加します。

kindbody
typesname(1〜50)、任意の color(小文字 #rrggbb)/ isDefault
statusestypes と同じフィールド + 任意の isClosed
categoriesname(1〜50)
{
  "name": "レビュー中",
  "color": "#ca8a04",
  "isClosed": false
}
status意味
201作成した item(種別・状態・カテゴリのいずれか)
400kind または入力が不正
409同じ名前の項目がある
PATCH/api/projects/{projectId}/issue-settings/{kind}/{id}admin

項目を更新します。作成時のフィールドか sortOrder を 1 つ以上指定します。

{
  "name": "確認中",
  "sortOrder": 20
}

sortOrder は 0〜1000 です。

status意味
200更新した item(種別・状態・カテゴリのいずれか)
400kind、ID、入力が不正
409既定の項目を isDefault: false にしようとした
DELETE/api/projects/{projectId}/issue-settings/{kind}/{id}?replaceWithId={id}admin

項目を削除します。使用中の項目には付け替え先の replaceWithId が必要です。

status意味
204削除済み
400付け替え先が未指定、自分自身、または存在しない
409既定の項目、または kind の最後の項目で削除できない

添付

添付はクライアントから S3 へ直接アップロードします。

  1. 添付メタデータを POST し、15 分有効の uploadUrl を取得します。
  2. uploadUrl へファイル本体を PUT します。
  3. complete API を呼び、ready にします。
  4. 課題やコメントの attachmentIds に渡すか、Markdown から attachment ID を参照します。
POST/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意味
200pending 添付と upload URL
400入力不正。実行ファイルなどは禁止形式 blocked_type
402Free の project ごとの添付容量上限(100 MB)を超過
4131 ファイル 50 MB を超過
503ストレージが未設定
PUT{uploadUrl}なし

発行された URL へファイル本体を送ります。Authorization ヘッダは付けません。

status意味
200S3 へのアップロード成功
POST/api/projects/{projectId}/attachments/{attachmentId}/completeアップロード本人

S3 のオブジェクト到達とサイズを確認し、添付を ready にします。

status意味
200{ "attachment": PublicAttachment }
403アップロードした本人ではない
409upload_missing、または size_mismatch。サイズ不一致時は行とオブジェクトを削除
GET/api/projects/{projectId}/attachments/{attachmentId}/url読む

ready な添付の 5 分有効 URL を返します。画像は inline、それ以外は attachment で配信します。

redirect=1 を query に付けると URL の JSON ではなく 302 で転送します。

status意味
200{ "url": "...", "expiresAt": "..." }
302redirect=1 の転送
404添付が見つからない、または ready ではない
DELETE/api/projects/{projectId}/attachments/{attachmentId}自分 / admin

自分がアップロードした添付を削除します。owner / admin は他の member の添付も削除できます。

status意味
204削除済み
403削除権限がない
502ストレージから削除できない

complete 後の ID は、自分がアップロードした ready かつ未紐付けの添付だけを attachmentIds に渡せます。本文では画像を ![name](attachment:<attachmentId>)、その他を [name](attachment:<attachmentId>) と書きます。24 時間以内に紐付けなかった添付は自動削除されます。

保存済みフィルタ

GET/api/projects/{projectId}/issue-filters読む

自分のフィルタと、他の member が共有したフィルタを名前順で返します。

{
  "mine": [],
  "shared": []
}
status意味
200mineshared のフィルタ一覧
POST/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同じ作成者に同名のフィルタがある
PATCH/api/projects/{projectId}/issue-filters/{filterId}作成者 / admin

名前、query、共有設定のいずれかを更新します。共有フィルタは owner / admin も更新できます。

{
  "name": "今週の担当課題",
  "isShared": true
}
status意味
200{ "filter": IssueFilter }
403更新権限がない
404フィルタが見つからない。他人の非共有フィルタも 404
DELETE/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 / nullparent は課題番号 / none / null を指定できます。assignee: "me" は見る人ごとに解決します。

マイ課題

GET/api/me/issuesBearer Token / Cookie

ログインユーザーが参加する課題機能 ON かつ key 設定済みの project を横断し、担当・登録した課題を返します。対象 project が無ければ空配列です。

query
roleassignee(既定)/ reporter / any
dueany(既定)/ overdue / week
closedexclude(既定)/ include / only
sortdue(既定)/ updated
orderasc / desc。既定は dueascupdateddesc
page1 始まり

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意味
200project 情報付きの課題一覧
401ログインが必要

プロフィール

GET/api/me/profileBearer Token / Cookie

ログインユーザーのプロフィールを返します。

{
  "profile": {
    "id": "user-uuid",
    "email": "dev@example.com",
    "displayName": "山田"
  }
}
status意味
200プロフィール
401ログインが必要
PATCH/api/me/profileBearer Token / Cookie

表示名を更新します。空文字は null として保存されます。

{
  "displayName": "山田"
}

displayNamenull または 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 を加えます。

フィールド
IssueCommentidauthorbodychangesattachmentscreatedAtupdatedAt
IssueChangefieldfromtofromLabeltoLabel
IssueTypeidnamecolorsortOrderisDefault
IssueStatusIssueType のフィールド + isClosed
IssueCategoryidnamesortOrder
IssueFilteridnamequeryisSharedcreatedByupdatedAt
SavedIssueQuerystatusIdsclosedassigneetypeIdprioritycategoryIdparentqsortorder
PublicAttachmentidfilenamesizemimestatusentityTypeentityIdcreatedAtcompletedAt

PublicAttachment.statuspending / ready / deletedentityTypeissue / issue_comment / null です。IssueChange.fieldsubject / body / type / status / priority / assignee / due_date / categories / parent です。

課題 API リファレンス | Nolto