API reference

AgentLeak API

This reference is built into the documentation so developers and agents can understand the API flow without leaving the docs. Swagger is still available for schema exploration, but the recommended path is this guide plus the OpenAPI schema for exact types.

Authentication

Human platform calls

Register or log in through /api/auth/*. The server sets a session cookie used by project, run, scenario and dashboard endpoints.

Agent-side calls

Generate or receive an ak_... project key and send it as X-AgentLeak-Key. Never place it in URLs, prompts, traces or source code.

Quick calls

Use these as the shortest working path for an autonomous agent integration.

curl -sS -X POST https://www.agentleak.org/api/agent/onboard \
  -H 'content-type: application/json' \
  -d '{"email":"[email protected]","agent_name":"SupportBot"}'

curl -sS -X POST https://www.agentleak.org/api/selftest \
  -H "X-AgentLeak-Key: $AGENTLEAK_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "trace": {"run_id":"run_001","events":[...]},
    "detectors": {"pii": true, "secrets": true},
    "redact": true
  }'

Endpoint reference

GET/api/meta

Discover runtime version, supported channels, detectors, framework labels, docs links and free-tier limits.

Auth: None
Request: No body.
Returns: version, channels, detectors, agent_api, documentation, free_tier.

GET/api/schemas/{name}

Fetch a versioned Draft 2020-12 JSON Schema. Omit {name} to list the catalog.

Auth: None
Request: Name: config, trace, event, finding, analysis-report, privacy-policy, privacy-policy-evaluation, redteam-request, code-scan or agent-card.
Returns: JSON Schema with x-agentleak-schema-version, or a catalog containing every schema URL.

GET/api/health | /readyz

Liveness and readiness probes for local, Docker and reverse-proxy deployments.

Auth: None
Request: No body.
Returns: Health status, version and readiness state.

POST/api/auth/register

Create a human account and session cookie for the hosted platform.

Auth: None
Request: email, password, optional name.
Returns: Authenticated user object. The server sets the session cookie.

POST/api/auth/login | /api/auth/logout

Create or clear the human dashboard session.

Auth: None or session cookie
Request: Login: email and password. Logout: no body.
Returns: Authenticated user or a cleared session.

GET/api/auth/me | /api/limits

Read the current user, quota and account-level limits.

Auth: None
Request: No body.
Returns: User identity, quota counters and reset metadata.

GET/api/scenarios | /api/scenario-packs

List built-in, uploaded and importable scenario packs.

Auth: Session cookie
Request: Optional filters or pagination depending on the resource.
Returns: Scenario metadata, coverage, domains and pack availability.

POST/api/analyze | /api/report/{fmt} | /api/render/{fmt}

Analyze a trace or render an existing report in a selected format.

Auth: Session cookie
Request: Trace/scenario and optional detectors, vault, privacy policy and redaction settings.
Returns: Analysis report or rendered JSON, Markdown or HTML document.

POST/api/projects

Create a project for one agent, one multi-agent workflow, or one product surface.

Auth: Session cookie
Request: name, optional agent_type, description and config.
Returns: Project with id, config, run counts and timestamps.

POST/api/analyze

Analyze a raw trace without attaching it to a saved project run.

Auth: Session cookie
Request: trace or scenario_id, detector toggles, custom detectors, vault settings and redact flag.
Returns: AgentRisk report with risk_index, privacy_score, findings, channel_risks and recommendations.

POST/api/projects/{project_id}/api-key

Generate a project-scoped key for autonomous agent calls.

Auth: Session cookie
Request: No body.
Returns: api_key and project_id. Store the key once; treat it like a secret.

GET/api/projects | /api/projects/{project_id}

List, read, update or delete projects and their stored configuration.

Auth: Session cookie
Request: Project ID for a single resource; PATCH accepts name, description, agent and config.
Returns: Project identity, configuration, run counts and latest run summary.

GET/api/projects/{project_id}/connect

Return a framework-specific SDK connection snippet.

Auth: Session cookie
Request: Project ID and selected agent type.
Returns: Integration name, install hints and copy-paste recorder snippet.

POST/api/selftest

Submit one runtime trace from an agent and receive a pass/fail self-test result.

Auth: X-AgentLeak-Key
Request: trace, detectors, custom_detectors, vault and redact.
Returns: report, passed, compliant, project_id and run_id.

POST/api/agent/onboard

Agent-friendly onboarding that creates an account, project and project key in one call.

Auth: None
Request: email plus optional agent_name.
Returns: project_id, api_key, instructions and next links.

POST/api/agent/register

Upsert the agent card: identity, capabilities, declared data types and optional source location.

Auth: X-AgentLeak-Key
Request: agent_card object.
Returns: project_id and normalized agent_card.

POST/api/agent/code

Scan declared or submitted source code before runtime execution.

Auth: X-AgentLeak-Key
Request: Empty body for declared source, or source=github|zip|files with source details.
Returns: scan id, verdict, score, findings, tier/confidence and redacted snippets.

POST/api/agent/improve

Run a self-test, compare with previous runs and return machine-actionable next_steps.

Auth: X-AgentLeak-Key
Request: trace plus optional detector/vault settings.
Returns: report, passed, delta, progression, code_scan summary and prioritized next_steps.

GET/api/agent/status

Read latest score, compliance posture, code scan state, progression and remaining work.

Auth: X-AgentLeak-Key
Request: No body.
Returns: project, latest_run, progression, compliance, code_scan and next_steps.

GET/api/agent/card | /api/projects/{project_id}/agent-card

Read the registered agent card and declared source/privacy metadata.

Auth: X-AgentLeak-Key or Session cookie
Request: No body for GET.
Returns: Normalized agent card, capabilities, source and privacy declaration.

GET/api/redteam/catalog

List attack classes, plugins, strategies and presets before creating a campaign.

Auth: Session cookie
Request: No body.
Returns: 46 classes, the complete executable plugin registry, 10 strategies, profiles and presets.

POST/api/projects/{project_id}/redteam

Run a scripted or authorized live adversarial campaign and persist its evidence.

Auth: Session cookie
Request: vertical, adversary_level, n, plugins/plugin_preset, strategies/strategy_profile and mode.
Returns: coverage, attacks, metrics, remediation, saved run IDs and report references.

GET/api/projects/{project_id}/runs | /api/runs/{run_id}

List or retrieve stored runtime, code and red-team evidence.

Auth: Session cookie
Request: Project or run ID; optional history filters.
Returns: Canonical report, source, label, timestamps and progression metadata.

GET/api/projects/{project_id}/history | /api/projects/{project_id}/compare

Compare releases and inspect score progression for a project.

Auth: Session cookie
Request: Project ID plus optional run IDs, limit and comparison parameters.
Returns: Deltas, regression direction, dominance comparison and evidence references.

POST/api/projects/{project_id}/execute

Execute a configured scripted/live agent scenario and store the resulting run.

Auth: Session cookie
Request: Scenario ID, mode, label and optional execution settings.
Returns: Stored run with trace-derived report and source metadata.

GET/openapi.json

Machine-readable OpenAPI schema for generated clients, validators and agent planning.

Auth: None
Request: No body.
Returns: OpenAPI 3 schema.

Core schemas

The live catalog at /api/schemas is the authoritative contract for files and response documents. Fetch schemas over HTTPS or useagentleak schema NAME offline.

# List every versioned machine contract
curl -sS https://www.agentleak.org/api/schemas | jq

# Fetch one Draft 2020-12 JSON Schema
curl -sS https://www.agentleak.org/api/schemas/trace > trace.schema.json
agentleak schema analysis-report > report.schema.json

# IDE validation for agentleak.yaml
# yaml-language-server: $schema=https://www.agentleak.org/api/schemas/config

Tracerun_id, agent_name and ordered events with channel, source, target and content.

Findingchannel, data_type, severity, level_label, confidence, redacted_value and recommendation.

Reportrisk_index, privacy_score, blocked, privacy_policy, channel_risks, findings, remediation_hints and compliance.

Privacy policyRisk, count, level, channel, data-type and explicit-vault assertions.

Policy evaluationenabled, passed, assertions_checked and violations with finding IDs.

Red-team requestVertical, adversary level, plugin preset, strategies, execution mode and target.

Code scanSource, score, verdict, findings, detector tier, confidence and redacted snippets.

Agent cardname, capabilities, protocol metadata, declared data types and optional source location.

Errors and retries

Treat 401 as a hard auth failure, 409 as ownership/account conflict, 422 as schema repair, 429 as a backoff signal and 5xx as a bounded retry. Agents should preserve idempotency and include no raw secrets in final reports.

OpenAPI and Swagger

Use OpenAPI as the authoritative contract for field names and generated clients. Use the built-in Swagger UI only when you need raw schema exploration.

curl -sS https://www.agentleak.org/openapi.json | jq '.paths | keys'

# Swagger remains available when you need raw schema exploration:
open https://www.agentleak.org/api/docs