Agent Etna API

Complete reference for the Agent Etna platform API. All endpoints return JSON.

Overview

Base URL: https://www.agentetna.com

Agent Etna exposes 133+ REST endpoints for testing, fixing, analyzing, and optimizing AI agents. The API supports three authentication methods:

Authentication

GitHub OAuth (Browser)

Navigate to /login to authenticate via GitHub. Session cookie is set automatically.

Bearer Token (API / CI)

Authorization: Bearer <github-token>

Used by the GitHub Action and MCP server. Your GitHub personal access token serves as the API key.

Agents

GET/api/agents

List all connected agents for the current user.

{
  "id": "my-agent",
  "name": "My Agent",
  "role": "customer support",
  "url": "https://my-agent.onrender.com",
  "github": { "repo": "user/repo", "branch": "main" }
}

POST/api/agents/connect auth

Connect a new agent. Provisions cryptographic identity automatically.

Parameter	Type	Description
name	string	Agent name (required)
source	string	github, gitlab, bitbucket, replit, gitee, desktop
repo	string	owner/repo format
branch	string	Default: main
directUrl	string	Agent URL (for desktop connections)

Fix Pipeline

POST/api/fix/start auth

Start a fix session using the graph-based orchestrator (reviewer-actor architecture, 2-pass review).

Parameter	Type	Description
errors	array	Errors to fix [{userNote, ownerMsg, agentMsg}]
agent	string	Agent ID
humanApproval	boolean	Enable pause-and-ask (default: false)

// Response
{ "id": "fix-1234567890" }

POST/api/fix/:id/apply auth

Deploy a ready fix to the agent's repository.

Parameter	Type	Description
branch	string	"master" (direct) or "sandbox" (PR workflow)

POST/api/fix/:id/resume auth

Resume a paused fix (human-in-the-loop response).

Parameter	Type	Description
response	string	"approve", "request_changes", or "reject"
feedback	string	Optional feedback for the AI

GET/api/fix/:id/graph auth

Get the execution graph trace for a fix session.

GET/api/fix/stream auth

SSE stream for real-time fix progress. Events: fix (progress), ping (keepalive).

Tests

POST/api/tests/generate auth

Generate behavioral test cases from agent instructions.

POST/api/tests/baseline auth

Generate tests from agent instructions and run them.

POST/api/tests/run auth

Run all tests against the agent.

Security

POST/api/tests/security-scan auth

Generate and run adversarial security tests (OWASP LLM Top 10).

GET/api/security/static auth

Run static code analysis for hardcoded secrets, dangerous functions, missing validation.

GET/api/security/chains auth

List available multi-turn attack chains.

POST/api/security/chain/run auth

Execute a multi-turn attack chain against the agent.

Parameter	Type	Description
chainId	string	Attack chain ID (from /api/security/chains)

GET/api/security/report auth

Full compliance report: OWASP coverage, risk score, remediation priorities.

GET/api/security/owasp public

OWASP LLM Top 10 reference data.

Architecture

GET/api/architecture auth

Full architecture graph: source files, routes, external services, call graph.

GET/api/architecture/risk auth

Risk scoring: cyclomatic complexity, dead code, circular dependencies.

GET/api/architecture/consumption auth

Token consumption analysis with architecture-aware optimization recommendations.

GET/api/architecture/blast-radius auth

Blast radius analysis for a specific function.

Optimize

POST/api/agent/optimize auth

Run parameter optimizer: analyze behavior and generate improved instructions.

POST/api/agent/parameters/apply auth

Apply an optimization to the agent's system prompt.

MCP Server

Agent Etna implements the Model Context Protocol — any MCP-compatible AI agent can discover and call Etna's tools.

POST/mcp Bearer token

JSON-RPC 2.0 endpoint. Supports: initialize, tools/list, tools/call, ping.

// Example: list available tools
POST /mcp
Authorization: Bearer <token>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

GET/mcp/tools public

List all MCP tools with schemas (convenience endpoint).

Available MCP Tools

Tool	Description
etna_fix	Generate and deploy fixes for agent bugs
etna_test	Generate and run behavioral tests
etna_security_scan	Run static + adversarial security analysis
etna_analyze	Get architecture analysis, risk scores, call graph
etna_optimize	Analyze behavior and generate improved instructions
etna_status	Check agent health and connection status
etna_identity	Get/verify/rotate cryptographic identity

GitHub Action

Add Agent Etna to your CI pipeline:

- uses: giuerr/agentetna@master
  with:
    agent-url: https://my-agent.onrender.com
    etna-api-key: ${{ secrets.ETNA_API_KEY }}
    auto-fix: true
    test-count: 10
    security-scan: true

Outputs

Output	Description
tests-passed	Number of tests that passed
tests-failed	Number of tests that failed
fixes-generated	Number of fix patches generated
pr-url	URL of the created pull request
security-issues	Number of security vulnerabilities found

Cryptographic Identity

GET/verify/:agentId public

Public verification of an agent's cryptographic identity. No auth required.

GET/badge/:agentId public

Live SVG badge showing verified status. Embed in README:

[![Agent Etna](https://www.agentetna.com/badge/my-agent)](https://www.agentetna.com/verify/my-agent)

POST/api/verify/fix public

Verify a fix attestation against an agent's public key.

GET/api/agent/identity auth

Get identity info. Auto-provisions if missing.

POST/api/agent/identity/rotate auth

Rotate keypair. Revokes old signatures.

Analytics founder only

GET/api/admin/analytics

Overview: DAU, WAU, MAU, funnel, top modes, top actions, trends.

GET/api/admin/analytics/users

All users sorted by last seen, with funnel stage.

GET/api/admin/analytics/events

Live tail of recent events (last 50-200).

System Health founder only

GET/api/admin/system

Memory usage, cache stats (hit rates, sizes), job queue status, SSE connections, provider availability.

GET/healthz public

Health check. Returns {"ok":true,"uptime":1234}.

Agent Etna API v1.0