Partner API

Use the Partner API when your product team needs to onboard customer organizations programmatically while Quotaflow remains the visible API platform. The API is independent from dashboard user sessions and uses a partner machine token.

Base URL and authentication

export QUOTAFLOW_PARTNER_TOKEN="qfp_your_partner_token"
export QUOTAFLOW_PARTNER_BASE_URL="https://api.quotaflow.ai/partner/v1"

Send the token as a bearer token:

-H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN"

Create and rotate partner machine tokens in Dashboard → Partner → Automation Tokens. The full qfp_... token is shown once; store it in your product secret manager. Choose the smallest scope your automation needs:

Keep partner tokens separate from customer routing keys:

All write requests require an Idempotency-Key header. Use a stable key per operation, such as customer-cust_123-create-v1.

What the API does

The v1 automation loop is intentionally small:

1. Check partner funding with GET /funding.
2. Create or find a customer organization by your own external_customer_id.
3. Credit an auditable USD amount from partner funding into that customer organization's balance.
4. List allowed model groups for that customer.
5. Create a qf_... customer API key bound to the customer organization balance.
6. Read balance and usage for automation, support, and alerts.

Quotaflow does not manage your end-customer pricing, plans, taxes, invoices, or multi-currency settlement. If you want a fully custom commercial layer, build it in your own product and use the Quotaflow customer API key behind it.

Funding

curl "$QUOTAFLOW_PARTNER_BASE_URL/funding" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN"

Example response:

{
  "code": 0,
  "message": "success",
  "data": {
    "reseller_id": 42,
    "available_funding_usd": 250.0,
    "reserved_allocations_usd": 100.0,
    "outstanding_usage_usd": 12.5,
    "top_up_url": "https://app.quotaflow.ai/billing"
  }
}

If you need more funds, create a top-up action URL:

curl -X POST "$QUOTAFLOW_PARTNER_BASE_URL/funding/top-up-sessions" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN" \
  -H "Idempotency-Key: topup-100-2026-07-02" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd":100}'

Create or find a customer organization

Use your own stable customer id in the URL. Repeating the same request with the same external_customer_id returns the existing customer.

curl -X PUT "$QUOTAFLOW_PARTNER_BASE_URL/customers/by-external-id/cust_123" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN" \
  -H "Idempotency-Key: customer-cust_123-create-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme AI",
    "contact_email": "owner@acme.example",
    "initial_allocation_usd": 50,
    "retail_rate_multiplier": 0.8
  }'

retail_rate_multiplier is the price multiplier charged to this customer organization across the partner's approved model groups. It is required and has no default: the platform never authors a billable rate on the partner's behalf, so an omitted or non-positive value returns INVALID_PARTNER_RETAIL_RATE without creating or funding an organization. It also cannot be lower than the partner's approved wholesale floor — a value below the floor returns PARTNER_RETAIL_RATE_BELOW_FLOOR without creating or funding an organization.

Example response:

{
  "code": 0,
  "message": "success",
  "data": {
    "external_customer_id": "cust_123",
    "created": true,
    "customer": {
      "id": 101,
      "organization_name": "Acme AI",
      "organization_slug": "partner-42-acme-ai",
      "display_name": "Acme AI",
      "billing_mode": "partner_bill",
      "billing_allocation_mode": "org_direct",
      "partner_allocation_cap_usd": 50,
      "partner_allocation_remaining_usd": 50,
      "organization_balance_usd": 50,
      "organization_available_usd": 50,
      "status": "active"
    }
  }
}

If the partner does not have enough available wholesale funding, the API returns PARTNER_FUNDING_INSUFFICIENT with available_funding_usd, required_usd, shortfall_usd, and next_action: top_up_partner_balance.

Manage customer funding

Increase the customer organization balance and its reporting target:

curl -X POST "$QUOTAFLOW_PARTNER_BASE_URL/customers/101/allocations" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN" \
  -H "Idempotency-Key: customer-101-allocation-increase-25" \
  -H "Content-Type: application/json" \
  -d '{"action":"increase","amount_usd":25}'

Set the partner-funded reporting target and adjust the organization balance by the corresponding delta:

curl -X POST "$QUOTAFLOW_PARTNER_BASE_URL/customers/101/allocations" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN" \
  -H "Idempotency-Key: customer-101-allocation-set-75" \
  -H "Content-Type: application/json" \
  -d '{"action":"set_limit","limit_usd":75}'

Read the current balance:

curl "$QUOTAFLOW_PARTNER_BASE_URL/customers/101/balance" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN"

Partner funding is credited, with idempotent audit provenance, to the customer organization's balance before it can be spent. Every project and key in that customer organization then spends from the same organization balance; project allocations remain attribution and reporting records, not wallets.

Create a customer API key

First list the model groups the customer can use:

curl "$QUOTAFLOW_PARTNER_BASE_URL/customers/101/groups" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN"

Then create a customer key. The full qf_... key is returned only on the first successful creation response; idempotent replays return the key preview without the full secret. Store the full key securely.

curl -X POST "$QUOTAFLOW_PARTNER_BASE_URL/customers/101/api-keys" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN" \
  -H "Idempotency-Key: customer-101-key-main-v1" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme production key","group_id":123}'

List existing key previews:

curl "$QUOTAFLOW_PARTNER_BASE_URL/customers/101/api-keys" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN"

Disable a key during rotation or abuse response:

curl -X DELETE "$QUOTAFLOW_PARTNER_BASE_URL/customers/101/api-keys/9001" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN" \
  -H "Idempotency-Key: customer-101-key-9001-disable"

Usage

curl "$QUOTAFLOW_PARTNER_BASE_URL/customers/101/usage?start_time=2026-07-01T00:00:00Z&end_time=2026-07-08T00:00:00Z" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN"

Usage returns daily buckets with burn_usd, request count, total tokens, and active API keys.