Maintenance API

GET /admin/auth-config#

Read: auth-config

Authentication: session token · Permission: manage_auth_config · Scope: global

Requires the manage_auth_config permission.

Responses

PUT /admin/auth-config#

Replace: auth-config

Authentication: session token · Permission: manage_auth_config · Scope: global

Requires the manage_auth_config permission.

Responses

POST /admin/auth-config/test#

Create or run: auth-config/test

Authentication: session token · Permission: manage_auth_config · Scope: global

Requires the manage_auth_config permission. Connects to the directory named by the submitted LDAP configuration and binds with its service account; nothing is saved.

Responses

GET /admin/backup/sqlite#

Read: backup/sqlite

Authentication: session token API token (full) · Permission: run_destructive_operations · Scope: global

Requires the run_destructive_operations permission. A consistent snapshot of the SQLite database, produced by VACUUM INTO while Sanshain runs, streamed as application/vnd.sqlite3 with a Content-Disposition filename sanshain-<instance version>-<UTC timestamp>.db. Only one snapshot runs at a time. Meant for the scheduled backup: a full API token of an account holding the permission is accepted beside a session, a read_only token is refused with 403. See the deployment guide, Backup and restore.

Responses

GET /admin/branches/{name}/timeline#

Read: branches/name/timeline

Authentication: session token · Permission: any signed-in caller · Scope: global

The instants this branch's graph changed (every open/close event of its append-only pin store), distinct and ascending — the timeline slider's markers (ADR-0005).

Parameters

Responses

GET /admin/trunk/graph#

Read: trunk/graph

Authentication: session token · Permission: any signed-in caller · Scope: global

The main graph's pin set — current, or as it was at the optional at instant, reconstructed from the append-only trunk history (ADR-0005). Pins on deleted versions are marked dangling; a non-RFC-3339 at answers 400.

Parameters

Responses

GET /admin/trunk/timeline#

Read: trunk/timeline

Authentication: session token · Permission: any signed-in caller · Scope: global

The instants the main graph changed, distinct and ascending — the timeline slider's markers (ADR-0005).

Responses

POST /admin/cache/clear#

Create or run: cache/clear

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Responses

POST /admin/cleanup/dependencies#

Create or run: cleanup/dependencies

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Responses

POST /admin/cleanup/trunk#

Create or run: cleanup/trunk

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Runs the trunk TTL cleanup immediately (ADR-0004): open trunk pins not re-required within trunk_max_age_days are closed (they leave the main graph's current view; the rows stay as timeline history) and stale trunk version markers are cleared. Answers {"closed": n}.

Responses

POST /admin/cleanup/snapshots#

Create or run: cleanup/snapshots

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Runs the use-based snapshot expiry immediately: snapshots neither provided nor required within snapshot_max_age_days are deleted. GA versions are never age-culled.

Responses

GET /admin/consumers#

Read: consumers

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

Responses

GET /admin/consumers/{name}#

Read: consumers/name

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

The Consumer's context (#48): what its Backstage catalog-info.yaml says about it — owner, description, source location and links. context is null until a catalog push described the system.

Parameters

Responses

{
  "name": "string",
  "context": {
    "owner": {
      "kind": "string",
      "name": "string"
    },
    "description": "string",
    "source_location": "string",
    "links": [
      {
        "url": "string",
        "title": "string",
        "type": "string",
        "icon": "string"
      }
    ]
  }
}

DELETE /admin/consumers/{name}#

Delete: consumers/name

Authentication: session token · Permission: manage_consumers · Scope: global

Requires the manage_consumers permission.

Answers {"deleted": name}. Refused with 409 while any sanshain-branch's recorded graph still references the Consumer — a release cut is a frozen record, and the delete would remove its edges retroactively. The message names the branches to retire first. Trunk presence does not block.

Parameters

Responses

GET /admin/consumers/{name}/endpoints#

Read: consumers/name/endpoints

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

Every endpoint the Consumer is recorded as depending on, with the pinned version, its current stability and the endpoint's one-line summary.

Parameters

Responses

GET /admin/endpoint-versions#

Read: endpoint-versions

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

The blame trail of one endpoint: which versions of the line changed it, with the Author attribution recorded on each Provide.

Responses

GET /admin/endpoint-yaml#

Read: endpoint-yaml

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

Responses

GET /admin/directory-groups#

Read: directory-groups

Authentication: session token · Permission: manage_roles · Scope: global

Requires the manage_roles permission.

Finds groups in the configured LDAP directory whose common name contains q (at most 20), through the service account of the LDAP configuration. Each hit carries its dn, its name and the group_id of the Sanshain group that stands for it, or null when it was not added yet.

Parameters

Responses

GET /admin/groups#

Read: groups

Authentication: session token · Permission: manage_roles · Scope: global

Requires the manage_roles permission.

Responses

POST /admin/groups#

Create or run: groups

Authentication: session token · Permission: manage_roles · Scope: global

Requires the manage_roles permission.

Responses

POST /admin/groups/directory#

Create or run: groups/directory

Authentication: session token · Permission: manage_roles · Scope: global

Requires the manage_roles permission.

Adds a directory group by its DN ({"dn": "cn=carla,ou=teams,dc=corp,dc=com"}), so roles and maintainerships can be attached to it; its members stay in the directory. Adding one that is known already answers that group.

Responses

PUT /admin/groups/{id}#

Replace: groups/id

Authentication: session token · Permission: manage_roles · Scope: global

Requires the manage_roles permission. Adding an admin-guarded role (admin, releaser) to the group's role set — or removing one it holds — additionally requires the caller to be an admin.

Parameters

Responses

DELETE /admin/groups/{id}#

Delete: groups/id

Authentication: session token · Permission: manage_roles · Scope: global

Requires the manage_roles permission. Deleting a group that holds an admin-guarded role (admin, releaser) strips that role from every member at once, so it additionally requires the caller to be an admin.

Parameters

Responses

POST /admin/groups/{id}/members#

Create or run: groups/id/members

Authentication: session token · Permission: manage_roles · Scope: global

Requires the manage_roles permission. Membership of a group that holds an admin-guarded role (admin, releaser) IS a grant of that role, so adding a member then additionally requires the caller to be an admin.

Parameters

Responses

DELETE /admin/groups/{id}/members/{user_id}#

Delete: groups/id/members/user_id

Authentication: session token · Permission: manage_roles · Scope: global

Requires the manage_roles permission. Removing a member from a group that holds an admin-guarded role (admin, releaser) strips that role, so it additionally requires the caller to be an admin.

Parameters

Responses

GET /admin/maintainers#

Read: maintainers

Authentication: session token · Permission: manage_roles · Scope: global

Requires the manage_roles permission.

Every Producer with its maintainer user and group ids, in one response — the aggregate behind the dashboard's Maintainers section, so it does not ask per Producer.

Responses

POST /admin/nuke/consumers#

Create or run: nuke/consumers

Authentication: session token · Permission: run_destructive_operations · Scope: global

Requires the run_destructive_operations permission.

Responses

POST /admin/nuke/database#

Create or run: nuke/database

Authentication: session token · Permission: run_destructive_operations · Scope: global

Requires the run_destructive_operations permission.

Responses

POST /admin/nuke/producers#

Create or run: nuke/producers

Authentication: session token · Permission: run_destructive_operations · Scope: global

Requires the run_destructive_operations permission.

Responses

POST /admin/nuke/users#

Create or run: nuke/users

Authentication: session token · Permission: run_destructive_operations · Scope: global

Deletes every user who is not an effective administrator — users with a direct admin role, admin via group membership, or a configured root username survive. Requires the run_destructive_operations permission.

Responses

GET /admin/observability/audit-logs#

Read: observability/audit-logs

Authentication: session token · Permission: view_audit · Scope: global

Requires the view_audit permission. The most recent audit entries for the observability panel; optional limit (default 100, capped at 200).

Parameters

Responses

GET /admin/observability/audit-logs/export#

Read: observability/audit-logs/export

Authentication: session token · Permission: view_audit · Scope: global

Requires the view_audit permission. CSV of the most recent audit entries, columns id,timestamp,username,action,details,service,version, action_type,stream — every field except the bulky diff blob.

Responses

GET /admin/observability/debug-config#

Read: observability/debug-config

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

Responses

POST /admin/observability/debug-config-update#

Create or run: observability/debug-config-update

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Responses

GET /admin/observability/logs#

Read: observability/logs

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

Responses

GET /admin/observability/stats#

Read: observability/stats

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

Responses

GET /admin/graph/diff#

Read: graph/diff

Authentication: session token · Permission: any signed-in caller · Scope: global

Structured diff between two graph selections (ADR-0005) — release vs release, release vs main, one graph at two instants. left/right are main[@rfc3339] or <branch>[@rfc3339]. Answers services added/removed, pins added/removed, per-pin version changes, and periphery edges (system → Peripheral Resource) added/removed; all arrays empty means no differences.

Parameters

Responses

GET /admin/periphery#

Read: periphery

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

The edges from systems to their Peripheral Resources (#46) — what their Backstage catalog-info.yaml lists under dependsOn — for one graph scope: dev (the default), main[@rfc3339] or <branch>[@rfc3339], the selector grammar of /admin/graph/diff. A past instant answers the periphery as it was then.

Parameters

Responses

GET /admin/graph/scope#

Read: graph scope

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

What the dependency graph needs of one scope beyond its pins, for dev (the default), main[@rfc3339] or <branch>[@rfc3339] — the selector grammar of /admin/graph/diff:

• producers: the producers in the scope at its instant, each with one version line per API type. dev: every producer with any version (its newest per line). main: trunk's member versions — every trunk-flagged provide records the version it provided, closed again by the trunk TTL, a retire, or a version/producer delete. A branch: its member versions (tag-flagged provides) and, for lines without one, the highest version its pins name. stability is null when the version was deleted since; last_provided_at is the latest provide known at the instant (null when none is known).
• harvested_subscriptions: dev all, live main the trunk-flagged ones, everything else none (there is no harvested timeline).
• systems: the context (#48) of every system that pushed one, by name — owner, description, source location and links from its Backstage catalog-info.yaml — so the node panel needs no extra request. A present-day fact, the same in every scope.

Parameters

Responses

{
  "producers": [
    {
      "name": "string",
      "versions": [
        {
          "api_type": "openapi",
          "version": "string",
          "stability": "snapshot",
          "last_provided_at": "string"
        }
      ]
    }
  ],
  "harvested_subscriptions": [
    {
      "client": "string",
      "channel": "string",
      "message_name": "string",
      "owner": "string",
      "trunk": false
    }
  ],
  "systems": {
    "key": {
      "owner": {
        "kind": "string",
        "name": "string"
      },
      "description": "string",
      "source_location": "string",
      "links": [
        {
          "url": "string",
          "title": "string",
          "type": "string",
          "icon": "string"
        }
      ]
    }
  }
}

GET /admin/producers#

Read: producers

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

Every Producer with metadata and its full version lines (version, stability, endpoint count, snapshot expiry).

Responses

POST /admin/producers/metadata#

Create or run: producers/metadata

Authentication: session token · Permission: manage_producers · Scope: global

Requires the manage_producers permission.

Responses

POST /admin/producers/provide#

Create or run: producers/provide

Authentication: session token · Permission: manage_producers · Scope: global

Requires the manage_producers permission.

The admin page's provide: publishes a pasted specification under the same rules as POST /provide and its siblings, and answers the same way. A Producer this call creates is someone else's API and is marked external in the same request. Body: producername, api_type (openapi, asyncapi or proto), content, stability and optional dry_run.

Responses

GET /admin/producers/{name}#

Read: producers/name

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

The Producer's context (#48): what its Backstage catalog-info.yaml says about it — owner, description, source location and links. context is null until a catalog push described the system.

Parameters

Responses

{
  "name": "string",
  "context": {
    "owner": {
      "kind": "string",
      "name": "string"
    },
    "description": "string",
    "source_location": "string",
    "links": [
      {
        "url": "string",
        "title": "string",
        "type": "string",
        "icon": "string"
      }
    ]
  }
}

DELETE /admin/producers/{name}#

Delete: producers/name

Authentication: session token · Permission: manage_producers · Scope: per Producer: also its maintainers

Requires the manage_producers permission, or maintainership of the Producer named in the path.

Answers {"deleted": name}. Refused with 409 while any sanshain-branch's recorded graph still references the Producer — a release cut is a frozen record, and the delete would remove its edges retroactively. The message names the branches to retire first. Trunk presence does not block.

Parameters

Responses

GET /admin/producers/{name}/branch-memberships#

Read: producers/name/branch-memberships

Authentication: session token · Permission: any signed-in caller · Scope: global

Reverse lookup (ADR-0005): every (api_type, version, branch) this producer is currently referenced by across all sanshain-branches — "which releases pin b@1.0.0?" answered where you're already looking.

Parameters

Responses

GET /admin/producers/{name}/diff#

Read: producers/name/diff

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

Line diff between two versions of a line (api_type, from, to query parameters), computed with the similar (Myers) diff. Both stored documents are compared, or, with path and method, one endpoint's snippet (a version without the endpoint diffs as an empty document).

Parameters

Responses

GET /admin/producers/{name}/blame#

Read: producers/name/blame

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

Blame for one version of a line: the version's text (the stored document, or with path and method one endpoint's snippet) as a JSON array of blocks of consecutive lines last changed in the same version, oldest version first walked with the same similar diff as /diff. Each block is {version, stability, provided_by, updated_at, start_line, lines}; start_line is 1-based. A version with identical content (a promotion) changes no line; in endpoint mode a version without the endpoint is an empty text. An empty array means the version's text is empty.

Parameters

Responses

GET /admin/producers/{name}/structure#

Read: producers/name/structure

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

The structure view of one OpenAPI or AsyncAPI version: {service, api_type, version, endpoints}, each endpoint a tree of nodes (parameters by location, request body and responses per media type, AsyncAPI messages with headers and payload), every local $ref inlined, allOf merged with each member's origin, oneOf/anyOf as a variants node with its discriminator, and a recursive $ref cut as a cycle node. A node carries key, kind, name and, when present, type, summary, description, required, deprecated, nullable, read_only, write_only, default, example, enum, constraints, and changed_in: the version of the line (up to this one) that last changed the node's own fields, with inside when something below changed later. With path and method the answer is that endpoint with its children, every body carrying an example (example_generated when built from the schema). Without them every endpoint comes without children (children_omitted).

Parameters

Responses

GET /admin/branches#

Read: branches

Authentication: session token · Permission: any signed-in caller · Scope: global

Every sanshain-branch (ADR-0005), newest first: id, name, created_at, created_by, source (trunk or the source branch's then-current name) and as_of (the instant of the source graph the branch was born from).

Responses

POST /admin/branches#

Write: branches

Authentication: session token · Permission: release_ga · Scope: global

Requires the release_ga permission (the releaser role; admins and root hold it implicitly) — creating a named release graph is release work, and this endpoint's primary caller is the DevOps release-cut script, which needs nothing beyond this description:

Creates a sanshain-branch: a named copy of a source graph at a chosen instant, from then on updated by tag-flagged hotfix builds.

Body (JSON):

• name (string, required): unique among existing branches; free text ("Release Maribou"). Duplicate → 409.
• source (string, optional): the name of an existing branch to copy from. Omitted → the trunk graph. Unknown name → 404, nothing is created.
• as_of (string, optional): RFC 3339 instant of the source graph to copy. Omitted → now. A past instant creates the branch retroactively — trunk-at-that-date is reconstructed from the append-only history, so a forgotten release day is repairable. Malformed → 400.

The call is not idempotent: repeating it answers 409. Creation is audited (BRANCH_CREATED, naming the caller, source and instant).

Responses

PUT /admin/branches/{name}#

Write: branches/name

Authentication: session token · Permission: manage_producers · Scope: global

Requires the manage_producers permission (admins) — deliberately a higher bar than creation. Renames the branch: identity is the internal id, so membership, timeline and audit stamps survive; a pipeline still sending the old tag name gets the instructive 404 until its configuration is updated (intended for a name wrong enough to rename). Body: {"new_name": "..."}. Audited with old and new name.

Parameters

Responses

DELETE /admin/branches/{name}#

Write: branches/name

Authentication: session token · Permission: manage_producers · Scope: global

Requires the manage_producers permission (admins). Deletes the branch and its graph rows — the deliberate, audited EOL act — and frees the name for reuse.

Parameters

Responses

GET /admin/branches/{name}/graph#

Read: branches/name/graph

Authentication: session token · Permission: any signed-in caller · Scope: global

The branch's pin set — its graph edges, each {client, service, api_type, version, path, method, valid_from, last_required_at} with the version by value (a deleted spec version renders as a dangling reference and heals when the number is re-provided). Optional at (RFC 3339) answers the branch's graph as it was at that instant; a non-RFC-3339 at answers 400.

Parameters

Responses

GET /admin/producers/{name}/endpoints#

Read: producers/name/endpoints

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

The endpoints of one version-line entry (api_type, version query parameters), ordered by path, then method.

Parameters

Responses

GET /admin/producers/{name}/full-spec#

Read: producers/name/full-spec

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

The full provided document of one version-line entry, exactly as the Producer submitted it (api_type, version query parameters).

Parameters

Responses

PUT /admin/producers/{name}/external#

Update: producers/name/external

Authentication: session token · Permission: manage_producers · Scope: global

Requires the manage_producers permission.

Marks a Producer as external, an outside API the company does not maintain ({"external": true}), or as the company's own again (false). A provide on the admin page (POST /admin/producers/provide) marks a Producer it creates. External Producers are drawn with a light grey fill in the graph and tagged in the lists (external on each Producer).

Parameters

Responses

GET /admin/producers/{name}/maintainers#

Read: producers/name/maintainers

Authentication: session token · Permission: manage_producers · Scope: per Producer: also its maintainers

Requires the manage_producers permission, or maintainership of the Producer named in the path.

Parameters

Responses

POST /admin/producers/{name}/maintainers#

Create or run: producers/name/maintainers

Authentication: session token · Permission: manage_roles · Scope: global

Requires the manage_roles permission.

Parameters

Responses

DELETE /admin/producers/{name}/maintainers/groups/{group_id}#

Delete: producers/name/maintainers/groups/group_id

Authentication: session token · Permission: manage_roles · Scope: global

Requires the manage_roles permission.

Parameters

Responses

DELETE /admin/producers/{name}/maintainers/users/{user_id}#

Delete: producers/name/maintainers/users/user_id

Authentication: session token · Permission: manage_roles · Scope: global

Requires the manage_roles permission.

Parameters

Responses

GET /admin/producers/{name}/versions#

Read: producers/name/versions

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

One Producer's version lines, optionally narrowed with an api_type query parameter.

Parameters

Responses

DELETE /admin/producers/{name}/versions/{api_type}/{version}#

Delete: producers/name/versions/api_type/version

Authentication: session token · Permission: manage_producers · Scope: per Producer: also its maintainers

Requires the manage_producers permission, or maintainership of the Producer named in the path.

The sole escape hatch from GA immutability (ADR-0003): delete the version outright, freeing its number. Consumers pinned to it hard-fail on their next require — check the dependents listing first. Audited, naming the pinned Consumers.

Parameters

Responses

POST /admin/producers/{name}/versions/{api_type}/{version}/promote#

Write: producers/name/versions/api_type/version/promote

Authentication: session token · Permission: release_ga · Scope: global

Requires the release_ga permission — enforced by the same GA gate every release goes through, so an unauthorized attempt answers the instructive 403 and is recorded as a VERSION_REJECTED audit entry with reason ga_requires_releaser.

One-click promote: releases the stored snapshot in place, exactly as if its content were re-provided with stability: ga — the original provider stays credited, the promoting Actor is named in the VERSION_PROMOTED audit entry, and AsyncAPI GA contract checks apply. Promoting an already-GA version is an idempotent no-op (promoted: false).

Parameters

Responses

GET /admin/producers/{name}/versions/{api_type}/{version}/dependents#

Read: producers/name/versions/api_type/version/dependents

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

The Consumers currently pinned to this version — what a delete would break. Shown by the UI before a delete-version is confirmed.

Parameters

Responses

GET /admin/roles#

Read: roles

Authentication: session token · Permission: manage_roles · Scope: global

Requires the manage_roles permission.

Responses

POST /admin/settings/registration#

Create or run: settings/registration

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission, like the auto-approve switch beside it.

Turns self-registration on or off ({"enabled": true}). Registration is offered only in Local mode; turning it off keeps every account already created.

Responses

GET /admin/settings/auto-approve#

Read: settings/auto-approve

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Responses

POST /admin/settings/auto-approve#

Create or run: settings/auto-approve

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Responses

GET /admin/settings/gravatar#

Read: settings/gravatar

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Responses

POST /admin/settings/gravatar#

Create or run: settings/gravatar

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Switches Gravatar pictures on or off ({"enabled": true}). Off by default: while on, the pages load each person's picture from gravatar.com by the SHA-256 of their e-mail address; the address itself never leaves the server.

Responses

GET /admin/settings/cache#

Read: settings/cache

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Responses

POST /admin/settings/cache#

Create or run: settings/cache

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Responses

GET /admin/settings/database#

Read: settings/database

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Responses

GET /admin/settings/dependency-max-age#

Read: settings/dependency-max-age

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Responses

POST /admin/settings/dependency-max-age#

Create or run: settings/dependency-max-age

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission. Body: {"days": n}, at least 1 and at most 36500 (~100 years); values outside answer 400.

Responses

GET /admin/settings/trunk-max-age#

Read: settings/trunk-max-age

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission. The trunk TTL in days (ADR-0004), default 90; 0 disables the cleanup.

Responses

POST /admin/settings/trunk-max-age#

Create or run: settings/trunk-max-age

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission. Body: {"days": n}, at most 36500 (~100 years); larger values answer 400.

Responses

GET /admin/instance-settings#

Read: instance-settings

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

The harmless instance settings as values, for the admin page to show to someone who may see but not change them: auto_approve_users, snapshot_max_age_days, dependency_max_age_days, trunk_max_age_days, ticket_url_template and cache (enabled, memory_limit_mb, memory_used_mb, entry_count, hit_count, miss_count, hit_rate). Changing each stays behind manage_settings; the auth configuration, the webhook allow-list and the database are not included.

Responses

GET /admin/ticket-url-template#

Read: ticket-url-template

Authentication: session token · Permission: any signed-in caller · Scope: global

Any signed-in caller.

The ticket URL template ({"template": "https://jira.acme.corp/browse/{id}"}, or null): the pages render the ticket ids of a version's origin as links with it. Set under /admin/settings/ticket-url-template.

Responses

POST /admin/settings/ticket-url-template#

Create or run: settings/ticket-url-template

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Set the ticket URL template: an absolute http(s) URL containing {id}, at most 2048 characters; a blank or missing template clears it. Audited as SET_TICKET_URL_TEMPLATE.

Responses

GET /admin/settings/snapshot-max-age#

Read: settings/snapshot-max-age

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Responses

POST /admin/settings/snapshot-max-age#

Create or run: settings/snapshot-max-age

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Days a snapshot survives without being provided or required. 0 disables the cleanup. At most 36500 (~100 years); larger values answer 400.

Responses

GET /admin/webhooks#

Read: webhooks/webhooks

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

The hooks of this scope, newest last, without their secrets (secret_hint is a prefix of the secret's SHA-256).

Responses

[
  {
    "id": 1,
    "scope": {
      "kind": "global",
      "name": "string"
    },
    "url": "string",
    "format": "json",
    "event_types": [
      "string"
    ],
    "producer_glob": "string",
    "secret_hint": "string",
    "paused": false,
    "allow_list_exempt": false,
    "created_by": "string",
    "created_at": "string"
  }
]

POST /admin/webhooks#

Create or run: webhooks/webhooks

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Register a hook (WebhookCreate). The URL must be https://, or http:// to a host the allow-list names with http://; callers without manage_settings are refused outside the allow-list (and with an empty allow-list), callers with it are exempt for good. The answer carries the signing secret once.

Responses

{
  "webhook": {
    "id": 1,
    "scope": {
      "kind": "global",
      "name": "string"
    },
    "url": "string",
    "format": "json",
    "event_types": [
      "string"
    ],
    "producer_glob": "string",
    "secret_hint": "string",
    "paused": false,
    "allow_list_exempt": false,
    "created_by": "string",
    "created_at": "string"
  },
  "secret": "string"
}

GET /admin/webhooks/{id}#

Read: webhooks/webhooks/id

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Parameters

Responses

{
  "id": 1,
  "scope": {
    "kind": "global",
    "name": "string"
  },
  "url": "string",
  "format": "json",
  "event_types": [
    "string"
  ],
  "producer_glob": "string",
  "secret_hint": "string",
  "paused": false,
  "allow_list_exempt": false,
  "created_by": "string",
  "created_at": "string"
}

PATCH /admin/webhooks/{id}#

Update: webhooks/webhooks/id

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Pause or resume (paused), replace the event-type filter (event_types, [] = every type) or the Producer glob (producer_glob, null clears it). Fields left out stay as they are.

Parameters

Responses

{
  "id": 1,
  "scope": {
    "kind": "global",
    "name": "string"
  },
  "url": "string",
  "format": "json",
  "event_types": [
    "string"
  ],
  "producer_glob": "string",
  "secret_hint": "string",
  "paused": false,
  "allow_list_exempt": false,
  "created_by": "string",
  "created_at": "string"
}

DELETE /admin/webhooks/{id}#

Delete: webhooks/webhooks/id

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Deletes the hook and its delivery log.

Parameters

Responses

POST /admin/webhooks/{id}/test#

Create or run: webhooks/webhooks/id/test

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Queue a webhook.test event for this hook alone; the worker delivers it like any other event, so the delivery log shows whether the receiver, the secret and the allow-list are in order.

Parameters

Responses

POST /admin/webhooks/{id}/rotate-secret#

Create or run: webhooks/webhooks/id/rotate-secret

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

A fresh secret, shown once; deliveries from now on are signed with it.

Parameters

Responses

{
  "webhook": {
    "id": 1,
    "scope": {
      "kind": "global",
      "name": "string"
    },
    "url": "string",
    "format": "json",
    "event_types": [
      "string"
    ],
    "producer_glob": "string",
    "secret_hint": "string",
    "paused": false,
    "allow_list_exempt": false,
    "created_by": "string",
    "created_at": "string"
  },
  "secret": "string"
}

GET /admin/webhooks/{id}/deliveries#

Read: webhooks/webhooks/id/deliveries

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

The newest deliveries of the hook (limit, default 50, at most 200): status, attempts, next attempt, last response code and error.

Parameters

Responses

[
  {
    "id": 1,
    "hook_id": 1,
    "event_id": "string",
    "event_type": "string",
    "occurred_at": "string",
    "status": "pending",
    "attempts": 0,
    "next_attempt_at": "string",
    "last_response_code": 0,
    "last_error": "string",
    "delivered_at": "string",
    "updated_at": "string"
  }
]

POST /admin/webhooks/{id}/deliveries/{delivery_id}/redeliver#

Create or run: webhooks/webhooks/id/deliveries/delivery_id/redeliver

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

Reset one delivery to pending, due now, attempt count kept — one more attempt even for a dead delivery.

Parameters

Responses

{
  "id": 1,
  "hook_id": 1,
  "event_id": "string",
  "event_type": "string",
  "occurred_at": "string",
  "status": "pending",
  "attempts": 0,
  "next_attempt_at": "string",
  "last_response_code": 0,
  "last_error": "string",
  "delivered_at": "string",
  "updated_at": "string"
}

GET /admin/producers/{name}/webhooks#

Read: producers/name/webhooks

Authentication: session token · Permission: manage_producers · Scope: per Producer: also its maintainers

Requires the manage_producers permission, or maintainership of the Producer named in the path.

The hooks of this scope, newest last, without their secrets (secret_hint is a prefix of the secret's SHA-256).

Parameters

Responses

[
  {
    "id": 1,
    "scope": {
      "kind": "global",
      "name": "string"
    },
    "url": "string",
    "format": "json",
    "event_types": [
      "string"
    ],
    "producer_glob": "string",
    "secret_hint": "string",
    "paused": false,
    "allow_list_exempt": false,
    "created_by": "string",
    "created_at": "string"
  }
]

POST /admin/producers/{name}/webhooks#

Create or run: producers/name/webhooks

Authentication: session token · Permission: manage_producers · Scope: per Producer: also its maintainers

Requires the manage_producers permission, or maintainership of the Producer named in the path.

Register a hook (WebhookCreate). The URL must be https://, or http:// to a host the allow-list names with http://; callers without manage_settings are refused outside the allow-list (and with an empty allow-list), callers with it are exempt for good. The answer carries the signing secret once.

Parameters

Responses

{
  "webhook": {
    "id": 1,
    "scope": {
      "kind": "global",
      "name": "string"
    },
    "url": "string",
    "format": "json",
    "event_types": [
      "string"
    ],
    "producer_glob": "string",
    "secret_hint": "string",
    "paused": false,
    "allow_list_exempt": false,
    "created_by": "string",
    "created_at": "string"
  },
  "secret": "string"
}

GET /admin/producers/{name}/webhooks/{id}#

Read: producers/name/webhooks/id

Authentication: session token · Permission: manage_producers · Scope: per Producer: also its maintainers

Requires the manage_producers permission, or maintainership of the Producer named in the path.

Parameters

Responses

{
  "id": 1,
  "scope": {
    "kind": "global",
    "name": "string"
  },
  "url": "string",
  "format": "json",
  "event_types": [
    "string"
  ],
  "producer_glob": "string",
  "secret_hint": "string",
  "paused": false,
  "allow_list_exempt": false,
  "created_by": "string",
  "created_at": "string"
}

PATCH /admin/producers/{name}/webhooks/{id}#

Update: producers/name/webhooks/id

Authentication: session token · Permission: manage_producers · Scope: per Producer: also its maintainers

Requires the manage_producers permission, or maintainership of the Producer named in the path.

Pause or resume (paused), replace the event-type filter (event_types, [] = every type) or the Producer glob (producer_glob, null clears it). Fields left out stay as they are.

Parameters

Responses

{
  "id": 1,
  "scope": {
    "kind": "global",
    "name": "string"
  },
  "url": "string",
  "format": "json",
  "event_types": [
    "string"
  ],
  "producer_glob": "string",
  "secret_hint": "string",
  "paused": false,
  "allow_list_exempt": false,
  "created_by": "string",
  "created_at": "string"
}

DELETE /admin/producers/{name}/webhooks/{id}#

Delete: producers/name/webhooks/id

Authentication: session token · Permission: manage_producers · Scope: per Producer: also its maintainers

Requires the manage_producers permission, or maintainership of the Producer named in the path.

Deletes the hook and its delivery log.

Parameters

Responses

POST /admin/producers/{name}/webhooks/{id}/test#

Create or run: producers/name/webhooks/id/test

Authentication: session token · Permission: manage_producers · Scope: per Producer: also its maintainers

Requires the manage_producers permission, or maintainership of the Producer named in the path.

Queue a webhook.test event for this hook alone; the worker delivers it like any other event, so the delivery log shows whether the receiver, the secret and the allow-list are in order.

Parameters

Responses

POST /admin/producers/{name}/webhooks/{id}/rotate-secret#

Create or run: producers/name/webhooks/id/rotate-secret

Authentication: session token · Permission: manage_producers · Scope: per Producer: also its maintainers

Requires the manage_producers permission, or maintainership of the Producer named in the path.

A fresh secret, shown once; deliveries from now on are signed with it.

Parameters

Responses

{
  "webhook": {
    "id": 1,
    "scope": {
      "kind": "global",
      "name": "string"
    },
    "url": "string",
    "format": "json",
    "event_types": [
      "string"
    ],
    "producer_glob": "string",
    "secret_hint": "string",
    "paused": false,
    "allow_list_exempt": false,
    "created_by": "string",
    "created_at": "string"
  },
  "secret": "string"
}

GET /admin/producers/{name}/webhooks/{id}/deliveries#

Read: producers/name/webhooks/id/deliveries

Authentication: session token · Permission: manage_producers · Scope: per Producer: also its maintainers

Requires the manage_producers permission, or maintainership of the Producer named in the path.

The newest deliveries of the hook (limit, default 50, at most 200): status, attempts, next attempt, last response code and error.

Parameters

Responses

[
  {
    "id": 1,
    "hook_id": 1,
    "event_id": "string",
    "event_type": "string",
    "occurred_at": "string",
    "status": "pending",
    "attempts": 0,
    "next_attempt_at": "string",
    "last_response_code": 0,
    "last_error": "string",
    "delivered_at": "string",
    "updated_at": "string"
  }
]

POST /admin/producers/{name}/webhooks/{id}/deliveries/{delivery_id}/redeliver#

Create or run: producers/name/webhooks/id/deliveries/delivery_id/redeliver

Authentication: session token · Permission: manage_producers · Scope: per Producer: also its maintainers

Requires the manage_producers permission, or maintainership of the Producer named in the path.

Reset one delivery to pending, due now, attempt count kept — one more attempt even for a dead delivery.

Parameters

Responses

{
  "id": 1,
  "hook_id": 1,
  "event_id": "string",
  "event_type": "string",
  "occurred_at": "string",
  "status": "pending",
  "attempts": 0,
  "next_attempt_at": "string",
  "last_response_code": 0,
  "last_error": "string",
  "delivered_at": "string",
  "updated_at": "string"
}

GET /admin/consumers/{name}/webhooks#

Read: consumers/name/webhooks

Authentication: session token · Permission: manage_producers · Scope: per Consumer: also maintainers of the Producer of the same name

Requires the manage_producers permission, or maintainership of the Producer of the same name as the Consumer in the path (the "same system" rule).

The hooks of this scope, newest last, without their secrets (secret_hint is a prefix of the secret's SHA-256).

Parameters

Responses

[
  {
    "id": 1,
    "scope": {
      "kind": "global",
      "name": "string"
    },
    "url": "string",
    "format": "json",
    "event_types": [
      "string"
    ],
    "producer_glob": "string",
    "secret_hint": "string",
    "paused": false,
    "allow_list_exempt": false,
    "created_by": "string",
    "created_at": "string"
  }
]

POST /admin/consumers/{name}/webhooks#

Create or run: consumers/name/webhooks

Authentication: session token · Permission: manage_producers · Scope: per Consumer: also maintainers of the Producer of the same name

Requires the manage_producers permission, or maintainership of the Producer of the same name as the Consumer in the path (the "same system" rule).

Register a hook (WebhookCreate). The URL must be https://, or http:// to a host the allow-list names with http://; callers without manage_settings are refused outside the allow-list (and with an empty allow-list), callers with it are exempt for good. The answer carries the signing secret once.

Parameters

Responses

{
  "webhook": {
    "id": 1,
    "scope": {
      "kind": "global",
      "name": "string"
    },
    "url": "string",
    "format": "json",
    "event_types": [
      "string"
    ],
    "producer_glob": "string",
    "secret_hint": "string",
    "paused": false,
    "allow_list_exempt": false,
    "created_by": "string",
    "created_at": "string"
  },
  "secret": "string"
}

GET /admin/consumers/{name}/webhooks/{id}#

Read: consumers/name/webhooks/id

Authentication: session token · Permission: manage_producers · Scope: per Consumer: also maintainers of the Producer of the same name

Requires the manage_producers permission, or maintainership of the Producer of the same name as the Consumer in the path (the "same system" rule).

Parameters

Responses

{
  "id": 1,
  "scope": {
    "kind": "global",
    "name": "string"
  },
  "url": "string",
  "format": "json",
  "event_types": [
    "string"
  ],
  "producer_glob": "string",
  "secret_hint": "string",
  "paused": false,
  "allow_list_exempt": false,
  "created_by": "string",
  "created_at": "string"
}

PATCH /admin/consumers/{name}/webhooks/{id}#

Update: consumers/name/webhooks/id

Authentication: session token · Permission: manage_producers · Scope: per Consumer: also maintainers of the Producer of the same name

Requires the manage_producers permission, or maintainership of the Producer of the same name as the Consumer in the path (the "same system" rule).

Pause or resume (paused), replace the event-type filter (event_types, [] = every type) or the Producer glob (producer_glob, null clears it). Fields left out stay as they are.

Parameters

Responses

{
  "id": 1,
  "scope": {
    "kind": "global",
    "name": "string"
  },
  "url": "string",
  "format": "json",
  "event_types": [
    "string"
  ],
  "producer_glob": "string",
  "secret_hint": "string",
  "paused": false,
  "allow_list_exempt": false,
  "created_by": "string",
  "created_at": "string"
}

DELETE /admin/consumers/{name}/webhooks/{id}#

Delete: consumers/name/webhooks/id

Authentication: session token · Permission: manage_producers · Scope: per Consumer: also maintainers of the Producer of the same name

Requires the manage_producers permission, or maintainership of the Producer of the same name as the Consumer in the path (the "same system" rule).

Deletes the hook and its delivery log.

Parameters

Responses

POST /admin/consumers/{name}/webhooks/{id}/test#

Create or run: consumers/name/webhooks/id/test

Authentication: session token · Permission: manage_producers · Scope: per Consumer: also maintainers of the Producer of the same name

Requires the manage_producers permission, or maintainership of the Producer of the same name as the Consumer in the path (the "same system" rule).

Queue a webhook.test event for this hook alone; the worker delivers it like any other event, so the delivery log shows whether the receiver, the secret and the allow-list are in order.

Parameters

Responses

POST /admin/consumers/{name}/webhooks/{id}/rotate-secret#

Create or run: consumers/name/webhooks/id/rotate-secret

Authentication: session token · Permission: manage_producers · Scope: per Consumer: also maintainers of the Producer of the same name

Requires the manage_producers permission, or maintainership of the Producer of the same name as the Consumer in the path (the "same system" rule).

A fresh secret, shown once; deliveries from now on are signed with it.

Parameters

Responses

{
  "webhook": {
    "id": 1,
    "scope": {
      "kind": "global",
      "name": "string"
    },
    "url": "string",
    "format": "json",
    "event_types": [
      "string"
    ],
    "producer_glob": "string",
    "secret_hint": "string",
    "paused": false,
    "allow_list_exempt": false,
    "created_by": "string",
    "created_at": "string"
  },
  "secret": "string"
}

GET /admin/consumers/{name}/webhooks/{id}/deliveries#

Read: consumers/name/webhooks/id/deliveries

Authentication: session token · Permission: manage_producers · Scope: per Consumer: also maintainers of the Producer of the same name

Requires the manage_producers permission, or maintainership of the Producer of the same name as the Consumer in the path (the "same system" rule).

The newest deliveries of the hook (limit, default 50, at most 200): status, attempts, next attempt, last response code and error.

Parameters

Responses

[
  {
    "id": 1,
    "hook_id": 1,
    "event_id": "string",
    "event_type": "string",
    "occurred_at": "string",
    "status": "pending",
    "attempts": 0,
    "next_attempt_at": "string",
    "last_response_code": 0,
    "last_error": "string",
    "delivered_at": "string",
    "updated_at": "string"
  }
]

POST /admin/consumers/{name}/webhooks/{id}/deliveries/{delivery_id}/redeliver#

Create or run: consumers/name/webhooks/id/deliveries/delivery_id/redeliver

Authentication: session token · Permission: manage_producers · Scope: per Consumer: also maintainers of the Producer of the same name

Requires the manage_producers permission, or maintainership of the Producer of the same name as the Consumer in the path (the "same system" rule).

Reset one delivery to pending, due now, attempt count kept — one more attempt even for a dead delivery.

Parameters

Responses

{
  "id": 1,
  "hook_id": 1,
  "event_id": "string",
  "event_type": "string",
  "occurred_at": "string",
  "status": "pending",
  "attempts": 0,
  "next_attempt_at": "string",
  "last_response_code": 0,
  "last_error": "string",
  "delivered_at": "string",
  "updated_at": "string"
}

GET /admin/settings/webhook-allowed-hosts#

Read: settings/webhook-allowed-hosts

Authentication: session token · Permission: manage_settings · Scope: global

Requires the manage_settings permission.

The egress allow-list: host patterns a hook URL may point at.

Responses