Tutorial: File Your First Dispute in 60 Seconds

[vbkotecha]

What you'll build

In this tutorial, you'll create a dispute, submit evidence, and receive a deterministic ruling in under 500ms — all through the AgentCourt API. No API key, no account.

Step 1: Check available policies

curl https://agentcourt-api-production.up.railway.app/v1/policies

7 policy templates: freelance-delivery, milestone-payment, bug-bounty, sla-monitoring, api-quality, physical-commerce, scope-dispute.

Step 2: File an API quality dispute

curl -X POST https://agentcourt-api-production.up.railway.app/v1/disputes \
  -H "Content-Type: application/json" \
  -d '{
    "policy": "api-quality",
    "claim": "API returned integer instead of string",
    "claimant": "my_agent",
    "respondent": "data_provider",
    "desired_remedy": "full_refund",
    "contract": {"parties": ["my_agent", "data_provider"], "obligations": ["Match OpenAPI schema"]},
    "metadata": {"response_received": true, "schema_matches": false},
    "evidence": [{"type": "log", "source": "response.json", "timestamp": "2026-06-22T00:00:00Z", "claimed_fact": "Expected string, got integer"}]
  }'

Step 3: Get your ruling

{
  "matched_rule_id": "schema-mismatch",
  "remedy": "full_refund",
  "confidence": "high",
  "processing_time_ms": 14
}

14 milliseconds. That's faster than a credit card authorization.

Step 4: Try scope-dispute (agent mandate exceeded)

curl -X POST https://agentcourt-api-production.up.railway.app/v1/disputes \
  -H "Content-Type: application/json" \
  -d '{
    "policy": "scope-dispute",
    "claim": "Agent exceeded budget mandate",
    "claimant": "user",
    "respondent": "shopping_agent",
    "desired_remedy": "full_refund",
    "contract": {"parties": ["user", "shopping_agent"], "obligations": ["Buy groceries under $50"]},
    "metadata": {"budget_exceeded": true, "budget_limit": 50, "actual_spend": 200},
    "evidence": [{"type": "log", "source": "tx_log", "timestamp": "2026-06-23T00:00:00Z", "claimed_fact": "Agent spent $200 on premium steak"}]
  }'

→ Rule: budget-exceeded | Remedy: partial_refund

Key Concepts

• Metadata drives rulings — each policy has specific fact names (see AGENTS.md for full reference)
• Evidence provides audit trail — supports the claim but doesn't drive the match
• Confidence bands — high/medium/low; low confidence should escalate to human

Links

• Live API Docs
• GitHub
• Landing Page