POST/repositories/{repo_id}/issues

File a work item in a repository

create_issue

issue:create
A token needs the issue:create scope: File work itemsGranted by mcp_agent_write, write_api, write_repository.Every operation this scope unlocks
Audited · mutation
x-gitmoap-audit: {"kind":"audited","arg":"mutation"}
Quota · open issues per scope
x-gitmoap-quota: {"kind":"enforced","arg":"open_issues_per_scope"}

Files a work item in the repository. Only a title is required; the type, status, assignees, labels, milestone, points, severity and parent are optional. The work item is numbered within the repository, and that number is how other operations and references name it.

Parameters

Path

repo_idRepositoryId (string · uuid)Repository ID

Request body

application/json

titleIssueTitle (string)
assignee_idsarray of PrincipalId (string · uuid)optional
descriptionMarkdownDoc (string) or nulloptional
labelsarray of LabelKey (string)optional
milestone_idMilestoneId (string · uuid) or nulloptional
parent_refIssueRef or nulloptional
- The IssueRef schema
- iidIssueId (integer · int64)
- scopeScopeRef
pointsinteger · int32 or nulloptional0–∞
severitySeveritycriticalhighmediumlowor nulloptional
status_idStatusId (string) or nulloptionalDefaults to the effective status set's default status.
type_profileBlueprintRef or nulloptionalFile the item as a custom type, naming a blueprint defined where the item is filed or on a group above it. The blueprint's base type replaces work_item_type, and the item is created with the blueprint's facets already added to its Definition of Done as criteria.
- The BlueprintRef schema
- blueprint_idBlueprintId (string)
- scopeScopeRef
work_item_typeWorkItemTypeepicstorybugtaskspikechoreincidentsub_taskor nulloptionalDefaults to the scope's effective default_issue_type.

Request body exampleSynthesized example

Responses

201Work item createdapplication/json

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.

201 exampleSynthesized example

400Invalid requestapplication/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

403Caller may not file hereapplication/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 foundapplication/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

409The parent's type may not parent this typeapplication/json

Error codes

CONFLICTThe request conflicts with the resource's current state; reason says how
LEGAL_ACCEPTANCE_REQUIREDAccept the current Terms of Service before changing anything; reading stays open

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.

409 exampleSynthesized example

429Open work-item limit reachedapplication/json

Error codes

TOO_MANY_REQUESTSRetryableA quota, a rate limit or a transfer budget is spent. When the response carries Retry-After, retry after that many seconds

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.

429 exampleSynthesized example

CLI

gitmoap issues create

--repo-ididRepository ID (id or owner/repo path)
--assignee-idsjsonoptional
--descriptionstringoptional
--labelsjsonoptional
--milestone-idstringoptional
--parent-refjsonoptional
--pointsnumberoptional
--severitycritical | high | medium | lowoptional
--status-idstringoptional
--titlestring
--type-profilejsonoptional
--work-item-typeepic | story | bug | task | spike | chore | incident | sub_taskoptional

Used in these guides

Work items

Request

curl -X POST "https://api.gitmoap.com/repositories//issues" \
  -H "Authorization: Bearer $GITMOAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": ""
  }'

gitmoap issues create \
  --repo-id  \
  --title

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.POST("/repositories/{repo_id}/issues", {
  params: {
    path: { repo_id: "" },
  },
  body: {
    title: ""
  },
});

POST /repositories//issues HTTP/1.1
Host: api.gitmoap.com
Authorization: Bearer $GITMOAP_TOKEN
Content-Type: application/json

{
  "title": ""
}

⌘↵

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