Endpoints

Account & Verbrauch

Kostenlos · 0 Credits

Schreibgeschützte Endpunkte für Deinen eigenen Account: Profil, verbleibende Credits, Nutzungshistorie und Abo-Status. Damit baust Du eigene Dashboards, Billing-Alerts oder Admin-Tools — Account-Requests sind kostenlos und verbrauchen keine Credits.

Method	Path	Description
GET	/v1/account	Profilübersicht: Name, E-Mail, Sprache, aktueller Plan.
GET	/v1/account/credits	Credit-Guthaben mit Aufschlüsselung je Buchung und nächstem Ablaufdatum.
GET	/v1/account/usage	Aggregierter Verbrauch: Summen, Aufschlüsselung je Endpunkt, Zeitreihe pro Tag oder Monat.
GET	/v1/account/usage/transactions	Seitenweises Protokoll der einzelnen abgerechneten Requests.
GET	/v1/account/subscription	Aktuelles Abo: Plan, Status, Abrechnungszeitraum, enthaltene Features.
GET	/v1/account/api-keys	Aktive API-Keys auflisten — maskiert (letzte 8 Zeichen), mit letztem Nutzungszeitpunkt.
POST	/v1/account/api-keys	Neuen API-Key erstellen. Erfordert einen Bearer-Token mit account:keys.
DELETE	/v1/account/api-keys/{id}	API-Key sofort widerrufen. Erfordert account:keys.

Die Account-Endpunkte akzeptieren die Authentifizierung nur über den x-api-key-Header oder einen Bearer-Token.

Parameter (usage & transactions)

Die Profil-, Credits- und Abo-Endpunkte haben keine Parameter. Die Usage- und Transactions-Endpunkte akzeptieren:

Nom	Type	Description
from / to	date	Datumsbereich als Y-m-d oder ISO 8601. Standard ist der aktuelle Monat; maximaler Bereich sind 366 Tage. Ein reines Datum als "to" schließt den ganzen Tag ein.
group_by	string	Bucket-Größe der Zeitreihe: "day" oder "month". Standard: day bis 3 Monate, darüber month. Nur beim Usage-Endpunkt.
endpoint	string	Filtert das Transaktionsprotokoll auf einen Endpunkt, z. B. "/api/v1/fetch-organization". Nur beim Transactions-Endpunkt.
per_page	integer	Seitengröße des Transaktionsprotokolls, 1–100 (Standard: 25).
cursor	string	Opaker Pagination-Cursor aus der vorherigen Antwort (pagination.next_cursor). Nur beim Transactions-Endpunkt.

Beispiel-Anfrage

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());

Beispiel-Antwort

{
  "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 brauchen für diese Endpunkte die Ability account:read. Tokens mit Standard-Abilities enthalten sie automatisch; API-Keys haben immer Zugriff.

Die Key-Verwaltung ist bewusst asymmetrisch: Auflisten funktioniert mit jedem Zugang (account:read), Erstellen und Widerrufen erfordern einen Bearer-Token mit der Ability account:keys. Diesen Token erstellst Du ausschließlich auf Deiner Profilseite — ein API-Key kann niemals Zugangsdaten erzeugen oder löschen.

Keys per API verwalten

Erstelle einen Admin-Token im Abschnitt "Admin-Token" auf Deiner Profilseite. Er trägt die Ability account:keys, wird einmalig angezeigt und ist ein Jahr gültig — ein neuer Token ersetzt ihn. Profil öffnen →
Nutze ihn als Bearer-Token, um neue API-Keys zu erstellen. Der vollständige Key wird nur in der Erstellungs-Antwort zurückgegeben — bewahre ihn sicher auf.
Widerrufe kompromittierte oder ungenutzte Keys per ID. Der Widerruf greift sofort: Der Key funktioniert ab dem nächsten Request nicht mehr.

Beispiele zur Key-Verwaltung

# 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'

Antwort beim Erstellen

{
  "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
  }
}