Platform reference
One page with every endpoint, every closed-union, every webhook event, every audit action, every safety invariant, every connector, every AI engineer the platform exposes.
Pulled from the same source-of-truth files the runtime uses — so the moment we add an event or an endpoint, this page is a PR diff away. Skim by jumping to any section below.
API endpoints
Every public v1 surface (9). All require Bearer vxlk_* unless marked.
/api/v1/whoamiscope · any read-classIdentifies the calling key + workspace + plan + quota.
Cheap probe used at the start of any session. Returns the key prefix (never the secret), its env (live/test), the organization id + plan tier, and the month-to-date v1 quota with a nearLimit flag at 90%.
response · 200 / 202
{
"ok": true,
"apiKey": { "id": "ak_…", "env": "live",
"scopes": ["pipeline:read", "pipeline:trigger"] },
"organization": { "id": "ws_acme_prod", "planTier": "pro" },
"quota": { "monthlyLimit": 10000, "currentCalls": 7420,
"remaining": 2580, "ratio": 0.74, "nearLimit": false },
"serverTimeSec": 1716506400
}errors · closed-union
no_bearer_tokenmalformed_tokenunknown_tokentoken_revokedrate_limited/api/v1/release-gatescope · release_gate:readLatest release-gate verdict for the workspace.
Returns whether the last eval run cleared the release gate, the pass-rate, average score, summary, and any structured blockers. Drives the deploy-ready badge on the Activity view.
response · 200 / 202
{
"ok": true,
"hasRun": true,
"gate": {
"passed": true,
"passRate": 0.94,
"averageScore": 8.7,
"summary": "All 142 evals passing.",
"blockers": []
},
"regressionCount": 0,
"improvementCount": 4
}errors · closed-union
missing_scopequota_exhausted/api/v1/pipelines/runsscope · pipeline:triggerKick off a coding pipeline run.
Validates the input, claims an optional Idempotency-Key slot Stripe-style, and starts the runner. 24h idempotency TTL. Returns 202 Accepted; caller polls the GET endpoint or subscribes to pipeline.* webhooks.
request
{
"pipelineId": "ai_coding",
"instruction": "Add a /healthz route returning 200 OK.",
"repoRef": "acme/example",
"branchHint": "main",
"metadata": { "ticket": "ACME-1242" }
}
# Optional header:
# Idempotency-Key: 9c7a32f8-12c4-4f8e-…response · 200 / 202
{
"ok": true,
"runId": "ckpipe_98zxa9q",
"correlationId": "pipe_ai_coding_1ax9zq",
"status": "running",
"pollUrl": "/api/v1/pipelines/runs/ckpipe_98zxa9q"
}errors · closed-union
invalid_jsoninvalid_pipeline_idinvalid_repo_refmissing_scopein_flightbody_mismatchidempotency_key_invalidquota_exhausted/api/v1/pipelines/runs/[id]scope · pipeline:readPoll one pipeline run's status + stages.
Cross-tenant-safe lookup. 404 collapses missing-and-different-tenant to the same response so attackers can't probe for cross-org run ids.
response · 200 / 202
{
"ok": true,
"run": {
"id": "ckpipe_98zxa9q",
"pipelineId": "ai_coding",
"status": "awaiting_approval",
"triggeredBy": "alice@acme.com",
"correlationId": "pipe_ai_coding_1ax9zq",
"startedAt": "2026-05-23T17:51:00.000Z",
"completedAt": null,
"errorSummary": null,
"stages": [
{ "id": "csg_…", "stageId": "read", "status": "succeeded" },
{ "id": "csg_…", "stageId": "propose", "status": "succeeded" },
{ "id": "csg_…", "stageId": "approval", "status": "awaiting_approval" }
]
}
}errors · closed-union
run_not_foundmissing_scope/api/v1/pipelines/runsscope · pipeline:readList recent runs, paginated + status-filterable.
Cursor pagination by run id (descending creation order). Filter by status (running | succeeded | failed | awaiting_approval). Used by the Activity view + tray badge + ApprovalsView.
response · 200 / 202
{
"ok": true,
"runs": [
{ "id": "ckpipe_…", "pipelineId": "ai_coding",
"status": "awaiting_approval", "stageCount": 6, … }
],
"nextCursor": "ckpipe_98zwbpy"
}errors · closed-union
missing_scopequota_exhausted/api/v1/pipelines/runs/[id]/decidescope · pipeline:triggerVote on a paused awaiting_approval stage.
Records ONE vote. Pipeline gates default to requiredApprovers=2 so isTerminal stays false until a second distinct approver votes. Fires the pipeline.stage_decision_recorded webhook on every vote (terminal or partial).
request
{
"decision": "approved",
"reason": "Reviewed diff + rollback plan",
"approverUserId": "desktop_tray"
}response · 200 / 202
{
"ok": true,
"runId": "ckpipe_98zxa9q",
"approvalId": "apr_pipe_ckpipe_98zxa9q_1ax",
"vote": "approved",
"snapshotStatus": "pending",
"approvedCount": 1,
"rejectedCount": 0,
"requiredApprovers": 2,
"isTerminal": false,
"decidedAt": null,
"stageTransitioned": false
}errors · closed-union
invalid_decisionrun_not_foundcross_tenantno_pending_approvalapproval_not_foundalready_decidedalready_votedmissing_scope/api/v1/events/streamscope · pipeline:readLong-lived SSE event stream (Phase 409).
Server-Sent Events. Replaces polling with push: approvals snapshots every 5s, connector snapshots every 30s, heartbeats every 25s to defeat any intermediate proxy idle-timeout. Closed-union event kinds: heartbeat · approvals.snapshot · connectors.snapshot · stream.ready · stream.shutdown. Subscribe via `?subscribe=approvals.snapshot,heartbeat` (default = wildcard). Server enforces a 5-minute max connection lifetime + emits stream.shutdown so clients can cleanly reconnect.
response · 200 / 202
event: stream.ready
data: { "correlationId": "v1_events_stream_…", "filter": ["approvals.snapshot","heartbeat"], "scopes": ["pipeline:read"] }
id: 1
event: approvals.snapshot
data: { "generatedAt": "2026-05-23T19:00:00.000Z", "count": 3, "runs": [ … ] }
id: 2
event: heartbeat
data: { "atSec": 25 }
id: 3errors · closed-union
missing_scopetoken_expiredtoken_revokedquota_exhausted/api/v1/connectors/healthscope · pipeline:readPer-connector health telemetry (Phase 407).
Closed-union status (healthy · degraded · stale · auth_failed · rate_limited) computed by a pure kernel from per-connector telemetry (last sync time, recent success / error counts, auth probe, rate-limit cooldown). Same inputs → same status, unit-tested against a fixture set.
response · 200 / 202
{
"ok": true,
"generatedAt": "2026-05-23T18:00:00.000Z",
"summary": {
"healthy": 3, "degraded": 0,
"stale": 1, "auth_failed": 0, "rate_limited": 0
},
"connectors": [
{
"name": "AWS", "category": "cloud",
"status": "healthy", "stage": "ok",
"reason": "Connector is syncing successfully.",
"successRatio": 0.947, "ageMs": 78420,
"recentSuccessCount": 18, "recentErrorCount": 1
},
{
"name": "Postgres", "category": "db",
"status": "stale", "stage": "staleness",
"reason": "Last successful sync was 10m ago (window for db: 5m).",
"successRatio": 0.857, "ageMs": 600000,
"recentSuccessCount": 6, "recentErrorCount": 1
}
]
}errors · closed-union
missing_scopequota_exhausted/api/v1/webhooks/jwksscope · (public — no auth)Public ES256 verification keys.
RFC 7517 JWK Set. Carries the rotating public keys integrators use to verify ES256 webhook signatures. Cached 1h at the CDN edge, 5m at the origin. kid is an RFC 7638 thumbprint.
response · 200 / 202
{
"keys": [
{
"kty": "EC", "crv": "P-256", "use": "sig", "alg": "ES256",
"kid": "f8a12b…", "x": "…", "y": "…"
}
]
}Webhook events
Every event the platform delivers (17). Signed HMAC-SHA256 + ES256 (JWS). Public keys at /api/v1/webhooks/jwks.
release_gate.passedEval run cleared the release gate.
emitted from · lib/workforce/releaseGate/passReleaseGate.ts
{ "evalRunId": "evr_…", "passRate": 0.94,
"averageScore": 8.7, "regressionCount": 0 }release_gate.blockedEval run failed the release gate.
emitted from · lib/workforce/releaseGate/blockReleaseGate.ts
{ "evalRunId": "evr_…", "blockers": [
{ "kind": "regression", "message": "case_42 below threshold" }
] }eval.regression_detectedA baseline-tagged eval case dropped below threshold.
emitted from · lib/workforce/evals/regressionDetector.ts
{ "evalRunId": "evr_…", "caseId": "case_42",
"currentScore": 6.2, "baselineScore": 8.8 }eval.run_completedEval run finished (pass or fail).
emitted from · lib/workforce/evals/finalizeEvalRun.ts
{ "evalRunId": "evr_…", "passRate": 0.94,
"averageScore": 8.7 }pipeline.run_startedPipelineRun row created, runner kicked off.
emitted from · lib/workforce/pipelines/pipelineRunner.ts:startPipelineRun
{ "runId": "ckpipe_…", "pipelineId": "ai_coding",
"triggeredBy": "alice@acme.com", "stageCount": 6 }pipeline.run_completedAll stages succeeded.
emitted from · lib/workforce/pipelines/pipelineRunner.ts:advancePipelineRun
{ "runId": "ckpipe_…", "completedAt": "2026-05-23T17:58:00Z",
"stageCount": 6 }pipeline.run_failedRun hit a terminal failure.
emitted from · lib/workforce/pipelines/pipelineRunner.ts:advancePipelineRun
{ "runId": "ckpipe_…", "failedOrdering": 3,
"errorSummary": "Stage ordering=3 failed." }pipeline.stage_failedOne stage failed (possibly recoverable mid-run).
emitted from · lib/workforce/pipelines/pipelineRunner.ts
{ "runId": "ckpipe_…", "stageRunId": "csg_…",
"stageKind": "lint", "reason": "budget_exceeded" }pipeline.stage_decision_recordedVote landed on a paused approval stage.
emitted from · app/api/v1/pipelines/runs/[id]/decide/route.ts
{ "runId": "ckpipe_…", "approvalId": "apr_pipe_…",
"vote": "approved", "approverUserId": "desktop_tray",
"approvedCount": 1, "requiredApprovers": 2,
"isTerminal": false, "snapshotStatus": "pending" }coding.pr_openedAI coding run opened a PR.
emitted from · lib/workforce/coding/openCodingPr.ts
{ "runId": "ckpipe_…", "prUrl": "https://github.com/acme/example/pull/24" }coding.lint_failedLint stage rejected the proposal.
emitted from · lib/workforce/coding/lintStage.ts
{ "runId": "ckpipe_…", "errors": [
{ "file": "src/index.ts", "line": 14, "rule": "no-unused-vars" }
] }coding.test_failedTest stage rejected the proposal.
emitted from · lib/workforce/coding/testStage.ts
{ "runId": "ckpipe_…", "failed": ["MyClass#shouldFoo"] }api_key.createdvxlk_* key minted (admin surface).
emitted from · app/admin/api-keys/createApiKey.action.ts
{ "apiKeyId": "ak_…", "env": "live",
"scopes": ["pipeline:read", "pipeline:trigger"] }api_key.revokedKey invalidated; subsequent calls return token_revoked.
emitted from · app/admin/api-keys/revokeApiKey.action.ts
{ "apiKeyId": "ak_…", "revokedAt": "2026-05-23T17:58:00Z" }connector.health_changedA connector transitioned between health states.
emitted from · app/api/cron/connector-health-scan/route.ts (Phase 410)
{ "connectorName": "Postgres", "kind": "degraded",
"previousStatus": "healthy", "currentStatus": "stale",
"reason": "Last successful sync was 10m ago (window for db: 5m).",
"detectedAt": "2026-05-23T19:45:00.000Z" }billing.threshold_crossedUsage crossed a 70 / 90 / 100 % bucket.
emitted from · lib/billing/alertScanner.ts
{ "dimension": "api_v1_calls", "ratio": 0.91,
"bucket": "90pct" }billing.quota_exhaustedMonthly cap hit; subsequent calls 429.
emitted from · lib/security/authenticateApiKey.ts
{ "dimension": "api_v1_calls",
"retryAfterSeconds": 432000 }Closed-union types
The platform's safety mechanism. Members can't drift apart from runtime checks — a typo is a compile error, not a silent denial.
ApiKeyScope
lib/security/apiKeyScope.tspipeline:readList + get pipeline runs.pipeline:triggerStart runs + decide approvals.pipeline:*Both pipeline scopes.eval:readRead eval runs + results.eval:writeSubmit eval cases / runs.eval:*Both eval scopes.release_gate:readRead release-gate verdicts.release_gate:*Same — gates aren't user-controllable.webhook:readList endpoints + deliveries.webhook:writeCreate / update endpoints.webhook:adminRotate signing keys.webhook:*All webhook scopes.*Universal admin — Enterprise only.
DemoStepApproval
lib/demo/demoScenarios.tsnoneNo approval gate; read-only or operator self-action.self_approveOperator acts on their own behalf (audited).two_personTwo distinct human approvers required to advance.
DemoAudience
lib/demo/demoScenarios.tspublicVisible on /demo without an API key (marketing-grade walkthroughs).clientShown to paired workspaces in /demo.internal_onlyAdmin-only; never surfaced to client workspaces.
WorkspaceKind
lib/workspace/workspaceKind.tsrealPaying customer; demo data is forbidden by assertNotDemoLeak().sandboxPublic /demo workspaces; safe to render mock data.internalAdmin / eval runner; can see internal_only scenarios.
DataSourceMode
desktop/src/components/Primitives.tsxliveAPI key paired + endpoint returned real data.authenticated_no_dataKey paired but surface not implemented yet — shows mock.previewNo key paired; showing mock data.
AuthFailureKind
lib/security/authenticateApiKey.tsno_bearer_tokenAuthorization header missing.malformed_tokenHeader doesn't parse as vxlk_*.unknown_tokenNo row match — collapses 'no row' + 'hash mismatch' to one outcome.token_expiredexpiresAt < now.token_revokedrevokedAt set.missing_scopeGranted scopes don't include the required scope.rate_limitedPer-prefix rate-limit bucket exhausted.quota_exhaustedMonthly plan quota hit.
PipelineRun.status
prisma/schema.prismaqueuedRun row created, no stage has started yet.runningAt least one stage in flight.awaiting_approvalPaused at an approval gate.succeededAll stages succeeded; terminal.failedOne stage failed terminally; terminal.cancelledOperator cancelled mid-run.
StreamEventKind
lib/events/streamKernel.ts (Phase 409)heartbeatKeep-alive ping every 25s so intermediate proxies don't idle the SSE connection out.approvals.snapshotFull snapshot of awaiting_approval runs (every 5s + on connect).connectors.snapshotFull per-connector health snapshot (every 30s + on connect).stream.readyFirst frame sent after a successful subscribe; carries the correlationId + applied filter.stream.shutdownServer-initiated close (max_lifetime_reached / client_disconnect). Client should reconnect cleanly.
ConnectorHealthStatus
lib/connectors/connectorHealth.ts (Phase 407)healthyConnector is syncing successfully within bounds.degradedRecent success ratio below threshold (default 85%) with at least 5 samples.staleLast successful sync older than the category window (cloud 30m · vcs 10m · db 5m · monitoring 15m). 'Never synced' counts as stale.auth_failedCredentials rejected on the most recent auth probe — beats every other signal.rate_limitedProvider is throttling us right now; scanner is backing off.
ApprovalSnapshot.status
prisma/schema.prisma (EngineerApprovalSnapshot)pendingAwaiting votes.approvedQuorum reached affirmatively.rejectedQuorum reached negatively.expiredAuto-expired by the sweeper before reaching quorum.
Audit actions
Every closed-union member of AuditAction, grouped by category. 95 total.
Auth / session
auth.signinauth.signoutauth.failed
Tenant isolation
tenant.cross_attempt
Connectors
connector.connectconnector.disconnectconnector.validate.attemptconnector.validate.successconnector.validate.failure
Scans
scan.startscan.successscan.failure
Recommendations
recommendation.generated
Execution
execution_plan.createexecution_plan.exportexecution_plan.submitexecution_plan.executerollback.preparerollback.execute
Approvals
approval.grantapproval.deny
Desktop
desktop.pairdesktop.revokedesktop.handoff.issuedesktop.handoff.verifydesktop.handoff.reject
Governance / policy
policy.updategovernance.updateautonomy.changemembers.invitemembers.remove
Audit data
audit.export
Copilot
copilot.querycopilot.blocked
AI Workforce runtime
engineer.action_attemptedengineer.action_allowedengineer.action_requires_approvalengineer.action_blockedengineer.approval_createdengineer.approval_votedengineer.approval_expiredengineer.action_executedengineer.action_execution_failedengineer.policy_override_updatedengineer.registry_synced
Billing
billing.usage_recordedbilling.credit_pool_exhaustedbilling.summary_rebuiltbilling.entitlement_blockedbilling.alert_firedbilling.addon_purchase_initiatedbilling.addon_purchase_completedbilling.addon_purchase_refunded
Pipelines
pipeline.run_startedpipeline.stage_startedpipeline.stage_completedpipeline.stage_failedpipeline.run_completedpipeline.run_failed
Repo context
workforce.repo_context_fetchedworkforce.repo_context_fetch_failed
PR open
workforce.pr_branch_pushedworkforce.pr_openedworkforce.pr_open_failed
Evals
eval.run_startedeval.case_recordedeval.run_completedeval.run_failedeval.regression_detectedeval.release_gate_passedeval.release_gate_blocked
Refinement
workforce.proposal_refinedworkforce.proposal_gave_up
Static lint
workforce.code_lint_passedworkforce.code_lint_failed
Test integrity
workforce.code_test_passedworkforce.code_test_failed
API keys
workforce.api_key_createdworkforce.api_key_revokedworkforce.api_key_authenticatedworkforce.api_key_denied
Webhook delivery
workforce.webhook_endpoint_createdworkforce.webhook_endpoint_revokedworkforce.webhook_event_dispatchedworkforce.webhook_deliveredworkforce.webhook_retry_scheduledworkforce.webhook_deadletteredworkforce.webhook_queue_processed
Budget / idempotency
workforce.budget_config_createdworkforce.budget_config_updatedworkforce.budget_config_deletedworkforce.idempotency_slot_completed
Model routing
workforce.model_downgraded
Connector health
workforce.connector_health_polled
Generic
system.error
AI engineers
6 registered engineers. Each has a closed tool list — the runtime gate checks every call against this scope BEFORE the model can see the tool definition.
Cloud Engineer
default · two_personScans, plans, and recommends cloud-infra fixes across AWS / Azure / GCP.
tools · 7
cloud.scancloud.plancloud.recommendcloud.terraform_diffcloud.rollback_plancloud.simulatecloud.budgetDevOps Engineer
default · two_personReads CI status, explains failures, suggests PRs.
tools · 5
github.read_workflowgithub.read_logsgithub.suggest_prgithub.read_commitgithub.open_prSecurity Engineer
default · two_personIAM + findings + advisories with severity-scored evidence.
tools · 6
sec.scansec.severitysec.terraform_diffsec.compliance_bindsec.advisesec.rollback_planDatabase Engineer
default · two_personSchema introspection + slow query + backup gap detection.
tools · 4
db.read_schemadb.read_slowlogdb.propose_ddldb.simulate_impactMonitoring Engineer
default · noneAlert ingestion + deploy/config correlation.
tools · 4
mon.read_metricmon.read_alertmon.correlate_deploymon.create_incidentIncident Engineer
default · two_personTimeline + root cause + postmortem skeleton.
tools · 4
inc.build_timelineinc.hypothesisinc.postmortem_draftinc.propose_mitigationConnectors
11 integrations. Auth model + scope detail for each.
AWS
cloudauth · Cross-account IAM role + externalId · sts:AssumeRole
scopes · Read-only at install (list-*, describe-*); write scopes opt-in per remediation action.
capability · Inventory · cost · IAM exposure · CloudTrail · drift detection.
Azure
cloudauth · Service principal · Reader role on subscription
scopes · Read-only at install.
capability · Inventory · RBAC posture · Key Vault audit.
GCP
cloudauth · Service account · roles/iam.securityReviewer
scopes · Read-only at install.
capability · Inventory · IAM posture · audit logs.
GitHub
vcsauth · OAuth app · repo + workflow scopes (read-only at install)
scopes · Reads repos + workflow runs; PR open requires explicit elevation.
capability · DevOps Engineer reads pipeline status + explains failures.
Postgres
dbauth · Read-only DB user · pg_monitor + pg_read_server_files
scopes · Read schema + slow-query logs; NO write tools by default.
capability · Database Engineer detects slow queries + backup gaps.
MySQL
dbauth · Read-only DB user · SELECT on information_schema.*
scopes · Read schema + slow-query log.
capability · Same as Postgres.
MongoDB
dbauth · Read-only DB user · listDatabases + collStats
scopes · Read collections + stats.
capability · Schema + slow-op detection.
CloudWatch
monitoringauth · Ingest webhook · HMAC-SHA256 signed
scopes · Inbound only — platform never writes back.
capability · Monitoring Engineer correlates alerts with recent deploys.
Grafana
monitoringauth · Ingest webhook · HMAC-SHA256 signed
scopes · Inbound only.
capability · Same as CloudWatch.
Dynatrace
monitoringauth · Ingest webhook · HMAC-SHA256 signed
scopes · Inbound only.
capability · Same as CloudWatch.
VS Code
ideauth · API key (same as desktop) · workspace-scoped
scopes · Whatever scopes the key carries.
capability · DevOps Engineer chat panel cites back to log lines.
Safety invariants
12 platform-wide guarantees. Each lists exactly where it is enforced.
Read-only by default
No write API is even minted until you explicitly grant write scope.
enforced at · lib/security/apiKeyScope.ts + per-route assertScope()
Two-person quorum
Pipeline gates default to requiredApprovers=2. DB-unique constraint on (snapshotId, approverUserId) blocks double-voting.
enforced at · prisma/schema.prisma (EngineerApprovalDecision)
Rollback verified
Every recommendation ships with a pre-validated rollback plan; the apply button is disabled until the rollback validates against a digital twin.
enforced at · lib/workforce/pipelines/rollbackValidator.ts
Blast radius capped
Each change is risk-tiered against the number of resources it touches; high tiers force extra approvers + slower deploy windows.
enforced at · lib/workforce/blastRadius.ts
Full audit fabric
Every action emits a row in the closed-union AuditAction log: actor, action, outcome, correlationId. Best-effort wrapped so observability outages never block business events.
enforced at · lib/audit/secureAudit.ts
Assume-role model
No long-lived access keys stored — workspace assumes a short-lived role you own and can revoke from your provider console.
enforced at · lib/cloud/awsAssumeRole.ts + per-provider counterparts
Closed-union types
Scope strings, event kinds, audit actions, approval rules are TypeScript closed unions; typos are compile errors, not runtime denial bugs.
enforced at · lib/security/apiKeyScope.ts · lib/webhooks/webhookEventKinds.ts · lib/audit/secureAudit.ts
Tenant isolation
Every Prisma read joins on organizationId; cross-tenant lookups collapse to 404 'not_found' so attackers can't probe for cross-org ids.
enforced at · every app/api/v1/*/route.ts handler
Idempotent writes
Stripe-style Idempotency-Key on every POST that fires side-effects. 24h TTL. Duplicate calls return the cached response with X-VXL-Idempotent-Replay.
enforced at · lib/security/idempotency.ts + idempotencyStore.ts
Signed webhooks
Every outbound delivery carries HMAC-SHA256 and ES256 (JWS) signatures. Public keys rotate at /api/v1/webhooks/jwks (RFC 7517 / 7518 / 7638).
enforced at · lib/security/webhookEs256.ts + lib/webhooks/signWebhookPayload.ts
Demo isolation
isSandboxWorkspace(orgId) gates every demo data path; assertNotDemoLeak() throws DemoLeakError if a sandbox-only fixture ever touches a real org.
enforced at · lib/workspace/workspaceKind.ts
Quota fail-open
If the billing DB is slow / unreachable, the v1 quota gate FAILS OPEN — better to over-serve than to lock customers out of their integration.
enforced at · lib/security/authenticateApiKey.ts