REST API

Overview

• Base URL: https://store-api.opsvanguard.com
• Auth: Bearer token (PAT or session JWT) in the Authorization header.
• Content type: application/json request and response bodies, both encrypted at the envelope layer.
• Versioning: all endpoints live under /api/v1/. Breaking changes ship behind a new path prefix; deprecations are announced 90 days in advance on the changelog.

Encryption

Every UI ↔ API call is wrapped at the envelope layer. The client fetches the rotating ML-KEM-768 public key, encapsulates a fresh AES-256 key, and encrypts the body. The server decrypts on receipt, processes the request, and encrypts the response back. TLS 1.3 still terminates the outer transport.

POST /api/v1/products HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json
{
  "encryptedPayload": {
    "kyberCiphertext": "...",
    "encryptedData":  "...",
    "nonce":          "...",
    "keyId":          "key_2026_04",
    "algorithm":      "ML-KEM-768+AES-256-GCM"
  }
}

The store UI handles this for you via the pqcFetch helper. Server-side and non-browser clients should use the same envelope format — sample implementations live in the documentation hub.

Endpoints

Rate limits

• Anonymous: 60 requests / 5 minutes per IP.
• Authenticated: 600 requests / 5 minutes per token.
• Agent invocation: per-agent limit, see each product's tier table.

429 responses include a Retry-After header. Production clients should implement exponential backoff with full jitter.

Error shape

{
  "error": {
    "code": "validation_failed",
    "message": "Field 'email' is required.",
    "fields": [{ "field": "email", "message": "Email is required" }],
    "requestId": "req_2026_04_29_abc123"
  }
}

Always log the requestId — it is the fastest way to get a response from support.

Webhooks

For long-running invocations and subscription events. Webhooks are signed with a per-tenant secret using HMAC-SHA-256 over the request body. The signature is sent inX-OpsVan-Signature with the format t=<timestamp>,v1=<hex>.