Report executor events
POST/api/v1/certops/executor/events
Aggregate executor ingestion endpoint for normalized job and public evidence events. Lifecycle events require certops:events:write; evidence-bearing events additionally require certops:evidence:write. The route is hidden with 404 when certops.enabled is disabled. eventId is idempotent within a workspace and job: exact retries return 202 without repeating logs, evidence, audit rows, or status side effects, while a different sanitized envelope using the same key returns 409. Late lifecycle events are recorded in the job log but cannot regress or reopen a terminal job. Payloads containing private key material are rejected with 422. Generic secret material in metadata and bounded evidence output is redacted to [REDACTED] before persistence. Per-job event/evidence routes are narrow machine-token aliases that reuse the same hardened ingestion behavior.
Request
Responses
- 202
- 400
- 401
- 403
- 404
- 409
- 413
- 422
- 429
- 500
- 503
Event accepted
Executor event body failed schema/idempotency validation (CERTOPS_EXECUTOR_EVENT_INVALID, CERTOPS_EXECUTOR_EVENT_TYPE_INVALID, CERTOPS_EXECUTOR_EVENT_STATUS_MISMATCH, CERTOPS_JOB_STATUS_INVALID, or CERTOPS_EVIDENCE_INVALID for evidence-bearing events)
Unauthorized
Caller lacks the required scope for this event type (CERTOPS_API_TOKEN_SCOPE_DENIED), or the token's workspace does not match the event's workspaceId (CERTOPS_EXECUTOR_WORKSPACE_MISMATCH)
Not found
Executor event idempotency key conflicts with a different sanitized payload (CERTOPS_EXECUTOR_EVENT_CONFLICT); the event conflicts with the job's current status (CERTOPS_JOB_STATUS_TRANSITION_INVALID); or a terminal status does not match the job's mode, e.g. a dry_run job completing as succeeded instead of dry_run_complete (CERTOPS_JOB_MODE_TERMINAL_INVALID); or the job is currently claimed by a CertOps agent and the event carries a terminal status (CERTOPS_EXECUTOR_JOB_AGENT_CLAIMED). The executor and agent lanes share one certificate_jobs table but the executor lane holds no lease, so allowing an executor token to end a job an agent is still executing would land the agent's side effects against a terminal row.
The executor event body exceeded the dedicated 4 MiB pre-auth boundary (CERTOPS_EXECUTOR_EVENT_BODY_TOO_LARGE), or normalized evidence output exceeded 65,536 UTF-8 bytes (CERTOPS_EVIDENCE_OUTPUT_TOO_LARGE). The payload is not echoed.
Request rejected because it contained private key material
The exact-path executor pre-auth or authenticated machine-token limiter rejected the request. The response never includes bearer-token material or request content.
Response Headers
Seconds until the caller may retry.
Internal server error
The security audit sink was unavailable while recording a private-key-material rejection. The endpoint fails closed; the original payload is neither persisted nor echoed and no executor-event side effects occur.