API Reference

Complete REST API documentation for Agent Diff

Base URLs

Hosted

https://api.agentdiff.dev

Self-Hosted

http://localhost:8000

Authentication

All API requests require authentication via API key header:

curl -H "X-API-Key: ad_live_sk_..." \
  https://api.agentdiff.dev/api/platform/health

Get your API key from the dashboard (hosted) or run make reissue-key (self-hosted).

API Structure

The API is organized into several groups:

Platform Endpoints

Core functionality: environments, runs, diffs

• /api/platform/initEnv
• /api/platform/startRun
• /api/platform/evaluateRun
• /api/platform/results/{runId}

Template Endpoints

Manage environment templates

• /api/platform/templates
• /api/platform/templates/{id}

Test Suite Endpoints

Manage test suites and tests

• /api/platform/testSuites
• /api/platform/testSuites/{id}

Service APIs

Isolated service replicas

• /api/env/{id}/services/slack/*
• /api/env/{id}/services/linear/*

Response Format

Success Response

{
  "environmentId": "abc123",
  "status": "ready",
  "data": {...}
}

Error Response

{
  "ok": false,
  "error": "error_code",
  "detail": "Human-readable error message"
}

Common Error Codes

Code	Status	Description
not_authed	401	Missing or invalid API key
invalid_environment_path	400	Malformed environment ID
environment_not_found	404	Environment doesn’t exist or expired
run_not_found	404	Test run doesn’t exist
template_not_found	404	Template doesn’t exist
internal_error	500	Server error

Rate Limits

Hosted

Plan	Requests/hour	Concurrent Environments
Free	100	5
Pro	1,000	50
Enterprise	Unlimited	Unlimited

Self-Hosted

No rate limits (limited by your infrastructure)

SDKs

We recommend using our SDKs instead of calling the API directly:

Python SDK

pip install agent-diff

TypeScript SDK

npm install agent-diff

Quick Example

# 1. Create environment
curl -X POST https://api.agentdiff.dev/api/platform/initEnv \
  -H "X-API-Key: ad_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "templateService": "slack",
    "templateName": "slack_default",
    "impersonateUserId": "U01AGENBOT9"
  }'

# Response: {"environmentId": "abc123", "environmentUrl": "..."}

# 2. Start run
curl -X POST https://api.agentdiff.dev/api/platform/startRun \
  -H "X-API-Key: ad_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"envId": "abc123"}'

# Response: {"runId": "run-456", "status": "running"}

# 3. Make API calls to isolated environment
curl -X POST https://api.agentdiff.dev/api/env/abc123/services/slack/chat.postMessage \
  -H "X-API-Key: ad_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"channel": "C01GENERAL99", "text": "Hello!"}'

# 4. Get diff
curl -X POST https://api.agentdiff.dev/api/platform/diffRun \
  -H "X-API-Key: ad_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"runId": "run-456"}'

# Response: {"diff": {"inserts": [...], "updates": [...], "deletes": []}}