Admin API Reference

Overview

The Admin API provides the administrative control plane for the SOAP-2-REST platform. All platform management actions, including those available through the no-code UI, are executed via this API. API publishers use the Admin API to manage the entire lifecycle of a service, from initial WSDL import to versioning, activation, and observability.

The API is organized around key platform capabilities:

• WSDL Onboarding: Importing and parsing WSDL artifacts.
• Service Management: Creating and configuring logical services and their operations.
• Backend Configuration: Managing backend SOAP endpoint connection details and credentials.
• Versioning and Activation: Managing immutable, versioned drafts of services and promoting them to active status.
• Observability: Querying aggregated metrics, logs, and audit trails.

The Admin API is located at the base path /admin/v1. Authentication is role-based, with identity determined from forwarded headers from an Identity Provider (IdP). All endpoints are protected by this model.

How it works

The Admin API orchestrates the creation and management of REST APIs from SOAP services. The core workflow involves several distinct stages and concepts.

WSDL Import and Service Generation

The process begins by importing a WSDL file, which serves as the contract for the backend SOAP service. The API provides endpoints to import a WSDL from a file (/wsdl/import), a URL (/wsdl/import-url), or pasted XML content (/wsdl/import-xml). During import, the platform validates and parses the WSDL, creating a persistent artifactId.

From this imported artifact, an API publisher can generate a draft service using POST /admin/v1/wsdl/import/{artifactId}/generate-service. This creates the initial service, version, and operation objects.

For accelerated onboarding, :autopilot variants of the import endpoints perform the import and service generation in a single atomic call, providing a readiness assessment and draft configuration.

Versioning and Immutability

Service configurations, particularly operation mappings, are immutable once activated. All changes are made to a draft version.

1. Create Draft: A new draft version is created by calling POST /admin/v1/services/{serviceId}/versions, which clones the operations and active mappings from the current active version. A service can only have one draft version at a time.
2. Edit Draft: While a version is a draft, its operations and mappings can be modified. This includes changing the REST path and method, timeouts, and transformation rules via endpoints like PATCH /admin/v1/operations/{operationId} and PUT /admin/v1/operations/{operationId}/mapping. Attempting to edit an active version results in a 409 conflict error.
3. Validate Readiness: Before activation, an API publisher can check the draft's readiness using GET .../publish-readiness. This endpoint returns a status (READY_TO_PUBLISH, READY_WITH_RISK, BLOCKED) and a list of issues.
4. Activate: A ready draft is activated via POST .../{versionId}:activate. This makes the new version the live, request-serving configuration. Activating a BLOCKED draft is rejected.
5. Rollback: If necessary, the service can be rolled back to a previous version using POST .../{versionId}:rollback.

Backend Profile and Credential Management

Each service is associated with one or more backend profiles, which define the target SOAP endpoint URL, authentication method, and timeouts. Credentials for backend authentication are managed through these profiles. When credentials are set, they are encrypted at rest and are never returned in API responses. Instead, a metadata envelope confirming the update is returned.

Example Credential Update Response

When setting or updating credentials for a backend profile, the API does not echo the secret material. The response body confirms that the credential has been set.

{
  "set": true,
  "lastUpdatedAt": "2026-05-25T14:30:00Z",
  "lastUpdatedBy": "user@example.com"
}

API Endpoints

This section details the available Admin API endpoints, grouped by capability.

The source for this documentation does not provide field-level definitions for request or response payloads. For the canonical contract, refer to the low-level design documentation.

Identity

Method & Path	Description
GET /admin/v1/me	Returns the resolved identity and application role of the caller.

WSDL Import & Onboarding

Endpoints for importing, parsing, and repairing WSDLs to onboard new services.

Method & Path	Description
POST /admin/v1/wsdl/import	Uploads a WSDL file via multipart/form-data using the file field.
POST /admin/v1/wsdl/import-url	Fetches and imports a WSDL from a specified URL.
POST /admin/v1/wsdl/import-xml	Imports a WSDL directly from a pasted XML payload.
POST /admin/v1/wsdl/namespace-repair-preview	Previews automatic namespace declaration repairs the parser will perform.
POST /admin/v1/wsdl/external-reference-preview	Checks the health of external WSDL or XSD references before import.
POST /admin/v1/wsdl/repair-report	Provides combined repair diagnostics. The :repair-package variant returns a ZIP archive with the repaired root WSDL and its references.
GET /admin/v1/wsdl/import/{artifactId}	Retrieves a previously persisted import artifact and its parsed operations.
POST /admin/v1/wsdl/import/{artifactId}/generate-service	Generates a draft service, version, and operations from an imported WSDL catalog.
POST /admin/v1/wsdl/import:autopilot	Imports a WSDL file and automatically generates the service, operations, and mappings in a single call.
POST /admin/v1/wsdl/import-url:autopilot	Imports a WSDL from a URL and automatically generates the service, operations, and mappings.
POST /admin/v1/wsdl/import-xml:autopilot	Imports a WSDL from pasted XML and automatically generates the service, operations, and mappings.
POST /admin/v1/wsdl/import/{artifactId}:autopilot	Automatically generates a service, operations, and mappings from an already-imported artifact.
POST /admin/v1/wsdl/import-urls:autopilot	Batch imports multiple WSDLs from URLs.
POST /admin/v1/wsdl/import-files:autopilot	Batch imports multiple WSDL files.

Services & Operations

Endpoints for managing the lifecycle of services and their constituent operations.

Services

Method & Path	Description
POST /admin/v1/services	Creates a new logical service. Requires serviceKey, serviceName, and environment.
GET /admin/v1/services	Lists services with support for pagination and filtering by q, environment, and traffic.
GET /admin/v1/services/{serviceId}	Retrieves a single service by its ID.
PATCH /admin/v1/services/{serviceId}	Updates a service's metadata, status (active/disabled), or debugEnabled flag.
POST /admin/v1/services:bulk-action	Performs bulk actions (enable, disable, debug_on, debug_off, delete) on a set of services.
DELETE /admin/v1/services/{serviceId}	Soft-deletes a service by setting its status to deprecated.
DELETE /admin/v1/services/{serviceId}:hard-delete	Permanently deletes a service and all its dependent objects. This action is restricted to administrators and is rejected if the service is active.

Operations & Mappings

Edits to operations and mappings are only permitted on draft service versions.

Method & Path	Description
GET /admin/v1/services/{serviceId}/versions/{versionId}/operations	Lists the operations generated for a specific service version.
PATCH /admin/v1/operations/{operationId}	Edits an operation's restMethod, restPath, timeoutMs, or retryCount.
GET /admin/v1/operations/{operationId}/validation-rules	Reads the per-field request/response validation rules for an operation.
PATCH /admin/v1/operations/{operationId}/validation-rules	Overrides per-field validation rules.
GET /admin/v1/operations/{operationId}/transform-rules	Reads the no-code transformation rules for an operation.
PUT /admin/v1/operations/{operationId}/transform-rules	Replaces the transformation rules. Supported rules include trim, uppercase, lowercase, default_value, rename, split, join, and date_format.
GET /admin/v1/operations/{operationId}/mapping	Reads the active request, response, and fault mapping for an operation.
PUT /admin/v1/operations/{operationId}/mapping	Replaces the active mapping, creating a new mappingVersion.
GET /admin/v1/operations/{operationId}/mapping-diagnostics	Retrieves the readiness status for a single operation's mapping (AUTO_READY, AUTO_READY_WITH_WARNINGS, MANUAL_REQUIRED).
GET /admin/v1/services/{serviceId}/mapping-diagnostics	Retrieves mapping diagnostics for all operations in a service, with summary counters.
POST /admin/v1/operations/{operationId}/mapping:regenerate	Regenerates the automatic mapping from the stored WSDL contract, preserving any existing fault mapping.
POST /admin/v1/services/{serviceId}/mapping:regenerate	Regenerates mappings for all operations in a draft service version.

Backend Profiles & Credentials

Endpoints for managing connectivity and authentication for backend SOAP services.

Method & Path	Description
GET /admin/v1/services/{serviceId}/backend-profiles	Lists backend profiles for a service.
POST /admin/v1/services/{serviceId}/backend-profiles	Creates a new backend profile for a service.
PATCH /admin/v1/backend-profiles/{profileId}	Updates a profile's endpoint URL, authentication settings, timeout, or retry configuration.
DELETE /admin/v1/backend-profiles/{profileId}	Deletes a backend profile. If it was the default, another profile is reassigned as the default.
POST /admin/v1/backend-profiles/{profileId}:test-connection	Runs connection diagnostics (DNS, TCP, WSDL fetch) for the backend endpoint.
POST /admin/v1/backend-profiles/{profileId}:test-application	Executes a real SOAP test against the backend for a single operation and saves preview payloads.
POST /admin/v1/backend-profiles/{profileId}:test-generated-samples	Automatically generates request payloads from the contract and runs application tests for one or more operations.
POST /admin/v1/backend-profiles/{profileId}:test-rest	Executes a REST-style test against the backend.
GET /admin/v1/backend-profiles/{profileId}/test-previews	Retrieves recent saved test previews for the profile.
GET /admin/v1/services/{serviceId}/synthetic-monitor	Reads the synthetic monitoring configuration for a service.
POST /admin/v1/services/{serviceId}/synthetic-monitor	Creates or updates the synthetic monitoring configuration for a service.
GET /admin/v1/services/{serviceId}/test-datasets	Lists reusable named test datasets for a service.
POST /admin/v1/services/{serviceId}/test-datasets	Creates a reusable named test dataset.
DELETE /admin/v1/test-datasets/{datasetId}	Deletes a reusable named test dataset.

Backend Authentication Types

The authType field for a backend profile supports the following values. Mutual TLS (mtlsEnabled=true) can be used in conjunction with any authType.

authType	Description
none	No authentication.
basic	HTTP Basic authentication.
bearer	Bearer token authentication.
api_key_header	API key sent in a request header.
oauth2_client_credentials	OAuth 2.0 Client Credentials Grant flow.

Versioning, Activation & Rollback

Endpoints for managing the lifecycle of service versions.

Method & Path	Description
GET /admin/v1/services/{serviceId}/versions	Lists all versions of a service, newest first.
POST /admin/v1/services/{serviceId}/versions	Creates a new draft version by cloning the current active version. Fails if a draft already exists.
GET /admin/v1/services/{serviceId}/versions/{versionId}/publish-readiness	Assesses a draft's readiness for activation, returning a status (READY_TO_PUBLISH, READY_WITH_RISK, BLOCKED) and a list of issues.
POST /admin/v1/services/{serviceId}/versions/{versionId}:activate	Activates a draft version, making it the live configuration. Fails if the draft is BLOCKED.
POST /admin/v1/services/{serviceId}/versions/{versionId}:rollback	Rolls back the active configuration to a specified previous version.
GET /admin/v1/services/{serviceId}/versions/{versionId}/wsdl-drift	Assesses drift between the service version's contract and the newest comparable WSDL import. Returns UP_TO_DATE, DRIFT_DETECTED, BREAKING_DRIFT, or UNTRACKED.
POST /admin/v1/services/{serviceId}/versions/{versionId}:generate-replacement-draft	Creates a new draft from a newer WSDL import, preserving REST route and other settings where possible.

OpenAPI Export

Endpoints for generating and downloading OpenAPI v3 specifications.

Method & Path	Description
POST /admin/v1/services/{serviceId}/versions/{versionId}:generate-openapi	Generates an OpenAPI v3 artifact for a service version (admin-only).
GET /admin/v1/services/{serviceId}/versions/{versionId}/openapi	Downloads the generated OpenAPI v3 specification in JSON format. The response includes an X-OpenAPI-SHA256 header.
GET /admin/v1/services/{serviceId}/versions/{versionId}/openapi/package	Downloads a ZIP archive containing openapi.json, mapping-metadata.json, and checksums.json.

Settings & Roles

Endpoints for managing global platform settings and Role-Based Access Control (RBAC).

Method & Path	Description
GET /admin/v1/settings	Reads mutable platform settings.
PATCH /admin/v1/settings	Updates mutable settings such as default_timeout_ms, default_retry_count, default_retention_days, debug toggles, and SMTP alert settings.
GET /admin/v1/settings/alert-mail-history	Retrieves the history of recently sent SMTP alerts.
GET /admin/v1/role-bindings	Reads the bindings between IdP groups and application roles.
PUT /admin/v1/role-bindings	Replaces the full set of IdP group-to-role bindings.
GET /admin/v1/permission-bindings	Lists direct user-to-role assignments.
POST /admin/v1/permission-bindings	Creates a direct user-to-role assignment.
DELETE /admin/v1/permission-bindings/{bindingId}	Deletes a direct user-to-role assignment.

Observability, Metrics & Audit

Read-only endpoints for querying aggregated metrics, logs, and audit events. These endpoints query pre-computed aggregation tables for performance.

Method & Path	Description
GET /admin/v1/metrics	Retrieves aggregated metrics for a specified window (15m, 1h, 24h, 7d, 30d, 60d), including request/error counts and p50/p95/p99 latencies.
GET /admin/v1/slo-report	Returns the current SLO status, including availability and latency targets and any breaches.
GET /admin/v1/service-metric-timeline	Returns the request and error trend over time for a specific service.
GET /admin/v1/runtime-logs	Searches paged runtime logs by environment, service, operation, correlationId, resultCode, and time window.
GET /admin/v1/backend-test-previews	Searches saved backend test preview payloads.
GET /admin/v1/async-executions	Searches for asynchronous callback executions. Related endpoints support replay, reprocessing, and manual completion or failure.
GET /admin/v1/observability-filter-options	Provides lists of possible values for filter dropdowns in the UI.
GET /admin/v1/debug-traces/{correlationId}	Retrieves debug trace payloads for a specific correlation ID.
GET /admin/v1/debug-traces/{correlationId}/replay-metadata	Retrieves replay metadata for a specific correlation ID.
GET /admin/v1/audit-events	Queries the paged and windowed history of audit events.

Troubleshooting

API calls can fail for various reasons. Errors are returned in a standard envelope with an error code prefixed with S2R-ADM-* or S2R-VAL-*.

Status Code	Error Code	Condition
409 Conflict	S2R-ADM-0410	This error code indicates a state conflict. It is returned in several scenarios: Attempting to hard-delete an active service via DELETE /admin/v1/services/{serviceId}:hard-delete. Attempting to edit an operation or mapping belonging to an active, immutable service version. Attempting to create a new draft version via POST .../versions when a draft already exists for the service. Attempting to activate a service version that has a BLOCKED readiness status.

See Also

• API Reference Overview
• Runtime API Reference
• Error Codes Reference
• WSDL Onboarding: Zero-touch Autopilot
• Service Publishing and Versioning
• Mapping and Transformation Concepts
• Security: RBAC and Roles
• Observability Overview

---

All SOAP-to-REST docs