API Reference

This is the canonical public contract for ValGuard. The live spec is served directly by the API at the quickstart and can be fetched from https://api.valguard.ai/openapi.json.

Find endpoints fast

Use the endpoint index for a complete route map, then jump to payload examples for request and response shapes.

Endpoint index Data payload cheat-sheet Download OpenAPI 3.2 JSON

Authentication

API keys, bearer auth, scopes, and dashboard key lifecycle.

Errors

Unified error envelopes and the status codes clients must handle.

Completions

OpenAI-compatible request and response contract for /v1/chat/completions.

Operations

Health checks and the public OpenAPI discovery endpoint.

Integration patterns

Choose the integration style that matches your stack. All paths use the same response envelope and validation headers.

Direct API call

Best for server apps, workers, and low-level control.

POST /v1/chat/completions
X-VG-Api-Key: ...
X-VG-Agent: default

Flow routing

Use playbook orchestration with deterministic branch logic.

POST /v1/chat/completions
X-VG-Api-Key: ...
X-VG-Flow: invoice-triage

Dashboard management API

Session-auth routes for workspace configuration and defaults.

GET/PATCH /api/org/features
Cookie: session=...

Common integration scenarios

Copy-paste flows for the most common production paths.

Backend request handler

Synchronous server call with full validation headers.

POST https://api.valguard.ai/v1/chat/completions
Headers:
  X-VG-Api-Key: vg_live_...
  X-VG-Agent: support-default
Body:
  {
    "model": "gpt-4o-mini",
    "messages": [{"role":"user","content":"Summarize order"}],
    "temperature": 0.2
  }

Read headers:
  X-VG-Request-Id
  X-VG-Validation-Status

Cron / batch job

Nightly processing with deterministic flow routing.

for each record in batch:
  POST https://api.valguard.ai/v1/chat/completions
  Headers:
    X-VG-Api-Key: vg_live_...
    X-VG-Flow: invoice-triage
  Body:
    {
      "model": "openai/gpt-4o-mini",
      "messages": [{"role":"user","content":"...record payload..."}]
    }

on 429/503:
  exponential backoff + retry

Workspace defaults workflow

Configure org-level self-heal defaults used by inherited agents.

GET /api/org/features

PATCH /api/org/features
{
  "self_heal_preset_default": "custom",
  "self_heal_rules_default": {
    "tier1:fix_trailing_comma": true,
    "tier2:cast_numeric": true
  }
}

Result:
  agents with preset=inherit use these defaults

SDK guides

Complete quick links for Python, Node.js, Go, and C#. Each SDK covers API auth headers, agent or flow routing, and validation metadata parsing.

SDK	Install	Quick docs	Package source
Python	`pip install valguard`	Python quickstart	packages/sdk-python
Node.js	`npm install @valguard/sdk-node`	Node quickstart	packages/sdk-node
Go	`go get github.com/valguard/valguard/packages/sdk-go`	Go quickstart	packages/sdk-go
C#	`dotnet add package ValGuard.Sdk`	C# quickstart	packages/sdk-csharp

SDK capabilities checklist

Injects ValGuard auth headers and default routing metadata.
Supports OpenAI-compatible request payloads for chat completions.
Parses validation metadata from response headers and error envelopes.
Can be used with official OpenAI SDK flow (Python/Node) or standalone helper calls.

Recommended SDK path

Start in SDK packages to install your language client.
Copy the language snippet from Python, Node, Go, or C#.
Return to this page for endpoint and response shape details.

Retry pseudocode by SDK language

Use this skeleton in your app-level wrapper around SDK calls.

Python

attempt = 0
while attempt < 5:
    try:
        return sdk.chat_completions(payload)
    except ApiError as err:
        if err.status not in (429, 503):
            raise
        sleep(min(10, 0.5 * (2 ** attempt)) + jitter_ms(0, 250) / 1000)
        attempt += 1
raise RetryExhausted()

Node.js

for (let attempt = 0; attempt < 5; attempt++) {
  try {
    return await sdk.chatCompletions(payload);
  } catch (err) {
    if (![429, 503].includes(err.status)) throw err;
    const delayMs = Math.min(10_000, 500 * 2 ** attempt) + jitter(0, 250);
    await wait(delayMs);
  }
}
throw new Error("retry_exhausted");

Go

for attempt := 0; attempt < 5; attempt++ {
    out, err := client.ChatCompletions(ctx, payload)
    if err == nil {
        return out, nil
    }
    if !isRetryable(err, 429, 503) {
        return nil, err
    }
    sleep(backoff(attempt, 500*time.Millisecond, 10*time.Second) + jitter(250*time.Millisecond))
}
return nil, errors.New("retry_exhausted")

C#

for (var attempt = 0; attempt < 5; attempt++)
{
    try { return await sdk.ChatCompletionsAsync(payload); }
    catch (ApiException ex) when (ex.StatusCode is 429 or 503)
    {
        var delay = Math.Min(10000, 500 * (int)Math.Pow(2, attempt)) + Jitter(0, 250);
        await Task.Delay(delay, cancellationToken);
    }
}
throw new Exception("retry_exhausted");

SDK troubleshooting

Fast runbook for the most common production integration failures.

401 Unauthorized

API key missing, invalid, or sent in the wrong header.

Use exactly one: Authorization: Bearer VG_API_KEY or X-VG-Api-Key.
Confirm key belongs to the expected workspace.
Check key is active and not revoked in dashboard.

429 Too Many Requests

Rate or quota limit reached.

Read Retry-After when present.
Use exponential backoff with jitter.
Reduce burst concurrency in workers/cron jobs.

503 Service Unavailable

Temporary upstream or platform unavailability.

Retry with bounded exponential backoff.
Log X-VG-Request-Id for support and incident traces.
Fallback to queued processing when possible.

Recommended retry policy

Retry on: 429, 503
Max attempts: 5
Backoff: min(10s, base * 2^attempt) + jitter(0-250ms)
Non-retryable: 400, 401, 403, 404, 422

Structured error logging fields

{
  "status": 429,
  "code": "rate_limited",
  "request_id": "from X-VG-Request-Id",
  "agent_or_flow": "support-default",
  "attempt": 2,
  "retry_after": "2"
}

Data load and returned data

What each endpoint expects on input and what it returns on success.

Endpoint	Data load (request)	Data returned (response)	Common statuses
`/v1/chat/completions`	Headers: `X-VG-Api-Key`, `X-VG-Agent` or `X-VG-Flow`. Body: `model`, `messages[]`, optional `stream`, `temperature`, `max_tokens`.	OpenAI-style completion: `id`, `choices[]`, `usage`. Response headers include `X-VG-Request-Id`, `X-VG-Validation-Status`.	200, 400, 401, 403, 404, 413, 429, 503
`/api/org/features` (GET)	Session-auth cookie, admin role.	`quarantine_payloads_enabled`, `self_heal_preset_default`, `self_heal_rules_default`.	200, 401, 403
`/api/org/features` (PATCH)	JSON patch for: `quarantine_payloads_enabled`, `self_heal_preset_default`, `self_heal_rules_default`.	Same shape as GET with normalized defaults.	200, 400, 401, 403
`/healthz`	No body.	Plain text liveness response.	200
`/readyz`	No body.	Plain text readiness response.	200, 503
`/openapi.json`	No body.	OpenAPI 3.2 JSON document.	200

Org features PATCH payload (new defaults)

{
  "quarantine_payloads_enabled": true,
  "self_heal_preset_default": "custom",
  "self_heal_rules_default": {
    "tier1:fix_trailing_comma": true,
    "tier1:fix_missing_comma": true,
    "tier2:cast_numeric": true
  }
}

Org features response shape

{
  "quarantine_payloads_enabled": true,
  "self_heal_preset_default": "custom",
  "self_heal_rules_default": {
    "tier1:fix_trailing_comma": true,
    "tier1:fix_missing_comma": true,
    "tier2:cast_numeric": true
  }
}

Endpoint index

Complete endpoint map for production use and dashboard management surfaces.

Public runtime API (API key auth)

These endpoints are part of the public contract and represented in OpenAPI.

Method	Path	Purpose	Body
POST	`/v1/chat/completions`	Validated chat completions	JSON request payload
GET	`/healthz`	Liveness probe	None
GET	`/readyz`	Readiness probe	None
GET	`/openapi.json`	Canonical API contract document	None

Workspace management API (dashboard session auth)

Used by the dashboard for CRUD and orchestration management. Requires active session cookies, not API key headers.

Area	Routes	Data operations
Agents	`/api/agents`, `/api/agents/{slug}`, `/api/agents/bulk-delete`	List, create, update, delete agents
Validators	`/api/agents/{slug}/validators`, `/history`, `/validation-summary`	Read and replace validator sets
Playbooks	`/api/orchestration/flows`, `/publish`, `/test`, `/import`	CRUD, publish, run tests, import/export
Templates	`/api/templates`, `/api/org/templates`, `/api/org/playbook-templates`	List, create, fork, submit, apply templates
Keys and org	`/api/keys`, `/api/org/`, `/api/dashboard/`	API keys, members, providers, usage and analytics

Data payload cheat-sheet

Copy-ready request shapes for common API operations.

Chat completion request

{
  "model": "openai/gpt-4o-mini",
  "messages": [
    {"role": "system", "content": "You are a safe assistant."},
    {"role": "user", "content": "Summarize this payload"}
  ],
  "stream": false,
  "temperature": 0.2,
  "max_tokens": 512
}

Agent create request (dashboard API)

{
  "slug": "invoice-agent",
  "name": "Invoice extraction",
  "preset": "standard",
  "settings": {
    "default_provider": "openai",
    "default_model": "gpt-4o-mini",
    "max_reasks": 1,
    "shadow_mode": true,
    "self_heal_preset": "safe"
  }
}

Validators replace request

{
  "validators": [
    {
      "name": "required_fields",
      "enabled": true,
      "priority": 10,
      "severity": "error",
      "on_fail": "block",
      "params": {"fields": ["invoice_id", "total"]}
    }
  ]
}

Playbook create request

{
  "name": "Invoice triage flow",
  "slug": "invoice-triage",
  "description": "Parse invoice and route for approval",
  "graph": {
    "nodes": [],
    "edges": []
  }
}

Authentication

Use a production API key from the dashboard or the X-VG-Api-Key header. Keys are masked in the UI, auditable, and revocable.

Errors

Every non-2xx response follows a structured JSON error envelope with a machine-readable code and a stable message.

Completions

The public completion endpoint is POST /v1/chat/completions and accepts OpenAI-style messages, with ValGuard validation and observability headers.

Request body parameters

Common fields include model, messages, stream, temperature, and max_tokens.

Field	Type	Required	Notes
`model`	string	Yes	Target model identifier such as `gpt-4o-mini`.
`messages`	array	Yes	OpenAI-style chat turns with `role` and `content`.
`stream`	boolean	No	Set to `true` for streaming responses.
`temperature`	number	No	Controls randomness for the generation step.
`max_tokens`	integer	No	Maximum output length for the completion.

{
  "model": "gpt-4o-mini",
  "messages": [{"role": "user", "content": "Summarize this payload"}],
  "stream": false,
  "temperature": 0.2,
  "max_tokens": 512
}

Authentication headers

Send your API key in the X-VG-Api-Key header, or use a bearer token if your deployment is configured for that scheme.

curl -X POST https://api.valguard.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-VG-Api-Key: YOUR_API_KEY" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello"}]}'

Example request

curl -X POST https://api.valguard.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-VG-Api-Key: YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Example response

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help?"
    },
    "finish_reason": "stop"
  }]
}

Operations

The API exposes GET /healthz, GET /readyz, and GET /openapi.json for health and discovery.

Response status codes

Successful requests return 200 or 202 for streamed or accepted work, while validation and auth failures use 400, 401, and 422.

200 OK

Completed successfully.

202 Accepted

Accepted for asynchronous or streaming work.

400 Bad Request

Malformed payload or invalid structure.

401 Unauthorized

Missing or invalid API key.

422 Unprocessable Entity

Validation failed for the submitted content.

Public endpoints

The canonical contract lives in the live OpenAPI document at https://api.valguard.ai/openapi.json.

Download OpenAPI 3.2 JSON

POST/v1/chat/completions

OpenAI-compatible chat completion endpoint. Accepts a JSON body with model, messages, and optional stream, temperature, and max_tokens.

GET/healthz

Returns the service health status for probes and uptime checks.

GET/readyz

Returns readiness for load balancer and deployment health checks.

GET/openapi.json

Returns the canonical public OpenAPI 3.2 document for clients and SDK generators.

API Reference

Find endpoints fast

Authentication

Errors

Completions

Operations

On this page

Integration patterns

Direct API call

Flow routing

Dashboard management API

Common integration scenarios

Backend request handler

Cron / batch job

Workspace defaults workflow

SDK guides

SDK capabilities checklist

Recommended SDK path

Retry pseudocode by SDK language

Python

Node.js

Go

C#

SDK troubleshooting

401 Unauthorized

429 Too Many Requests

503 Service Unavailable

Recommended retry policy

Structured error logging fields

Data load and returned data

Org features PATCH payload (new defaults)

Org features response shape

Endpoint index

Public runtime API (API key auth)

Workspace management API (dashboard session auth)

Data payload cheat-sheet

Chat completion request

Agent create request (dashboard API)

Validators replace request

Playbook create request

Authentication

Errors

Completions

Request body parameters

Authentication headers

Example request

Example response

Operations

Response status codes

Public endpoints