Endpoints

Account & Usage

Free · 0 credits

Read-only endpoints for your own account: profile, remaining credits, usage history, and subscription status. Build your own dashboards, billing alerts, or admin tooling on top — account requests are free and never consume credits.

Method	Path	Description
GET	/v1/account	Profile summary: name, email, language, current plan.
GET	/v1/account/credits	Credit balance with a per-grant breakdown and the next expiry date.
GET	/v1/account/usage	Aggregated usage: totals, per-endpoint breakdown, daily or monthly time series.
GET	/v1/account/usage/transactions	Paginated ledger of individual billed requests.
GET	/v1/account/subscription	Current subscription: plan, status, billing period, included features.
GET	/v1/account/api-keys	List active API keys — masked (last 8 characters), with the last-use timestamp.
POST	/v1/account/api-keys	Create a new API key. Requires a Bearer token with account:keys.
DELETE	/v1/account/api-keys/{id}	Revoke an API key immediately. Requires account:keys.

Account endpoints accept authentication via the x-api-key header or a Bearer token only.

Parameters (usage & transactions)

The profile, credits, and subscription endpoints take no parameters. The usage and transactions endpoints accept:

Name	Type	Description
from / to	date	Date range as Y-m-d or ISO 8601. Defaults to the current month; the maximum range is 366 days. A date-only "to" includes that whole day.
group_by	string	Time-series bucket size: "day" or "month". Defaults to day for ranges up to 3 months, month beyond that. Usage endpoint only.
endpoint	string	Filters the transaction ledger to a single endpoint, e.g. "/api/v1/fetch-organization". Transactions endpoint only.
per_page	integer	Page size for the transaction ledger, 1–100 (default: 25).
cursor	string	Opaque pagination cursor from the previous response (pagination.next_cursor). Transactions endpoint only.

Example Request

curl --get 'https://handelsregister.ai/api/v1/account/usage' \
  -H 'x-api-key: YOUR_API_KEY' \
  --data-urlencode 'from=2026-07-01' \
  --data-urlencode 'to=2026-07-30'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/account/usage",
    params={"from": "2026-07-01", "to": "2026-07-30"},
    headers={"x-api-key": "YOUR_API_KEY"},
)
print(response.json())

const response = await fetch(
  'https://handelsregister.ai/api/v1/account/usage?from=2026-07-01&to=2026-07-30',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
console.log(await response.json());

Example Response

{
  "period": {
    "from": "2026-07-01T00:00:00+00:00",
    "to": "2026-07-30T23:59:59+00:00"
  },
  "totals": { "requests": 412, "credits_used": 3180 },
  "by_endpoint": [
    { "endpoint": "/api/v1/fetch-organization", "requests": 300, "credits_used": 2700 },
    { "endpoint": "/api/v1/search-organizations", "requests": 112, "credits_used": 480 }
  ],
  "series": {
    "group_by": "day",
    "buckets": [
      { "date": "2026-07-01", "requests": 12, "credits_used": 96 }
    ]
  },
  "meta": { "request_credit_cost": 0, "credits_remaining": 1250 }
}

Bearer tokens need the account:read ability for these endpoints. Tokens created with the default abilities include it automatically; API keys always have access.

Key management is deliberately asymmetric: listing works with any credential (account:read), but creating and revoking keys requires a Bearer token with the account:keys ability. That token can only be created on your profile page — an API key can never mint or destroy credentials.

Managing keys via API

Create an admin token in the "Admin Token" section of your profile page. It carries the account:keys ability, is shown once, and is valid for one year — creating a new one replaces it. Open profile →
Use it as a Bearer token to create new API keys. The full key is returned only in the create response — store it securely.
Revoke compromised or unused keys by ID. Revocation is immediate: the key stops working with the next request.

Key Management Examples

# List keys, masked — works with any credential
curl 'https://handelsregister.ai/api/v1/account/api-keys' \
  -H 'x-api-key: YOUR_API_KEY'

# Create a key — admin token required, full key shown only in this response
curl -X POST 'https://handelsregister.ai/api/v1/account/api-keys' \
  -H 'Authorization: Bearer YOUR_ADMIN_TOKEN'

# Revoke a key by id — takes effect with the next request
curl -X DELETE 'https://handelsregister.ai/api/v1/account/api-keys/123' \
  -H 'Authorization: Bearer YOUR_ADMIN_TOKEN'

Create Response

{
  "api_key": {
    "id": 124,
    "key": "JUoO1CCeZnAJeAERdyZwVT2Qq2zvD4zX8nsUKMyrlg7W1KcieuIZE5d7mzR",
    "created_at": "2026-07-30T12:00:00+00:00"
  },
  "meta": {
    "message": "Store this key securely. It grants full data access to this account.",
    "request_credit_cost": 0,
    "credits_remaining": 1250
  }
}