API & Automation

AgentWatch has two API surfaces: the inference API applications call, and an administrative API covering everything the console can do — so provisioning and policy can be driven from existing automation rather than clicked through a UI.

What does the inference API look like?

A full OpenAI-compatible surface — chat completions, legacy completions, embeddings, images, audio, batches, reranking, fine-tuning, moderations, and the complete Assistants, Files, and Vector Stores APIs — plus native Anthropic Messages, Google Vertex AI, Azure OpenAI, and Cohere V2 endpoints. Streaming is fully supported, with token counting and time-to-first-token measured on streamed responses.

Authentication accepts an API key (header or bearer), a session token, or a per-user key. Every request, on every path, passes through the full pipeline: authentication, rate limiting, DLP, guardrails, schema validation, routing, proxying, response processing, and event emission. There is no bypass route.

What does the administrative API cover?

The full governance surface: organizations, teams, and employees; provider and key management including efficacy testing and rotation; the model catalog and per-team model access; budgets and rate limits; DLP policies and custom recognizers; guardrail policies; gateway routes and plugins; schema definitions; MCP server registration and access-control lists; identity providers and SCIM configuration; roles and permissions; audit and usage queries; the event pipeline; webhooks; agent-fleet administration and identity policy; insider-risk indicators, cases, and enforcement policy; and observability queries behind the console dashboards.

Is there an API specification?

Yes. AgentWatch auto-publishes OpenAPI 3.x specifications for its gateway routes, with an interactive documentation page mounted in the product so developers can authorize and try endpoints against a live instance. Security schemes and scopes are included in the generated specification, so client generation and contract testing work without reverse-engineering the surface. A full API test collection with a CI runner ships alongside each release for smoke testing and post-upgrade acceptance.

How is machine-to-machine access handled?

Through scoped API keys with time-to-live and rotation hooks, rather than a separate client-credentials token endpoint. Keys carry the organization’s model access, budget, and DLP policy, can be scoped to an individual service or employee, and are revocable independently of any deployment change. Incoming OIDC tokens can additionally carry scopes, and gateway routes can require named scopes and reject calls missing them.

What is worth automating first?

• Employee lifecycle — provision and deprovision users, keys, and budgets from the HR system or directory, or hand it entirely to SCIM.
• Key rotation — rotate provider keys and user keys on a schedule as part of the existing secrets workflow.
• Policy as code — keep DLP policies, guardrail settings, gateway routes, and budgets in version control and apply them through the API, so a change is reviewed before it reaches production.
• Compliance export — pull audit records on a schedule into a SIEM or long-term archive.
• Cost reporting — export usage and cost by team, user, model, and task category into the finance system for chargeback.
• Incident response — pause an employee’s or an agent’s access, and open an insider-risk case, from an existing security-orchestration playbook.

Can the gateway be extended in code?

Yes. Sandboxed JavaScript plugins run at pre-request and post-response hooks, filtered by route pattern, with their own configuration and priority — used for organization-specific transformations, header injection, and custom checks. A separate enrichment pipeline can call external tools or APIs in response to configurable triggers, with a full audit trail of what each enrichment did.

How do I authenticate?

Two credential types, for two different jobs:

Credential	Use	Obtain
ak_… gateway key	Calling /v1/* — the LLM traffic itself	Employee Management, per employee or service account
Tenant-admin JWT	Calling /admin/* — configuration and reporting	POST /api/auth/login, 24h, revocable on logout

TOKEN=$(curl -s -X POST https://<your-agentwatch-host>/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@yourcompany.com","password":"…","slug":"<your-org-slug>"}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])')

curl -s https://<your-agentwatch-host>/admin/tenants/enhanced \
  -H "Authorization: Bearer $TOKEN"

slug scopes the login to one organization — the same token the console uses, so anything you can do in the UI you can do over the API.

What can I automate?

Task	Endpoint
Create an employee	POST /admin/tenants/enhanced
List employees and their keys	GET /admin/tenants/enhanced
Create or update a team	POST / PUT /admin/teams
Expose a model to a team	POST /admin/teams/:teamId/models
Set budgets	POST /admin/budget/limits/:tenantId
Read spend	GET /admin/budget/report
Classify a key (service / delegated identity)	PUT /admin/keys/identity-policy
Configure SSO	POST /api/admin/oauth2/providers
Read the audit trail	GET /admin/audit/trail
Export for compliance	GET /api/admin/audit/export
Gateway route export / import	GET /admin/gateway/routes/export

How do I provision a new employee end to end?

# 1. create them — this also mints their ak_ gateway key
curl -s -X POST https://<your-agentwatch-host>/admin/tenants/enhanced \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"Jane Doe","email":"jane.doe@acme.com"}'

# 2. give them a budget
curl -s -X POST https://<your-agentwatch-host>/admin/budget/limits/<tenantId> \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"dailyBudgetUSD": 10, "monthlyBudgetUSD": 200}'

# 3. confirm the key works
curl -s https://<your-agentwatch-host>/api/models/available -H "Authorization: Bearer ak_…"

For bulk provisioning use SCIM or CSV import rather than looping this — both handle joiner/leaver semantics that a create call does not.

Error handling that matters for scripts

• 401 on /admin/* — the JWT expired (24h) or was revoked. Re-login.
• 403 on /admin/* — the caller is not an admin of that organization. Cross-organization writes require a platform super-admin.
• 409 — the email already exists. Look it up rather than retrying.
• 429 — you are being rate limited like any other client; honour Retry-After.

Sources and references

• Route configuration: LLM gateway and routing.
• Administrative surface in context: Configuration and admin.