API reference

JSON over HTTPS, generated from the API's contract. What every route shares, then every group.

The 60 routes an API key can call: what each takes, returns and can refuse, with its cURL request and the SDKs' example.

Anatomy · request

  1. POST: the method, as each endpoint names it
  2. https://api.qbitflow.app/v2/products: the base URL and the route: the version is part of the path
  3. X-API-Key: sk_…: your key: its space and mode decide everything the request sees
  4. On-Behalf-Of: <member>: optional: an organization's key acting in a member's space
  5. Idempotency-Key: <uuid>: on creates: a retry with the same key never creates twice

Base URL and versions

Every path is relative to:

https://api.qbitflow.app/v2

The version is part of the path, and the SDKs default to this URL. A trailing slash is ignored (/products = /products/). Keys, parameters and enum values are lowerCamelCase (userUuid, pastDue); error codes stay snake_case.

Authentication

Send your key in the X-API-Key header of every authenticated request:

Text

X-API-Key: sk_<test|live>_<uuid>_<secret>
  • Opaque. Created in the dashboard and shown once; the API can't create or revoke keys.
  • One space, one mode. An organization's key acts as an admin of the organization; a member's key acts as that member. It only sees its space's resources.
  • Admin routes say "an admin key": a member's key answers 403 forbidden.
  • A missing, unknown, deleted or expired key answers 401 unauthorized. A few routes are public (the currency lookups, a subscription's public history).

Check which key you hold, and its mode, with GET /me.

On-Behalf-Of

An organization's key acts as one of its members with On-Behalf-Of: <userUuid> (Member.userUuid, from GET /members). The request then works in the member's space, in the key's mode, as if the member had sent it.

  • The effective role is user: admin routes answer 403. Manage members without the header.
  • A value that isn't a uuid, or a member's key naming anyone but itself: 403 forbidden.
  • Not a member of your organization in this mode (another organization's user, an owner or admin, a removed member): 404 not_found. Existence is never revealed.
  • Each endpoint says whether it honors the header.
Act in a member's space

client-on-behalf-of.sh

# An organization key acting in a member's space: the request reads the member's products, in the# key's mode. Without the header, the same key reads the organization's own.curl https://api.qbitflow.app/v2/products \  -H "X-API-Key: $QBITFLOW_API_KEY" \  -H "On-Behalf-Of: $MEMBER_UUID"# 200: a page of Product ({ items, hasMore, nextCursor? })
// An organization key acting in a member's space: every request of seller sends// On-Behalf-Of. It shares client's configuration.const seller = client.onBehalfOf(memberUuid);const products = await seller.products.list();console.log(`${products.items.length} products on the first page of the seller's space`);
# Every request of this client sends On-Behalf-Of: it acts in the member's space.seller = client.on_behalf_of(member_uuid)  # shares the connections and settings of clientproducts = seller.products.list()print(len(products.items), "products on the first page of the seller's space")
// A client acting in the member's space (organization key): every request sends// On-Behalf-Of. It shares the connections and configuration of client.seller := client.OnBehalfOf(memberUUID)products, err := seller.Products.List(ctx, nil)if err != nil {	log.Fatal(err)}fmt.Println(len(products.Items), "products on the first page of the seller's space")
// An organization key acts in a member's space: every request sends On-Behalf-Of.$seller = $client->onBehalfOf($memberUuid); // shares $client's transport and configurationecho count($seller->products->list()->items), " products on the first page of the member's space\n";

Every request

One line each, the details on the linked page.

Idempotency-Key and X-Request-Id

Send one Idempotency-Key per create, the same on every retry: it never runs twice (idempotency). Every response carries X-Request-Id (yours, if you sent a plain token of 1 to 128 letters, digits and -_.:, else a new UUID), repeated as requestId in every error: log it, quote it to support.

Pagination

Lists take a cursor: pass nextCursor back as cursor until hasMore is false; limit is clamped, never refused (pagination).

Errors

One body for every failure: branch on code and the status, never on error (every code).

Rate limits

Past a limit, 429 rate_limit_exceeded with Retry-After: the request did nothing, wait and send it again (rate limits).

Test mode

The key picks the mode: a test key only sees test resources, on test networks, and nothing carries over to live (test mode, going live).

Resource groups

One page per group. Also: webhook events and every error code.