API Reference
Vectra exposes a REST API via ASP.NET Core Minimal APIs. Interactive API documentation is also available at /open-api when the server is running.
Authentication
All requests to management endpoints should include a valid agent JWT (see Tokens).
Authorization: Bearer <token>
Tokens
POST /tokens — Exchange credentials for JWT
Exchange an agent's ID and client secret for a JWT token.
Request
{
"agentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"clientSecret": "my-strong-secret"
}
Response 200 OK
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresAt": "2025-01-01T13:00:00Z"
}
Response 401 Unauthorized — invalid credentials.
Agents
Base path: /agents
GET /agents — List agents
| Query Param | Type | Default | Description |
|---|---|---|---|
page | int | 1 | Page number |
pageSize | int | 25 | Items per page |
Response 200 OK
{
"items": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "billing-agent",
"ownerId": "team-finance",
"status": "Active",
"policyName": "billing-policy",
"trustScore": 0.75
}
],
"page": 1,
"pageSize": 25,
"totalCount": 1
}
POST /agents — Register agent
Request
{
"name": "billing-agent",
"ownerId": "team-finance",
"clientSecret": "my-strong-secret"
}
Response 201 Created
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "billing-agent",
"clientSecret": "my-strong-secret"
}
PUT /agents/{agentId}/policy — Assign policy
Request
{ "policyName": "billing-policy" }
Response 200 OK
DELETE /agents/{agentId} — Delete agent
Response 200 OK
Policies
Base path: /policies
GET /policies — List policies
| Query Param | Type | Default |
|---|---|---|
page | int | 1 |
pageSize | int | 25 |
Response 200 OK
{
"items": [
{
"name": "billing-policy",
"description": "Governs the billing agent",
"owner": "team-finance",
"default": "Deny",
"ruleCount": 3
}
],
"page": 1,
"pageSize": 25,
"totalCount": 1
}
GET /policies/{name} — Get policy details
Response 200 OK
{
"name": "billing-policy",
"description": "Governs the billing agent",
"owner": "team-finance",
"default": "Deny",
"rules": [
{
"name": "block-delete",
"priority": 100,
"effect": "Deny",
"conditions": [
{ "field": "input.method", "operator": "eq", "value": "DELETE" }
]
}
]
}
Response 404 Not Found
Proxy
ANY /proxy/{url} — Proxy a request
GET /proxy/https://api.example.com/resource
Authorization: Bearer <agent-token>
| Status | Description |
|---|---|
| Upstream status | Request was allowed and forwarded. Returns upstream response. |
202 Accepted | Request intercepted — HITL review required. Location header set. |
401 Unauthorized | Missing or invalid agent token |
403 Forbidden | Agent is revoked or policy denied the request |
429 Too Many Requests | Rate limit exceeded |
503 Service Unavailable | Circuit breaker open for upstream host |
Human-in-the-Loop
Base path: /hitl
GET /hitl — List pending HITL requests
Response 200 OK
[
{
"id": "abc-123",
"method": "DELETE",
"url": "https://api.example.com/users/all",
"reason": "High risk score: 0.92",
"agentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"timestamp": "2025-01-01T12:00:00Z",
"expiresAt": "2025-01-01T13:00:00Z"
}
]
GET /hitl/{id} — Get HITL request status
Response 200 OK
{
"id": "abc-123",
"status": "Pending",
"pending": { ... }
}
Response 404 Not Found
POST /hitl/{id}/approve — Approve request
Request
{ "comment": "Approved by ops team" }
Response 200 OK — upstream response proxied back.
Response 404 Not Found — expired or not found.
POST /hitl/{id}/deny — Deny request
Request
{ "comment": "Not authorised" }
Response 200 OK
Response 404 Not Found
Health Check
GET /health
Response 200 OK
{
"status": "Healthy",
"healthCheckDuration": "00:00:00.0123456"
}
Response 503 Service Unavailable — one or more health checks are unhealthy.
OpenAPI / Swagger
Interactive API documentation is available at /open-api when the server is running. The raw specification is at /open-api/vectra/specifications.json.