API reference

The AgentChoice API

Create AI buyer verdicts programmatically. Available on the Enterprise plan. All requests are JSON over HTTPS.

Authentication

Create a key under Account → API keys. It is shown once. Send it as a bearer token on every request. Keep it server-side; treat it like a password.

Authorization: Bearer ac_live_xxxxxxxxxxxxxxxx

Endpoints

POST/api/v1/verdicts

Start a verdict. Returns immediately with 202; the simulation runs in the background.

Request

curl -X POST https://agentchoice.app/api/v1/verdicts \
  -H "Authorization: Bearer $AGENTCHOICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userUrl": "https://yourstore.com",
    "competitorUrls": ["https://rival-a.com", "https://rival-b.com"],
    "industry": "SaaS / Software",
    "buyerQuery": "Best CRM for a 5-person startup"
  }'

Response · 202

{
  "id": "8f3c…",
  "status": "processing",
  "url": "https://agentchoice.app/api/v1/verdicts/8f3c…"
}

competitorUrlsis capped at your plan’s competitor limit. Each verdict counts against your monthly quota.

GET/api/v1/verdicts/:id

Poll a verdict until status is 'complete'. Returns the full report payload.

curl https://agentchoice.app/api/v1/verdicts/8f3c… \
  -H "Authorization: Bearer $AGENTCHOICE_KEY"

Response · 200

{
  "id": "8f3c…",
  "status": "complete",
  "buyerQuery": "Best CRM for a 5-person startup",
  "preferenceScores": [
    { "name": "yourstore", "percentage": 42, "isUser": true },
    { "name": "rival-a",   "percentage": 33, "isUser": false }
  ],
  "avgConfidence": 0.81,
  "topWeaknesses": [{ "text": "Pricing is hidden", "count": 12 }],
  "report": {
    "overall_result": "…",
    "top_5_fixes": ["…"],
    "projected_score": 61
  }
}

While running, status is "processing". Poll every few seconds; a verdict typically completes within a minute or two.

GET/api/v1/verdicts

List your team's most recent verdicts.

{
  "verdicts": [
    { "id": "8f3c…", "status": "complete", "buyerQuery": "…", "userPreference": 42, "created_at": "…" }
  ]
}

Use from AI tools (MCP)

AgentChoice runs a Model Context Protocol server, so AI assistants and agents (Claude, Cursor, and other MCP clients) can run visibility checks and verdicts directly. Tools: check_visibility, run_verdict, get_verdict.

Endpoint

https://agentchoice.app/api/mcp   (JSON-RPC over HTTP, Bearer API key)

Connect a client (e.g. Claude Desktop / Code)

npx mcp-remote https://agentchoice.app/api/mcp \
  --header "Authorization: Bearer $AGENTCHOICE_KEY"

Then ask your assistant: “Use AgentChoice to check if my brand is recommended for ‘best CRM’, and tell me what to fix.” Full MCP guide →

Errors

400Missing or invalid parameters.

401Missing, invalid, or revoked API key.

402Monthly verdict quota reached.

403Your plan does not include API access.

404Verdict not found, or not owned by your team.

422A site could not be read (down, blocks bots, or JavaScript-only).

429Rate limit exceeded. Slow down and retry.

Errors return { "error": "message" } with the status above.

Ready to integrate?

Create your first API key in your account settings.