Claim pending jobs

POST 
/api/v1/certops/agent/jobs/claim

Outbound-only claim poll authenticated with the per-agent credential (bearer). Request body is the agent-protocol envelope with messageType claim (packages/contracts/certops/agent-protocol.schema.json, additionalProperties false); the body only expresses poll preferences (maxJobs, supportedActions), never a specific job selection. Server selects pending workspace jobs with FOR UPDATE SKIP LOCKED, leases them, and returns signed dispatch payloads: job-payload fields plus claimId, leaseExpiresAt, attemptCount, and the Ed25519 dispatch fields nonce, issuedAt, expiresAt, signingKeyId, signature. Dispatch is blocked while the workspace kill switch is on (409 CERTOPS_WORKSPACE_PAUSED); results reporting never is. A retired agent receives 410. Hidden with 404 while certops.enabled is disabled.

Request

Responses

200

Zero or more signed claimed jobs

400

Message envelope or claim body failed agent-protocol validation

401

Per-agent credential missing, unknown, or revoked

404

CertOps is disabled deployment-wide (route is hidden)

409

Workspace CertOps is paused (CERTOPS_WORKSPACE_PAUSED); message sequence regression (CERTOPS_AGENT_SEQUENCE_REGRESSION); agent blocked by compatibility policy (CERTOPS_AGENT_COMPATIBILITY_BLOCKED); or the deploy public certificate is unavailable (CERTOPS_AGENT_DEPLOY_CERT_UNAVAILABLE)

410

Agent is retired

422

Request rejected because it contained private key material

429

CertOps machine-token rate limit exceeded

500

Internal server error

503

Security audit sink unavailable while rejecting private material