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 and its current stability.

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

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

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/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).

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

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

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

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

Create or run: settings/webhook-allowed-hosts

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

Requires the manage_settings permission.

Replace the allow-list ({"hosts": [...]}). A pattern is a host name with */? wildcards (hooks.slack.com, *.webhook.office.com); prefixed http:// it also admits plain HTTP to that host (http://n8n.corp.internal). Ports are not matched. An empty list means only callers with manage_settings may register hooks. Evaluated at registration and again at every delivery.

Responses

GET /admin/users#

Read: users

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

Requires the manage_users permission.

Responses

DELETE /admin/users/{id}#

Delete: users/id

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

Requires the manage_users permission. Deleting a user who holds an admin-guarded role (admin, releaser) — directly or via a stored group — strips those roles at once, and deleting a configured root account un-claims the reserved name, so both additionally require the caller to be an admin.

Parameters

Responses

POST /admin/users/{id}/approve#

Create or run: users/id/approve

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

Requires the manage_users permission.

Parameters

Responses

GET /admin/users/{id}/maintains#

Read: users/id/maintains

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

Requires the manage_roles permission.

Parameters

Responses

GET /admin/users/{id}/roles#

Read: users/id/roles

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

Requires the manage_roles permission.

Parameters

Responses

POST /admin/users/{id}/roles#

Create or run: users/id/roles

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

Requires the manage_roles permission. Granting an admin-guarded role (admin, releaser) additionally requires the caller to be an admin.

Parameters

Responses

DELETE /admin/users/{id}/roles/{role}#

Delete: users/id/roles/role

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

Requires the manage_roles permission. Revoking an admin-guarded role (admin, releaser) additionally requires the caller to be an admin.

Parameters

Responses