Skip to content
GitmoapAPIBeta
Planissue-blueprints
PUT/groups/{group_id}/issue-blueprints/{blueprint_id}

Replace a group's custom type

update_group_blueprint
  • issue_blueprint:manage
    A token needs the issue_blueprint:manage scope: Define and remove custom work-item types (blueprints)Granted by write_api, write_repository.Every operation this scope unlocks
  • Audited · mutation

    x-gitmoap-audit: {"kind":"audited","arg":"mutation"}

Replaces the type's name, base type, description, facets and archived flag in one go. Send the version you last read: if the type has changed since, the update is refused, so read it again and retry. Work items already filed as the type are not changed. Maintainers and above may update types.

Parameters

Path
  • group_idGroupId (string · uuid)Group ID
  • blueprint_idBlueprintId (string)Blueprint id (slug)

Request body

application/json
  • base_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.
  • namestring
  • versioninteger · int640–∞The version you last read. The update is refused with a 409 if the blueprint changed since.
  • archivedbooleanoptional
  • descriptionstring or nulloptional
  • facetsarray of FacetTemplateoptional
    • The FacetTemplate schema
    • categoryFacetCategory (string)The facet's category — any value you choose. Facets with the same category are grouped together.
    • keyFacetKey (string)The facet's identifier within the blueprint. It stays the same when the label changes, so a work item re-applying the blueprint updates the facet in place.
    • labelstringThe facet's display name, such as "Observability".
    • bindingFacetBindingTemplateoptionalHow the seeded criterion is bound. Defaults to a manual checkbox.
    • hintstring or nulloptionalThe starter criterion's text. When absent the criterion is titled by the facet label.
    • requiredbooleanoptionalWhether the facet's criterion must be satisfied before the work item can be closed or verified. Defaults to true.
Request body exampleSynthesized example
{
"base_type": "epic",
"name": "payments-api",
"version": 80
}

Responses

200The updated blueprintapplication/json
  • base_typeWorkItemTypeepicstorybugtaskspikechoreincidentsub_taskThe built-in type the custom type is based on, which decides where its items may live, their children and their fields. "API Feature" might be a story with a blueprint on top.
  • blueprint_idBlueprintId (string)The blueprint's slug, unique within its group or repository. It never changes.
  • created_atstring
  • created_byActorSummaryWho created the blueprint, as they were when they created it.
  • namestringThe custom type's display name, such as "API Feature".
  • scope_idstring
  • scope_typeScopeTypegrouprepository
  • updated_atstring
  • archivedbooleanoptionalHidden from the type picker; items already filed keep their type_profile.
  • descriptionstring or nulloptional
  • facetsarray of FacetTemplateoptionalThe blueprint's facets, in order.
    • The FacetTemplate schema
    • categoryFacetCategory (string)The facet's category — any value you choose. Facets with the same category are grouped together.
    • keyFacetKey (string)The facet's identifier within the blueprint. It stays the same when the label changes, so a work item re-applying the blueprint updates the facet in place.
    • labelstringThe facet's display name, such as "Observability".
    • bindingFacetBindingTemplateoptionalHow the seeded criterion is bound. Defaults to a manual checkbox.
    • hintstring or nulloptionalThe starter criterion's text. When absent the criterion is titled by the facet label.
    • requiredbooleanoptionalWhether the facet's criterion must be satisfied before the work item can be closed or verified. Defaults to true.
  • versioninteger · int64optional0–∞The blueprint's revision, incremented on every change. An update must send the version it read, and is refused with a 409 if the blueprint changed since.
200 exampleSynthesized example
{
"base_type": "epic",
"blueprint_id": "7ab5f143-c16d-4e00-aacf-9c88f62adc2e",
"created_at": "2026-10-10T20:56:34Z",
"created_by": {
"email": "mara@acme.example",
"id": "id-25e5",
"username": "lin",
"avatar_url": "https://gitmoap.example/acme/cf74a3c2"
},
"name": "payments-api",
"scope_id": "d2dd1eab-2e52-4787-9847-73b14cabd80c",
"scope_type": "group",
"updated_at": "2026-10-11T09:10:57Z",
"archived": false,
"description": "Renders each region as density contours of its operations.",
"facets": [
{
"category": "category-28f2",
"key": "key-fa7e",
"label": "label-5760"
}
],
"version": 59
}
400Invalid facetsapplication/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
{
"error": {
"code": "code-5a7d",
"message": "Draw the region map from operation density"
}
}
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
{
"error": {
"code": "code-7b10",
"message": "Inline scalar newtypes but keep their brand"
}
}
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
{
"error": {
"code": "code-0a77",
"message": "Draw the region map from operation density"
}
}
404Blueprint 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
{
"error": {
"code": "code-de47",
"message": "Stream pipeline status into the run header"
}
}
409The blueprint was modified concurrentlyapplication/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
{
"error": {
"code": "code-9f8e",
"message": "Label every synthesized example"
}
}

CLI

gitmoap issue-blueprints update-group-blueprint

  • --group-ididGroup ID (id or group path)
  • --blueprint-ididBlueprint id (slug)
  • --archivedflagoptional
  • --base-typeepic | story | bug | task | spike | chore | incident | sub_task
  • --descriptionstringoptional
  • --facetsjsonoptional
  • --namestring
  • --versionnumberThe `version` you last read. The update is refused with a `409` if the blueprint changed since.

Used in these guides