Clef Docs

Appearance

API Reference ​

Base URL: /api/v1

Authentication ​

JWT (dashboard) — Authorization: Bearer <jwt> via Cognito.

API key (CLI/CI) — x-api-key: clef_<token> or Authorization: Bearer clef_<token>. Resolves to a team + integration.

Integrations ​

List integrations ​

GET /integrations
Auth: JWT

Get integration ​

GET /integrations/:integrationId
Auth: JWT or API key

Create integration ​

POST /integrations
Auth: JWT
Body: { name: string, description?: string }

Delete integration ​

DELETE /integrations/:integrationId
Auth: JWT

Get integration config ​

GET /integrations/:integrationId/config
Auth: JWT

Update integration config ​

PUT /integrations/:integrationId/config
Auth: JWT
Body: { collectCIContext?: boolean, notifications?: NotificationChannel[] }

API Keys ​

List keys ​

GET /integrations/:integrationId/keys
Auth: JWT

Create key ​

POST /integrations/:integrationId/keys
Auth: JWT
Body: { name: string }
Response: { rawKey: string, apiKey: { id, prefix, name, createdAt } }

The raw key is returned once. Store it securely.

Revoke key ​

DELETE /integrations/:integrationId/keys/:keyId
Auth: JWT

Reports ​

Submit single report ​

POST /reports
Auth: API key (or JWT with integrationId in body)
Body: See CLI Integration docs

Submit batch report ​

POST /reports/batch
Auth: API key only
Body: { cliVersion, reports: [...] }

List reports for integration ​

GET /integrations/:integrationId/reports
Auth: JWT
Query: pageToken (optional)

Get single report ​

GET /integrations/:integrationId/reports/:commitSha
Auth: JWT

Matrix ​

Get current matrix ​

GET /integrations/:integrationId/matrix
Auth: JWT

Returns the matrix built from the latest report's summary, drift, and policy results.

Alerts ​

List alerts ​

GET /alerts
Auth: JWT
Query: integrationId (optional), acknowledged (optional: "true"/"false")

Acknowledge alert ​

PUT /alerts/:alertKey
Auth: JWT

alertKey format: {integrationId}#{ruleId}#{scope}

Onboarding ​

Get onboarding status ​

GET /onboarding/status
Auth: JWT
Response: { needsOnboarding, hasIntegration }

Schema Types ​

NotificationChannel ​

typescript
{
  channel: 'email',
  target: string,           // email address
  minSeverity: 'info' | 'warning' | 'critical'
}

CellStatus ​

typescript
{
  namespace: string,
  environment: string,
  healthStatus: 'healthy' | 'warning' | 'critical' | 'unknown',
  description: string       // CLI-composed, no sensitive data
}

ReportDrift ​

typescript
{
  namespace: string,
  isDrifted: boolean,
  severity: 'info' | 'warning' | 'critical',
  summary?: string
}

PolicyResult ​

typescript
{
  ruleId: string,
  ruleName: string,
  passed: boolean,
  severity: 'info' | 'warning' | 'critical',
  message: string,
  scope?: string            // opaque, no sensitive data
}

CIContext ​

typescript
{
  provider?: string,        // e.g. "github_actions"
  pipelineUrl?: string,
  triggeredBy?: string      // "push" | "schedule" | "manual"
}