Reference · Endpoints

Manage endpoint lifecycle

Suspend or resume an endpoint; a suspended endpoint refuses new operations while its record stays readable.

POST/v1/programmable-endpoints/{endpointRef}/lifecycle

Authorization: Bearer ak_test_… · Application API key

Idempotency-Key: <uuid> · required

Try it

This operation writes. Compose it in the playground, where you pick refs from objects you hold and pass one human check before it fires — then follow it back here.

Key capabilities

ProgrammableEndpointLifecycleManage

Parameters

endpointRefpath · required

Request body fields

operation
reason
lifecycleGuard.stateVersion
lifecycleGuard.fingerprint

Refused request fields

The platform derives this material itself; a request that supplies any of it is refused.

policyFingerprint
expectedStateVersion
expectedPolicyFingerprint
commandRef
providerRefs
topologyRefs
obligationRefs

Contract notes

supportedOperationssuspend · resume

suspendReasonsoperator_hold · provider_restriction · compliance_hold

resumeReasonsoperator_cleared

guardSemanticsopaque guard is returned by public endpoint read and revalidated against Accounts before mutation

staleGuardslifecycleGuard

Sharp edges

The command carries one opaque lifecycle guard returned by the latest programmable endpoint read. Accounts revalidates its state version and fingerprint before mutation.
The guard is concurrency evidence, not permission or policy truth. After a stale rejection, read again, decide again, and submit a new command with a new idempotency key; do not retry automatically.

Wire receipt

Captured from the real gateway by the scenario suite; nothing here is composed by hand.

The lifecycle command uses exactly the guard returned by the immediately preceding public read.

Request

POST /v1/programmable-endpoints/184dac2f-5c2c-3c3d-bd6f-5f1c83f33348/lifecycle
Authorization: Bearer ak_test_…
Idempotency-Key: e3e91f47-7b87-467d-8a19-c951d73828d1
Content-Type: application/json

{
  "operation": "suspend",
  "reason": "operator_hold",
  "lifecycleGuard": {
    "stateVersion": 1,
    "fingerprint": "fp:endpoint-lifecycle-guard:4f629ad6910ac2f3ecb9f705962f10b31aa494ccb19083f90fd49dfa6b6fd762"
  }
}

Response · 200

{
  "status": 200,
  "body": {
    "command": {
      "occurrence": "first_accepted",
      "lifecycleStatus": "applied",
      "replayed": false
    },
    "endpoint": {
      "value": {
        "organisationRef": "41a1d9f8-e50b-4e1c-8daa-14afcb683453",
        "appRef": "e591e8dd-a950-40f7-a852-15fb96359274",
        "environmentRef": "96222014-531b-429d-bc91-77298cb2a01e",
        "result": {
          "kind": "applied",
          "applied": {
            "endpointRef": "184dac2f-5c2c-3c3d-bd6f-5f1c83f33348",
            "previousPosture": "active",
            "currentPosture": "suspended",
            "previousStateVersion": 1,
            "currentStateVersion": 2,
            "lifecycleGuard": {
              "stateVersion": 2,
              "fingerprint": "fp:endpoint-lifecycle-guard:d73b68aea901aa889410da5f8d7cbdb04c0990f24b2ecd0c7394bf6d908faa33"
            },
            "reason": "operator_hold"
          }
        }
      },
      "freshness": "Current",
      "visibility": "Full",
      "evidence": [
        {
          "receiptRef": "ff078a72-b6a5-34a6-b852-a0993de61e1d",
          "source": "VaeRuntime"
        },
        {
          "receiptRef": "d9409298-37dd-3235-91f3-8bfe9d98d9fd",
          "source": "SecurityIdentity"
        },
        {
          "receiptRef": "09017e81-7665-3dc7-99fe-ba4a24919466",
          "source": "SecurityIdentity"
        }
      ]
    }
  },
  "evidence": [
    {
      "receiptRef": "ff078a72-b6a5-34a6-b852-a0993de61e1d"
    },
    {
      "receiptRef": "d9409298-37dd-3235-91f3-8bfe9d98d9fd"
    },
    {
      "receiptRef": "09017e81-7665-3dc7-99fe-ba4a24919466"
    }
  ]
}

captured 2026-07-12 · gateway 0.1.0 · Suspend and resume safely · Suspend with the current guard

generated from openapi.json · gateway 0.1.0 · sandbox