Skip to content

REST API reference

Auto-generated from the backend's code-derived OpenAPI spec (utoipa annotations on each handler). Run scripts/docs/regen.py to refresh — CI does this on every push. Open /api-docs on your AppControl instance for the bundled Swagger UI and see the guided walkthrough (FR). The same spec is served at GET /api/v1/openapi.json, or exported offline with appcontrol-backend --export-openapi <path>.

API version: 1.24.5

Base URL: /api/v1 (relative to the backend host)

Enterprise platform for operational mastery and IT system resilience. Maps applications as dependency graphs (DAGs), monitors component health, orchestrates sequenced start/stop/restart operations, and manages DR site failover.

This document is generated from the handler source — never hand-edited. Coverage is incremental: absence from this document does not mean an endpoint is unavailable. Map validation and import are documented here. In same-origin Swagger UI, the current AppControl login is used automatically. For another identity, authorize with either an AppControl JWT or ApiKey <key>; import permissions are separate from validation access.

Authentication

Protected operations use the following alternatives. Authentication does not override application/site permissions or the limits of a restricted API key.

  • apiKeyAuth — Enter ApiKey <key> for a personal or service API key. The Authorization header (not X-API-Key) is accepted by the authentication middleware.
  • bearerAuth — AppControl session JWT. Pass as Authorization: Bearer <token>. An identity-provider token is not accepted directly as an AppControl session.
  • embeddedSessionAuth — Short-lived simulation-only bearer issued by /apps/{id}/embedded-sessions. Not accepted by Operations APIs. Never put this token in URLs or browser storage.
  • sessionCookie — Existing AppControl browser session (HttpOnly cookie, sent automatically for same-origin requests). Sign in through AppControl; do not paste the cookie into Swagger UI.

All API key activity is recorded in action_log with actor_type='api_key'.

Endpoints

Agents

Applications

Catalog

Embedded

Gateways

Knowledge

Map generation

Map imports

Operations

PKI maintenance

Permissions

Sites

Teams

X4B map generation

Endpoint detail

Tag — Agents

GET /agents

Lists enrolled agents in the caller organization. The response object contains agents[]. Use agents[].id for import profile mappings and agents[].gateway_id to choose the gateway scope. connected is live connection status; is_active is administrative status. An arbitrary hostname does not enroll an agent.

Responses

  • 200 — Object with agents array; includes id, hostname, gateway_id, gateway_name, connected, is_active, OS/version and heartbeat metadata
  • 401 — Authentication required
  • 403 — Insufficient API scope

Tag — Applications

GET /apps

Parameters

  • search (query, ['string', 'null'], optional) —
  • site_id (query, ['string', 'null'], optional) —
  • limit (query, ['integer', 'null'], optional) —
  • offset (query, ['integer', 'null'], optional) —

Responses

  • 200 — List of applications visible to the caller, each annotated with computed global state and weather
  • 401 — Unauthorized

POST /apps

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/CreateAppRequest"
}

Responses

  • 201 — Application created
  • 400 — Validation error
  • 403 — Forbidden

GET /apps/{app_id}/site-overrides

GET /api/v1/apps/:app_id/site-bindings

Returns all site bindings for components in the given application. This is based on binding profiles (which define where components run) merged with any command overrides from site_overrides table.

Each component shows: - All sites where it has a binding (from binding_profile_mappings) - The agent assigned for each site - Any command overrides for that site (from site_overrides) - Whether this is the active profile

Parameters

  • app_id (path, string, required) — Application id

Responses

  • 200 — Per-site command/agent overrides for this application
  • 403 — Forbidden
  • 404 — Not found

DELETE /apps/{id}

Parameters

  • id (path, string, required) — Application id

Responses

  • 204 — Application deleted
  • 403 — Forbidden
  • 404 — Not found
  • 409 — Operation lock or retained history prevents deletion; configuration is unchanged

GET /apps/{id}

Parameters

  • id (path, string, required) — Application id

Responses

  • 200 — Application details with components and topology
  • 403 — Forbidden
  • 404 — Not found

PUT /apps/{id}

Parameters

  • id (path, string, required) — Application id

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/UpdateAppRequest"
}

Responses

  • 200 — Updated application
  • 400 — Validation error
  • 403 — Forbidden
  • 404 — Not found

POST /apps/{id}/cancel

Request cancellation of a running operation on an application. The operation will check for cancellation and stop gracefully.

Parameters

  • id (path, string, required) — Application id

Responses

  • 200 — Cancellation requested. Body indicates whether an active operation was found
  • 403 — Forbidden

POST /apps/{id}/force-unlock

Force-release an operation lock. Use as last resort when cancel doesn't work. This immediately removes the lock, potentially leaving the operation orphaned.

Parameters

  • id (path, string, required) — Application id

Responses

  • 200 — Lock force-released or no lock found
  • 403 — Forbidden (requires Manage permission)

PUT /apps/{id}/resume

PUT /api/v1/applications/:id/resume

Resume a suspended application. The agent will restart health checks for all components in this application.

Parameters

  • id (path, string, required) — Application id

Responses

  • 200 — Application resumed
  • 403 — Forbidden (requires Manage permission)
  • 409 — Not suspended

POST /apps/{id}/start

Parameters

  • id (path, string, required) — Application id

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/StartAppRequest"
}

Responses

  • 200 — Start sequence dispatched (or simulated when dry_run=true)
  • 403 — Forbidden
  • 404 — Not found
  • 409 — Another operation is already running on this app

POST /apps/{id}/start-branch

Parameters

  • id (path, string, required) — Application id

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/StartBranchRequest"
}

Responses

  • 200 — Error-branch restart dispatched
  • 403 — Forbidden
  • 404 — Not found
  • 409 — Another operation is already running on this app

POST /apps/{id}/start-to

Parameters

  • id (path, string, required) — Application id

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/StartToRequest"
}

Responses

  • 200 — Partial start dispatched (upstream subset of target)
  • 403 — Forbidden
  • 404 — Target component not found
  • 409 — Target component does not belong to this app, or operation already running

POST /apps/{id}/stop

Parameters

  • id (path, string, required) — Application id

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/StopAppRequest"
}

Responses

  • 200 — Stop sequence dispatched (or simulated when dry_run=true)
  • 403 — Forbidden
  • 404 — Not found
  • 409 — Another operation is already running on this app

PUT /apps/{id}/suspend

PUT /api/v1/applications/:id/suspend

Suspend an application. The agent will stop health checks for all components in this application until it is resumed.

Parameters

  • id (path, string, required) — Application id

Responses

  • 200 — Application suspended
  • 403 — Forbidden (requires Manage permission)
  • 409 — Already suspended

Tag — Catalog

POST /catalog/component-types/import

Atomic catalog import; preview an upsert before applying its full records.

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/ImportCatalogRequest"
}

Responses

  • 200 — Created/updated/skipped entries, per-entry diff and catalog digest
  • 400 — Invalid catalog
  • 403 — Admin required
  • 409 — Reviewed catalog changed

Tag — Embedded

GET /apps/{id}/embedded-options

Parameters

  • id (path, string, required) —

Responses

  • 200 — Eligible isolated simulation sites and allowed host origins

POST /apps/{id}/embedded-sessions

Parameters

  • id (path, string, required) —

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/CreateEmbeddedSession"
}

Responses

  • 201 — Short-lived simulation-only session; keep token out of URLs
  • 403 — Origin, application or simulation target not authorized

GET /embedded/resolve

Resolve a published external application reference for Embedded simulation. API keys require simulate access on the resolved application. Visibility follows the issuing account's application and site permissions.

Parameters

  • system (query, string, required) — Source system, for example documentation
  • id (query, string, required) — Stable application identifier in the source system

Responses

  • 200 — Published application available to the caller
  • 400 — Invalid source reference
  • 401 — Authentication required
  • 403 — API key lacks a simulation scope
  • 404 — No published application available to the caller

DELETE /embedded/sessions/{id}

Parameters

  • id (path, string, required) —

Responses

  • 204 — Session revoked

GET /embedded/sessions/{id}

Parameters

  • id (path, string, required) —

Responses

  • 200 — Sanitized reference, simulation state and history
  • 401 — Invalid, revoked or expired Embedded token

POST /embedded/sessions/{id}/scenarios

Parameters

  • id (path, string, required) —

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/EmbeddedScenario"
}

Responses

  • 202 — Scenario accepted; poll session for real runtime results
  • 409 — Busy or unreviewed recovery plan

Tag — Gateways

GET /gateways

Lists gateways grouped by site in the caller organization. The response is {sites: [...]}, not a flat gateway array. Select sites[].gateways[].id for import preview/profile gateway_ids and inspect connected before an operational demo.

Responses

  • 200 — Object with sites array; each site contains site_id, site_name and gateways with id, name, connected, role and agent_count
  • 401 — Authentication required
  • 403 — Insufficient API scope

Tag — Knowledge

GET /apps/{id}/knowledge

Parameters

  • id (path, string, required) — Application ID

Responses

  • 200 — Knowledge operation result
  • 403 — Insufficient scope or application/site rights
  • 409 — Revision, review or publication conflict

GET /apps/{id}/knowledge/history

Parameters

  • id (path, string, required) — Application ID

Responses

  • 200 — Knowledge operation result
  • 403 — Insufficient scope or application/site rights
  • 409 — Revision, review or publication conflict

POST /apps/{id}/knowledge/ingest

Parameters

  • id (path, string, required) — Application ID

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/IngestRequest"
}

Responses

  • 200 — Knowledge operation result
  • 403 — Insufficient scope or application/site rights
  • 409 — Revision, review or publication conflict

POST /apps/{id}/knowledge/proposals

Parameters

  • id (path, string, required) — Application ID

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/ProposeRequest"
}

Responses

  • 200 — Knowledge operation result
  • 403 — Insufficient scope or application/site rights
  • 409 — Revision, review or publication conflict

POST /apps/{id}/knowledge/proposals/{proposal}/approve

Parameters

  • id (path, string, required) — Application ID
  • proposal (path, string, required) — Proposal ID

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/ApprovalRequest"
}

Responses

  • 200 — Knowledge operation result
  • 403 — Insufficient scope or application/site rights
  • 409 — Revision, review or publication conflict

POST /apps/{id}/knowledge/proposals/{proposal}/publish

Parameters

  • id (path, string, required) — Application ID
  • proposal (path, string, required) — Proposal ID

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/ApprovalRequest"
}

Responses

  • 200 — Knowledge operation result
  • 403 — Insufficient scope or application/site rights
  • 409 — Revision, review or publication conflict

Tag — Map generation

PUT /apps/{id}/source-reference

Parameters

  • id (path, string, required) — Existing application UUID

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/SourceReference"
}

Responses

  • 200 — Source reference bound
  • 400 — Invalid source identity
  • 403 — Manage permission or site access denied
  • 404 — Application unavailable
  • 409 — Source identity already reserved or application already linked

GET /map-generation/context

Parameters

  • profile (query, string, optional) — standard (default), mock-linux or mock-windows; standard requires maps:import for API keys
  • site_code (query, string, optional) —
  • hosting_name (query, string, optional) —

Responses

  • 200 — Only issuer-accessible sites and enrolled agents
  • 403 — Insufficient scope or site access

POST /map-generation/import

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/MapPlacementRequest"
}

Responses

  • 201 — New application with simultaneous per-component placements
  • 400 — Unresolved placement or invalid grants
  • 403 — Site access or maps:import scope denied
  • 409 — Application already exists; no overwrite supported

POST /map-generation/mock/import

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/MockMapRequest"
}

Responses

  • 201 — New simulation application and explicit site profiles created
  • 400 — Invalid map, ambiguous site or unavailable mock agent
  • 403 — Site or mock:import scope denied
  • 409 — Application name exists; no update or overwrite is supported

POST /map-generation/mock/prepare

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/MockMapRequest"
}

Responses

  • 200 — Read-only materialized simulation and resolved site bindings
  • 400 — Invalid map, ambiguous site or unavailable mock agent
  • 403 — Site or mock:import scope denied

POST /map-generation/prepare

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/MapPlacementRequest"
}

Responses

  • 200 — Read-only placement report for real or simulated execution
  • 400 — Invalid map, site, placement or team grants
  • 403 — Site access or maps:import scope denied

POST /maps/validate

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/ValidateMapRequest"
}

Responses

  • 200 — Inspect valid even for HTTP 200. No application writes or command execution. Does not verify agents, source fidelity or command safety.
  • 400 — Malformed JSON request
  • 401 — Authentication required
  • 409 — Contract version differs from the installed version
  • 422 — Invalid request envelope, missing fields or wrong types

DELETE /sites/{site_id}/mock-agents/{profile}

Parameters

  • site_id (path, string, required) —
  • profile (path, string, required) —

Responses

  • 204 — Default removed; agent retained
  • 403 — Administrator required

PUT /sites/{site_id}/mock-agents/{profile}

Parameters

  • site_id (path, string, required) —
  • profile (path, string, required) —

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/SetMockAgentRequest"
}

Responses

  • 200 — Administrator assigned a connected compatible agent to its own site
  • 400 — Target is ineligible
  • 403 — Administrator required

Tag — Map imports

POST /import/execute

POST /api/v1/import/execute

Publishes a reviewed map with explicit component-to-agent UUID mappings supplied outside content. Strict generated maps must not also contain binding_profiles; use /import/json for that alternative. conflict_action defaults to fail; update replaces the imported configuration of the application with the same name after authorization and binding checks. Periodic checks may begin immediately on bound agents. Not a global transaction: after a timeout/server error inspect the application before retrying. Sample UUIDs must be replaced with your enrolled resources.

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/ImportExecuteRequest"
}

Responses

  • 201 — Application created or updated, including active binding profile
  • 400 — Invalid map, profile, agent/site binding, or unsupported embedded profiles
  • 401 — Authentication required
  • 403 — Insufficient scope, application permission or target-site access
  • 409 — Application-name conflict or incompatible generation contract
  • 422 — Malformed request envelope

POST /import/json

POST /api/v1/import/json Import a v4 native JSON map into the database.

Creates a new application; not an idempotent upsert. Agent bindings are resolved from hosts/binding_profiles inside the map. generation_contract_version enables strict validation before writes. Review commands first: periodic checks may execute as soon as configuration reaches a bound agent. Import does not itself start or stop the application. After a timeout or server error, inspect the application list before retrying; the import is not a global transaction.

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/JsonImportRequest"
}

Responses

  • 201 — Application created; retain application_id and review warnings
  • 400 — Invalid map, unresolved/ambiguous explicit target, unsupported merge_into_app_id, or invalid site
  • 401 — Authentication required
  • 403 — Insufficient import scope or target-site access
  • 409 — Incompatible generation contract version
  • 422 — Malformed request envelope

POST /import/preview

POST /api/v1/import/preview

Read-only import preview: lists available agents, host resolutions and an existing application with the same name. Does not create a map or execute commands. First call /maps/validate for a strict generated map; preview does not accept generation_contract_version. Replace sample gateway UUIDs with values from GET /gateways.

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/ImportPreviewRequest"
}

Responses

  • 200 — Resolution report; inspect warnings and each component's resolution.status
  • 400 — Unsupported format or invalid map
  • 401 — Authentication required
  • 403 — Insufficient API scope
  • 422 — Malformed request envelope

Tag — Operations

POST /components/{id}/restart-branch

Restart a target and its consumers under one operation lock, restoring their upstream prerequisites before restarting the stopped runtime branch.

Parameters

  • id (path, string, required) — Runtime component to restart with its consumers

Responses

  • 200 — Atomic runtime restart accepted; completion is reported by component checks and activity. Consumers stop first; prerequisites start before the target and consumers.
  • 401 — Authentication required
  • 403 — Operate permission required
  • 404 — Component absent
  • 409 — Another application operation is active

Tag — PKI maintenance

GET /pki/maintenance

Responses

  • 200 — Installation credential metadata and recent maintenance requests
  • 403 — Administrator required

POST /pki/maintenance/complete

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/CompleteRequest"
}

Responses

  • 200 — Completion acknowledged
  • 403 — Administrator required
  • 409 — Request is not running or has a different result

POST /pki/maintenance/requests

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/EnqueueRequest"
}

Responses

  • 200 — Renewal requested
  • 403 — Administrator required
  • 409 — Worker unavailable or request already active

POST /pki/maintenance/worker

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/WorkerInventory"
}

Responses

  • 200 — Inventory accepted and at most one renewal claimed
  • 403 — Installation worker identity or administrator role required

Tag — Permissions

GET /apps/{app_id}/permissions

Parameters

  • app_id (path, string, required) —

Responses

  • 200 — Application permission operation within actor rights
  • 403 — Manage permission and execution-site access required
  • 404 — Application or recipient not in this organization

GET /apps/{app_id}/permissions/effective

Parameters

  • app_id (path, string, required) —

Responses

  • 200 — Application permission operation within actor rights
  • 403 — Manage permission and execution-site access required
  • 404 — Application or recipient not in this organization

GET /apps/{app_id}/permissions/teams

Parameters

  • app_id (path, string, required) —

Responses

  • 200 — Application permission operation within actor rights
  • 403 — Manage permission and execution-site access required
  • 404 — Application or recipient not in this organization

POST /apps/{app_id}/permissions/teams

Parameters

  • app_id (path, string, required) —

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/GrantTeamPermissionRequest"
}

Responses

  • 201 — Application permission operation within actor rights
  • 403 — Manage permission and execution-site access required
  • 404 — Application or recipient not in this organization

GET /apps/{app_id}/permissions/users

Parameters

  • app_id (path, string, required) —

Responses

  • 200 — Application permission operation within actor rights
  • 403 — Manage permission and execution-site access required
  • 404 — Application or recipient not in this organization

POST /apps/{app_id}/permissions/users

Parameters

  • app_id (path, string, required) —

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/GrantUserPermissionRequest"
}

Responses

  • 201 — Application permission operation within actor rights
  • 403 — Manage permission and execution-site access required
  • 404 — Application or recipient not in this organization

DELETE /apps/{app_id}/permissions/{perm_id}

Parameters

  • app_id (path, string, required) —
  • perm_id (path, string, required) —

Responses

  • 204 — Application permission operation within actor rights
  • 403 — Manage permission and execution-site access required
  • 404 — Application or recipient not in this organization

Tag — Sites

GET /sites

Lists the caller organization's sites. Select sites[].id as the import site_id. A site is a logical/physical execution location; it is distinct from an OpenShift namespace. Import also checks the caller's permission on the selected site.

Parameters

  • site_type (query, string, optional) — Optional site type filter
  • is_active (query, boolean, optional) — Optional active-state filter

Responses

  • 200 — Object with sites array; includes id, name, code, site_type, is_active and hosting information
  • 401 — Authentication required
  • 403 — Insufficient API scope

Tag — Teams

GET /teams

Responses

  • 200 — Organization-scoped team operation
  • 403 — Team lead or organization administrator required for modifications
  • 404 — Team or user not in this organization

POST /teams

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/CreateTeamRequest"
}

Responses

  • 201 — Organization-scoped team operation
  • 403 — Team lead or organization administrator required for modifications
  • 404 — Team or user not in this organization

GET /teams/search

Search teams by name (for pickers/autocomplete).

Responses

  • 200 — Organization-scoped team operation
  • 403 — Team lead or organization administrator required for modifications
  • 404 — Team or user not in this organization

DELETE /teams/{id}

Parameters

  • id (path, string, required) —

Responses

  • 204 — Organization-scoped team operation
  • 403 — Team lead or organization administrator required for modifications
  • 404 — Team or user not in this organization

GET /teams/{id}

Parameters

  • id (path, string, required) —

Responses

  • 200 — Organization-scoped team operation
  • 403 — Team lead or organization administrator required for modifications
  • 404 — Team or user not in this organization

PUT /teams/{id}

Parameters

  • id (path, string, required) —

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/UpdateTeamRequest"
}

Responses

  • 200 — Organization-scoped team operation
  • 403 — Team lead or organization administrator required for modifications
  • 404 — Team or user not in this organization

GET /teams/{id}/members

Parameters

  • id (path, string, required) —

Responses

  • 200 — Organization-scoped team operation
  • 403 — Team lead or organization administrator required for modifications
  • 404 — Team or user not in this organization

POST /teams/{id}/members

Parameters

  • id (path, string, required) —

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/AddMemberRequest"
}

Responses

  • 201 — Organization-scoped team operation
  • 403 — Team lead or organization administrator required for modifications
  • 404 — Team or user not in this organization

GET /teams/{team_id}/apps

List applications that a team has been granted access to.

Parameters

  • team_id (path, string, required) —

Responses

  • 200 — Organization-scoped team operation
  • 403 — Team lead or organization administrator required for modifications
  • 404 — Team or user not in this organization

DELETE /teams/{team_id}/members/{user_id}

Parameters

  • team_id (path, string, required) —
  • user_id (path, string, required) —

Responses

  • 204 — Organization-scoped team operation
  • 403 — Team lead or organization administrator required for modifications
  • 404 — Team or user not in this organization

Tag — X4B map generation

GET /x4b/map-generation

Parameters

  • offset (query, integer, optional) —
  • limit (query, integer, optional) —
  • status (query, string, optional) —
  • q (query, string, optional) —

Responses

  • 200 — Queue, published revisions and last source refresh
  • 403 — Administrator required

GET /x4b/map-generation/connection

Responses

  • 200 — Reachability of the configured knowledge catalogue; no generation is queued
  • 403 — Administrator required

GET /x4b/map-generation/jobs/{id}

Parameters

  • id (path, string, required) — Current generation job ID

Responses

  • 200 — Job and its validated candidate when available
  • 404 — Job unavailable or superseded

PUT /x4b/map-generation/jobs/{id}

Store only a reviewed descriptive map, using the same lock as publication.

Parameters

  • id (path, string, required) — Current generation job ID

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/CandidateEdit"
}

Responses

  • 200 — Proposal saved without publication
  • 409 — Proposal changed or already published

POST /x4b/map-generation/jobs/{id}/publish

Parameters

  • id (path, string, required) — Reviewed generation job ID

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/PublishRequest"
}

Responses

  • 200 — Application ID of the published topology
  • 409 — Stale review, missing review, or superseded candidate

POST /x4b/map-generation/jobs/{id}/retry

Parameters

  • id (path, string, required) — Current generation job ID

Responses

  • 202 — Generation requeued; any unpublished candidate is replaced
  • 409 — Job is no longer eligible for retry

POST /x4b/map-generation/jobs/{id}/review

Review the saved draft against its source revision without saving any changes.

Parameters

  • id (path, string, required) — Current generation job ID

Request body

Content-Type: application/json

{
  "oneOf": [
    {
      "type": "null"
    },
    {
      "$ref": "#/components/schemas/ProposalReviewRequest"
    }
  ]
}

Responses

  • 200 — Draft snapshot, suggested changes, advice, and open questions
  • 400 — Invalid review instruction or review input exceeds the size limit
  • 401 — Authentication required
  • 403 — Administrator required
  • 404 — Job unavailable or superseded
  • 409 — Proposal is no longer editable
  • 413 — Request body is too large
  • 503 — Connector unavailable

POST /x4b/map-generation/publish

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/PublishBatchRequest"
}

Responses

  • 200 — Independent publication result per job
  • 400 — Invalid publication selection

POST /x4b/map-generation/refresh

Responses

  • 202 — Refresh queued or already active
  • 503 — Connector unavailable

GET /x4b/map-generation/settings

Responses

  • 200 — Connector settings without credentials
  • 403 — Administrator session required

PUT /x4b/map-generation/settings

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/SettingsUpdate"
}

Responses

  • 200 — Saved settings without credentials
  • 403 — Administrator session required
  • 409 — Settings changed concurrently or managed by the deployment

POST /x4b/map-generation/settings/test

Request body

Content-Type: application/json

{
  "$ref": "#/components/schemas/SettingsTest"
}

Responses

  • 200 — Checks on a draft connector without saving or publishing
  • 400 — Invalid draft or unapproved origin
  • 403 — Administrator session required

Error responses

Application errors use the following body shape. Malformed requests rejected by the HTTP framework, authentication middleware, or a reverse proxy may use a different response format:

{ "error": "<machine-readable code>", "message": "<human-readable>" }

The full mapping of error codes to HTTP statuses is in the error reference.

See also