GET/repositories/{repo_id}/issues

List a repository's work items

list_issues

issue:read
A token needs the issue:read scope: Read work items and their settingsGranted by mcp_agent, mcp_agent_write, read_api, read_repository, write_api, write_repository.Every operation this scope unlocks
Single-resource
x-gitmoap-isolation: {"kind":"single_or_self_scoped"}
Paginated
Pass the next_token a page returns to get the next one.

Returns the repository's work items a page at a time, most recently updated first. Filter by status category or status, type, assignee, label or milestone, and use search to find words in the title or description; an invalid filter value is refused rather than ignored. Anyone who can see the repository's work items may list them — on a public repository, without signing in.

Parameters

Path

repo_idRepositoryId (string · uuid)Repository ID

Query

status_categorystringoptionalStatus category — triage, todo, in_progress, in_review, blocked, done or cancelled
status_idstringoptionalThe named status within its category
typestringoptionalWork-item type
assigneestringoptionalAssigned principal
labelstringoptionalLabel key
milestonestringoptionalMilestone ID
searchstringoptionalWords to find in the title or description, or part of the title
limitinteger · int32optionalPage size (default 20, max 100)
next_tokenstringoptionalPagination cursor

Responses

200The work items, newest-updated firstapplication/json

itemsarray of object
- created_atstring
- created_byActorSummaryWho created the work item, as they were when they created it.
  - The ActorSummary schema
  - emailstring
  - idstring
  - usernamestring
  - avatar_urlstring or nulloptional
- iidIssueId (integer · int64)
- root_scope_idGroupId (string · uuid)The top-level group the item's group or repository belongs to.
- scope_idstring
- scope_typeScopeTypegrouprepositoryWhether the item lives in a group or a repository. With scope_id and iid it forms the item's current address — the #412 a person types — which changes when the item moves.
- status_categoryStatusCategorytriagetodoin_progressin_reviewblockeddonecancelledThe fixed category of the item's current status, which boards, filters and progress rollups work from.
- status_idStatusId (string)
- titleIssueTitle (string)
- uidIssueUid (string · uuid)The work item's permanent identifier. Unlike its number, it never changes, even when the item moves to another group or repository.
- updated_atstringWhen the work item last changed, ISO 8601. Listings order by it, newest first.
- work_item_typeWorkItemTypeepicstorybugtaskspikechoreincidentsub_taskThe kind of work item. The type decides where an item may live (a group or a repository), which types it may have as children, and which fields it accepts.
- ancestor_group_idsarray of GroupId (string · uuid)optionalThe groups the item sits beneath, nearest first.
- ancestor_issue_uidsarray of IssueUid (string · uuid)optionalThe item's ancestors' permanent identifiers, nearest first, for display. It can briefly lag behind a change of parent higher up the chain.
- assignee_idsarray of PrincipalId (string · uuid)optionalThe people assigned to the work item. Absent when nobody is.
- author_can_pushboolean or nulloptionalWhether the author can push to where this work item lives — its repository, or a group work item's group. False for a drive-by contributor's text. Absent where it was not computed.
- closed_atstring or nulloptional
- closed_byPrincipalId (string · uuid) or nulloptional
- descriptionMarkdownDoc (string) or nulloptional
- labelsarray of LabelKey (string)optionalThe keys of the labels applied to the work item. Absent when it has none.
- milestone_idMilestoneId (string · uuid) or nulloptional
- milestone_scope_idstring or nulloptional
- milestone_scope_typeScopeTypegrouprepositoryor nulloptionalWhether the item's milestone belongs to a group or a repository — not necessarily the item's own, since a group milestone can hold work items from several repositories.
- parent_refIssueRef or nulloptionalThe parent's current address, for display. Absent when the item has no parent.
  - The IssueRef schema
  - iidIssueId (integer · int64)
  - scopeScopeRef
- parent_uidIssueUid (string · uuid) or nulloptionalThe parent work item's permanent identifier, if the item has a parent.
- pointsinteger · int32 or nulloptional0–∞
- regressed_atstring or nulloptional
- regressed_at_shaCommitHash (string) or nulloptionalThe commit whose evidence proved the regression — the first known bad commit, and the upper end of the range of suspect commits.
- regressed_from_shaCommitHash (string) or nulloptionalThe commit at which the item was last verified, kept when it regresses — the last known good commit.
- regressed_run_idPipelineRunId (string · uuid) or nulloptional
- severitySeveritycriticalhighmediumlowor nulloptional
- type_profileBlueprintRef or nulloptionalThe custom type this item was filed as, pointing at the group or repository where the blueprint is defined. work_item_type still decides where the item may live, its children and its fields; the blueprint adds a display label and facets. Absent for an item filed as a plain built-in type.
  - The BlueprintRef schema
  - blueprint_idBlueprintId (string)
  - scopeScopeRef
- verificationVerificationStateunverifiedverifiedregressedoptionalWhether CI has proved the work item's acceptance criteria. unverified until a pipeline run proves them, verified once one has, and regressed when a later run shows that evidence no longer holds.
- verified_atstring or nulloptional
- verified_at_shaCommitHash (string) or nulloptionalThe commit at which CI proved the acceptance criteria. Absent until a pipeline run has.
- verified_run_idPipelineRunId (string · uuid) or nulloptional
- versioninteger · int64optional0–∞The work item's revision, incremented on every change. Send it back with an update; if the item has changed since you read it, the update is refused with a 409.
next_tokenstring or nulloptional

200 exampleSynthesized example

400Invalid filter or cursorapplication/json

Error codes

BAD_REQUESTThe request is malformed: a parameter or a body field is not a well-formed value of its type

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

400 exampleSynthesized example

401Unauthenticated — no credential, or an invalid oneapplication/json

Error codes

UNAUTHORIZEDNo credential was sent, or the one sent is invalid, expired or revoked

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

401 exampleSynthesized example

403Forbidden — the caller's access level or token scope is insufficientapplication/json

Error codes

FORBIDDENYou are signed in but may not do this here; reason names the permission or the rule that refused it
INSUFFICIENT_SCOPEThe access token lacks the scope this operation needs; required_scope names it
PERMISSION_REQUIREDYou need a permission you do not hold here; the message names it

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

403 exampleSynthesized example

404Repository not found, or private with no accessapplication/json

Error codes

NOT_FOUNDThe resource does not exist — or exists and you cannot see it: a private resource you have no access to answers exactly as an absent one does

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

404 exampleSynthesized example

CLI

gitmoap issues list

--repo-ididRepository ID (id or owner/repo path)
--assigneestringoptionalAssigned principal
--labelstringoptionalLabel key
--limitnumberoptionalPage size (default 20, max 100)
--milestonestringoptionalMilestone ID
--next-tokenstringoptionalPagination cursor
--searchstringoptionalWords to find in the title or description, or part of the title
--status-categorystringoptionalStatus category — triage, todo, in_progress, in_review, blocked, done or cancelled
--status-idstringoptionalThe named status within its category
--typestringoptionalWork-item type

Used in these guides

Work items

Request

curl "https://api.gitmoap.com/repositories//issues" \
  -H "Authorization: Bearer $GITMOAP_TOKEN"

gitmoap issues list \
  --repo-id

import { createApiClient } from "@gitmoap/backend-types";

const client = createApiClient({
  baseUrl: "https://api.gitmoap.com",
  headers: { Authorization: `Bearer ${process.env.GITMOAP_TOKEN}` },
});

const { data, error } = await client.GET("/repositories/{repo_id}/issues", {
  params: {
    path: { repo_id: "" },
  },
});

GET /repositories//issues HTTP/1.1
Host: api.gitmoap.com
Authorization: Bearer $GITMOAP_TOKEN

⌘↵

Send to see the sandbox's answer. Nothing leaves your browser.