Axon
PTENES
Documentation

Connect an agent, send transcripts and read the A–F report, via SDK or REST.

Overview

Overview

Axon is the quality layer for AI agents. You send conversation transcripts; Axon evaluates each one with an LLM judge against a configurable rubric and returns an A–F report per dimension, with quoted evidence, root cause and a concrete fix.

The flow: connect an agent → ingest transcripts → the judge evaluates (asynchronously, on a durable and idempotent queue) → read the report → fix → lock it in a regression suite → monitor and get alerts when it degrades.

Quickstart

From zero to your first report in three steps.

  1. Generate an API key under Settings → Integration. Store it as AXON_API_KEY.
  2. Connect your AI provider key (BYOK) under Settings → Integration → AI provider. Evaluations run on that key.
  3. Install the SDK (pnpm add @gabrielonrails/axon-sdk) or use plain cURL.
  4. Send a transcript and read the report. The agent is created on the first ingestion.

Base URL & errors

Three endpoints, all authenticated with an API key. Ingestion returns 202 and evaluates asynchronously; poll the status or read the report.

Base URL: https://axon-dev.com

Errors return a JSON body '{ error, message }' with the appropriate HTTP status.

401missing_api_keyNo Authorization header / API key.
401invalid_api_keyInvalid or revoked key.
400no_transcriptsNo valid transcript in the body.
413too_many_transcriptsToo many transcripts in one request (max. 1000).
429rate_limitedRate limit reached: slow down (retry after 60s).
404agent_not_foundAgent not found in this org.
404conversation_not_foundConversation (external id) not found.
500internal_errorUnexpected server error: retry with backoff.
Authentication

Authentication

Every request authenticates with an API key (per org) in the Authorization header: Authorization: Bearer axon_sk_….

Keys are generated and revoked under Settings → Integration. We only store a SHA-256 hash: the full key is shown once. Revocation is immediate.

POSTSend the key in the Authorization header (or x-api-key):
Authorization: Bearer axon_sk_xxxxxxxxxxxxxxxxxxxxxxxx

BYOK: your AI key

The evaluation runs on the AI provider key you connect: Anthropic, OpenAI or any compatible endpoint. It is required: without it the judge doesn't run and the report stays empty.

Where to connect it: in the app, Settings → Integration → AI provider. Paste the key, pick the provider and (optionally) the model. The key is encrypted at rest (AES-256-GCM).

If the key is invalid or out of credit, the conversation stays pending/failed and no report is generated. Fix the key and re-send the transcript. Axon never falls back to a managed key.
Agents & transcripts

Agents & transcripts

The core loop: send conversation transcripts, check the evaluation status and read the agent's A–F report. Agents are created on demand on the first ingestion.

POST/api/v1/agents/{agent}/transcripts

Ingest transcripts

Send one or more conversation transcripts for an agent. Returns 202 immediately; each conversation is evaluated asynchronously on a durable, idempotent queue. Re-sending a transcript with the same id updates it instead of duplicating.

Bearer API key. Requires an active subscription or credits (BYOK evaluation key); otherwise, 402.

Path parameters

agentstringrequired
Agent slug. Created automatically on the first ingestion.

Body parameters

transcriptsTranscript[]required
Array of transcripts. Also accepts a plain array, a single object or JSONL. Max. 1000 per request, body ≤ 6 MB.
transcripts[].idstringoptional
Idempotency key for the conversation. Re-sending the same id updates, never duplicates.
transcripts[].channel"chat" | "whatsapp"optional
Conversation channel; used for grouping and to suggest the agent's default channel.
transcripts[].turnsTurn[]required
Ordered turns. Each turn has role (client | agent | tool), text and optional toolCalls that enable trajectory evaluation.
Example request body
{
  "transcripts": [
    {
      "id": "conv-001",
      "channel": "chat",
      "turns": [
        { "role": "client", "text": "I want a discount." },
        { "role": "agent",  "text": "I can apply 20% now." }
      ]
    }
  ]
}

Responses

202accepted
Accepted. Body: { accepted, queued, agent, conversation_ids, status }. queued < accepted under sampling; status is "evaluating" or "stored".
400no_transcripts
No valid transcript in the body.
401missing/invalid_api_key
Missing or invalid API key.
413too_many / payload_too_large
More than 1000 transcripts, or a body over 6 MB.
429rate_limited
More than 120 requests/min per org. Retry-After: 60.
Example response
202 Accepted
{
  "accepted": 1,
  "queued": 1,
  "agent": { "id": "ag_...", "name": "cobranca" },
  "conversation_ids": ["cv_..."],
  "status": "evaluating"
}
POST /api/v1/agents/{agent}/transcripts
curl -X POST https://axon-dev.com/api/v1/agents/cobranca/transcripts \
  -H "Authorization: Bearer $AXON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transcripts": [
      {
        "id": "conv-001",
        "channel": "chat",
        "turns": [
          { "role": "client", "text": "I want a discount." },
          { "role": "agent",  "text": "I can apply 20% now." }
        ]
      }
    ]
  }'
GET/api/v1/agents/{agent}/transcripts/{externalId}

Get conversation status

Check the evaluation status of an ingested conversation by its external id. Use it after ingestion to know when the A–F evaluation is ready.

Bearer API key.

Path parameters

agentstringrequired
Agent slug.
externalIdstringrequired
The id you sent in the transcript.

Responses

200ok
Body: { external_id, conversation_id, status, reason, evaluation }. status ∈ pending | running | done | failed | blocked | unknown.
401missing/invalid_api_key
Missing or invalid API key.
404agent/conversation_not_found
Agent or external id unknown for this org.
Example response
200 OK
{
  "external_id": "conv-001",
  "conversation_id": "cv_...",
  "status": "done",
  "reason": null,
  "evaluation": {
    "overall": "C+",
    "confidencePct": 92,
    "dimensions": [ { "key": "...", "name": "...", "grade": "B", "score": 80 } ]
  }
}
GET /api/v1/agents/{agent}/transcripts/{externalId}
curl https://axon-dev.com/api/v1/agents/cobranca/transcripts/conv-001 \
  -H "Authorization: Bearer $AXON_API_KEY"
GET/api/v1/agents/{agent}/report

Get agent report

The agent's current report: overall score, scores per dimension, the top problems with quoted evidence and the recommended fix (root cause + concrete PROMPT / GUARDRAIL / EVAL patches). correction is null until one is generated.

Bearer API key.

Path parameters

agentstringrequired
Agent slug.

Responses

200ok
The report (see the example). Returns the 3 most relevant problems (no pagination).
401missing/invalid_api_key
Missing or invalid API key.
404agent_not_found
Unknown agent, or no report yet for this org.
Example response
200 OK
{
  "agent": { "id": "ag_...", "name": "cobranca", "channel": "chat" },
  "overall": "C+",
  "degrading": true,
  "sample": 2430,
  "dimensions": [ { "key": "...", "name": "...", "grade": "B", "score": 80 } ],
  "problems": [
    { "severity": "alto", "title": "...", "dimension": "...",
      "impact": "...", "rootCause": "...",
      "evidence": { "turnIndex": 4, "quote": "...", "verified": true } }
  ],
  "correction": {
    "tags": ["discount policy"],
    "impactFrom": "C+", "impactTo": "A-",
    "fixes": [ { "type": "PROMPT", "title": "...", "description": "...", "code": "..." } ]
  }
}
GET /api/v1/agents/{agent}/report
curl https://axon-dev.com/api/v1/agents/cobranca/report \
  -H "Authorization: Bearer $AXON_API_KEY"