DocsAPI Reference

API Reference

The AKIOS Pro CLI and REST API surfaces for evidence management, configuration, and export.

CLI Reference#

The AKIOS Pro CLI is the primary interface for deployment, configuration, and evidence management. Commands run inside the running container via docker exec akios-pro akios <command>.

Evidence commands

akios status
Display collection status: connected sources, total traces, findings breakdown, retention, storage usage.
akios traces list
List traces with filters: --session, --agent, --since, --until, --framework, --limit, --offset.
akios traces get <id>
Full trace detail: all events, policy evaluations, PII findings, tool calls, review actions.
akios findings list
List findings with filters: --severity (low|medium|high|critical), --type, --status, --since, --until.
akios findings get <id>
Full finding detail: evidence context, timestamps, remediation history, control mappings.
akios findings update <id>
Update finding status: --status (open|reviewing|remediated|closed), --comment.
akios pack
Generate evidence pack: --last (time range), --session, --format (json|html|pdf), --include-controls.
akios export
Export raw evidence: --format (json|parquet|csv), --since, --until, --output.

Configuration commands

akios sources add
Add evidence source: --type (gateway|webhook|otel|logfile), --name, --endpoint.
akios sources list
List all sources with connection status, last event, and event count per source.
akios sources remove <id>
Remove source. --purge to delete associated traces.
akios sources test <id>
Test source connection and report latency, authentication, and sample event.
akios retention set
Set retention: --days (7-365), --enforce for automatic purging.
akios retention status
Display policy, storage usage %, oldest record date, legal hold count.
akios siem add
Configure SIEM: splunk|sentinel|syslog with endpoint, port, protocol, format.
akios siem status
SIEM forwarding status, last event timestamp, total forwarded, error count.
akios siem test
Send test event to verify SIEM connectivity and schema.

Admin commands

akios admin users
List dashboard users, roles, and last login.
akios admin license
Display license status, expiry, usage limits, and upgrade path.
akios admin logs
Tail AKIOS Pro system logs for debugging: --follow, --level (info|warn|error).
akios admin backup
Create evidence store backup: --output, --full (includes config).

REST API#

The AKIOS Pro REST API is available on port 8080 (configurable via AKIOS_API_PORT). All endpoints require authentication.

Authentication

API key
Pass via Authorization: Bearer <key> header. Keys managed via AKIOS_API_KEY env var or admin CLI.
OIDC
Bearer token from your OIDC provider. Configure via AKIOS_OIDC_ISSUER_URL and AKIOS_OIDC_CLIENT_ID.
Rate limiting
1000 requests/minute per API key. Rate limit headers: X-RateLimit-Remaining, X-RateLimit-Reset.

Evidence ingestion

bash
# Push a trace event
curl -X POST http://localhost:8080/api/v1/traces \
  -H "Authorization: Bearer $AKIOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_abc123",
    "agent": "customer-support-v2",
    "framework": "langchain",
    "events": [
      {
        "type": "llm_call",
        "model": "gpt-4o",
        "prompt": "I need a refund for my order",
        "completion": "Let me check your order history",
        "tokens_prompt": 45,
        "tokens_completion": 120,
        "timestamp": "2026-05-04T14:23:11Z"
      }
    ]
  }'

# Response: 201 Created
# {
#   "trace_id": "trc_8f7d3a1e",
#   "status": "accepted",
#   "events_ingested": 1,
#   "findings_generated": 2
# }

Evidence retrieval

bash
# List traces with filters
curl "http://localhost:8080/api/v1/traces?agent=customer-support&since=2026-05-01&limit=10"
# Response: { "traces": [...], "total": 247, "page": 1, "page_size": 10 }

# Get specific trace
curl "http://localhost:8080/api/v1/traces/sess_abc123"
# Response: { "trace_id": "sess_abc123", "events": [...], "findings": [...], "status": "completed" }

# List findings by severity
curl "http://localhost:8080/api/v1/findings?severity=high&status=open"
# Response: { "findings": [...], "total": 3, "page": 1 }

# Get export bundle
curl -o evidence-pack.zip   "http://localhost:8080/api/v1/exports/pack_xyz123"

Error codes

400
Bad request
Invalid payload structure, missing required fields, or schema validation failure.
401
Unauthorized
Missing or invalid API key or OIDC token.
403
Forbidden
API key does not have permission for the requested operation.
404
Not found
The requested trace, finding, or export does not exist or has been purged.
409
Conflict
Duplicate session_id or event_id. Idempotency key already processed.
429
Rate limited
Too many requests. Check X-RateLimit-Remaining and X-RateLimit-Reset headers.
500
Internal error
Contact support with trace_id from response headers.

SDK Reference#

AKIOS Pro provides SDKs for pushing evidence events programmatically from your agent runtime.

Python

pip install akios-pro-sdk. Push trace events, configure sources, and manage exports from Python agent runtimes.

TypeScript

npm install @akios/pro-sdk. Integrate with existing Node.js agent infrastructure.

REST (any)

Direct HTTP integration via the REST API. Compatible with any language and runtime.

OpenTelemetry

AKIOS Pro accepts OTel traces natively. Configure your agent runtime to export OTel signals to the AKIOS Pro endpoint.

Previous← FAQ