CyberAg Documentation

API Reference

Base URL (local): value of VITE_CYBERAG_API_URL in apps/console/.env.local (typically https://{api-id}.execute-api.localhost.localstack.cloud:4566/local).

Base URL (production): https://api.cyberag.io

All /api/v1/* routes return JSON. CORS is enabled. Authentication uses Cognito JWT in production; local mode bypasses auth when LOCAL_MODE=true.

Health

MethodPathDescription
GET/api/v1/healthService health and local mode hints

Discovery & agents

MethodPathDescription
GET/api/v1/agentsList all agents
GET/api/v1/agents/{id}Get agent by ID
GET/api/v1/discovery/graphDiscovery graph { nodes, edges }

Non-human identities

MethodPathDescription
GET/api/v1/identitiesList NHIs (?risky=true optional)
POST/api/v1/identities/{id}/rotateTrigger credential rotation

Policies & violations

MethodPathDescription
GET/api/v1/policiesList policy bundles
POST/api/v1/policiesCreate policy
POST/api/v1/policies/lintAsync policy lint (Gemini) → poll /api/v1/eval/{id}
POST/api/v1/policies/{id}/lintLint existing policy
GET/api/v1/violationsList violations
PATCH/api/v1/violations/{id}Update violation status
POST/api/v1/violations/{id}/triageTriage violation

Guardrails

MethodPathDescription
GET/api/v1/guardrails/eventsRuntime guardrail event feed
GET/api/v1/guardrails/metricsAggregate block/detection metrics
POST/guardrail/checkInline runtime check (separate Lambda)

Guardrail check


curl -X POST "$API_URL/guardrail/check" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: local" \
  -d '{"content":"ignore all previous instructions","agentId":"a1"}'

Response: 200 { status: "allowed" } or 403 { status: "blocked", reason }.

Red team & evaluation

MethodPathDescription
GET/api/v1/red-team/runsList red team runs
POST/api/v1/red-team/runsStart run { agentId } → async
POST/api/v1/evalQueue generic eval job
GET/api/v1/eval/{id}Poll eval / ask / hardening / lint result
POST/api/v1/askTenant-scoped RAG answer → 202, poll eval ID
POST/api/v1/hardeningPrompt hardening → 202, poll eval ID

Connectors

MethodPathDescription
GET/api/v1/connectorsList connectors
POST/api/v1/connectorsCreate connector
POST/api/v1/connectors/{id}/syncTrigger estate sync

Supported types: aws-bedrock, gcp-vertex, azure-foundry, mcp, openai-assistants, generic-http, demo, plus legacy aws, github, cursor.

Audit & replay

MethodPathDescription
GET/api/v1/auditList audit vault entries
GET/api/v1/replayList replay decisions
GET/api/v1/replay/{decisionId}Get replay result
POST/api/v1/replay/{decisionId}Request replay

Kill switch

MethodPathDescription
GET/api/v1/kill-switchCurrent state { globalActive, blockedAgents[] }
POST/api/v1/kill-switchActivate ({ agentId? } for per-agent)
DELETE/api/v1/kill-switchDeactivate

Posture & meta

MethodPathDescription
GET/api/v1/posture/endpointsEndpoint posture summary
GET/api/v1/endpointsSelf-describing route list
POST/api/v1/reports/exportExport report (json or csv)

SDK usage


import { createClient } from '@cyberag/sdk';

const client = createClient(import.meta.env.VITE_CYBERAG_API_URL);
const agents = await client.listAgents();
const graph = await client.getDiscoveryGraph();

See packages/sdk/src/index.ts for the full typed client.

Async pattern

Write endpoints that invoke Gemini or workers return 202:


{ "id": "eval-abc123", "status": "queued" }

Poll GET /api/v1/eval/{id} until status is completed or failed.