APIs¶

Target Architecture — Final-State Design

The endpoints below are the final-state contract surface of the Runtime & Cloud Platform. They follow the REST resource conventions in naming conventions: plural, lowercase, hyphenated collection nouns; sub-resources nested under their parent; non-CRUD actions as verb sub-paths.

The platform exposes a small, deliberate API surface. Public APIs are consumed by the Control Plane and the Factory Studio Runtime Center. Internal APIs are used service-to-service. gRPC is used for high-volume, low-latency runtime queries (health, inventory). All endpoints are prefixed /runtime and carried over HTTPS.

Authorization¶

All calls require an OAuth2 / OpenID Connect bearer token issued by the factory authorization server (OpenIddict).
Every request is tenant-scoped: the tenantId claim is asserted against the target environment's RuntimeTenantBinding before any action.
Scopes follow runtime.{resource}.{action}:

Scope	Grants
`runtime.environments.write`	Provision / decommission environments
`runtime.environments.read`	Read environment state and inventory
`runtime.deployments.write`	Create deployments and trigger rollback
`runtime.deployments.read`	Read deployment status and history
`runtime.configurations.write`	Publish runtime configuration
`runtime.secrets.write`	Create secret bindings, request rotation
`runtime.health.read`	Read health results
`runtime.scaling.write`	Apply scaling policies
`runtime.drift.read`	Read drift findings

Mutating environment, deployment, scaling, and secret operations additionally require a governance policy decision from the Governance, Security & Compliance Platform for production environments.

Versioning¶

APIs are versioned by URL prefix (/v1/runtime/...); v1 is implied where omitted in examples.
Additive changes (new optional fields) are non-breaking; breaking changes introduce a new version and the prior version is supported through a published deprecation window.
Every response carries cs-schema-version so clients can verify compatibility.

Public REST APIs¶

Method	Path	Purpose	Scope
`POST`	`/runtime/environments`	Provision a new runtime environment	`runtime.environments.write`
`GET`	`/runtime/environments/{environmentId}`	Get environment state and inventory	`runtime.environments.read`
`POST`	`/runtime/deployments`	Deploy generated workloads into an environment	`runtime.deployments.write`
`GET`	`/runtime/deployments/{deploymentId}`	Get deployment status and rollout history	`runtime.deployments.read`
`POST`	`/runtime/configurations`	Publish a versioned runtime configuration	`runtime.configurations.write`
`POST`	`/runtime/secret-bindings`	Bind a workload to Key Vault secrets	`runtime.secrets.write`
`GET`	`/runtime/services/{serviceId}/health`	Get the latest health result for a service	`runtime.health.read`
`POST`	`/runtime/scaling-policies`	Apply a scaling policy to a service	`runtime.scaling.write`
`GET`	`/runtime/drift/{environmentId}`	List drift findings for an environment	`runtime.drift.read`

Internal APIs¶

ServiceCatalogRuntimeService exposes internal inventory mutation endpoints consumed by the RuntimeInventoryWorker.
TenantRuntimeIsolationService exposes internal binding endpoints consumed during provisioning and deployment.
RuntimeHealthService exposes a streaming internal endpoint for the RuntimeHealthWorker.

gRPC APIs¶

High-frequency runtime queries are served over gRPC to minimize latency and payload overhead:

RuntimeInventory.GetServices(environmentId, tenantId) — live inventory snapshot.
RuntimeHealth.StreamHealth(serviceId) — server-streaming health updates.
RuntimeDrift.GetFindings(environmentId) — current drift findings.

gRPC services share the same OAuth2 bearer auth and tenant-scoping as REST.

Examples¶

Provision an environment¶

POST /v1/runtime/environments
Authorization: Bearer <token>
Content-Type: application/json

{
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "name": "booking-prod-weu",
  "stage": "prod",
  "region": "westeurope",
  "isolationModel": "silo",
  "computeTargets": ["aks", "container-apps", "functions", "app-service"]
}

{
  "environmentId": "env-9f1c2b7d",
  "status": "Provisioning",
  "traceId": "trace-9f1c2b7d",
  "pulumiStackRef": "booking-prod-weu"
}

Deploy generated workloads¶

POST /v1/runtime/deployments
Authorization: Bearer <token>
Content-Type: application/json

{
  "tenantId": "connectsoft",
  "environmentId": "env-9f1c2b7d",
  "releaseRef": "release-2026.6.11",
  "components": [
    { "moduleId": "module-reservations-api", "image": "acr.azurecr.io/reservations-api:1.4.2", "target": "aks" },
    { "moduleId": "module-billing-worker", "image": "acr.azurecr.io/billing-worker:1.4.2", "target": "container-apps" }
  ],
  "configurationId": "cfg-3a6e1d40",
  "strategy": "RollingHealthGated"
}

{
  "deploymentId": "dep-3a6e1d40",
  "status": "InProgress",
  "traceId": "trace-9f1c2b7d"
}

Get service health¶

GET /v1/runtime/services/module-reservations-api/health
Authorization: Bearer <token>

{
  "serviceId": "module-reservations-api",
  "environmentId": "env-9f1c2b7d",
  "status": "Healthy",
  "checks": [
    { "name": "self", "status": "Healthy" },
    { "name": "sql", "status": "Healthy", "durationMs": 12 },
    { "name": "service-bus", "status": "Healthy", "durationMs": 8 }
  ],
  "evaluatedAt": "2026-06-11T18:00:00Z"
}

Apply a scaling policy¶

POST /v1/runtime/scaling-policies
Authorization: Bearer <token>
Content-Type: application/json

{
  "tenantId": "connectsoft",
  "environmentId": "env-9f1c2b7d",
  "serviceId": "module-reservations-api",
  "target": "aks",
  "metric": "cpu",
  "minReplicas": 2,
  "maxReplicas": 20,
  "targetUtilizationPercent": 65,
  "scaleToZero": false
}

{
  "scalingPolicyId": "scl-7c12",
  "status": "Applied",
  "traceId": "trace-9f1c2b7d"
}

List drift findings¶

GET /v1/runtime/drift/env-9f1c2b7d
Authorization: Bearer <token>

{
  "environmentId": "env-9f1c2b7d",
  "findings": [
    {
      "findingId": "drift-1a2b",
      "serviceId": "module-reservations-api",
      "kind": "ImageVersionMismatch",
      "desired": "1.4.2",
      "actual": "1.4.1",
      "severity": "High",
      "detectedAt": "2026-06-11T18:05:00Z"
    }
  ]
}