API Reference

The Veto API is a REST API served by the FastAPI backend. All endpoints are prefixed with /api/v1.

Authentication

Most endpoints require authentication via one of:

Bearer token (JWT) — obtained from the login endpoint, used by the dashboard
API key — created in the dashboard, passed as Authorization: Bearer <key>

Evaluation

Evaluate a tool call (hooks)

POST /api/v1/hooks/evaluate

Called by the Claude Code plugin. Evaluates a tool call against the org's rules and AI scoring.

Request body:

{
  "session_id": "abc-123",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  },
  "cwd": "/home/user/project",
  "permission_mode": "default"
}

Response:

{
  "decision": "allow",
  "reasoning": "Matched whitelist rule: Allow test commands",
  "rule_id": "uuid",
  "score": null,
  "latency_ms": 12
}

Possible decision values: allow, deny, ask

Evaluate a tool call (proxy)

POST /api/v1/proxy/evaluate

Called by the LiteLLM guardrail. Same evaluation logic, different authentication (uses the LiteLLM API key).

Request body:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /"
  },
  "response_id": "resp_abc123",
  "model": "claude-sonnet-4-20250514"
}

Response:

{
  "decision": "deny",
  "reasoning": "Matched blacklist rule: Block dangerous shell commands",
  "rule_id": "uuid"
}

Rules

List rules

GET /api/v1/rules

Returns all rules for the authenticated org, ordered by priority descending.

Create a rule

POST /api/v1/rules

{
  "rule_type": "blacklist",
  "tool_pattern": "Bash",
  "content_pattern": "rm\\s+-rf",
  "description": "Block rm -rf",
  "priority": 100,
  "enabled": true
}

Update a rule

PUT /api/v1/rules/{id}

Accepts the same fields as create. Only provided fields are updated.

Delete a rule

DELETE /api/v1/rules/{id}

Bulk operations

POST /api/v1/rules/bulk

Create or update multiple rules at once.

Simulate

POST /api/v1/rules/simulate

Test a tool call against the current rules without logging an audit event.

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

Import / Export

GET /api/v1/rules/export
POST /api/v1/rules/import

Export rules as JSON for backup or sharing. Import replaces all rules.

Sessions

List sessions

GET /api/v1/sessions?active_only=false

Returns sessions for the authenticated org. Automatically cleans up expired whitelists and stale sessions.

Query parameters:

Parameter	Type	Description
`active_only`	bool	Only return sessions without an `ended_at` (default false)

Response:

[
  {
    "id": "uuid",
    "session_id": "claude-session-abc123",
    "started_at": "2026-03-12T10:00:00Z",
    "ended_at": null,
    "permission_mode": "default",
    "api_key_id": "uuid",
    "has_whitelist": true
  }
]

Rename a session

PATCH /api/v1/sessions/{session_id}

Update the session's display name.

Delete a session

DELETE /api/v1/sessions/{session_id}

Whitelist a session

POST /api/v1/sessions/{session_id}/whitelist

Temporarily allow all tool calls within a session for a specified duration.

Request body:

{
  "duration_minutes": 240
}

duration_minutes must be between 1 and 1440 (24 hours).

Response:

{
  "rule_id": "uuid",
  "session_id": "claude-session-abc123",
  "expires_at": "2026-03-12T14:00:00Z",
  "duration_minutes": 240
}

Returns 409 Conflict if the session already has an active whitelist.

Revoke a session whitelist

DELETE /api/v1/sessions/{session_id}/whitelist

Immediately removes the whitelist. Subsequent tool calls go through normal rule evaluation.

Returns 204 No Content on success.

Audit

List audit events

GET /api/v1/audit?limit=50&offset=0

Query parameters:

Parameter	Type	Description
`limit`	int	Max results (default 50)
`offset`	int	Pagination offset
`session_id`	string	Filter by session
`tool_name`	string	Filter by tool name
`decision`	string	Filter by decision (allow/deny/ask)
`from`	datetime	Start date
`to`	datetime	End date

Audit stats

GET /api/v1/audit/stats

Returns aggregated statistics (decision counts, top tools, average latency).

Export audit log

GET /api/v1/audit/export?format=csv

Export the audit log as CSV or JSON.

Auth

Register

POST /api/v1/auth/register

{
  "email": "you@company.com",
  "password": "your-password",
  "org_name": "Your Company"
}

Returns a JWT access token.

POST /api/v1/auth/login

{
  "email": "you@company.com",
  "password": "your-password"
}

Returns a JWT access token.

Get current user

GET /api/v1/auth/me

Returns the authenticated user's profile and org info.

Accept invite

POST /api/v1/auth/accept-invite

Accept a team invitation using the invite token.

Change password

PUT /api/v1/auth/me/password

Change email

PUT /api/v1/auth/me/email

Team

List members

GET /api/v1/team/members

Invite a member

POST /api/v1/team/invites

{
  "email": "colleague@company.com",
  "role": "member"
}

Roles: admin, member, viewer

List pending invites

GET /api/v1/team/invites

Revoke an invite

DELETE /api/v1/team/invites/{invite_id}

Change member role

PUT /api/v1/team/members/{user_id}/role

Remove a member

DELETE /api/v1/team/members/{user_id}

Transfer ownership

POST /api/v1/team/transfer-ownership

Settings

API Keys

GET /api/v1/settings/api-keys
POST /api/v1/settings/api-keys
DELETE /api/v1/settings/api-keys/{id}

Scoring config

GET /api/v1/settings/scoring
PUT /api/v1/settings/scoring

Configure AI scoring (enable/disable, model, thresholds, fail policy).

Scoring cache

GET /api/v1/settings/scoring/cache
DELETE /api/v1/settings/scoring/cache

Get cache statistics or clear the scoring cache.

API key usage

GET /api/v1/settings/api-keys/{key_id}/usage

Get usage statistics for a specific API key.

Billing

Get subscription

GET /api/v1/billing/subscription

Returns current plan, usage, and subscription status.

Create checkout session

POST /api/v1/billing/checkout

Creates a Stripe checkout session for upgrading plans. Admin only.

Create billing portal session

POST /api/v1/billing/portal

Creates a Stripe billing portal session for managing payment methods and invoices. Admin only.

LLM Proxy Settings

Get proxy config

GET /api/v1/settings/litellm

Returns the current LLM proxy configuration. Admin only.

Enable proxy

POST /api/v1/settings/litellm/enable

Enable the LLM proxy in passthrough or BYOK mode. Admin only.

Disable proxy

POST /api/v1/settings/litellm/disable

Rotate virtual key

POST /api/v1/settings/litellm/rotate-key

Rotate the organization's virtual proxy key. Admin only.

Get user proxy key

GET /api/v1/settings/litellm/proxy-keys

Get the current user's proxy key (passthrough mode).

Create proxy key

POST /api/v1/settings/litellm/proxy-keys

Create a proxy key for the current user.

Delete proxy key

DELETE /api/v1/settings/litellm/proxy-keys

Regenerate proxy key

POST /api/v1/settings/litellm/proxy-keys/regenerate

Scoring Usage

Get scoring costs

GET /api/v1/scoring-usage/costs

Returns AI scoring cost breakdown and usage statistics.

Admin Actions

List admin actions

GET /api/v1/admin-actions

Returns the dashboard admin activity log (rule changes, config updates, member actions, etc.). Admin only.

Health

GET /health

Returns server status and build SHA. No authentication required.

{
  "status": "ok",
  "build_sha": "abc1234"
}

API Reference

Authentication

Evaluation

Evaluate a tool call (hooks)

Evaluate a tool call (proxy)

Rules

List rules

Create a rule

Update a rule

Delete a rule

Bulk operations

Simulate

Import / Export

Sessions

List sessions

Rename a session

Delete a session

Whitelist a session

Revoke a session whitelist

Audit

List audit events

Audit stats

Export audit log

Auth

Register

Login

Get current user

Accept invite

Change password

Change email

Team

List members

Invite a member

List pending invites

Revoke an invite

Change member role

Remove a member

Transfer ownership

Settings

API Keys

Scoring config

Scoring cache

API key usage

Billing

Get subscription

Create checkout session

Create billing portal session

LLM Proxy Settings

Get proxy config

Enable proxy

Disable proxy

Rotate virtual key

Get user proxy key

Create proxy key

Delete proxy key

Regenerate proxy key

Scoring Usage

Get scoring costs

Admin Actions

List admin actions

Health