API reference

Authenticate server-to-server with credentials from your VoxCartAI dashboard. Never ship raw API keys in public front-end bundles or theme files. See how API keys are handled.

# PLACEHOLDER - base URL and headers pending product confirmation
Base URL: https://api.example.voxcartai.com/v1

Authorization: Bearer <API_KEY>
X-VoxCart-Agent-Id: <AGENT_ID>

• Where to put the key - Backend services, workers, and official plugins only.
• Transport - HTTPS only. Prefer short-lived request contexts over embedding long-lived keys in browsers.
• Rotation - Rotate from the dashboard if a secret may have leaked, then update every consumer.

Need credentials? Create an account.

Illustrative resource groups for custom clients. Paths and payloads below are placeholders pending the published OpenAPI / partner pack.

Session retention and recordings: voice recordings. Customer data principles: customer data.

Clients should treat limits as fair-use guardrails and back off on HTTP 429. Exact quotas and response headers are placeholders until product publishes production numbers.

• Default window - e.g. N requests per minute per API key (TBD).
• Burst - Short bursts may be allowed; do not hammer session-start endpoints.
• Headers (illustrative) - X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After.
• On 429 - Exponential backoff with jitter; surface a human handoff for shopper-facing flows if retries fail.

Sample shapes only - replace with product-approved examples before treating as contractual API behavior.

Start a session (placeholder)

POST /v1/sessions
Authorization: Bearer <API_KEY>
X-VoxCart-Agent-Id: <AGENT_ID>
Content-Type: application/json

{
  "channel": "widget",
  "storefrontUrl": "https://example-store.com/product/sku-123",
  "customerId": "store-customer-42"
}

Success response (placeholder)

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "sess_placeholder_01",
  "status": "active",
  "agentId": "<AGENT_ID>",
  "createdAt": "2026-06-01T12:00:00Z"
}

Error response (placeholder)

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or revoked API key",
    "requestId": "req_placeholder_01"
  }
}

New to the product? Start with getting started.