API Reference Overview: Control-Plane, Runtime, and Ingest APIs

Overview

The platform exposes three distinct API surfaces, each designed for a different purpose and audience. Understanding which API to use is critical for integration and operation. The primary surfaces for external integration are the Control-plane (Admin) API and the Runtime (Data-plane) API.

Surface	Base Path	Audience	Purpose
Control-plane (Admin) API	/admin/v1/*	Operators & platform teams	Provides no-code management of the platform, including WSDL import, service configuration, mappings, backends, settings, roles, and all observability queries.
Runtime (Data-plane) API	/{direction}/{env}/...	API consumers / SOAP clients	The live conversion traffic surface. Publish exposes a SOAP backend as REST; Consume exposes a REST backend as SOAP.
Ingest API	/ingest/v1/*	Edge connectors (internal)	Receives traffic-log feeds from gateway or load-balancer connectors to power traffic-driven discovery. This is not a customer-called API.

The Ingest API is an internal component used by the platform's own connectors and is not detailed here.

How it works

This section details the common mechanisms shared across the API surfaces, including authentication, request routing, correlation, and error handling.

Authentication Model

Authentication methods differ significantly between the control-plane and the runtime data-plane.

Control-plane (Admin) API

The Admin API is not publicly reachable and is deployed behind an identity-aware ingress (such as Google IAP or an OIDC/SAML front door). The platform performs role-based authorization for every request to an /admin/v1/* endpoint.

The caller's identity is resolved from forwarded identity headers sent by the ingress:

• X-Goog-Authenticated-User-Email
• X-Goog-Authenticated-User-Groups (a comma-separated list of group emails)

This resolved identity is mapped to one of three application roles: admin, operator, or reader. This mapping is determined by role bindings configured via IdP group membership, direct in-app principal assignments, or an emergency bootstrap list. An API call that is forbidden for the caller's role will be rejected with the error code S2R-ADM-0403.

To inspect the currently resolved identity and role, an authenticated user can call GET /admin/v1/me.

Runtime (Data-plane) API

The runtime API is an internal-only service that should never be published directly. Authentication of the inbound API consumer is handled by the ingress or API gateway positioned in front of the runtime. The runtime's own credential handling is focused on authenticating its outbound calls to backend services.

Base Paths

API endpoints are organized under distinct base paths that determine their function.

• Admin API: All endpoints are prefixed with /admin/v1. Paths in the documentation are relative to this base, e.g., /services refers to /admin/v1/services.
• Runtime API: All conversion routes begin with a direction segment: /publish/{env}/{serviceKey}/{op...} or /consume/{env}/{serviceKey}/{op...}. A request to the runtime that omits this direction segment will be rejected with the error code S2R-RUN-0405.

Correlation IDs

Every request processed by the runtime API is assigned a unique correlation ID. This ID is propagated through the entire request lifecycle, including the inbound call, backend call, data mapping, structured logs, and any debug traces.

• Supplying an ID: API consumers can provide their own correlation ID by sending the X-Correlation-Id header on the request. If this header is absent, the runtime generates a new ID.
• Response Header: The correlation ID is echoed back in the X-Correlation-Id response header.
• Observability: The correlation ID serves as the primary join key across all observability surfaces, allowing a single request to be traced through searchable logs, live traffic views, and debug traces. It is also included in all error responses.

Standard Error Envelope

Both the Admin and Runtime APIs return errors in a standardized JSON format to ensure consistent error handling.

{
  "error": {
    "code": "S2R-RUN-0413",
    "message": "Payload too large",
    "details": {
      "maxPayloadMb": 30
    },
    "correlationId": "00000000-0000-0000-0000-000000000000"
  }
}

Error Fields

Field	Type	Description
code	String	A stable, machine-readable error code in the format S2R-<AREA>-<NNNN>.
message	String	A human-readable summary of the error.
details	Object	A JSON object containing code-specific context about the error. May be an empty object ({}).
correlationId	String	The correlation ID for the request, used for tracing the error in logs and other observability tools.

Exception for SOAP Consumers: For requests on the /consume/... path, which exposes a REST service as a SOAP facade, errors are returned as a SOAP Fault envelope with a Content-Type of application/soap+xml or text/xml. This is to ensure compatibility with SOAP clients that expect a fault response. The error codes within the fault are the same as those used in the JSON envelope.

Troubleshooting

• S2R-ADM-0403: This error on an /admin/v1/* endpoint indicates a permissions failure. The resolved identity of the caller does not have the required role (admin, operator, or reader) to perform the requested action. Check the role bindings for the user or group.
• S2R-RUN-0405: This error on a runtime API call means the request path is missing the required initial direction segment (/publish or /consume).
• S2R-RUN-0413: As shown in the example, this indicates the request payload exceeds a configured limit. The details object may contain the specific limit that was violated.
• Tracing Errors: Use the correlationId from any error response to find the full request lifecycle in the platform's logging and tracing systems.

See Also

• Admin (control-plane) API
• Runtime API
• Error codes
• RBAC & roles
• Observability overview

---

All SOAP-to-REST docs