API Reference
Overview
The Clocknext Payments API and Node.js SDK — meter LLM usage, manage customers and plans.
Clocknext works through the Node.js SDK and API. Both meter LLM usage — against a credit, outcome, wallet, unit, or composite — and manage customers and their plans. Every request is authenticated with an organisation-scoped API key, and every response, from either the SDK or the API, follows the same response envelope.
Install the SDK
npm install @clocknext/sdkThe SDK is optional. You can call the API directly with cURL or your own HTTP client.
Base URLs
The API has two hosts. Each endpoint calls one of them, and its page shows the full URL. You cannot change the base URL of an endpoint.
| Host | Base URL | Endpoints |
|---|---|---|
| Events API | https://events.clocknext.com/api/v1 | Record signals, list and retry signals, read the usage log |
| Payments API | https://payments.clocknext.com/api/v1 | Customers, balances, plans, purchases, invoices, payments and everything else |
All paths in this reference are relative to the base URL of their host —
POST /signal/credit calls POST https://events.clocknext.com/api/v1/signal/credit.
The same signal and usage-log routes on payments.clocknext.com are
deprecated. They still answer, but they will be removed.
Both hosts take the same API key and return the same response envelope.
OpenAPI specs
Each host has an OpenAPI 3.1 file. Use it to generate a client in any language.
| Host | OpenAPI file |
|---|---|
| Events API | /openapi-events.yaml |
| Payments API | /openapi.yaml |
Each API page ends with a Types section. It gives a field table for every object type that the page uses, nested types included.
Authentication
Every request carries a per-organisation API key as a bearer token:
Authorization: Bearer cnk_your_key_hereCreate, send, and rotate keys in Settings → API Keys.
The shape of every response
Success or error, every response has the same envelope:
{
"statusCode": 200,
"statusDetail": { "status": "SUCCESS", "message": "OK" },
"result": { }
}See Response format for the full contract.
Where to go next
Quickstart
Create a customer and record your first usage signal in under ten minutes.
API keys
Create an API key, send it, and rotate it safely.
Response format
The one response shape every endpoint returns.
Handling errors
Every status code the API returns and how to handle it.
Paginating results
Page through list endpoints with limit and cursor.
What you can do
| Area | Endpoints | What it's for |
|---|---|---|
| Signals | /signal/* | Record one metered request against a credit, outcome, wallet, or unit, and close a composite. List raw signals, retry the ones that could not be counted, and read the usage log. On events.clocknext.com. |
| Customers | /customers | Create, read, update, and delete customers; read balances and plan. |
| Members | /customers/{id}/members | Manage the people who belong to a customer. |
| Billing | Purchases · Packages · Plan changes · Invoices · Credit notes · Refunds · Payments | Subscribe customers, add packages to their subscription, change their plan, read invoices, credit and refund them, and mint hosted pay links. |
| Customer Portal | /portal/token | Mint short-lived tokens to embed the customer portal. |
Server-side only
Your cnk_… key has organisation-wide read/write access. Call this API from a
server, script, or job you control — never ship the key to a browser or mobile
app. To give a customer access to their own data, mint a
portal token instead.