Using the API

The Zquence API is plain JSON over HTTPS. You can use any HTTP client. The important part is to keep authentication and error handling in one backend helper.

Required headers

Every server-to-server request needs:

x-api-key: pk_test_...
x-api-secret: sk_test_...
Content-Type: application/json

Use test keys with the sandbox environment and live keys with production.

Recommended backend helper

const BASE_URL = process.env.ZQUENCE_BASE_URL ?? "https://api.zquence.ai/v1";

type ZquenceError = {
  type: string;
  code: string;
  message: string;
  requestId?: string;
};

export async function zquence<T>(
  path: string,
  init: RequestInit = {},
): Promise<T> {
  const res = await fetch(`${BASE_URL}${path}`, {
    ...init,
    headers: {
      "x-api-key": process.env.ZQUENCE_PUBLIC_KEY!,
      "x-api-secret": process.env.ZQUENCE_SECRET_KEY!,
      "Content-Type": "application/json",
      ...(init.headers ?? {}),
    },
  });

  const body = await res.json();

  if (!res.ok) {
    const err = body.error as ZquenceError;
    throw Object.assign(new Error(err.message), {
      ...err,
      requestId: err.requestId ?? res.headers.get("x-request-id"),
    });
  }

  return body as T;
}

// Example
const tenant = await zquence("/tenants/me");

import os
import requests

BASE_URL = os.getenv("ZQUENCE_BASE_URL", "https://api.zquence.ai/v1")

def zquence(method, path, json=None, idempotency_key=None):
    headers = {
        "x-api-key": os.environ["ZQUENCE_PUBLIC_KEY"],
        "x-api-secret": os.environ["ZQUENCE_SECRET_KEY"],
        "Content-Type": "application/json",
    }
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key

    res = requests.request(
        method,
        f"{BASE_URL}{path}",
        headers=headers,
        json=json,
        timeout=30,
    )
    body = res.json()

    if not res.ok:
        error = body.get("error", {})
        raise RuntimeError(
            f"{error.get('code', 'api_error')}: {error.get('message', 'Request failed')}"
        )

    return body

# Example
tenant = zquence("GET", "/tenants/me")

Create resources safely

For create/update actions that your system might retry, send an Idempotency-Key.

Node.js

const user = await zquence("/tenants/add-user", {
  method: "POST",
  headers: {
    "Idempotency-Key": `user_${customer.id}`,
  },
  body: JSON.stringify({
    name: customer.name,
    email: customer.email,
    phone: customer.phone,
  }),
});

Use a stable key from your own system, such as an order ID, user ID, or job ID.

Handle errors by code

Errors use a stable shape:

{
  "error": {
    "type": "validation_error",
    "code": "email_invalid",
    "message": "Email is invalid",
    "param": "email",
    "requestId": "req_01HX3ZE..."
  }
}

In your app:

Show validation errors next to the relevant field.
Retry 429 and 5xx errors with backoff.
Log requestId for support.
Do not retry validation or permission errors without changing the request.

Production checklist

Store keys in a secrets manager.
Use separate keys for test and live.
Add timeouts to all HTTP calls.
Add Idempotency-Key to retried POST requests.
Verify all webhooks before processing them.
Store webhook event IDs so duplicate deliveries do not double-process work.

Where to go next

Authentication

Key types, rotation, and where secrets belong.

Errors

Error codes and retry behavior.

Idempotency

Make retries safe.

API reference

Endpoint-by-endpoint details.

Start here

Integration basics

Required headers

Recommended backend helper

Create resources safely

Handle errors by code

Production checklist

Where to go next

Authentication

Errors

Idempotency

API reference

​Required headers

​Recommended backend helper

​Create resources safely

​Handle errors by code

​Production checklist

​Where to go next

Authentication

Errors

Idempotency

API reference

Required headers

Recommended backend helper

Create resources safely

Handle errors by code

Production checklist

Where to go next