Requests & responses

Every Knit endpoint follows the same rules for how you send data and what comes back. Read this once and the rest of the reference is mechanical.

Field casing

Send camelCase. It matches what the API returns, so one convention covers both directions.

{
  "tokenAmount": 2500,
  "confirmationThreshold": 10,
  "merchantCallbackUrl": "https://example.com/webhooks/knit"
}

Top-level fields are mapped to their internal names before validation, so snake_case is also accepted — token_amount works exactly like tokenAmount. Both forms are supported, but pick one and stay consistent; camelCase is the form documented on every endpoint page.

Nested objects

The camelCase mapping applies to top-level fields. Nested objects are converted only where an endpoint says so:

Response envelope

Every response — success or failure — shares the same top-level shape.

{
  "statusCode": 200,
  "message": "Collections fetched successfully",
  "data": [],
  "success": true
}

Response keys are always camelCase, including nested ones. The one place this does not hold is webhook payloads, which are delivered by a different path — see Webhooks for the per-event casing.

Status codes

Validation errors

Validation failures come back in two different shapes depending on whether the endpoint validates a request body or query parameters. Branch on the HTTP status, and read errors — it is present on both.

Request bodies — 400

Almost every endpoint. The body is trimmed to message and errors; the usual statusCode, data, and success keys are not present.

{
  "message": "Callback URL must be a valid URL",
  "errors": {
    "merchantCallbackUrl": ["Callback URL must be a valid URL"],
    "merchantReference": ["The merchant reference has already been taken."]
  }
}

Query parameters — 422

Only List collections and List wallet transactions. These return the full envelope with errors alongside it.

{
  "statusCode": 422,
  "message": "The given data was invalid.",
  "data": null,
  "errors": {
    "perPage": ["The per page field must not be greater than 100."]
  },
  "success": false
}

Handling both

async function call(path, init) {
  const res = await fetch(`https://api-prod.useknit.io${path}`, init);
  const body = await res.json();
 
  if (res.status === 400 || res.status === 422) {
    // `errors` is present on both shapes; the envelope is not.
    throw new ValidationError(body.message, body.errors ?? {});
  }
  if (!res.ok) throw new ApiError(body.message, res.status);
 
  return body.data;
}

Pagination

Endpoints that paginate accept page and per_page and return a pagination object next to data.

{
  "statusCode": 200,
  "message": "Wallet transactions fetched successfully",
  "data": [],
  "pagination": {
    "totalItems": 128,
    "page": 2,
    "perPage": 25,
    "currentPage": 2,
    "lastPage": 6
  },
  "success": true
}

Not every list endpoint paginates. Where pagination is absent, the endpoint returned the full result set — each endpoint page states which applies.

Retrying safely

• Reads (GET) are safe to retry unconditionally.
• Payouts are protected by merchantReference, which must be unique. Reuse the same reference when retrying a request whose outcome you are unsure of — a duplicate is rejected with 400 instead of sending twice. Only generate a new reference for a genuinely new payout.
• Managed signing requests accept an idempotencyKey in the body; replaying the same key returns the original request rather than creating another.
• 5xx and network timeouts should be retried with exponential backoff. A timeout does not mean the request was rejected — re-read the resource before assuming it was not created.