REST API

Specification accepted and stored — or, for retired: true, the family retired. The two answer different objects; a caller knows which it sent.

Header Sanshain-Warning: A warning the caller's build should print — the call itself succeeded. Sent once per warning (the header may appear several times). The value is plain ASCII: any other character, e.g. from a tag name, is escaped as \u{XXXX} (its Unicode code point in hex, at least four digits). The graph is informational and never fails a build: an unknown tag (no sanshain-branch '<name>' - this build was not recorded in a release graph), trunk and tag together (trunk and tag are mutually exclusive - this build was recorded in neither), or a catalog push that recorded nothing (the reason). Clients fail on it only in strict mode.

Example 202 response (recorded from a live instance)

{
  "version": "1.0.0",
  "stability": "snapshot",
  "content_hash": "sha256:c79fec9c98fc8f883b24e080ef5f3a19644c5200c82362f06122186585d4574b",
  "changes": {
    "inserts": 2,
    "updates": 0,
    "deletes": 0
  },
  "promoted": false
}

Invalid request — malformed spec YAML, a missing/non-semver info.version, or two paths that are the same endpoint after normalization (differing only in a path-parameter name, a trailing slash, or doubled separators).

stability: ga without the release_ga permission. Releasing is a role: grant releaser to the publishing user or token (admins and root always may), or publish as a snapshot.

Also retired: true without the release_ga permission and without a maintainer grant on this Producer. Retiring is a role for the same reason releasing is — see ProvidePayload.retired.

Also any request with a read_only API token — see the ReadOnlyToken response.

Rejected by the version rules. The body carries proposed_version, the next free version to publish as instead. Every rejection is self-service — fix the version and republish.

Example 409 response (recorded from a live instance)

{
  "error": "version 1.0.0 of openapi 'payments' is GA and immutable, but the submitted content differs — did you forget to increment info's version? Publish as 1.1.0 instead",
  "proposed_version": "1.1.0"
}

Request body exceeds the configured size limit (MAX_SPEC_BODY_BYTES, default 4 MiB).

Request body has the wrong shape — missing stability, or unknown (1.x) fields such as branch, base_version or force, which are rejected by name rather than silently ignored.

Specification accepted and stored — or, for retired: true, the family retired. The two answer different objects; a caller knows which it sent.

Header Sanshain-Warning: A warning the caller's build should print — the call itself succeeded. Sent once per warning (the header may appear several times). The value is plain ASCII: any other character, e.g. from a tag name, is escaped as \u{XXXX} (its Unicode code point in hex, at least four digits). The graph is informational and never fails a build: an unknown tag (no sanshain-branch '<name>' - this build was not recorded in a release graph), trunk and tag together (trunk and tag are mutually exclusive - this build was recorded in neither), or a catalog push that recorded nothing (the reason). Clients fail on it only in strict mode.

Example 202 response (placeholder values derived from the schema)

{
  "version": "string",
  "stability": "snapshot",
  "content_hash": "string",
  "changes": {
    "inserts": 0,
    "updates": 0,
    "deletes": 0
  },
  "promoted": false,
  "harvested_subscriptions": [
    {
      "channel": "string",
      "message_name": "string",
      "owner": "string",
      "drift": "string"
    }
  ]
}

Invalid request (e.g. malformed YAML, bad version).

stability: ga without the release_ga permission, or retired: true without it and without a maintainer grant on this Producer (see /provide), or a read_only API token (see the ReadOnlyToken response).

Rejected by the version rules (see /provide), or by a channel message contract owned by another Producer with a different schema.

Request body exceeds the configured size limit (MAX_SPEC_BODY_BYTES, default 4 MiB).

Specification accepted and stored — or, for retired: true, the family retired. The two answer different objects; a caller knows which it sent.

Header Sanshain-Warning: A warning the caller's build should print — the call itself succeeded. Sent once per warning (the header may appear several times). The value is plain ASCII: any other character, e.g. from a tag name, is escaped as \u{XXXX} (its Unicode code point in hex, at least four digits). The graph is informational and never fails a build: an unknown tag (no sanshain-branch '<name>' - this build was not recorded in a release graph), trunk and tag together (trunk and tag are mutually exclusive - this build was recorded in neither), or a catalog push that recorded nothing (the reason). Clients fail on it only in strict mode.

Example 202 response (placeholder values derived from the schema)

{
  "version": "string",
  "stability": "snapshot",
  "content_hash": "string",
  "changes": {
    "inserts": 0,
    "updates": 0,
    "deletes": 0
  },
  "promoted": false,
  "harvested_subscriptions": [
    {
      "channel": "string",
      "message_name": "string",
      "owner": "string",
      "drift": "string"
    }
  ]
}

Invalid request (e.g. missing sanshain-version marker).

stability: ga without the release_ga permission, or retired: true without it and without a maintainer grant on this Producer (see /provide), or a read_only API token (see the ReadOnlyToken response).

Rejected by the version rules (see /provide).

Request body exceeds the configured size limit (MAX_SPEC_BODY_BYTES, default 4 MiB).

The endpoint snippet as YAML.

Header Sanshain-Warning: A warning the caller's build should print — the call itself succeeded. Sent once per warning (the header may appear several times). The value is plain ASCII: any other character, e.g. from a tag name, is escaped as \u{XXXX} (its Unicode code point in hex, at least four digits). The graph is informational and never fails a build: an unknown tag (no sanshain-branch '<name>' - this build was not recorded in a release graph), trunk and tag together (trunk and tag are mutually exclusive - this build was recorded in neither), or a catalog push that recorded nothing (the reason). Clients fail on it only in strict mode.

Example 200 response (recorded from a live instance)

openapi: 3.0.3
info:
  title: Payments
  version: 1.0.0
paths:
  /payments:
    post:
      summary: Create a payment
      responses:
        '201':
          description: Created

Not modified (ETag match).

Header Sanshain-Warning: A warning the caller's build should print — the call itself succeeded. Sent once per warning (the header may appear several times). The value is plain ASCII: any other character, e.g. from a tag name, is escaped as \u{XXXX} (its Unicode code point in hex, at least four digits). The graph is informational and never fails a build: an unknown tag (no sanshain-branch '<name>' - this build was not recorded in a release graph), trunk and tag together (trunk and tag are mutually exclusive - this build was recorded in neither), or a catalog push that recorded nothing (the reason). Clients fail on it only in strict mode.

The request carried an API token with scope read_only. Such a token may read — reports, /producers/{producername}/versions, /endpoint-versions, the update streams and the MCP endpoint — but never provide, retire, require or push a catalog. error names the token's scope and the scope the call needs (full).

Example 403 response (recorded from a live instance)

{
  "error": "this API token has scope 'read_only' and may not change the catalog; create a token with scope 'full' for provide, require and catalog pushes"
}

Unknown — the Producer, or the pinned version, does not exist in either stability. Fails in milliseconds; nothing waits for a version to appear.

Absent — the pinned version exists and deliberately does not include this endpoint. Provided specs are complete, so absence is a definitive no, distinct from an unknown version.

The channel snippet as YAML, or with format=openapi the OpenAPI 3.0.3 document of its payload schemas.

Header Sanshain-Warning: A warning the caller's build should print — the call itself succeeded. Sent once per warning (the header may appear several times). The value is plain ASCII: any other character, e.g. from a tag name, is escaped as \u{XXXX} (its Unicode code point in hex, at least four digits). The graph is informational and never fails a build: an unknown tag (no sanshain-branch '<name>' - this build was not recorded in a release graph), trunk and tag together (trunk and tag are mutually exclusive - this build was recorded in neither), or a catalog push that recorded nothing (the reason). Clients fail on it only in strict mode.

Not modified (ETag match).

Header Sanshain-Warning: A warning the caller's build should print — the call itself succeeded. Sent once per warning (the header may appear several times). The value is plain ASCII: any other character, e.g. from a tag name, is escaped as \u{XXXX} (its Unicode code point in hex, at least four digits). The graph is informational and never fails a build: an unknown tag (no sanshain-branch '<name>' - this build was not recorded in a release graph), trunk and tag together (trunk and tag are mutually exclusive - this build was recorded in neither), or a catalog push that recorded nothing (the reason). Clients fail on it only in strict mode.

An unknown format, or the spec cannot be converted with format=openapi: two different schemas would get the same name, a message payload has a non-AsyncAPI schemaFormat (e.g. Avro), a $ref is external or does not resolve, or an inline payload has no message key to be named after.

The request carried an API token with scope read_only. Such a token may read — reports, /producers/{producername}/versions, /endpoint-versions, the update streams and the MCP endpoint — but never provide, retire, require or push a catalog. error names the token's scope and the scope the call needs (full).

Example 403 response (recorded from a live instance)

{
  "error": "this API token has scope 'read_only' and may not change the catalog; create a token with scope 'full' for provide, require and catalog pushes"
}

Unknown Producer or version.

The pinned version deliberately lacks this channel.

The .proto snippet.

Header Sanshain-Warning: A warning the caller's build should print — the call itself succeeded. Sent once per warning (the header may appear several times). The value is plain ASCII: any other character, e.g. from a tag name, is escaped as \u{XXXX} (its Unicode code point in hex, at least four digits). The graph is informational and never fails a build: an unknown tag (no sanshain-branch '<name>' - this build was not recorded in a release graph), trunk and tag together (trunk and tag are mutually exclusive - this build was recorded in neither), or a catalog push that recorded nothing (the reason). Clients fail on it only in strict mode.

Not modified (ETag match).

Header Sanshain-Warning: A warning the caller's build should print — the call itself succeeded. Sent once per warning (the header may appear several times). The value is plain ASCII: any other character, e.g. from a tag name, is escaped as \u{XXXX} (its Unicode code point in hex, at least four digits). The graph is informational and never fails a build: an unknown tag (no sanshain-branch '<name>' - this build was not recorded in a release graph), trunk and tag together (trunk and tag are mutually exclusive - this build was recorded in neither), or a catalog push that recorded nothing (the reason). Clients fail on it only in strict mode.

The request carried an API token with scope read_only. Such a token may read — reports, /producers/{producername}/versions, /endpoint-versions, the update streams and the MCP endpoint — but never provide, retire, require or push a catalog. error names the token's scope and the scope the call needs (full).

Example 403 response (recorded from a live instance)

{
  "error": "this API token has scope 'read_only' and may not change the catalog; create a token with scope 'full' for provide, require and catalog pushes"
}

Unknown Producer or version.

The pinned version deliberately lacks this method.

The merged specification as YAML, or with format=openapi the OpenAPI 3.0.3 document of the channels' payload schemas.

Header Sanshain-Warning: A warning the caller's build should print — the call itself succeeded. Sent once per warning (the header may appear several times). The value is plain ASCII: any other character, e.g. from a tag name, is escaped as \u{XXXX} (its Unicode code point in hex, at least four digits). The graph is informational and never fails a build: an unknown tag (no sanshain-branch '<name>' - this build was not recorded in a release graph), trunk and tag together (trunk and tag are mutually exclusive - this build was recorded in neither), or a catalog push that recorded nothing (the reason). Clients fail on it only in strict mode.

Not modified (ETag match).

Header Sanshain-Warning: A warning the caller's build should print — the call itself succeeded. Sent once per warning (the header may appear several times). The value is plain ASCII: any other character, e.g. from a tag name, is escaped as \u{XXXX} (its Unicode code point in hex, at least four digits). The graph is informational and never fails a build: an unknown tag (no sanshain-branch '<name>' - this build was not recorded in a release graph), trunk and tag together (trunk and tag are mutually exclusive - this build was recorded in neither), or a catalog push that recorded nothing (the reason). Clients fail on it only in strict mode.

format with an api_type other than asyncapi (the default is openapi), an unknown format, or a spec format=openapi cannot convert (see /require/asyncapi).

The request carried an API token with scope read_only. Such a token may read — reports, /producers/{producername}/versions, /endpoint-versions, the update streams and the MCP endpoint — but never provide, retire, require or push a catalog. error names the token's scope and the scope the call needs (full).

Example 403 response (recorded from a live instance)

{
  "error": "this API token has scope 'read_only' and may not change the catalog; create a token with scope 'full' for provide, require and catalog pushes"
}

Unknown Producer or version.

The pinned version deliberately lacks one or more requested endpoints.

The periphery now recorded for the system (recorded: true).

When the file is not valid YAML, a document in it is not a Backstage entity, it has no (or more than one) Component named systemname, or its dependsOn is not a list of entity refs, the answer is still 200, with resources: [] and recorded: false: nothing is recorded — neither periphery nor context — the system's previous state stays as it was, and a Sanshain-Warning header names the reason.

Header Sanshain-Warning: A warning the caller's build should print — the call itself succeeded. Sent once per warning (the header may appear several times). The value is plain ASCII: any other character, e.g. from a tag name, is escaped as \u{XXXX} (its Unicode code point in hex, at least four digits). The graph is informational and never fails a build: an unknown tag (no sanshain-branch '<name>' - this build was not recorded in a release graph), trunk and tag together (trunk and tag are mutually exclusive - this build was recorded in neither), or a catalog push that recorded nothing (the reason). Clients fail on it only in strict mode.

Example 200 response (recorded from a live instance)

{
  "system": "payments",
  "trunk": true,
  "resources": [
    "resource:default/bank-gateway",
    "resource:default/payments-db"
  ],
  "recorded": true
}

The request carried an API token with scope read_only. Such a token may read — reports, /producers/{producername}/versions, /endpoint-versions, the update streams and the MCP endpoint — but never provide, retire, require or push a catalog. error names the token's scope and the scope the call needs (full).

Example 403 response (recorded from a live instance)

{
  "error": "this API token has scope 'read_only' and may not change the catalog; create a token with scope 'full' for provide, require and catalog pushes"
}

Request body exceeds the configured size limit (MAX_SPEC_BODY_BYTES, default 4 MiB).

Request body has the wrong shape (missing catalog_info_yaml, unknown fields).

The version-line entries, API types grouped, newest first.

Example 200 response (recorded from a live instance)

[
  {
    "api_type": "openapi",
    "version": "1.0.0",
    "stability": "snapshot",
    "content_hash": "sha256:c79fec9c98fc8f883b24e080ef5f3a19644c5200c82362f06122186585d4574b",
    "provided_by": "root",
    "created_at": "2026-10-18T16:07:53Z",
    "updated_at": "2026-10-18T16:07:53Z",
    "last_required_at": null,
    "endpoint_count": 2,
    "expires_at": "2026-11-17T16:07:53Z",
    "trunk_provided_at": "2026-10-18T16:07:53Z"
  }
]

Unknown Producer.

The report; scope_label names the selected scope.

Example 200 response (recorded from a live instance)

{
  "unused_endpoints": [],
  "missing_endpoints": [],
  "dependency_graph": [
    {
      "api_type": "openapi",
      "client": "orders",
      "service": "payments",
      "version": "1.0.0",
      "stability": "ga",
      "path": "/payments",
      "method": "POST",
      "deprecated": false
    }
  ],
  "service_tags": {},
  "trunk_graph": [],
  "harvested_subscriptions": [],
  "peripheral_dependencies": [],
  "systems": {},
  "scope_label": "release-2026.10"
}

dev@<instant> (the dev scope has no timeline), or main@… with an instant that does not parse as a date.

Missing or invalid token.

No sanshain-branch of that name.

The report.

Unusable scope, as for /report.

Missing or invalid token.

No sanshain-branch of that name.

The report.

Unusable scope, as for /report.

Missing or invalid token.

No sanshain-branch of that name.

Oldest version first.

Example 200 response (recorded from a live instance)

[
  {
    "version": "1.0.0",
    "stability": "ga",
    "provided_by": "root",
    "updated_at": "2026-10-18T16:07:54Z",
    "yaml_content": "openapi: 3.0.3\ninfo:\n  title: Payments\n  version: 1.0.0\npaths:\n  /payments:\n    post:\n      summary: Create a payment\n      responses:\n        '201':\n          description: Created\n",
    "changed": true
  },
  {
    "version": "2.0.0",
    "stability": "ga",
    "provided_by": "root",
    "updated_at": "2026-10-18T16:08:02Z",
    "yaml_content": "openapi: 3.0.3\ninfo:\n  title: Payments\n  version: 2.0.0\npaths:\n  /payments:\n    post:\n      summary: Create a payment\n      responses:\n        '201':\n          description: Created\n",
    "changed": true
  }
]

Missing or invalid token.

No such Producer.

Newest first, at most limit entries.

Example 200 response (recorded from a live instance)

[
  {
    "id": 25,
    "timestamp": "2026-10-18T16:08:05.620855031+00:00",
    "username": "root",
    "action": "DATABASE_SNAPSHOT",
    "details": "Produced database snapshot sanshain-2.6.1-20261018T160805Z.db (385024 bytes)",
    "service": null,
    "version": null,
    "action_type": "ADMIN",
    "diff": null,
    "stream": null
  }
]

Not signed in, or an API token.

Signed in without view_audit.

An open event stream; each event's data is updated.

Missing or invalid token.

Switching protocols; text frames updated follow.

Missing or invalid token.

The verdict.

Example 200 response (recorded from a live instance)

{
  "valid": true,
  "api_type": "openapi",
  "version": "1.0.0",
  "endpoint_count": 1,
  "endpoints": [
    "POST /payments"
  ]
}

Request body exceeds the configured size limit.

Instance version and id.

Example 200 response (recorded from a live instance)

{
  "version": "2.10.0"
}

The caller's tokens.

Example 200 response (placeholder values derived from the schema)

[
  {
    "id": "string",
    "user_id": 1,
    "name": "string",
    "scope": "full",
    "created_at": "string",
    "expires_at": "string",
    "last_used_at": "string"
  }
]

No valid session.

The new token. Copy token now; it is not stored and not shown again.

Example 200 response (recorded from a live instance)

{
  "id": "376e96e4-3808-4c5f-a6c4-0e4c9deacd14",
  "name": "claude-code",
  "scope": "read_only",
  "token": "san_…"
}

No valid session.

The caller already has a token of that name.

Revoked.

No valid session.

No such token owned by the caller.