API Docs — AgentWatch by Iterate.ai

Authentication

Two Authentication Methods

API Key (Bearer) — For LLM endpoints (/v1/*), pass your tenant API key as Authorization: Bearer <api-key>.

JWT Token — For Admin endpoints (/api/*), login via POST /api/auth/login to receive a JWT valid for 24 hours.

POST /api/auth/login User login — get JWT token

Authenticate a user and receive a JWT token. Include the token in subsequent admin API requests as Authorization: Bearer <token>.

Request Body

Field	Type	Description
email*	string	User's email address
password*	string	User's password

curl -X POST http://localhost:8787/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "your-password"}'

200 Returns JWT token 401 Invalid credentials 423 Account locked

GET /api/auth/me Get current user JWT

Returns the authenticated user's profile, organization, and role information.

200 User object 401 Unauthorized

Rate Limiting

Sliding Window Algorithm

Default: 1,000 tokens/minute with a refill rate of 100 tokens/second.

Configurable per tenant. Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

When exceeded: HTTP 429 Too Many Requests with a Retry-After header.

Error Codes

Code	Meaning	Common Cause
400	Bad Request	Invalid request body or DLP policy violation
401	Unauthorized	Missing or invalid API key / JWT token
403	Forbidden	Insufficient role permissions
404	Not Found	Resource doesn't exist
423	Locked	Account locked due to failed login attempts
429	Too Many Requests	Rate limit exceeded for this tenant
402	Payment Required	Budget exceeded for this tenant/team
502	Bad Gateway	Upstream LLM provider error

Chat Completions

OpenAI Compatible

POST /v1/chat/completions Create a chat completion API Key

Creates a chat completion. Fully compatible with the OpenAI Chat Completions API — existing integrations work with a base URL change only. Set stream: true for SSE streaming. Requests are automatically scanned by DLP before forwarding to providers.

Request Body

Field	Type	Description
model*	string	Model ID (e.g., gpt-4o, claude-3-5-sonnet-20241022)
messages*	array	Array of message objects with role and content
temperature	number	Sampling temperature 0–2 (default: 1)
max_tokens	integer	Maximum tokens in the response
stream	boolean	Enable SSE streaming (default: false)
top_p	number	Nucleus sampling 0–1
stop	string\|array	Stop sequences

curl http://localhost:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-tenant-your-api-key" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello, how are you?"}
    ],
    "max_tokens": 1000
  }'

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8787/v1",
    api_key="sk-tenant-your-api-key"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello, how are you?"}
    ],
    max_tokens=1000
)
print(response.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:8787/v1',
  apiKey: 'sk-tenant-your-api-key',
});

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Hello, how are you?' },
  ],
  max_tokens: 1000,
});
console.log(response.choices[0].message.content);

Response Schema

idstringUnique completion ID

objectstring"chat.completion"

createdintegerUnix timestamp

modelstringActual model used

choicesarrayCompletion choices with message and finish_reason

usageobjectprompt_tokens, completion_tokens, total_tokens

200 Completion returned 400 DLP violation 401 Bad API key 402 Budget exceeded 429 Rate limited 502 Provider error

Models

OpenAI Compatible

GET /v1/models List available models API Key

Lists all available models across configured providers. Results are cached for 30 seconds.

curl http://localhost:8787/v1/models \
  -H "Authorization: Bearer sk-tenant-your-api-key"

200 Model list 401 Unauthorized

Auth Endpoints

Admin API

Admin API Authentication

All /api/* endpoints require a valid JWT token from POST /api/auth/login. Pass it as Authorization: Bearer <token>. Tokens expire after 24 hours.

POST /api/auth/logout Invalidate session JWT

Invalidates the current JWT session token.

200 Logged out

Providers

Admin API

GET /api/providers List all configured providers JWT

Returns all LLM providers with status, health information, and configuration. Scoped to the authenticated user's organization.

200 Provider list 401 Unauthorized

POST /api/providers Create a provider JWT

Adds a new LLM provider. Types: openai, anthropic, openrouter, google, custom.

Request Body

Field	Type	Description
name*	string	Display name
kind*	string	openai \| anthropic \| openrouter \| google \| custom
base_url*	string	Provider API base URL
priority	integer	Routing priority (default: 100)
enabled	boolean	Active state (default: true)

201 Provider created 400 Validation error

POST /api/providers/{id}/test Test provider connectivity JWT

Tests connectivity to a provider's API and returns latency and status.

200 Test result 404 Provider not found

API Keys

Admin API

Encrypted at Rest

All provider API keys are stored encrypted using AES-256-GCM. Keys are never returned in full from the API — only the first/last 4 characters are shown after creation.

GET /api/providers/{id}/keys List keys for a provider JWT

Returns all API keys configured for the given provider (masked — first/last 4 chars only).

200 Key list

POST /api/providers/{id}/keys Add a provider API key JWT

Adds and encrypts a new API key for a provider. Set concurrency and RPM limits.

Request Body

Field	Type	Description
key*	string	The plaintext API key (encrypted on write)
label	string	Friendly label for this key
concurrency_limit	integer	Max concurrent requests (default: 10)
rpm_limit	integer	Max requests per minute

201 Key added 400 Validation error

Tenants

Admin API

GET /api/tenants List all tenants JWT

Returns all API consumer entities (tenants) with their keys and usage stats. Optionally filter by team or status.

Query Parameters

Parameter	Type	Description
team_id	integer	Filter by team
status	string	active \| inactive \| suspended

200 Tenant list

POST /api/tenants Create a tenant JWT

Creates a new tenant with auto-generated API key, budget limits, and optional team assignment.

Request Body

Field	Type	Description
name*	string	Tenant display name
team_id	integer	Assign to a team
daily_budget	number	Daily spending limit in USD
monthly_budget	number	Monthly spending limit in USD
rate_limit	integer	Requests per minute limit

201 Tenant created with API key 400 Validation error

Usage & Analytics

Admin API

GET /api/usage Get usage records JWT

Returns usage records with tokens, costs, latencies, and DLP events. Paginated. Scoped to the organization.

Query Parameters

Parameter	Type	Description
start_date	string	ISO 8601 start date filter
end_date	string	ISO 8601 end date filter
tenant_id	integer	Filter by specific tenant
team_id	integer	Filter by team
page	integer	Page number (default: 1)
limit	integer	Records per page (default: 50, max: 1000)

200 Paginated usage records

GET /api/usage/summary Aggregated usage summary JWT

Returns aggregated totals: total requests, tokens, costs, and DLP events for the current period. Used by the dashboard.

200 Summary object

Health & Monitoring

GET /health System health check — no auth required

Returns overall system health including database connectivity, provider statuses, memory, and uptime. No authentication required.

curl http://localhost:8787/health

200 System healthy503 Degraded

GET /metrics Prometheus metrics endpoint

Prometheus-format metrics: request counts by tenant/model, latency histograms (P50/P95/P99), error rates, cache hit rates, and provider health gauges.

200 Prometheus text format

Knowledge Extraction (MCP)

Port 4000

MCP Server — Port 4000

The knowledge extraction server runs on port 4000 and exposes repository indexing, semantic search, and security scanning via the Model Context Protocol (MCP) and REST API.

POST /api/knowledge/repositories Index a repository JWT

Submits a repository for indexing. AgentWatch clones the repo, parses it with Tree-sitter, builds a symbol/dependency graph, and stores vectors in LanceDB for semantic search.

Request Body

Field	Type	Description
url*	string	Git repository URL (HTTPS)
branch	string	Branch to index (default: main)
run_security_scan	boolean	Run Semgrep + Trivy scan after index

202 Indexing job queued 400 Invalid URL

GET /api/knowledge/repositories/{id}/status Indexing job status JWT

Returns the current indexing status, progress percentage, file count, node/edge counts in the symbol graph, and any errors.

200 Status object

POST /api/knowledge/repositories/{id}/scan Run security scan JWT

Triggers a security scan on the indexed repository using Semgrep (SAST) and Trivy (infrastructure vulnerabilities). Returns findings with severity, file path, and rule IDs.

202 Scan started 404 Repository not indexed

API Documentation

Two Authentication Methods

Request Body

Sliding Window Algorithm

Request Body

Response Schema

Admin API Authentication

Request Body

Encrypted at Rest

Request Body

Query Parameters

Request Body

Query Parameters

MCP Server — Port 4000

Request Body