Halo API · v1

Public API Dokumentation

Über die Halo Public-API kannst du die KI-Sichtbarkeits-Scores einer Person programmatisch abfragen — z.B. um Halo-Score, GEO-Score, Thought Leadership oder Wettbewerber-Vergleiche in eigene Dashboards, CRMs oder Reports einzubinden.

Base URL

https://digital-halo.de/api/v1

Einführung

Die API gibt programmatischen Zugriff auf die Sichtbarkeits-Daten eines Halo-Accounts — lesend (Scores, Verlauf, KI-Antworten, Empfehlungen, Wettbewerber) und verwaltend (Wettbewerber anlegen/löschen, Analysen auslösen, Sub-Accounts anlegen). Sie ist Bestandteil der Tarife Pro und Enterprise; Free- und Starter-Accounts können sich nicht authentifizieren.

18 Endpoints: 11× GET (lesen), 5× POST (anlegen/auslösen), 2× DELETE
Tageslimit je Tarif — Pro 1.000/Tag, Enterprise unbegrenzt (siehe Limits & Tarife)
Sub-Accounts: Enterprise legt verwaltete Unter-Accounts an und steuert sie per sub_account_id
JSON-Responses mit konsistenter Fehler-Struktur, Bearer-Token-Auth, HTTPS-Pflicht

Lebenszyklus eines (Sub-)Accounts

POST /sub-accounts — Account anlegen (nur Enterprise; bei sich selbst überspringen)
POST /topics?sub_account_id=… — mindestens ein Thema anlegen
POST /analyze/{id}?sub_account_id=… — Analyse für dieses Thema auslösen
GET /scores/latest?sub_account_id=… — Ergebnisse abrufen

Ohne Thema (Schritt 2) liefern /analyze und /scores nichts, da der Account kein Tracking-Ziel hat. Die Analyse sucht nach dem Namen des Accounts (full_name).

Authentifizierung

Jede Anfrage benötigt einen API-Key im Authorization Header:

http

Authorization: Bearer aur_sk_<dein-key>

Key erstellen

Einloggen in Halo Einstellungen
Zum Block „API-Keys" scrollen
„+ Neuen API-Key generieren" klicken
Name vergeben (z.B. „Production CRM") und Submit
Den angezeigten Key sofort sicher speichern — er wird nur einmal angezeigt

⚠ Schlüssel-Sicherheit

API-Keys gewähren vollen Lesezugriff auf alle deine Sichtbarkeits-Daten. Behandle sie wie Passwörter: niemals in Frontend-Code hardcoden, niemals in Git committen, niemals öffentlich teilen. Bei Verdacht auf Kompromittierung den Key sofort in den Einstellungen widerrufen.

Limits & Tarife

Der API-Zugang ist Bestandteil der Tarife Pro und Enterprise. Die Anzahl der Abfragen pro Tag hängt vom Tarif ab:

Tarif	API-Zugang	Abfragen / Tag
Free / Starter	—	Kein API-Zugang
Pro	✓	1.000
Enterprise	✓	Unbegrenzt

Das Limit wird pro Account gezählt und setzt sich täglich um 00:00 UTC zurück. Wird es überschritten, antwortet die API mit 429 RATE_LIMITED; die Antwort enthält das erreichte Limit und den Reset-Zeitpunkt:

json

{
  "error": "Tägliches API-Limit erreicht (1000 Abfragen/Tag im Tarif pro). …",
  "code": "RATE_LIMITED",
  "limit": 1000,
  "used": 1001,
  "reset": "2026-06-09T00:00:00.000Z",
  "plan": "pro"
}

Enterprise-Lizenz — unbegrenzte Abfragen

Für produktive Integrationen mit hohem Volumen bieten wir Enterprise-Lizenzen ohne Abfragelimit an, inklusive priorisiertem Support. Schreib uns für ein Angebot an michael.schreck@entrenous.de oder sieh dir die Tarifübersicht an.

Fehler-Codes

Alle Fehlerantworten haben das gleiche JSON-Schema:

json

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE"
}

HTTP	Code	Bedeutung
401	`MISSING_TOKEN`	Authorization-Header fehlt oder ist nicht Bearer.
401	`INVALID_TOKEN_FORMAT`	Token beginnt nicht mit aur_sk_.
401	`INVALID_TOKEN`	Token nicht gefunden — wurde er ggf. widerrufen oder falsch kopiert?
401	`TOKEN_REVOKED`	Der Key wurde in den Einstellungen widerrufen.
403	`PLAN_REQUIRED`	Tarif unterstützt API nicht. Upgrade auf Pro/Enterprise nötig.
429	`RATE_LIMITED`	Tägliches Abfragelimit erreicht. Reset um 00:00 UTC — oder Enterprise-Lizenz für unbegrenzte Abfragen.
404	`NO_REPORT`	Noch keine Sichtbarkeits-Analyse vorhanden. Im Tool zuerst eine Analyse triggern.
409	`EMAIL_EXISTS`	Beim Anlegen eines Sub-Accounts: ein Account mit dieser E-Mail existiert bereits.
403	`SUB_ACCOUNT_FORBIDDEN`	sub_account_id gehört nicht zu diesem Account (oder existiert nicht).
400	`INVALID_INPUT`	Ungültiger Request-Body (z.B. fehlendes Pflichtfeld beim Anlegen/POST).
500	`INTERNAL`	Serverseitiger Fehler — Support kontaktieren falls anhaltend.

Endpoints

Alle Endpoints liefern application/json. Lesende Endpoints sind GET; schreibende nutzen POST (Thema/Wettbewerber anlegen, Analyse/Wettbewerber-Analyse auslösen, Sub-Account anlegen) bzw. DELETE (Thema/Wettbewerber entfernen). Daten-Endpoints akzeptieren zusätzlich den optionalen Query-Parameter sub_account_id (siehe Hinweis am Ende dieses Abschnitts).

GET/api/v1/me

Gibt die Profil-Basics des authentifizierten Accounts zurück. Nützlich, um zu prüfen, ob ein Key gültig ist und zu welchem Account er gehört.

Beispiel-Request

bash

curl https://digital-halo.de/api/v1/me \
  -H "Authorization: Bearer aur_sk_xxxxx"

Beispiel-Response (200 OK)

json

{
  "id": "e24182d8-446a-4bbf-8aba-3459ff31bd66",
  "email": "user@example.com",
  "full_name": "Elon Musk",
  "plan": "pro",
  "language": "de"
}

GET/api/v1/scores/latest

Aktuelle Werte für die 4 Master-Scores (Halo, GEO, Thought Leadership, Digitale Autorität) aus dem jüngsten Report — inkl. Score-Herleitung pro Dimension (Messwert × Gewicht = Beitrag) und Per-Modell-Aufschlüsselung. Antwortet 404, wenn noch keine Analyse durchgeführt wurde.

Beispiel-Request

bash

curl https://digital-halo.de/api/v1/scores/latest \
  -H "Authorization: Bearer aur_sk_xxxxx"

Beispiel-Response (200 OK)

json

{
  "aura": {
    "value": 58,
    "band": "Etabliert",
    "breakdown": {
      "total": 58,
      "factors": [
        { "key": "presence",  "label": "Erwähnungsrate",
          "raw_value": 29, "weight": 0.35, "contribution": 10 },
        { "key": "position",  "label": "Positionsqualität",
          "raw_value": 85, "weight": 0.25, "contribution": 21 }
        // … context, topic
      ]
    }
  },
  "geo":                { "value": 58, "band": "Etabliert", "breakdown": { ... } },
  "thought_leadership": { "value": 48, "band": "Bekannt im Fachkreis", "breakdown": { ... } },
  "digital_authority":  { "value": 49, "band": "Etablierend", "breakdown": { ... } },
  "strongest":          { "key": "geo", "value": 58 },
  "biggest_opportunity":{ "key": "thought-leadership", "value": 48 },
  "mention_rate": 29,
  "average_position": 2.0,
  "per_model": [
    { "provider": "claude-sonnet", "label": "Claude Sonnet",
      "model": "claude-sonnet-4-5", "score": 58, "mention_rate": 29,
      "average_position": 2.0, "error": null }
  ],
  "providers_used": ["claude-sonnet"],
  "queried_at": "2026-05-31T06:19:12Z",
  "summary": "Score: 58/100. Erwähnt in 29% der Abfragen."
}

GET/api/v1/scores/history

Score-Zeitreihe der letzten N Tage. Default = 30 Tage. Min = 1, Max = 365.

Query-Parameter

daysinteger Anzahl Tage rückwirkend. Optional, default 30, clamp 1–365.

Beispiel-Request

bash

curl "https://digital-halo.de/api/v1/scores/history?days=90" \
  -H "Authorization: Bearer aur_sk_xxxxx"

Beispiel-Response (200 OK)

json

{
  "days": 90,
  "since": "2026-02-25T...",
  "points": [
    {
      "date": "2026-03-01T06:00:00Z",
      "score": 75,
      "sentiment": "positive",
      "trigger": "scheduled"
    },
    ...
  ]
}

GET/api/v1/competitors

Liste aller verfolgten Wettbewerber mit zuletzt gemessenem Score (oder null falls noch nicht analysiert).

Beispiel-Request

bash

curl https://digital-halo.de/api/v1/competitors \
  -H "Authorization: Bearer aur_sk_xxxxx"

Beispiel-Response (200 OK)

json

{
  "competitors": [
    {
      "id": "f73395d1-7ce1-443f-b9e6-c0d594ca583c",
      "name": "Mark Zuckerberg",
      "topics": ["Social Media", "AI", "Metaverse"],
      "language": "en",
      "last_score": 48,
      "last_analyzed_at": "2026-05-26T14:55:21Z"
    },
    {
      "id": "8eb0e9ef-2894-4796-880a-cd6c2cd3a302",
      "name": "Andrew Ng",
      "topics": ["AI", "Machine Learning", "Education"],
      "language": "en",
      "last_score": 84,
      "last_analyzed_at": "2026-05-26T14:42:39Z"
    }
  ]
}

POST/api/v1/competitors

Legt einen neuen Wettbewerber an. topics kann ein Array oder ein kommagetrennter String sein (max. 10). language steuert die Sprache der KI-Abfragen (Standard en, region-neutral für globale Figuren).

Beispiel-Request

bash

curl -X POST https://digital-halo.de/api/v1/competitors \
  -H "Authorization: Bearer aur_sk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Andrew Ng","topics":["AI","Machine Learning"],"language":"en"}'

Beispiel-Response (200 OK)

json

{
  "competitor": {
    "id": "uuid",
    "name": "Andrew Ng",
    "topics": ["AI", "Machine Learning"],
    "language": "en",
    "last_score": null,
    "last_analyzed_at": null
  }
}

DELETE/api/v1/competitors/{id}

Entfernt einen Wettbewerber samt seiner gespeicherten Analyse-Berichte.

Query-Parameter

iduuid (Pfad) ID des Wettbewerbers (aus /competitors).

Beispiel-Request

bash

curl -X DELETE https://digital-halo.de/api/v1/competitors/8eb0e9ef-... \
  -H "Authorization: Bearer aur_sk_xxxxx"

Beispiel-Response (200 OK)

json

{ "deleted": true, "id": "8eb0e9ef-..." }

POST/api/v1/competitors/{id}/analyze

Löst eine Sichtbarkeits-Analyse für einen Wettbewerber aus (entspricht „Analysieren“ im Dashboard). Läuft synchron ~10–30 Sekunden. Kein Request-Body nötig.

Query-Parameter

iduuid (Pfad) ID des Wettbewerbers.

Beispiel-Request

bash

curl -X POST https://digital-halo.de/api/v1/competitors/8eb0e9ef-.../analyze \
  -H "Authorization: Bearer aur_sk_xxxxx"

Beispiel-Response (200 OK)

json

{
  "competitor": { "id": "8eb0e9ef-...", "name": "Andrew Ng" },
  "report_id": "uuid",
  "score": 84,
  "sentiment": "positive",
  "mention_rate": 100,
  "providers_used": ["claude-sonnet"]
}

GET/api/v1/competitors/{id}/gaps

Lückenanalyse zwischen dir und einem Wettbewerber: pro Frage-Archetyp, wer genannt wird. Zeigt konkrete inhaltliche Lücken (Wettbewerber genannt, du nicht) und Vorsprünge. Nutzt deinen jüngsten Report und den jüngsten Report des Wettbewerbers (404, falls einer fehlt).

Query-Parameter

iduuid (Pfad) ID des Wettbewerbers (aus /competitors).

Beispiel-Request

bash

curl https://digital-halo.de/api/v1/competitors/8eb0e9ef-.../gaps \
  -H "Authorization: Bearer aur_sk_xxxxx"

Beispiel-Response (200 OK)

json

{
  "competitor": { "id": "8eb0e9ef-...", "name": "Andrew Ng" },
  "gap_count": 3,
  "advantage_count": 2,
  "comparisons": [
    {
      "type": "expert_discovery",
      "label": "Experten-Suche",
      "hint": "Wer gilt als führende Expertin/Experte für das Thema?",
      "self_mentioned": false,
      "competitor_mentioned": true,
      "verdict": "gap"
    }
    // … topic_authority, recommendation, leadership, popular_figures
  ]
}

GET/api/v1/responses

Die tatsächlichen KI-Antworten hinter deinen Scores (Belege) aus der jüngsten Analyse, gruppiert nach Frage. Pro Antwort: Modell, ob du genannt wurdest, Listenposition, Tonalität und der volle Antworttext.

Beispiel-Request

bash

curl https://digital-halo.de/api/v1/responses \
  -H "Authorization: Bearer aur_sk_xxxxx"

Beispiel-Response (200 OK)

json

{
  "analyzed_at": "2026-05-31T06:19:12Z",
  "total": 7,
  "mentioned": 2,
  "groups": [
    {
      "prompt": "Wer sind die führenden Experten für …?",
      "answers": [
        {
          "model": "claude-sonnet-4-5",
          "mentioned": true,
          "position": 2,
          "sentiment": "positive",
          "response": "… vollständiger Antworttext …"
        }
      ]
    }
  ]
}

GET/api/v1/monopoly

Expert Monopoly Score je Thema: wie konsequent KI dich auf die vordersten Plätze setzt, wenn sie offen nach den führenden Köpfen eines Themas gefragt wird. Rein aus Positions-/Nennungsdaten der jüngsten Analyse je Thema abgeleitet — kein zusätzlicher LLM-Aufruf. Bänder: Monopol (80+), Dominant (60+), Umkämpft (40+), Randständig (20+), Unsichtbar (0+).

Beispiel-Request

bash

curl https://digital-halo.de/api/v1/monopoly \
  -H "Authorization: Bearer aur_sk_xxxxx"

Beispiel-Response (200 OK)

json

{
  "average": 64,
  "topics": [
    {
      "topic": "Elektroautos",
      "score": 88,
      "band": "Monopol",
      "mention_share": 100,
      "top_position_share": 80,
      "best_position": 1,
      "rivals_mentioned": 4,
      "analyzed_at": "2026-06-11T06:19:12Z"
    }
  ]
}

GET/api/v1/recommendation-probability

Letzte Messung der Empfehlungs-Wahrscheinlichkeit: wie oft die Person genannt wird, wenn KI nach einem Keynote-Speaker, Berater, Trainer oder Podcast-Gast für ihre Themen gefragt wird. Pro Rolle: Wahrscheinlichkeit (Trefferquote), Treffer/Abfragen und beste Position. 404, falls noch keine Messung lief. Die Messung selbst wird im Dashboard ausgelöst (Pro-Feature).

Beispiel-Request

bash

curl https://digital-halo.de/api/v1/recommendation-probability \
  -H "Authorization: Bearer aur_sk_xxxxx"

Beispiel-Response (200 OK)

json

{
  "overall": 58,
  "measured_at": "2026-06-11T06:19:12Z",
  "roles": [
    {
      "role": "keynote",
      "label": "Keynote-Speaker",
      "probability": 75,
      "mentions": 3,
      "samples": 4,
      "best_position": 1
    }
    // … consultant, trainer, podcast
  ]
}

GET/api/v1/recommendations

Persistierte Handlungsempfehlungen (offen + umgesetzt), inkl. Score-Stand bei Erstellung und Umsetzung für die Wirkungs-Messung.

Query-Parameter

statusstring open | done | all. Optional; Standard = offen + umgesetzt (dismissed ausgeblendet).

Beispiel-Request

bash

curl "https://digital-halo.de/api/v1/recommendations?status=open" \
  -H "Authorization: Bearer aur_sk_xxxxx"

Beispiel-Response (200 OK)

json

{
  "recommendations": [
    {
      "id": "uuid",
      "title": "Veröffentliche regelmäßig zu deinen Zielthemen",
      "description": "…",
      "impact": "high",
      "category": "Inhalt",
      "status": "open",
      "score_at_creation": 58,
      "score_at_done": null,
      "created_at": "2026-05-31T06:20:00Z",
      "done_at": null
    }
  ]
}

GET/api/v1/topics

Listet die Themen (monitoring_schedules) des Accounts. Jedes Thema hat eine ID, die als scheduleId für POST /analyze dient.

Beispiel-Request

bash

curl https://digital-halo.de/api/v1/topics \
  -H "Authorization: Bearer aur_sk_xxxxx"

Beispiel-Response (200 OK)

json

{
  "topics": [
    {
      "id": "uuid",
      "name": "Personal Branding",
      "query": "Personal Branding",
      "frequency": "weekly",
      "language": "de",
      "is_active": true,
      "last_run_at": null,
      "next_run_at": "2026-06-15T06:00:00Z",
      "created_at": "2026-06-08T09:12:00Z"
    }
  ]
}

POST/api/v1/topics

Legt ein neues Thema an. Pflicht für frisch erstellte (Sub-)Accounts, bevor /analyze und /scores funktionieren. Die zurückgegebene id ist die scheduleId für POST /analyze.

Query-Parameter

`query`string (Body)	Das zu trackende Thema (z.B. „Personal Branding“). Pflicht, max. 200 Zeichen.
`name`string (Body)	Anzeige-Label. Optional, Default = query.
`frequency`string (Body)	daily \| weekly \| monthly. Optional, Default weekly.
`language`string (Body)	Abfragesprache (de, en, fr, es, it, nl, pt). Optional, Default = Sprache des Accounts.

Beispiel-Request

bash

curl -X POST https://digital-halo.de/api/v1/topics \
  -H "Authorization: Bearer aur_sk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"query":"Personal Branding","frequency":"weekly","language":"de"}'

Beispiel-Response (200 OK)

json

{
  "topic": {
    "id": "uuid",
    "name": "Personal Branding",
    "query": "Personal Branding",
    "frequency": "weekly",
    "language": "de",
    "is_active": true,
    "next_run_at": "2026-06-15T06:00:00Z"
  }
}

DELETE/api/v1/topics/{id}

Löscht ein Thema des Accounts.

Query-Parameter

iduuid (Pfad) ID des Themas (aus GET /topics bzw. POST /topics).

Beispiel-Request

bash

curl -X DELETE https://digital-halo.de/api/v1/topics/02f2c43e-... \
  -H "Authorization: Bearer aur_sk_xxxxx"

Beispiel-Response (200 OK)

json

{ "deleted": true, "id": "uuid" }

POST/api/v1/analyze/{scheduleId}

Löst eine neue Sichtbarkeits-Analyse für eines deiner Themen aus (entspricht „Jetzt analysieren“ im Dashboard). Läuft synchron ~10–30 Sekunden und gibt das Ergebnis zurück. Erfordert kein Request-Body.

Query-Parameter

scheduleIduuid (Pfad) ID des Themas (monitoring_schedule). IDs findest du in /me-Kontext bzw. im Dashboard.

Beispiel-Request

bash

curl -X POST https://digital-halo.de/api/v1/analyze/02f2c43e-... \
  -H "Authorization: Bearer aur_sk_xxxxx"

Beispiel-Response (200 OK)

json

{
  "report_id": "uuid",
  "score": 58,
  "sentiment": "positive",
  "mention_rate": 29,
  "providers_used": ["claude-sonnet"]
}

GET/api/v1/sub-accounts

Listet alle Sub-Accounts, die unter diesem Account angelegt wurden. Verwaltete Sub-Accounts sind eigene Halo-Profile (eigene Themen & Scores), die über den Eltern-Account verknüpft sind.

Beispiel-Request

bash

curl https://digital-halo.de/api/v1/sub-accounts \
  -H "Authorization: Bearer aur_sk_xxxxx"

Beispiel-Response (200 OK)

json

{
  "sub_accounts": [
    {
      "id": "uuid",
      "email": "kunde@example.com",
      "full_name": "Kunden-Name",
      "plan": "pro",
      "language": "de",
      "created_at": "2026-06-08T09:12:00Z"
    }
  ]
}

POST/api/v1/sub-accounts

Legt einen neuen verwalteten Sub-Account an. Nur mit Enterprise-Lizenz verfügbar, ohne Mengenbegrenzung. Der Sub-Account erhält den Tarif „Pro“ und wird über den Eltern-Account gesteuert (kein eigener Login-Flow — es wird keine Einladungs- oder Bestätigungsmail versendet).

Query-Parameter

`full_name`string (Body)	Anzeigename des Sub-Accounts. Pflicht, max. 120 Zeichen.
`email`string (Body)	Eindeutige E-Mail-Adresse. Pflicht. Wird zur Identifikation genutzt.
`language`string (Body)	Abfragesprache (de, en, fr, es, it, nl, pt). Optional, Default = Sprache des Eltern-Accounts.

Beispiel-Request

bash

curl -X POST https://digital-halo.de/api/v1/sub-accounts \
  -H "Authorization: Bearer aur_sk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"full_name":"Kunden-Name","email":"kunde@example.com","language":"de"}'

Beispiel-Response (200 OK)

json

{
  "sub_account": {
    "id": "uuid",
    "email": "kunde@example.com",
    "full_name": "Kunden-Name",
    "plan": "pro",
    "language": "de",
    "parent_account_id": "uuid-des-eltern-accounts"
  }
}

Im Namen eines Sub-Accounts handeln

Alle Daten-Endpoints akzeptieren den optionalen Query-Parameter sub_account_id. Damit liest oder verwaltet der Eltern-Account die Daten eines seiner Sub-Accounts mit demselben API-Key — z.B. GET /scores/latest?sub_account_id=… oder POST /analyze/{id}?sub_account_id=…. Ohne den Parameter bezieht sich jeder Aufruf auf den eigenen Account. Gehört die angegebene sub_account_id nicht zum authentifizierten Account, antwortet die API mit 403 SUB_ACCOUNT_FORBIDDEN.

Code-Beispiele

cURL

bash

# Profile abrufen
curl https://digital-halo.de/api/v1/me \
  -H "Authorization: Bearer $AURALIS_API_KEY"

# Aktuelle Scores
curl https://digital-halo.de/api/v1/scores/latest \
  -H "Authorization: Bearer $AURALIS_API_KEY"

JavaScript (Node.js / Browser)

javascript

const API_KEY = process.env.AURALIS_API_KEY
const headers = { Authorization: `Bearer ${API_KEY}` }

async function getLatestScores() {
  const res = await fetch(
    "https://digital-halo.de/api/v1/scores/latest",
    { headers }
  )
  if (!res.ok) {
    const { error, code } = await res.json()
    throw new Error(`${code}: ${error}`)
  }
  return res.json()
}

getLatestScores().then(console.log)

Python (requests)

python

import os
import requests

API_KEY = os.environ["AURALIS_API_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
BASE   = "https://digital-halo.de/api/v1"

def get_latest_scores():
    r = requests.get(f"{BASE}/scores/latest", headers=HEADERS, timeout=15)
    r.raise_for_status()
    return r.json()

print(get_latest_scores())

Support

Bei Fragen, Bug-Reports oder Feature-Requests zur API erreichst du das Halo-Team unter support@entrenous.de.

Diese API ist als v1 markiert. Breaking Changes werden in einer neuen Version (/api/v2) ausgeliefert; v1 bleibt mindestens 12 Monate nach Release einer v2 verfügbar.