PUT/providers/{provider_id}/listing

Set the marketplace listing for a provider you own

set_provider_listing

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"}

Edits the provider's marketplace page: its README, homepage and repository links, usage examples, and the categories and keywords it is found by. A field you leave out is unchanged and an explicit null clears it; categories, when sent, cannot be empty. Answers with the updated page. Only the publisher that owns the provider may edit it.

Parameters

Path

provider_idProviderId (string)Provider slug

Request body

application/json

categoriesarray of Category: one of source-control | build | test | quality | security | release | deploy | infrastructure | notify | other or nulloptionalThe categories to list the provider under, one to three. Replaces the current ones.
examplesarray of ProviderExample or nulloptionalUsage examples, up to 10. Replaces the current ones; [] removes them all.
- The ProviderExample schema
- capability_idsarray of CapabilityId (string)The capabilities this example exercises; each must exist in some published version of the provider (validated at write time).
- descriptionstringOne- or two-sentence summary (<= 500 chars).
- snippetstringA pipeline YAML/JSON fragment (<= 8 KB).
- titlestringShort heading (<= 120 chars).
homepage_urlHttpsUrl (string) or nulloptional
keywordsarray of Keyword (string) or nulloptionalSearch keywords, up to 10. Replaces the current ones; [] removes them all.
readmeMarkdownDoc (string) or nulloptionalThe listing's README, in Markdown. null removes it.
repository_urlHttpsUrl (string) or nulloptional

Request body exampleSynthesized example

Responses

200Updated listing detailapplication/json

categoriesarray of Category: one of source-control | build | test | quality | security | release | deploy | infrastructure | notify | other
examplesarray of ProviderExample
- The ProviderExample schema
- capability_idsarray of CapabilityId (string)The capabilities this example exercises; each must exist in some published version of the provider (validated at write time).
- descriptionstringOne- or two-sentence summary (<= 500 chars).
- snippetstringA pipeline YAML/JSON fragment (<= 8 KB).
- titlestringShort heading (<= 120 chars).
keywordsarray of Keyword (string)
namespace_verifiedboolean
providerMarketplaceProviderCard
- The MarketplaceProviderCard schema
- categoriesarray of Category: one of source-control | build | test | quality | security | release | deploy | infrastructure | notify | other
- created_atstring
- descriptionstring
- idProviderId (string)
- keywordsarray of Keyword (string)
- namestring
- namespace_verifiedbooleanWhether the provider's publisher has verified its namespace. false for providers gitmoap builds itself, which have no publisher.
- signedbooleanWhether the latest version's images are signed by gitmoap, as platform and verified providers' are.
- tierProviderTierplatformverifiedcommunityprivateHow a pipeline provider is distributed and how much it is vouched for.
- updated_atstring
- visibilityProviderVisibility
- featured_rankinteger · int32 or nulloptional0–∞Where gitmoap features the provider: lower numbers are placed higher. Absent when it is not featured.
- install_countinteger · int64 or nulloptional0–∞How many organizations have installed the provider. Absent for providers gitmoap builds itself.
- latest_versionProviderVersion (string) or nulloptional
- lifecycle_stateVersionLifecycleactivedeprecatedsunsetor nulloptionalWhere the latest version is in its life: active, deprecated or sunset.
- publisher_idPublisherId (string · uuid) or nulloptional
versionsarray of ListingVersionView
- The ListingVersionView schema
- lifecycle_stateVersionLifecycleactivedeprecatedsunsetLifecycle state of a published ProviderVersionManifest. Active is the default; Deprecated still runs but the trigger-time validator surfaces a warning; Sunset runs only inside its grace window, after which a trigger referencing it fails validation.
- published_atstring
- published_bystring
- sbom_availablebooleanWhether a software bill of materials (SBOM) is available for this version, as it is for platform and verified providers.
- signedboolean
- versionProviderVersion (string)
- changelogMarkdownDoc (string) or nulloptional
homepage_urlHttpsUrl (string) or nulloptional
install_countinteger · int64 or nulloptional0–∞
publisherPublisherBadge or nulloptional
- The PublisherBadge schema
- display_namestring
- namespacePublisherNamespace (string)
- publisher_idPublisherId (string · uuid)
- verifiedboolean
- verification_methodVerificationMethodmanualdnsgithubor nulloptionalHow the publisher was verified, so you can judge how strong the check was. Absent until verified.
- verification_targetstring or nulloptional
readmeMarkdownDoc (string) or nulloptional
repository_urlHttpsUrl (string) or nulloptional

200 exampleSynthesized example

400application/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

401application/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

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

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

409The request conflicts with the resource's current state; `reason` says howapplication/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

CLI

gitmoap provider-catalog set-provider-listing

--provider-ididProvider slug
--categoriesjsonoptionalThe categories to list the provider under, one to three. Replaces the current ones.
--examplesjsonoptionalUsage examples, up to 10. Replaces the current ones; `[]` removes them all.
--homepage-urlstringoptional
--keywordsjsonoptionalSearch keywords, up to 10. Replaces the current ones; `[]` removes them all.
--readmestringoptional
--repository-urlstringoptional

Used in these guides

Using providers

Request

curl -X PUT "https://api.gitmoap.com/providers//listing" \
  -H "Authorization: Bearer $GITMOAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

gitmoap provider-catalog set-provider-listing \
  --provider-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.PUT("/providers/{provider_id}/listing", {
  params: {
    path: { provider_id: "" },
  },
  body: {},
});

PUT /providers//listing HTTP/1.1
Host: api.gitmoap.com
Authorization: Bearer $GITMOAP_TOKEN
Content-Type: application/json

{}

⌘↵

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