Skip to main content
POST
Connect an application to a managed service

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
instance_id
string<uuid>
required

Body

application/json
​
consumer_id
string<uuid>
required

The binding of the application environment to connect, from POST .../consumers.

​
expected_generation
integer<int64>
required

The instance generation the person read; a request against any other generation is refused.

Required range: x >= 1

Response

The instance with the environment among its consumers.

​
id
string<uuid>
required
​
package_version_id
string<uuid>
required
​
cluster_id
string<uuid>
required
​
cluster_name
string
required

The service cluster's name as it reads now, for display; cluster_id is the identity.

​
state
enum<string>
required

The instance's lifecycle in one word, folded at read time from deployment_state, health, readiness and retirement; those fields stay the evidence. released: the instance was released and its name is free. retiring: a confirmed retirement is removing it. failed: its admission or deployment operation failed. deploying: it is being installed, or its workload is rolling out. serving: the platform last observed its workload serving and no readiness check found it failing. degraded: an observation or readiness check found it not serving, or a namespace quota refuses its pods. deployed: its deployment finished and nothing observes its health (a package that is not a first-party engine, or one the health loop has not reached); not a statement that it serves. unknown: the recorded evidence establishes none of these. Precedence is released, retiring, failed, deploying, then the health-based states.

Available options:
deploying,
deployed,
serving,
degraded,
failed,
retiring,
released,
unknown
​
admission_operation_id
string<uuid>
required
​
name
string
required
​
region
string
required

Physical cloud region of the placement, for example eu-north-1. It locates infrastructure; it is not the data-location promise, which is data_boundary.

​
data_boundary
string
required

Boundary the data is permitted to stay within, for example eu. Sharing a service across clusters is decided by this boundary, never by the physical region.

​
generation
integer<int64>
required
Required range: x >= 1
​
mode
enum<string>
required
Available options:
customer,
existing,
hosted
​
requested_destinations
object[]
required

Requested destinations from the durable plan; not proof of a live service connection.

​
consumers
object[]
required

The reviewed plan's consumers with their ids: exactly the set a retirement request names in disconnect_consumer_ids. Reviewed intent, not proof of a live connection.

​
deployment_operation_id
string<uuid> | null
required

Present only when current execution evidence matches the stored receipt and organisation/cluster scope.

​
deployment_state
enum<string>
required
Available options:
accepted,
admission_failed,
deploying,
deployment_failed,
verification_pending,
unknown,
released
​
readiness
enum<string>
required

Whether a consumer can use the service, from a scoped consumer-path canary - for PostgreSQL, a pod in the instance namespace logging in with the generated credentials by Secret reference and running SELECT 1 every five minutes; a result stands fifteen minutes. unverified: no canary covers this instance (an engine other than PostgreSQL, a hosted, released or later-generation instance, or one with no deployment receipt); a successful deployment is not readiness. verifying: covered, and no canary has established readiness yet - none has run, or the service is still deploying or inside its first start's grace window. ready: an unexpired canary passed. degraded: an unexpired canary ran and failed after the service had its chance to start. stale: readiness cannot currently be established - the canary could not run (no agent, the cluster unavailable, the canary pod refused or not finishing) or its last result expired; an expired ready is never reported.

Available options:
unverified,
verifying,
ready,
degraded,
stale
​
readiness_check
object | null
required

The canary evidence behind readiness, folded against the database clock at read time. Null when no canary has run at this generation. A canary that could not run leaves an unexpired pass or failure standing until it expires, so observed_at is when the standing result was observed, not necessarily the latest attempt. Never carries a probe log or a credential.

​
created_at
string<date-time>
required
​
released_at
string<date-time> | null
required
​
evidence_updated_at
string<date-time> | null
required
​
connection
object | null
required

Where a first-party engine instance is reached inside its cluster and which Secret in its namespace holds the credentials the engine generated. Derived from the engine profile, not observed; null for any other package.

​
health
object | null
required

Health as the platform last observed it from the service cluster's synced state: whether the engine's workload reports ready, its Service and credentials Secret exist, and the stack that owns it is still deployed. It is not readiness - no consumer connection is proven. Evidence past expires_at reads unknown, folded against the database clock at read time, so a stopped observer never leaves a stale serving. Null when nothing has observed this generation: a package that is not a first-party engine, an instance not deployed yet, a released instance, or one not observed yet.

​
retirement
object | null
required

The latest confirmed retirement, running or settled; null when none was ever confirmed. A settled outcome other than retired left the service and its name in place.