Skip to content
GitmoapAPIBeta
Integrateprovider-publishing
POST/providers/{provider_id}/versions/{version}/deprecate

Deprecate a published version

deprecate_provider_version
  • provider_publishing:write
    A token needs the provider_publishing:write scope: Submit and manage provider versionsGranted by write_api.Every operation this scope unlocks
  • Audited · mutation

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

A deprecated version keeps running, but pipelines that use it are warned that it is deprecated, and it can still be the provider's latest version. A sunset version cannot be deprecated: sunset is permanent. Answers with the version's manifest. The publisher that owns the provider, or a platform administrator.

Parameters

Path
  • provider_idProviderId (string)Provider id
  • versionProviderVersion (string)Version

Responses

200application/json
  • capabilitiesarray of CapabilityDescriptor
    • The CapabilityDescriptor schema
    • cache_enabledboolean
    • capability_idCapabilityId (string)
    • config_schemaobjectThe JSON Schema a step's config must satisfy to use this capability.
    • default_timeout_secondsinteger · int320–∞
    • descriptionstring
    • image_uristringThe container image that runs the capability, with an immutable version tag.
    • inputsarray of PortDescriptor
      • The PortDescriptor schema
      • namePortName (string)
      • port_typePortTypegit_refartifactcontainer_imagetest_reportdeployment_refcredentialsevidencevaluecustomSemantic type of the data this port carries. Drives edge type-compatibility in the pipeline builder and validation/routing in the engine.
      • requiredboolean
      • cardinalityPortCardinalityonemanyoptionalHow many sources this input accepts. one by default; many takes several at once.
      • descriptionstring or nulloptionalWhat this port is for, in the provider's own words. Absent on a few older providers.
      • schema_idPortSchemaId (string) or nulloptionalFor a custom port, the id of the schema it carries (e.g. aws.ecs.task-definition/v1). Two custom ports connect only when their schema ids agree, or when either leaves this unset.
    • namestring
    • outputsarray of PortDescriptor
      • The PortDescriptor schema
      • namePortName (string)
      • port_typePortTypegit_refartifactcontainer_imagetest_reportdeployment_refcredentialsevidencevaluecustomSemantic type of the data this port carries. Drives edge type-compatibility in the pipeline builder and validation/routing in the engine.
      • requiredboolean
      • cardinalityPortCardinalityonemanyoptionalHow many sources this input accepts. one by default; many takes several at once.
      • descriptionstring or nulloptionalWhat this port is for, in the provider's own words. Absent on a few older providers.
      • schema_idPortSchemaId (string) or nulloptionalFor a custom port, the id of the schema it carries (e.g. aws.ecs.task-definition/v1). Two custom ports connect only when their schema ids agree, or when either leaves this unset.
    • requires_dockerboolean
    • stage_typeStageTypesourcebuildtestpublishdeploynotifycustomThe pipeline stage a capability belongs to. Maps verbatim to the stage_type field of a capability in gitmoap-provider.yaml.
    • bindablearray of PortName (string)optionalConfig keys that can take their value from an earlier step. Each has an optional value input port of the same name: connect it and read it with {"$from": "<key>"}, or leave it unconnected and write the value yourself.
    • image_digeststring or nulloptionalThe exact build of the capability's container image, when the catalog records one. Pinned so a run cannot pick up a different build behind the same tag.
    • input_groupsarray of PortGroupoptionalRules about which inputs are alternatives to each other. Empty for most capabilities.
      • The PortGroup schema
      • kindPortGroupKindexactly_one_ofat_most_one_ofat_least_one_ofHow many of a group's ports may be connected.
      • portsarray of PortName (string)The member input ports, in the order the author should read them.
      • descriptionstring or nulloptionalWhy these ports constrain each other, in the provider's own words. Rendered beside the group, and repeated in the validation error when the group is unsatisfied — which is the point: the sentence explaining the rule reaches the person who broke it.
    • source_image_refstring or nulloptionalFor a verified provider, the image's location in its publisher's registry before gitmoap copied it. Absent for providers gitmoap builds itself.
  • contract_versioninteger · int320–∞
  • manifest_digeststringThe SHA-256 digest of the version's gitmoap-provider.yaml. May be empty.
  • provider_idProviderId (string)
  • published_atstring
  • published_bystring"platform" for platform-authored providers; a publisher id otherwise.
  • versionProviderVersion (string)
  • changelogMarkdownDoc (string) or nulloptionalThe version's release notes, in Markdown, up to 64 KB. They cannot be changed once published. Absent when the version has none.
  • cosign_signature_refstring or nulloptionalWhere the cosign signature is stored in the registry, when the images are signed.
  • lifecycle_stateVersionLifecycleactivedeprecatedsunsetoptionalWhere the version is in its life: active, deprecated or sunset. Checked whenever a run starts.
  • signedbooleanoptionalWhether the version's images are signed with gitmoap's cosign key, as verified and platform providers' are.
  • sunset_atstring or nulloptionalWhen the version was sunset. Set only for a sunset version.
  • sunset_enforced_atstring or nulloptionalWhen the sunset's grace period ends. After it, a run that uses the version fails to start.
200 exampleSynthesized example
{
"capabilities": [
{
"cache_enabled": false,
"capability_id": "a571b54b-6179-4af6-b270-fc3f46edc0d4",
"config_schema": {},
"default_timeout_seconds": 61,
"description": "Renders each region as density contours of its operations.",
"image_uri": "https://gitmoap.example/acme/358be713",
"inputs": [],
"name": "payments-api",
"outputs": [],
"requires_docker": false,
"stage_type": "source"
}
],
"contract_version": 27,
"manifest_digest": "manifest-digest-2c93",
"provider_id": "d84ae278-883e-44a9-a553-7d92a6e818c6",
"published_at": "2026-10-11T16:30:17Z",
"published_by": "a3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"version": "version-07cf",
"changelog": "changelog-a23f",
"cosign_signature_ref": "cosign-signature-ref-4746",
"lifecycle_state": "active",
"signed": false,
"sunset_at": "2026-10-08T19:14:23Z",
"sunset_enforced_at": "2026-10-10T10:17:04Z"
}
400Bad request — a path parameter is not a well-formed value of its typeapplication/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-47cb",
"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-eef7",
"message": "Inline scalar newtypes but keep their brand"
}
}
403application/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-a551",
"message": "Inline scalar newtypes but keep their brand"
}
}
404application/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-5192",
"message": "Stream pipeline status into the run header"
}
}
409application/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-c43c",
"message": "Label every synthesized example"
}
}

CLI

gitmoap provider-publishing deprecate-provider-version

  • --provider-ididProvider id
  • --versionidVersion

Used in these guides