tenseleyflow/shithub / 89bf8df

+- [Labels](./api/labels.md)

+Issues live per repo. They share the `issues` table with pull

+requests, but the REST surface here returns issues only (PRs land

+in their own section). Markdown bodies are stored raw; the cached

+HTML render comes from the same `internal/markdown` pipeline the

+web UI uses.

+

+## Issue shape

+

+```json

+{

+  "id": 17,

+  "number": 1,

+  "title": "first bug",

+  "body": "kaboom",

+  "state": "open",

+  "state_reason": "",

+  "locked": false,

+  "lock_reason": "",

+  "author_id": 42,

+  "labels": ["bug"],

+  "created_at": "2026-05-12T05:00:00Z",

+  "updated_at": "2026-05-12T05:00:00Z"

+}

+```

+

+`state` is `"open"` or `"closed"`. `state_reason` is one of

+`"completed"`, `"not_planned"`, `"duplicate"`, `"reopened"`, or

+empty when no reason has been recorded. `closed_at` is present

+only on closed issues.

+

+## List issues

+

+```

+GET /api/v1/repos/{owner}/{repo}/issues

+```

+

+Required scope: `repo:read`. Paginated; `?per_page=` (≤100) and

+`?page=` apply, with the standard `Link:` header.

+

+Optional `?state=open|closed|all` filter; `state=all` (or omitted)

+returns both.

+

+Pull requests are not included on this endpoint — fetch them via

+the pulls surface.

+

+## Get a single issue

+

+```

+GET /api/v1/repos/{owner}/{repo}/issues/{number}

+```

+

+Required scope: `repo:read`. `404` when the issue doesn't exist,

+when the caller can't see the repo, or when `{number}` belongs to

+a pull request (use the pulls surface).

+

+## Create an issue

+

+```

+POST /api/v1/repos/{owner}/{repo}/issues

+```

+

+Required scope: `repo:write`. Policy: `ActionIssueCreate`.

+

+```json

+{ "title": "first bug", "body": "kaboom" }

+```

+

+| Field   | Type   | Notes                                         |

+|---------|--------|-----------------------------------------------|

+| `title` | string | Required, 1–256 chars.                        |

+| `body`  | string | Optional markdown body, ≤65535 chars.         |

+

+Returns `201` with the issue envelope.

+

+### Errors

+

+| Status | When                                              |

+|-------:|---------------------------------------------------|

+|    401 | PAT missing/invalid.                              |

+|    403 | PAT lacks `repo:write` scope or policy denial.    |

+|    422 | Empty title, title too long, body too long.       |

+

+## Update an issue

+

+```

+PATCH /api/v1/repos/{owner}/{repo}/issues/{number}

+```

+

+Required scope: `repo:write`. Only the fields you send are

+modified; everything else stays.

+

+```json

+{

+  "title": "first bug — root cause found",

+  "body": "see comment #3",

+  "state": "closed",

+  "state_reason": "completed"

+}

+```

+

+Permission rules:

+

+- **Title / body** — the issue author OR a repo collaborator with

+  write access. Other callers `403`.

+- **State / state_reason** — any caller with `ActionIssueClose`

+  on the repo. `state_reason` must be one of `completed`,

+  `not_planned`, `duplicate`, `reopened` (or empty).

+

+Returns the freshly-loaded issue.

+

+## Lock and unlock

+

+```

+PUT    /api/v1/repos/{owner}/{repo}/issues/{number}/lock

+DELETE /api/v1/repos/{owner}/{repo}/issues/{number}/lock

+```

+

+Required scope: `repo:write`. PUT body is optional:

+

+```json

+{ "lock_reason": "off-topic" }

+```

+

+Returns `204`. Locking refuses non-collaborator comments; the

+issue itself stays visible.

+

+## Comments

+

+### List

+

+```

+GET /api/v1/repos/{owner}/{repo}/issues/{number}/comments

+```

+

+Required scope: `repo:read`. Returns comments in chronological

+order.

+

+### Add

+

+```

+POST /api/v1/repos/{owner}/{repo}/issues/{number}/comments

+```

+

+Required scope: `repo:write`. Policy: `ActionIssueComment`. Body:

+

+```json

+{ "body": "lgtm" }

+```

+

+Subject to the per-author comment rate limit (20/hour); `429`

+when exceeded.

+

+### Edit own comment

+

+```

+PATCH /api/v1/repos/{owner}/{repo}/issues/comments/{cid}

+```

+

+Required scope: `repo:write`. The comment author can edit their

+own; other callers `403`.

+

+### Delete a comment

+

+```

+DELETE /api/v1/repos/{owner}/{repo}/issues/comments/{cid}

+```

+

+Required scope: `repo:write`. The comment author can delete their

+own; repo collaborators with write access can delete any comment

+on the repo (moderation affordance, matches the gh shape).

+

+Returns `204`.

+

+## Not yet shipped

+

+`POST /api/v1/repos/{o}/{r}/issues/{n}/transfer`, pinning,

+applying labels / assignees / milestones over the issue PATCH —

+all queued for a follow-up batch.

+# Labels

+

+Repo-scoped labels for issues and pull requests. The default

+label set is seeded at repo create and can be edited or removed

+freely.

+

+## Label shape

+

+```json

+{

+  "id": 7,

+  "name": "bug",

+  "color": "ee0701",

+  "description": "Something isn't working",

+  "created_at": "2026-05-12T05:00:00Z"

+}

+```

+

+`color` is six hex chars without the leading `#`.

+

+## List labels

+

+```

+GET /api/v1/repos/{owner}/{repo}/labels

+```

+

+Required scope: `repo:read`. Sorted alphabetically by name.

+

+## Get a single label

+

+```

+GET /api/v1/repos/{owner}/{repo}/labels/{name}

+```

+

+Required scope: `repo:read`. `404` when the label does not exist.

+

+## Create a label

+

+```

+POST /api/v1/repos/{owner}/{repo}/labels

+```

+

+Required scope: `repo:write`. Policy: `ActionIssueLabel`.

+

+```json

+{ "name": "needs-triage", "color": "ff00aa", "description": "triage me" }

+```

+

+| Field         | Type   | Notes                                  |

+|---------------|--------|----------------------------------------|

+| `name`        | string | Required, 1–50 chars.                  |

+| `color`       | string | Required, six hex chars (no `#`).      |

+| `description` | string | Optional, ≤100 chars.                  |

+

+Returns `201`. `409` when the name is already taken on the repo;

+`422` on invalid color or empty name.

+

+## Update a label

+

+```

+PATCH /api/v1/repos/{owner}/{repo}/labels/{name}

+```

+

+Required scope: `repo:write`. Send only the fields you want to

+change. Renaming a label is allowed via `name`.

+

+```json

+{ "color": "00ff00", "description": "ready for triage" }

+```

+

+## Delete a label

+

+```

+DELETE /api/v1/repos/{owner}/{repo}/labels/{name}

+```

+

+Required scope: `repo:write`. Returns `204`. Issue / PR label

+associations cascade away automatically.