API Reference

Complete REST API documentation for the Valensys AI FinOps Control Plane. All endpoints use JSON for requests and responses, with authentication via Bearer tokens or HMAC signatures.

Authentication

Bearer Token (Admin UI)

curl https://gateway.valensys.ai/v1/policies \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

HMAC Signature (Internal Services)

curl https://router.valensys.ai/v1/route \
  -H "Authorization: Bearer YOUR_INTERNAL_TOKEN" \
  -H "x-request-id: req_123" \
  -H "x-feature: support_gpt" \
  -H "x-team: customer_success"

API Services

Policy Gateway API

https://gateway.valensys.ai

Enforce budgets, latency SLOs, quality thresholds, and residency constraints before routing requests.

POST

/v1/chat/completions

Route LLM request with policy enforcement

GET

/v1/policies

List all policies (requires admin role)

POST

/v1/policies

Create or update policy (Ed25519 signed)

GET

/v1/policies/:id/audit

Get policy version history

Router API

https://router.valensys.ai

Intelligent multi-provider routing optimized for cost, latency, and residency.

POST

/v1/route

Route request to optimal provider

GET

/v1/providers

List available providers and models

GET

/metrics

Prometheus metrics (provider share, latency)

Savings Ledger API

https://ledger.valensys.ai

Append-only audit trail of cost savings with cryptographic signatures.

POST

/append

Append ledger entry (internal only)

GET

/v1/baseline/:feature

Get locked baseline configuration

GET

/v1/ledger/export.json

Export ledger as JSON

GET

/v1/ledger/export.csv

Export ledger as CSV (signed)

GET

/v1/ledger/weekly

Get weekly savings summary

Compliance API

https://compliance.valensys.ai

Residency enforcement, PII detection, and evidence pack generation.

POST

/v1/classify

Classify residency and detect PII

GET

/v1/violations

List policy violations (filterable)

GET

/v1/evidence/export

Export evidence pack (ZIP with SHA256 manifest)

GET

/v1/evidence/verify

Verify evidence signature (Ed25519)

GET

/v1/public_keys

Get current and next public keys (rotation)

Finance API

https://finance.valensys.ai

Cost attribution, forecasting, and chargeback reporting.

GET

/v1/pricebook

Get current pricebook (with filters)

POST

/v1/pricebook

Create pricebook version (admin only)

GET

/v1/finance/attribution

Get cost attribution by feature/team/user

GET

/v1/finance/forecast

Get moving-average cost forecast

GET

/v1/finance/chargeback.csv

Export signed chargeback report

Semantic Cache API

https://cache.valensys.ai

pgvector-backed semantic caching with TTL and policy-scoped invalidation.

POST

/v1/cache/lookup

Check cache for similar prompt (embedding similarity)

POST

/v1/cache/store

Store response in cache

POST

/v1/cache/invalidate_policy

Invalidate cache for policy fingerprint

Common Request Headers

Header	Description	Required
Authorization	Bearer token for authentication	Yes
x-request-id	Unique request ID for tracing (auto-generated if not provided)	No
x-feature	Feature identifier for cost attribution	Recommended
x-team	Team identifier for cost attribution	Recommended
x-residency	Data residency requirement (e.g., "EU", "US")	No

Error Responses

All errors follow RFC 7807 Problem Details format:

{
  "type": "https://valensys.ai/errors/budget-exceeded",
  "title": "Budget Exceeded",
  "status": 429,
  "detail": "Monthly budget of €5000 for feature 'support_gpt' exceeded.",
  "instance": "/v1/chat/completions",
  "request_id": "req_abc123",
  "timestamp": "2025-10-01T14:30:00Z"
}

Rate Limits

Standard Plan: 1,000 requests per minute per account

Enterprise Plan: Custom rate limits negotiable

Rate limit headers are returned in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

OpenAPI Specification

The complete OpenAPI 3.0 specification for automated client generation and API testing will be available soon.

Contact support@valensys.ai for early access