Skip to main content
The WAVIS API is a versioned REST service over HTTPS+JSON. Everything is under /api/v1/.

​
Base URL

https://api.wavis.xyz

​
Endpoint groups

Authentication

API keys, RBAC, brute-force protection

Health

Service status and dependency checks

Keys

FHE key generation, upload, deletion

TFHE

Boolean gate evaluation (NAND, AND, OR, XOR, MUX)

Compute

CKKS arithmetic (add, multiply, matmul, bootstrap)

Webhooks

Async event delivery with HMAC signing

Billing

Subscriptions, invoices, budget caps

​
Conventions

​
Authentication

Every request needs a Bearer token: 
Authorization: Bearer wvs_live_<32-hex>
The unauthenticated exceptions are:
  • GET /api/v1/health — public liveness probe
  • GET /api/v1/models — list of available FHE-LLM models
  • GET /api/v1/tfhe/pricing — gate pricing table
  • POST /api/v1/onboarding/temp-key — issue trial key
  • POST /api/v1/billing/stripe_webhook — signature-verified Stripe events
See Authentication for full details.

​
Content type

Request and response bodies are JSON unless noted. Empty bodies return either 204 No Content or 429 Too Many Requests. 
Content-Type: application/json
Accept: application/json

​
HTTP verbs

VerbUsed for
GETFetch resources, list endpoints
POSTCreate resources, run computations
PATCHPartial update (e.g. webhook URL)
DELETERemove resources
PUT is intentionally not used — all updates are PATCH.

​
Status codes

CodeMeaning
200OK
201Created
204No Content
400Bad Request — schema or validation failure
401Unauthorized — missing/invalid auth
402Payment Required — quota exhausted, no overage allowed
403Forbidden — auth valid, role insufficient
404Not Found
409Conflict
413Payload Too Large (>40 MB eval keys, >2 MB ciphertexts)
422Unprocessable Entity — JSON schema mismatch
429Too Many Requests — rate limit
500Internal Server Error
502Bad Gateway — upstream (Stripe/Redis) unavailable
503Service Unavailable — maintenance

​
Error shape

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "field 'preset' must be one of fast_128, standard_128, conservative_128",
    "request_id": "req_a1b2c3d4",
    "documentation_url": "https://docs.wavis.xyz/api-reference/tfhe"
  }
}
request_id is the single most useful thing to include in support tickets.

​
Pagination

List endpoints use cursor pagination: 
GET /api/v1/keys?limit=20

{
  "items": [...],
  "next_cursor": "eyJvZmZzZXQiOiAyMH0=",
  "has_more": true,
  "total_count": 142
}
limit ranges 1–100 (default 20). The cursor is opaque base64 — pass it as-is to fetch the next page.

​
Idempotency

For mutating endpoints (POST/PATCH), include an Idempotency-Key header to safely retry: 
POST /api/v1/keys/upload
Idempotency-Key: client-uuid-v4-here
Replays within 24 h return the cached response.

​
Rate limit headers

Every response includes: 
X-RateLimit-Daily-Limit: 33000
X-RateLimit-Daily-Remaining: 31250
X-RateLimit-Daily-Reset: 1714435200
X-RateLimit-Monthly-Limit: 1000000
X-RateLimit-Monthly-Remaining: 980450
X-RateLimit-Monthly-Reset: 1717113600
When throttled (429): 
Retry-After: 42

​
Versioning

WAVIS follows semver on the path. Breaking changes go into /api/v2/. Within v1, we guarantee:
  • ✅ New endpoints may be added
  • ✅ New optional response fields may be added
  • ✅ New optional request fields may be added
  • ❌ Existing fields will not be renamed or removed
  • ❌ Existing required fields will not become optional
  • ❌ HTTP status codes for existing error conditions will not change
If we need to break compatibility, we’ll launch /api/v2/ and run both for at least 12 months.

​
OpenAPI spec

https://api.wavis.xyz/openapi.json    Machine-readable schema
https://api.wavis.xyz/redoc           Browsable HTML reference
https://api.wavis.xyz/docs            Swagger UI (try-it-now)
Generate clients with openapi-generator: 
openapi-generator-cli generate \
  -i https://api.wavis.xyz/openapi.json \
  -g go \
  -o ./wavis-go-client

​
SLA & uptime

TierUptime SLA
Free / PAYGBest effort
Starter / ProBest effort
Scale99.9% (max 8.7 h downtime/month)
EnterpriseCustom (typically 99.95%+)
Live status: status.wavis.xyz

​
Support