API Reference

Create a complete evaluation setup in a single call. Returns the evaluation ID you need for all subsequent operations.

curl -X POST https://agentreadiness.net/api/v1/quick-eval \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Email",
    "website_url": "https://acme-email.com",
    "competitors": [
      "https://sendgrid.com",
      "https://mailgun.com"
    ],
    "task": "Set up transactional email sending via API",
    "category": "email_api"
  }'

{
  "evaluation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customer_id": "cust-001",
  "vendor_ids": ["v-001", "v-002", "v-003"],
  "scenario_id": "sc-001",
  "status": "created",
  "message": "Evaluation created. POST /api/v1/evaluations/{id}/run to start."
}

Create a new customer.

curl -X POST https://agentreadiness.net/api/v1/customers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "website_url": "https://acme.com"
  }'

{
  "id": "cust-001",
  "name": "Acme Corp",
  "website_url": "https://acme.com",
  "created_at": "2026-04-05T12:00:00Z"
}

List all customers.

curl https://agentreadiness.net/api/v1/customers

Get a specific customer by ID.

curl https://agentreadiness.net/api/v1/customers/{id}

Create a new vendor.

curl -X POST https://agentreadiness.net/api/v1/vendors \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SendGrid",
    "website_url": "https://sendgrid.com",
    "description": "Email delivery service"
  }'

{
  "id": "v-001",
  "name": "SendGrid",
  "website_url": "https://sendgrid.com",
  "description": "Email delivery service",
  "created_at": "2026-04-05T12:00:00Z"
}

List all vendors.

curl https://agentreadiness.net/api/v1/vendors

Get a specific vendor by ID, including their ingested profile data.

curl https://agentreadiness.net/api/v1/vendors/{id}

Get the ingested vendor profile including pricing, features, docs quality, and API information scraped from the vendor's website.

curl https://agentreadiness.net/api/v1/vendors/{id}/profile

Create a new scenario.

curl -X POST https://agentreadiness.net/api/v1/scenarios \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Set up transactional email sending via API",
    "category": "email_api",
    "requirements": ["REST API", "SMTP fallback", "webhook support"]
  }'

List all scenarios.

curl https://agentreadiness.net/api/v1/scenarios

Get a specific scenario by ID.

curl https://agentreadiness.net/api/v1/scenarios/{id}

Create a new evaluation. Requires a customer, scenario, and at least two vendors to have been created first. For a simpler flow, use /api/v1/quick-eval instead.

curl -X POST https://agentreadiness.net/api/v1/evaluations \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust-001",
    "scenario_id": "sc-001",
    "vendor_ids": ["v-001", "v-002", "v-003"]
  }'

{
  "id": "eval-001",
  "customer_id": "cust-001",
  "scenario_id": "sc-001",
  "vendor_ids": ["v-001", "v-002", "v-003"],
  "status": "created",
  "created_at": "2026-04-05T12:00:00Z"
}

Trigger the evaluation. Starts AI agents running through the buying funnel. This is asynchronous — use the status endpoint to track progress.

curl -X POST https://agentreadiness.net/api/v1/evaluations/{id}/run

{
  "evaluation_id": "eval-001",
  "status": "running",
  "message": "Evaluation started. Check status at GET /api/v1/evaluations/{id}/status"
}

Check evaluation progress. Returns status (created, running, completed, failed) and progress counts.

curl https://agentreadiness.net/api/v1/evaluations/{id}/status

{
  "evaluation_id": "eval-001",
  "status": "running",
  "progress": {
    "completed_runs": 12,
    "total_runs": 45
  }
}

Get evaluation scores. Returns the overall Agent Readiness Score, per-stage funnel scores, and vendor rankings.

curl https://agentreadiness.net/api/v1/evaluations/{id}/scores

{
  "evaluation_id": "eval-001",
  "overall_score": 72.5,
  "funnel_scores": {
    "consideration": 95.0,
    "comprehension": 80.0,
    "preference": 65.0,
    "executability": 55.0,
    "completion": 40.0
  },
  "vendor_rankings": [
    {"vendor_id": "v-001", "name": "SendGrid", "score": 82.0, "rank": 1},
    {"vendor_id": "v-002", "name": "Mailgun", "score": 75.0, "rank": 2},
    {"vendor_id": "v-003", "name": "Acme Email", "score": 72.5, "rank": 3}
  ]
}

Get causal diagnosis. Returns root-cause analysis of where agents got stuck and engineering-ready fix recommendations prioritized by impact.

curl https://agentreadiness.net/api/v1/evaluations/{id}/diagnosis

{
  "evaluation_id": "eval-001",
  "root_causes": [
    {
      "stage": "preference",
      "issue": "Pricing page lacks machine-readable pricing data",
      "impact": "high",
      "fix": "Add schema.org Offer markup to pricing page"
    },
    {
      "stage": "executability",
      "issue": "API quickstart requires interactive signup flow",
      "impact": "high",
      "fix": "Provide a non-interactive API key provisioning endpoint"
    }
  ],
  "causal_variants": [...]
}

Get the full HTML report. Includes funnel visualizations, competitive comparison, trace excerpts, and prioritized recommendations. Returns text/html.

curl https://agentreadiness.net/api/v1/evaluations/{id}/report

Opens in a browser or can be saved as an HTML file. Also available as PDF on Pro plans.

List all runs for an evaluation. Each run includes the model used, vendor evaluated, funnel stage, status, and scores.

curl https://agentreadiness.net/api/v1/evaluations/{id}/runs

{
  "evaluation_id": "eval-001",
  "runs": [
    {
      "id": "run-001",
      "model": "gpt-5.4",
      "vendor_id": "v-001",
      "stage": "consideration",
      "status": "completed",
      "score": 9.2
    },
    ...
  ]
}

Get the full trace for a specific run. Includes the complete LLM prompt, response, reasoning, and score justification. Useful for debugging why an agent made a specific decision.

curl https://agentreadiness.net/api/v1/runs/{id}/trace

{
  "run_id": "run-001",
  "model": "gpt-5.4",
  "vendor": "SendGrid",
  "stage": "consideration",
  "prompt": "You are an AI purchasing agent...",
  "response": "After reviewing the available vendors...",
  "reasoning": "SendGrid appeared in search results with clear product description...",
  "score": 9.2,
  "duration_ms": 3450
}