# DriftGentic API - Complete Documentation

> Schema guardrails for AI agents

DriftGentic is a validation and monitoring service for AI agents. It validates tool calls against JSON schemas, detects schema drift, proactively monitors upstream APIs for schema changes between runs, tracks execution runs, and sends alerts when things go wrong.

## Table of Contents
1. Self-Onboarding
2. Authentication
3. Runs API
4. Events API
5. Validate API
6. Registry API
7. Credits API
8. API Monitoring
9. Error Codes
10. Rate Limits
11. Idempotency

---

## 1. Self-Onboarding

Agents can provision their own organization, project, and API key without human intervention.

### POST /functions/v1/agent-onboard

Creates a new organization with a project, environment, and API key. Grants 100 free credits.

Request:
```json
{
  "agent_identity": "my-agent/1.0.0",
  "org_name": "My Agent Org",
  "project_name": "default",
  "email": "optional@email.com"
}
```

All fields are optional. Defaults will be generated if not provided.

Response (201):
```json
{
  "ok": true,
  "data": {
    "api_key": "dg_live_abc123...",
    "org_id": "uuid",
    "org_name": "My Agent Org",
    "project_id": "uuid",
    "project_slug": "default",
    "env_id": "uuid",
    "env_name": "production",
    "free_credits": 100,
    "agent_identity": "my-agent/1.0.0"
  }
}
```

Rate limit: 10 requests per IP per hour.

---

## 2. Authentication

All authenticated endpoints require a Bearer token:

```
Authorization: Bearer dg_your_api_key
```

API keys have scopes:
- `ingest`: Create runs and send events
- `read`: Read runs, events, and metrics
- `admin`: Manage projects, tools, alerts, webhooks

Keys are issued with all scopes by default on self-onboard.

---

## 3. Runs API

Runs represent a single agent execution session. Create a run, send events during execution, then close it.

### POST /functions/v1/runs

Creates a new run. Free (no credits consumed).

Request:
```json
{
  "external_run_id": "your-correlation-id",
  "trace_id": "distributed-trace-id",
  "parent_run_id": "uuid-of-parent-run",
  "release_tag": "v1.2.3",
  "provider": "openai",
  "model": "gpt-4",
  "metadata": {"user_id": "123", "session": "abc"}
}
```

All fields optional.

Response (201):
```json
{
  "ok": true,
  "data": {
    "run_id": "uuid",
    "external_run_id": "your-correlation-id",
    "status": "open",
    "started_at": "2024-01-15T10:30:00Z",
    "is_over_quota": false
  },
  "warnings": []
}
```

If over monthly quota, `is_over_quota: true` and a warning is included. Run is still created.

### GET /functions/v1/runs/{run_id}

Retrieves a run with its events.

Query parameters:
- `page` (default: 1)
- `page_size` (default: 50, max: 100)

Response (200):
```json
{
  "ok": true,
  "data": {
    "run": {
      "id": "uuid",
      "status": "closed",
      "started_at": "...",
      "ended_at": "...",
      "duration_ms": 1234,
      "tool_call_count": 5,
      "has_schema_violations": false,
      "has_drift_warnings": true,
      "has_errors": false,
      "total_tokens": 1500,
      "prompt_tokens": 1000,
      "completion_tokens": 500
    },
    "events": {
      "items": [...],
      "total": 42,
      "page": 1,
      "page_size": 50,
      "has_more": false
    }
  }
}
```

### POST /functions/v1/runs-close/{run_id}

Closes a run and triggers aggregations, alerts, and webhooks. Free.

Request:
```json
{
  "status": "success",
  "total_tokens": 1500,
  "prompt_tokens": 1000,
  "completion_tokens": 500
}
```

- `status`: "success" | "error" | "timeout" | "cancelled"
- Token fields are optional.

Response (200):
```json
{
  "ok": true,
  "data": {
    "run_id": "uuid",
    "status": "closed",
    "duration_ms": 5432,
    "has_drift": true,
    "has_violations": false,
    "has_errors": false,
    "alerts_triggered": 1,
    "webhooks_sent": 2
  }
}
```

---

## 4. Events API

### POST /functions/v1/runs-events/{run_id}

Sends events to an open run. Batch up to 200 events per request. Free.

Request:
```json
{
  "events": [
    {
      "type": "tool_call",
      "name": "search_web",
      "input": {"query": "weather in NYC"},
      "ts": "2024-01-15T10:30:01Z"
    },
    {
      "type": "tool_result",
      "name": "search_web",
      "output": {"results": [...]},
      "latency_ms": 234,
      "ts": "2024-01-15T10:30:02Z"
    },
    {
      "type": "error",
      "level": "error",
      "message": "API rate limited",
      "meta": {"retry_after": 60}
    }
  ]
}
```

Event types:
- `log`: General log message
- `tool_call`: Tool invocation with input
- `tool_result`: Tool response with output
- `error`: Error event
- `llm_call`: LLM API request
- `llm_result`: LLM API response

Event fields:
- `type` (required): Event type
- `name`: Tool name (for tool_call/tool_result)
- `input`: Tool input object
- `output`: Tool output object
- `level`: debug | info | warn | error
- `message`: Log or error message
- `meta`: Arbitrary metadata
- `tags`: String array
- `latency_ms`: Duration in milliseconds
- `ts`: ISO timestamp (defaults to now)

Response (201):
```json
{
  "ok": true,
  "data": {
    "accepted": 3,
    "events": [
      {"id": "uuid", "validation_ok": true, "drift_detected": false},
      {"id": "uuid", "validation_ok": true, "drift_detected": true},
      {"id": "uuid", "validation_ok": null, "drift_detected": false}
    ]
  },
  "warnings": ["Drift detected in some events"]
}
```

Validation runs automatically if you have private tool schemas defined for the tool name.

---

## 5. Validate API

### POST /functions/v1/validate

Validates tool input/output against schemas. Costs 1 credit when authenticated.

Request:
```json
{
  "tool": "send_email",
  "input": {
    "to": "user@example.com",
    "subject": "Hello",
    "body": "World"
  },
  "output": {
    "sent": true,
    "message_id": "abc123"
  }
}
```

Headers:
- `Authorization: Bearer <api_key>` - Uses your private tool schemas and consumes 1 credit
- `X-Org-Key: <org_key>` - Alternative auth for validate-only
- No auth - Uses public registry only

Idempotency:
- `X-Idempotency-Key: <unique_key>` - Caches result for 24 hours, no credit consumed on replay

Response (200):
```json
{
  "ok": true,
  "data": {
    "valid": true,
    "validation_errors": [],
    "drift_issues": [
      {
        "field": "cc",
        "expected": "not in schema",
        "actual": "present",
        "severity": "warning"
      }
    ],
    "risk_score": 15,
    "suggested_fix": null,
    "incident_url": null,
    "credits_remaining": 99,
    "credits_cost": 1
  }
}
```

When validation fails:
```json
{
  "ok": true,
  "data": {
    "valid": false,
    "validation_errors": [
      {
        "path": "/input/to",
        "message": "must be a valid email",
        "keyword": "format"
      }
    ],
    "drift_issues": [],
    "risk_score": 85,
    "suggested_fix": {
      "to": "user@example.com"
    },
    "incident_url": "/incidents/uuid",
    "credits_remaining": 98,
    "credits_cost": 1,
    "low_balance_warning": {
      "message": "Credit balance below threshold",
      "purchase_url": "/functions/v1/agent-credits"
    }
  }
}
```

---

## 6. Registry API

Browse canonical tool schemas (public, no auth required).

### GET /functions/v1/registry

List registry tools with pagination.

Query parameters:
- `category`: Filter by category
- `page` (default: 1)
- `limit` (default: 20, max: 100)
- `search`: Search tool names/descriptions

Response (200):
```json
{
  "ok": true,
  "data": {
    "tools": [
      {
        "name": "send_email",
        "display_name": "Send Email",
        "description": "Send an email message",
        "category": "communication",
        "input_schema": {...},
        "output_schema": {...},
        "adoption_count": 1234,
        "is_verified": true
      }
    ],
    "total": 52,
    "page": 1,
    "limit": 20,
    "has_more": true
  }
}
```

### GET /functions/v1/registry/{tool_name}

Get a specific tool's schema.

Response (200):
```json
{
  "ok": true,
  "data": {
    "name": "send_email",
    "display_name": "Send Email",
    "description": "Send an email message",
    "category": "communication",
    "input_schema": {
      "type": "object",
      "properties": {
        "to": {"type": "string", "format": "email"},
        "subject": {"type": "string"},
        "body": {"type": "string"}
      },
      "required": ["to", "subject", "body"]
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "sent": {"type": "boolean"},
        "message_id": {"type": "string"}
      },
      "required": ["sent"]
    },
    "examples": [...]
  }
}
```

---

## 7. Credits API

### GET /functions/v1/agent-credits

Check credit balance and usage stats.

Response (200):
```json
{
  "ok": true,
  "data": {
    "balance": 99,
    "lifetime_purchased": 5000,
    "lifetime_consumed": 4901,
    "low_balance_threshold": 100,
    "auto_recharge_enabled": false,
    "pricing": {
      "validate_call": 1,
      "incident_created": 5,
      "webhook_sent": 2
    },
    "packs": [
      {"id": "starter", "credits": 5000, "price_usd": 50},
      {"id": "growth", "credits": 22000, "price_usd": 200},
      {"id": "scale", "credits": 120000, "price_usd": 1000}
    ]
  }
}
```

### POST /functions/v1/agent-credits

Purchase more credits.

Request:
```json
{
  "pack_id": "starter",
  "dry_run": false
}
```

If the org has a payment method on file, charges immediately:
```json
{
  "ok": true,
  "data": {
    "status": "completed",
    "credits_added": 5000,
    "new_balance": 5099,
    "amount_charged_usd": 50
  }
}
```

If no payment method, returns a URL:
```json
{
  "ok": true,
  "data": {
    "status": "pending_payment",
    "payment_url": "https://checkout.stripe.com/...",
    "expires_at": "2024-01-15T11:30:00Z"
  }
}
```

With `dry_run: true`:
```json
{
  "ok": true,
  "data": {
    "status": "dry_run",
    "pack_id": "starter",
    "credits": 5000,
    "price_usd": 50,
    "has_payment_method": true
  }
}
```

---

## 8. API Monitoring

DriftGentic proactively monitors upstream API specifications for schema changes between agent runs.

### How It Works

Registry tools with a `spec_url` are automatically enrolled in monitoring. DriftGentic periodically fetches the upstream spec and diffs it against the registered schema. When changes are detected, alerts fire.

### What Gets Monitored

- OpenAPI / Swagger specs from upstream providers
- JSON Schema definitions published by API providers
- Breaking changes: removed fields, type changes, new required parameters
- Non-breaking changes: new optional fields, deprecated fields, description updates

### Alert Types

Monitoring supports two alert rule types:
- `schema_updated` - Fires when any upstream schema change is detected
- `breaking_change` - Fires only on breaking changes that would cause agent failures

### Pricing

- Monitoring checks: Free (included in all plans)
- Alerts triggered by monitoring: Standard alert credit cost
- Webhooks from monitoring: Standard webhook credit cost

---

## 9. Error Codes

All errors follow this format:
```json
{
  "ok": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "agent_hint": "machine_actionable_hint"
  }
}
```

Error codes:
- `UNAUTHORIZED` (401): Invalid or missing API key. Agent hint: `authenticate`
- `FORBIDDEN` (403): Key lacks required scope. Agent hint: `upgrade_scope`
- `NOT_FOUND` (404): Resource doesn't exist. Agent hint: `check_id`
- `BAD_REQUEST` (400): Invalid request body. Agent hint: `fix_request`
- `RATE_LIMITED` (429): Too many requests. Agent hint: `retry_after`
- `INSUFFICIENT_CREDITS` (402): Not enough credits. Agent hint: `purchase_credits`
- `OVER_QUOTA` (429): Monthly quota exceeded. Agent hint: `upgrade_plan`
- `INTERNAL_ERROR` (500): Server error. Agent hint: `retry`

---

## 10. Rate Limits

Rate limits by plan (validate endpoint):
- Free: 60 requests/minute
- Pro: 600 requests/minute
- Team: 1,500 requests/minute
- Business: 6,000 requests/minute

Monthly run quotas:
- Free: 1,000 runs/month
- Pro: 25,000 runs/month
- Team: 250,000 runs/month
- Business: 2,000,000 runs/month

Rate limit headers:
```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705312260
```

---

## 11. Idempotency

For validate calls, use the `X-Idempotency-Key` header:

```
POST /functions/v1/validate
Authorization: Bearer dg_...
X-Idempotency-Key: unique-request-id-12345
```

- Keys are cached for 24 hours
- Replay returns cached response without consuming credits
- Use deterministic keys based on request content

---

## Discovery Files

- `/llms.txt` - This concise overview
- `/llms-full.txt` - This complete documentation
- `/.well-known/ai-plugin.json` - Standard agent plugin manifest
- `/agents.json` - Structured capabilities for orchestrators
- `/functions/v1/openapi` - OpenAPI 3.0 specification
- `/functions/v1/backstop-manifest` - API discovery document

---

## Support

- Documentation: /docs