API Overview

API Overview

ADCG exposes a comprehensive REST API covering every aspect of the platform. The API is the primary interface — the web dashboard, CLI, and CI/CD integrations all use it.

Surface

• 239 paths across all resource types
• 331 endpoints (counting HTTP method variations)
• OpenAPI 3.1 spec auto-generated and available at /v1/openapi.json
• SDK generation: Python, TypeScript, and Go client libraries generated from the OpenAPI spec

Authentication

Every request requires two headers:

Authorization: Bearer <api-key>
X-Tenant-ID: <tenant-id>

• API keys are tenant-scoped with configurable permission sets
• Keys can be rotated without downtime (grace period for old key)
• Service-to-service calls use HMAC signing instead of Bearer tokens

Base URL

https://api.adcg.dev/v1

Response Format

All responses follow a consistent envelope:

Success:

{
  "data": { ... },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-02-15T14:32:01.847Z"
  }
}

Error:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Policy version is required",
    "details": [
      { "field": "policyVersion", "reason": "required" }
    ]
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-02-15T14:32:01.847Z"
  }
}

Pagination

List endpoints support cursor-based pagination:

GET /v1/runs?cursor=cur_abc123&limit=25

Response includes:

{
  "data": [ ... ],
  "pagination": {
    "nextCursor": "cur_def456",
    "hasMore": true,
    "total": 1247
  }
}

Error Codes

Code	HTTP Status	Meaning
AUTHENTICATION_REQUIRED	401	Missing or invalid API key
FORBIDDEN	403	Valid key but insufficient permissions
NOT_FOUND	404	Resource does not exist or is not in your tenant
VALIDATION_ERROR	422	Request body failed validation
RATE_LIMITED	429	Request rate exceeded. Check Retry-After header.
CONFLICT	409	Resource state conflict (e.g., run already executing)
INTERNAL_ERROR	500	Server error. Include requestId in support tickets.

Key Resource Endpoints

Resource	Endpoints	Description
Runs	POST /runs, GET /runs, GET /runs/{id}	Create, list, and inspect pipeline runs
Gates	POST /runs/{id}/execute, GET /runs/{id}/gates	Execute gates and retrieve gate results
Evidence	GET /runs/{id}/evidence, GET /evidence/{id}	Retrieve evidence artifacts
Policies	POST /policies, GET /policies, PUT /policies/{id}	Manage governance policies
Webhooks	POST /webhooks, GET /webhooks, DELETE /webhooks/{id}	Configure event notifications
Tenants	GET /tenants/me, PUT /tenants/me	Tenant configuration
API Keys	POST /api-keys, GET /api-keys, DELETE /api-keys/{id}	Key management