Skip to content

Unpublished SDK candidate: reviewed source snapshot of 13 September 2026; SDK modules, v2 writes and the external-worker dispatcher are unavailable in main. See availability and source.

SDK HTTP operation reference

Generated by python3 scripts/sdk/reference.py. Do not edit generated tables.

These are the SDK candidate contracts. The current CPRa application serves v1 read-only endpoints; its v2 management and worker servers are not implemented. A listed SDK method is not evidence of a deployed server route. See the guide for runnable local examples.

Schema input SHA-256: 71723960b55145b57009faa9daa7fede20b08d85117171474b7c0631b4eb4977.

Shared request rules

Every method takes context.Context first. Authenticated v2 requests require HTTPS by default. Redirects and automatic mutation retries are disabled. Config.AllowInsecureHTTP explicitly permits the configured origin. Ordinary requests default to ten seconds and a 64 MiB decoded-response ceiling.

Response[T] keeps Data, ResourceVersion, RequestID, OperationID, StatusCode, and RetryAfter separate. Pass the version you inspected to conditional changes. List calls default to 100 items and reject limits above 500. Iterate retains one page. Unknown driver observations are readable but cannot be blindly reapplied.

Errors support errors.Is for conflicts, missing resources, unavailable features, expired operations, authentication, invalid input, oversized responses, and ambiguous mutations. Use errors.As for structured *cpra.Error details; avoid logging server detail or credential-bearing payloads. A cancelled wait does not cancel the server operation.

Operation inventory

SDK method HTTP operation Request Response Condition Build
MonitorsService.List GET /api/v2/monitors — MonitorList — default
MonitorsService.Create POST /api/v2/monitors Monitor Monitor If-None-Match: * default
MonitorsService.Get GET /api/v2/monitors/{id} — Monitor — default
MonitorsService.Replace PUT /api/v2/monitors/{id} Monitor Monitor inspected version default
MonitorsService.Patch PATCH /api/v2/monitors/{id} MergePatch Monitor inspected version default
MonitorsService.Delete DELETE /api/v2/monitors/{id} — Operation inspected version default
NotificationEndpointsService.List GET /api/v2/notification-endpoints — NotificationEndpointList — default
NotificationEndpointsService.Create POST /api/v2/notification-endpoints NotificationEndpoint NotificationEndpoint If-None-Match: * default
NotificationEndpointsService.Get GET /api/v2/notification-endpoints/{id} — NotificationEndpoint — default
NotificationEndpointsService.Replace PUT /api/v2/notification-endpoints/{id} NotificationEndpoint NotificationEndpoint inspected version default
NotificationEndpointsService.Patch PATCH /api/v2/notification-endpoints/{id} MergePatch NotificationEndpoint inspected version default
NotificationEndpointsService.Delete DELETE /api/v2/notification-endpoints/{id} — Operation inspected version default
NotificationGroupsService.List GET /api/v2/notification-groups — NotificationGroupList — default
NotificationGroupsService.Create POST /api/v2/notification-groups NotificationGroup NotificationGroup If-None-Match: * default
NotificationGroupsService.Get GET /api/v2/notification-groups/{id} — NotificationGroup — default
NotificationGroupsService.Replace PUT /api/v2/notification-groups/{id} NotificationGroup NotificationGroup inspected version default
NotificationGroupsService.Patch PATCH /api/v2/notification-groups/{id} MergePatch NotificationGroup inspected version default
NotificationGroupsService.Delete DELETE /api/v2/notification-groups/{id} — Operation inspected version default
CredentialsService.List GET /api/v2/credentials — CredentialList — default
CredentialsService.Create POST /api/v2/credentials Credential Credential If-None-Match: * default
CredentialsService.Get GET /api/v2/credentials/{id} — Credential — default
CredentialsService.Replace PUT /api/v2/credentials/{id} Credential Credential inspected version default
CredentialsService.Patch PATCH /api/v2/credentials/{id} MergePatch Credential inspected version default
CredentialsService.Delete DELETE /api/v2/credentials/{id} — Operation inspected version default
IncidentsService.List GET /api/v2/incidents — IncidentList — default
IncidentsService.Get GET /api/v2/incidents/{id} — Incident — default
ActionsService.List GET /api/v2/actions — ActionList — default
ActionsService.Get GET /api/v2/actions/{id} — Action — default
IncidentsService.Acknowledge POST /api/v2/incidents/{id}/acknowledge ControlRequest Incident inspected version default
IncidentsService.Dismiss POST /api/v2/incidents/{id}/dismiss ControlRequest Incident inspected version default
IncidentsService.Reopen POST /api/v2/incidents/{id}/reopen ControlRequest Incident inspected version default
MonitorsService.Snooze POST /api/v2/monitors/{id}/snooze ControlRequest Operation inspected version default
MonitorsService.Unsnooze POST /api/v2/monitors/{id}/unsnooze ControlRequest Operation inspected version default
MonitorsService.Recover POST /api/v2/monitors/{id}/recover ControlRequest Operation inspected version default
ActionsService.Review POST /api/v2/actions/{id}/review ControlRequest Action inspected version default
OperationsService.Preflight POST /api/v2/collections/preflight PreflightRequest Preflight — default
OperationsService.Create POST /api/v2/operations OperationCreateRequest Operation — default
OperationsService.Upload PUT /api/v2/operations/{id}/items UploadRequest Operation — default
OperationsService.Activate POST /api/v2/operations/{id}/activate — Operation — default
OperationsService.Cancel POST /api/v2/operations/{id}/cancel — Operation — default
OperationsService.Get GET /api/v2/operations/{id} — Operation — default
Client.State GET /api/v2/state — State — default
Client.History GET /api/v2/history — EventList — default
SLOService.Get GET /api/v2/slo — SLOView — default
QueuesService.List GET /api/v2/queues — QueueList — default
PoolsService.List GET /api/v2/pools — PoolList — default
SystemsService.List GET /api/v2/systems — SystemList — default
Client.RuntimeConfig GET /api/v2/config — RuntimeConfig — default
Client.Ready GET /api/v2/readyz — Health — default
Client.Live GET /api/v2/healthz — Health — default
Client.Metrics GET /api/v2/metrics — Metrics — default
Client.Capabilities GET /api/v2/discovery — Capabilities — default
Client.Version GET /api/v2/version — Version — default
Client.Explain GET /api/v2/schemas/{id} — Explanation — default
WorkerClient.Poll POST /api/v2/external-workers/poll PollRequest Assignments — externaljobs
WorkerClient.Start POST /api/v2/external-workers/start StartRequest StartResponse — externaljobs
WorkerClient.Heartbeat POST /api/v2/external-workers/heartbeat HeartbeatRequest HeartbeatResponse — externaljobs
WorkerClient.Result POST /api/v2/external-workers/result Outcome Receipt — externaljobs
WorkerClient.LateEvidence POST /api/v2/external-workers/late-evidence LateEvidenceRequest Receipt — externaljobs
JobTypesService.List GET /api/v2/job-types — JobTypeList — externaljobs
JobTypesService.Create POST /api/v2/job-types JobType JobType If-None-Match: * externaljobs
JobTypesService.Get GET /api/v2/job-types/{id} — JobType — externaljobs
JobTypesService.Replace PUT /api/v2/job-types/{id} JobType JobType inspected version externaljobs
JobTypesService.Delete DELETE /api/v2/job-types/{id} — Operation inspected version externaljobs
Client.Workers GET /api/v2/external-workers — WorkerObservationList — externaljobs
OperationsService.Validate POST /api/v2/operations/{id}/validate — Preflight — default

Disable and Enable are narrow conditional monitor patches. Acknowledge records who is investigating; dismiss pauses incident notifications; snooze pauses checks and notifications until its deadline. These controls have separate revision requirements. No check-now operation exists.

Operation parameters

ListMonitors

MonitorsService.List → GET /api/v2/monitors

Parameter Location Required Type
cursor query false string
limit query false integer
selector query false string
monitorID query false string

Response: MonitorList. See wire types and Go declarations.

CreateMonitor

MonitorsService.Create → POST /api/v2/monitors

Parameter Location Required Type
If-None-Match header true string

Body: Monitor. Content type: application/json.

Response: Monitor. See wire types and Go declarations.

GetMonitor

MonitorsService.Get → GET /api/v2/monitors/{id}

Parameter Location Required Type
id path true string

Response: Monitor. See wire types and Go declarations.

ReplaceMonitor

MonitorsService.Replace → PUT /api/v2/monitors/{id}

Parameter Location Required Type
id path true string
If-Match header true string

Body: Monitor. Content type: application/json.

Response: Monitor. See wire types and Go declarations.

PatchMonitor

MonitorsService.Patch → PATCH /api/v2/monitors/{id}

Parameter Location Required Type
id path true string
If-Match header true string

Body: MergePatch. Content type: application/merge-patch+json.

Response: Monitor. See wire types and Go declarations.

DeleteMonitor

MonitorsService.Delete → DELETE /api/v2/monitors/{id}

Parameter Location Required Type
id path true string
If-Match header true string

Response: Operation. See wire types and Go declarations.

ListNotificationEndpoints

NotificationEndpointsService.List → GET /api/v2/notification-endpoints

Parameter Location Required Type
cursor query false string
limit query false integer
selector query false string
monitorID query false string

Response: NotificationEndpointList. See wire types and Go declarations.

CreateNotificationEndpoint

NotificationEndpointsService.Create → POST /api/v2/notification-endpoints

Parameter Location Required Type
If-None-Match header true string

Body: NotificationEndpoint. Content type: application/json.

Response: NotificationEndpoint. See wire types and Go declarations.

GetNotificationEndpoint

NotificationEndpointsService.Get → GET /api/v2/notification-endpoints/{id}

Parameter Location Required Type
id path true string

Response: NotificationEndpoint. See wire types and Go declarations.

ReplaceNotificationEndpoint

NotificationEndpointsService.Replace → PUT /api/v2/notification-endpoints/{id}

Parameter Location Required Type
id path true string
If-Match header true string

Body: NotificationEndpoint. Content type: application/json.

Response: NotificationEndpoint. See wire types and Go declarations.

PatchNotificationEndpoint

NotificationEndpointsService.Patch → PATCH /api/v2/notification-endpoints/{id}

Parameter Location Required Type
id path true string
If-Match header true string

Body: MergePatch. Content type: application/merge-patch+json.

Response: NotificationEndpoint. See wire types and Go declarations.

DeleteNotificationEndpoint

NotificationEndpointsService.Delete → DELETE /api/v2/notification-endpoints/{id}

Parameter Location Required Type
id path true string
If-Match header true string

Response: Operation. See wire types and Go declarations.

ListNotificationGroups

NotificationGroupsService.List → GET /api/v2/notification-groups

Parameter Location Required Type
cursor query false string
limit query false integer
selector query false string
monitorID query false string

Response: NotificationGroupList. See wire types and Go declarations.

CreateNotificationGroup

NotificationGroupsService.Create → POST /api/v2/notification-groups

Parameter Location Required Type
If-None-Match header true string

Body: NotificationGroup. Content type: application/json.

Response: NotificationGroup. See wire types and Go declarations.

GetNotificationGroup

NotificationGroupsService.Get → GET /api/v2/notification-groups/{id}

Parameter Location Required Type
id path true string

Response: NotificationGroup. See wire types and Go declarations.

ReplaceNotificationGroup

NotificationGroupsService.Replace → PUT /api/v2/notification-groups/{id}

Parameter Location Required Type
id path true string
If-Match header true string

Body: NotificationGroup. Content type: application/json.

Response: NotificationGroup. See wire types and Go declarations.

PatchNotificationGroup

NotificationGroupsService.Patch → PATCH /api/v2/notification-groups/{id}

Parameter Location Required Type
id path true string
If-Match header true string

Body: MergePatch. Content type: application/merge-patch+json.

Response: NotificationGroup. See wire types and Go declarations.

DeleteNotificationGroup

NotificationGroupsService.Delete → DELETE /api/v2/notification-groups/{id}

Parameter Location Required Type
id path true string
If-Match header true string

Response: Operation. See wire types and Go declarations.

ListCredentials

CredentialsService.List → GET /api/v2/credentials

Parameter Location Required Type
cursor query false string
limit query false integer
selector query false string
monitorID query false string

Response: CredentialList. See wire types and Go declarations.

CreateCredential

CredentialsService.Create → POST /api/v2/credentials

Parameter Location Required Type
If-None-Match header true string

Body: Credential. Content type: application/json.

Response: Credential. See wire types and Go declarations.

GetCredential

CredentialsService.Get → GET /api/v2/credentials/{id}

Parameter Location Required Type
id path true string

Response: Credential. See wire types and Go declarations.

ReplaceCredential

CredentialsService.Replace → PUT /api/v2/credentials/{id}

Parameter Location Required Type
id path true string
If-Match header true string

Body: Credential. Content type: application/json.

Response: Credential. See wire types and Go declarations.

PatchCredential

CredentialsService.Patch → PATCH /api/v2/credentials/{id}

Parameter Location Required Type
id path true string
If-Match header true string

Body: MergePatch. Content type: application/merge-patch+json.

Response: Credential. See wire types and Go declarations.

DeleteCredential

CredentialsService.Delete → DELETE /api/v2/credentials/{id}

Parameter Location Required Type
id path true string
If-Match header true string

Response: Operation. See wire types and Go declarations.

ListIncidents

IncidentsService.List → GET /api/v2/incidents

Parameter Location Required Type
cursor query false string
limit query false integer
selector query false string
monitorID query false string

Response: IncidentList. See wire types and Go declarations.

GetIncident

IncidentsService.Get → GET /api/v2/incidents/{id}

Parameter Location Required Type
id path true string

Response: Incident. See wire types and Go declarations.

ListActions

ActionsService.List → GET /api/v2/actions

Parameter Location Required Type
cursor query false string
limit query false integer
selector query false string
monitorID query false string

Response: ActionList. See wire types and Go declarations.

GetAction

ActionsService.Get → GET /api/v2/actions/{id}

Parameter Location Required Type
id path true string

Response: Action. See wire types and Go declarations.

AcknowledgeIncident

IncidentsService.Acknowledge → POST /api/v2/incidents/{id}/acknowledge

Parameter Location Required Type
id path true string
If-Match header true string

Body: ControlRequest. Content type: application/json.

Response: Incident. See wire types and Go declarations.

DismissIncident

IncidentsService.Dismiss → POST /api/v2/incidents/{id}/dismiss

Parameter Location Required Type
id path true string
If-Match header true string

Body: ControlRequest. Content type: application/json.

Response: Incident. See wire types and Go declarations.

ReopenIncident

IncidentsService.Reopen → POST /api/v2/incidents/{id}/reopen

Parameter Location Required Type
id path true string
If-Match header true string

Body: ControlRequest. Content type: application/json.

Response: Incident. See wire types and Go declarations.

SnoozeMonitor

MonitorsService.Snooze → POST /api/v2/monitors/{id}/snooze

Parameter Location Required Type
id path true string
If-Match header true string

Body: ControlRequest. Content type: application/json.

Response: Operation. See wire types and Go declarations.

UnsnoozeMonitor

MonitorsService.Unsnooze → POST /api/v2/monitors/{id}/unsnooze

Parameter Location Required Type
id path true string
If-Match header true string

Body: ControlRequest. Content type: application/json.

Response: Operation. See wire types and Go declarations.

RecoverMonitor

MonitorsService.Recover → POST /api/v2/monitors/{id}/recover

Parameter Location Required Type
id path true string
If-Match header true string

Body: ControlRequest. Content type: application/json.

Response: Operation. See wire types and Go declarations.

ReviewAction

ActionsService.Review → POST /api/v2/actions/{id}/review

Parameter Location Required Type
id path true string
If-Match header true string

Body: ControlRequest. Content type: application/json.

Response: Action. See wire types and Go declarations.

PreflightCollection

OperationsService.Preflight → POST /api/v2/collections/preflight

No path, query, or header parameters beyond common authentication.

Body: PreflightRequest. Content type: application/json.

Response: Preflight. See wire types and Go declarations.

CreateOperation

OperationsService.Create → POST /api/v2/operations

No path, query, or header parameters beyond common authentication.

Body: OperationCreateRequest. Content type: application/json.

Response: Operation. See wire types and Go declarations.

UploadOperation

OperationsService.Upload → PUT /api/v2/operations/{id}/items

Parameter Location Required Type
id path true string

Body: UploadRequest. Content type: application/json.

Response: Operation. See wire types and Go declarations.

ActivateOperation

OperationsService.Activate → POST /api/v2/operations/{id}/activate

Parameter Location Required Type
id path true string

Response: Operation. See wire types and Go declarations.

CancelOperation

OperationsService.Cancel → POST /api/v2/operations/{id}/cancel

Parameter Location Required Type
id path true string

Response: Operation. See wire types and Go declarations.

GetOperation

OperationsService.Get → GET /api/v2/operations/{id}

Parameter Location Required Type
id path true string

Response: Operation. See wire types and Go declarations.

GetState

Client.State → GET /api/v2/state

No path, query, or header parameters beyond common authentication.

Response: State. See wire types and Go declarations.

GetHistory

Client.History → GET /api/v2/history

Parameter Location Required Type
cursor query false string
limit query false integer
selector query false string
monitorID query false string

Response: EventList. See wire types and Go declarations.

GetSLO

SLOService.Get → GET /api/v2/slo

No path, query, or header parameters beyond common authentication.

Response: SLOView. See wire types and Go declarations.

GetQueues

QueuesService.List → GET /api/v2/queues

Parameter Location Required Type
cursor query false string
limit query false integer
selector query false string
monitorID query false string

Response: QueueList. See wire types and Go declarations.

GetPools

PoolsService.List → GET /api/v2/pools

Parameter Location Required Type
cursor query false string
limit query false integer
selector query false string
monitorID query false string

Response: PoolList. See wire types and Go declarations.

GetSystems

SystemsService.List → GET /api/v2/systems

Parameter Location Required Type
cursor query false string
limit query false integer
selector query false string
monitorID query false string

Response: SystemList. See wire types and Go declarations.

GetConfig

Client.RuntimeConfig → GET /api/v2/config

No path, query, or header parameters beyond common authentication.

Response: RuntimeConfig. See wire types and Go declarations.

GetReady

Client.Ready → GET /api/v2/readyz

No path, query, or header parameters beyond common authentication.

Response: Health. See wire types and Go declarations.

GetLive

Client.Live → GET /api/v2/healthz

No path, query, or header parameters beyond common authentication.

Response: Health. See wire types and Go declarations.

GetMetrics

Client.Metrics → GET /api/v2/metrics

No path, query, or header parameters beyond common authentication.

Response: Metrics. See wire types and Go declarations.

GetCapabilities

Client.Capabilities → GET /api/v2/discovery

No path, query, or header parameters beyond common authentication.

Response: Capabilities. See wire types and Go declarations.

GetVersion

Client.Version → GET /api/v2/version

No path, query, or header parameters beyond common authentication.

Response: Version. See wire types and Go declarations.

ExplainResource

Client.Explain → GET /api/v2/schemas/{id}

Parameter Location Required Type
id path true string

Response: Explanation. See wire types and Go declarations.

WorkerPoll

WorkerClient.Poll → POST /api/v2/external-workers/poll

No path, query, or header parameters beyond common authentication.

Body: PollRequest. Content type: application/json.

Response: Assignments. See wire types and Go declarations.

WorkerStart

WorkerClient.Start → POST /api/v2/external-workers/start

No path, query, or header parameters beyond common authentication.

Body: StartRequest. Content type: application/json.

Response: StartResponse. See wire types and Go declarations.

WorkerHeartbeat

WorkerClient.Heartbeat → POST /api/v2/external-workers/heartbeat

No path, query, or header parameters beyond common authentication.

Body: HeartbeatRequest. Content type: application/json.

Response: HeartbeatResponse. See wire types and Go declarations.

WorkerResult

WorkerClient.Result → POST /api/v2/external-workers/result

No path, query, or header parameters beyond common authentication.

Body: Outcome. Content type: application/json.

Response: Receipt. See wire types and Go declarations.

WorkerLateEvidence

WorkerClient.LateEvidence → POST /api/v2/external-workers/late-evidence

No path, query, or header parameters beyond common authentication.

Body: LateEvidenceRequest. Content type: application/json.

Response: Receipt. See wire types and Go declarations.

ListJobTypes

JobTypesService.List → GET /api/v2/job-types

Parameter Location Required Type
cursor query false string
limit query false integer
selector query false string
monitorID query false string

Response: JobTypeList. See wire types and Go declarations.

CreateJobType

JobTypesService.Create → POST /api/v2/job-types

Parameter Location Required Type
If-None-Match header true string

Body: JobType. Content type: application/json.

Response: JobType. See wire types and Go declarations.

GetJobType

JobTypesService.Get → GET /api/v2/job-types/{id}

Parameter Location Required Type
id path true string

Response: JobType. See wire types and Go declarations.

ReplaceJobType

JobTypesService.Replace → PUT /api/v2/job-types/{id}

Parameter Location Required Type
id path true string
If-Match header true string

Body: JobType. Content type: application/json.

Response: JobType. See wire types and Go declarations.

DeleteJobType

JobTypesService.Delete → DELETE /api/v2/job-types/{id}

Parameter Location Required Type
id path true string
If-Match header true string

Response: Operation. See wire types and Go declarations.

ListWorkers

Client.Workers → GET /api/v2/external-workers

Parameter Location Required Type
cursor query false string
limit query false integer
selector query false string
monitorID query false string

Response: WorkerObservationList. See wire types and Go declarations.

ValidateOperation

OperationsService.Validate → POST /api/v2/operations/{id}/validate

Parameter Location Required Type
id path true string

Response: Preflight. See wire types and Go declarations.

Streaming Prometheus export

Client.Prometheus(ctx context.Context, w io.Writer) error streams GET /metrics into a caller-owned writer. It is a handwritten helper outside the 66 generated v2 operations. The SDK closes the HTTP response body and leaves the writer open. Cancellation and the configured response-byte ceiling apply; an error can leave a partial export in the writer. Discard that partial output when the export must be complete.

Client.Metrics(ctx) instead decodes the structured GET /api/v2/metrics response. Use it for typed observations; use Prometheus when you need exposition text.

Existing v1 compatibility

Import github.com/ziad-hsn/cpra/sdk/go/legacy. Its read-only methods preserve the existing server and numeric monitor routes. It never silently substitutes for a v2 mutation. Exact options and return types appear in the legacy section of Go declarations.

Method Route
legacy.Client.Config /api/v1/config
legacy.Client.Health /api/v1/healthz
legacy.Client.Ready /api/v1/readyz
legacy.Client.Metrics /metrics
legacy.Client.History /api/v1/history
legacy.Client.State /api/v1/state
legacy.Client.SLO /api/v1/slo
legacy.Client.Overview /api/v1/overview
legacy.Client.ListMonitors /api/v1/monitors
legacy.Client.GetMonitor /api/v1/monitors/%d
legacy.Client.ListIncidents /api/v1/incidents
legacy.Client.Queues /api/v1/queues
legacy.Client.QueuesHistory /api/v1/queues/history
legacy.Client.Pools /api/v1/pools
legacy.Client.PoolsHistory /api/v1/pools/history
legacy.Client.Systems /api/v1/systems