brandfound.

Command Palette

Search for a command to run...

v1.2.0

brandfound. API

API zum Verfolgen von Markenerwähnungen in KI-Assistenten (ChatGPT, Gemini, Claude, Perplexity). Verwaltung von Unternehmen, Produkten, Wettbewerbern, Anfragen, Erwähnungen und Analytik.

Basis-URL

https://app.brandfound.ai/api/v1

Playground

Klicken Sie auf im Anfragebereich, um den interaktiven Playground zu öffnen. Wählen Sie einen API-Schlüssel, legen Sie Parameter fest und senden Sie die Anfrage direkt aus der Dokumentation.

Schnellstart
1
2
curl -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  https://app.brandfound.ai/api/v1/companies
Erfolgreiche Antwort
1
2
3
4
5
6
{
  "success": true,
  "data": {
    "...": "..."
  }
}
Fehler
1
2
3
4
5
6
7
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Nicht gefunden"
  }
}
Anfragelimits
Pro IP-Adresse120 / Min.
Pro Benutzer60 / Min.
Fehlercodes
401
UNAUTHORIZEDUngültige Autorisierung
403
FORBIDDENUnzureichende Berechtigungen
404
NOT_FOUNDRessource nicht gefunden
400
VALIDATION_ERRORValidierungsfehler
429
RATE_LIMIT_EXCEEDEDLimit überschritten
500
INTERNAL_ERRORInterner Fehler

Neu in Version 1.2

Die öffentlichen Adressen der Methoden bleiben unverändert, die Abwärtskompatibilität bleibt erhalten.

Analytik antwortet wieder

Methoden der Bereiche Analytik, Links und Werbung lieferten wegen eines Fehlers auf unserer Seite einen 500er. Behoben, von Ihrer Seite ist nichts zu tun.

Status der Anfrage sichtbar

In der Anfrageliste gibt es jetzt answersCount, die tatsächliche Liste der Assistenten in providers und den Sammelstatus queue.status. Zuvor war providers immer leer.

Warteschlange der Abfragen

queries/queue und queue/summary zeigen, was abgefragt wird und was es kostet. Wegen fehlender FoxCoin gestoppte Abfragen werden über queue/resume fortgesetzt, von selbst starten sie nicht.

Guthaben und Ausgaben

billing/balance liefert den Kontostand und die Preise aller Vorgänge, billing/transactions die Abbuchungshistorie samt zugehöriger Anfrage.

Antwortsprache

Das Feld language bestimmt jetzt die Antwortsprache. Funktioniert in ChatGPT, Gemini, Perplexity und DeepSeek.

Verzeichnis der Assistenten

Die Methode sources liefert die verfügbaren Assistenten und markiert die standardmäßig genutzten.

Monitoring

Eine Anfrage lässt sich mit eigenem Zeitplan regelmäßig abfragen. Das war bisher nur in der Oberfläche möglich.

KI-Traffic

Websitebesuche aus KI-Antworten, Besucherverhalten, Funnel und Ziele auf Basis von Yandex.Metrica.

Commerce

Produktkarten in KI-Antworten und das Sortiment zum Abgleich.

Unternehmen jetzt Pflicht

Die Methoden links, links/filter-options, analytics/links/top-domains, analytics/competitors/preview und advertising verlangen companyId. Ohne sie wurden zuvor alle Unternehmen des Kontos zusammengefasst.

Für KI-Assistenten

Kopieren Sie die API-Anleitung und übergeben Sie sie einem KI-Assistenten (ChatGPT, Claude, Gemini usw.) — er kann dann Anfragen an die brandfound.-API für Sie erstellen. Der API-Schlüssel ist im kopierten Text nicht enthalten.

Neben jeder Methode und jedem Abschnitt gibt es eine Schaltfläche — sie kopiert die Beschreibung der jeweiligen Methode oder der gesamten Kategorie.

Der API-Schlüssel ist nicht enthalten — fügen Sie ihn separat ein oder verwenden Sie den Playground.

Authentifizierung

Alle API-Anfragen erfordern eine Autorisierung. Erstellen Sie einen API-Schlüssel im Bereich Einstellungen → API-Schlüssel. Schlüssel haben das Präfix gfx_.

Bearer Token
Empfohlen

Übergeben Sie den Schlüssel im Header Authorization jeder Anfrage.

Session-Cookie

Die Webanwendung verwendet automatisch das Cookie session-token. Es ist keine zusätzliche Konfiguration erforderlich.

Anfragebeispiel
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/companies" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
Antwortbeispiel
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "success": true,
  "data": [
    {
      "id": "comp_123",
      "name": "Mein Unternehmen",
      "slug": "my-company"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Workspaces

Umgebungen (Workspaces/Teams). Ein OAuth-Token kann auf alle Umgebungen zugreifen, für die der Nutzer berechtigt ist: eigene und ACCEPTED TeamMember. Die aktive Umgebung steht in ApiKey.activeAccountId; ein Wechsel bleibt gespeichert und gilt ab der nächsten Anfrage auch für andere MCP-Clients dieses Schlüssels. Berechtigungen werden bei jeder Anfrage geprüft. Nach Verlust der Mitgliedschaft fällt die Middleware ohne 401 auf die bei OAuth erteilte accountId zurück. Beim Wechsel wird preferredCompanyId zurückgesetzt, da sie zur alten Umgebung gehört.

Verfügbare Arbeitsbereiche auflisten

/api/v1/workspaces

Liefert alle Workspaces (accountId), auf die der aktuelle Nutzer zugreifen darf: eigene und ACCEPTED TeamMember. `isCurrent: true` markiert die aktuell vom API-Schlüssel verwendete Umgebung einschließlich activeAccountId-Override.

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/workspaces
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/workspaces" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "success": true,
  "data": {
    "workspaces": [
      {
        "accountId": "example_accountId",
        "role": "owner",
        "ownerName": "example_ownerName",
        "ownerEmail": "example_ownerEmail",
        "companiesCount": 0,
        "isCurrent": true,
        "teamRoleName": "example_teamRoleName",
        "teamRoleKey": "example_teamRoleKey"
      }
    ],
    "currentAccountId": "example_currentAccountId",
    "tokenAccountId": "example_tokenAccountId",
    "activeAccountId": "example_activeAccountId"
  }
}

Erfolgreiche Antwort

Aktiven Arbeitsbereich des API-Schlüssels wechseln

/api/v1/workspaces/switch

Aktualisiert ApiKey.activeAccountId dauerhaft für ALLE folgenden Anfragen dieses Schlüssels, auch aus anderen MCP-Clients. accountId=null entfernt den Override und verwendet wieder die accountId des Tokens. preferredCompanyId wird auf null gesetzt, da sie zur alten Umgebung gehört. Nur mit API-Schlüssel-Authentifizierung.

Anfragetext

accountIdstringerforderlich

UUID des Ziel-Workspaces. null entfernt den aktiven Override und kehrt zur bei OAuth erteilten accountId zurück.

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
403application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/workspaces/switch
1
2
3
4
5
6
curl -X POST "https://app.brandfound.ai/api/v1/workspaces/switch" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "7b2f1d4e-8c9a-4e5b-b6c2-3d7a1f8e9c4b"
}'
1
2
3
4
5
6
7
8
9
10
{
  "success": true,
  "data": {
    "apiKeyId": "example_apiKeyId",
    "tokenAccountId": "example_tokenAccountId",
    "activeAccountId": "example_activeAccountId",
    "effectiveAccountId": "example_effectiveAccountId",
    "preferredCompanyIdReset": true
  }
}

Erfolgreiche Antwort

Unternehmen

Unternehmen verwalten

Unternehmen auflisten

/api/v1/companies

Liefert die Unternehmen des Nutzers mit Produkten, Wettbewerbern und Schlüsselwörtern.

Anfrageparameter

offsetinteger= 0

Offset für die Paginierung

limitinteger= 20

Einträge pro Seite

sortBystring= createdAt
createdAtupdatedAtnamelastUsedAt
sortOrderstring= desc

Sortierreihenfolge

ascdesc
searchstring

Suchtext, ohne Beachtung der Groß-/Kleinschreibung

categoryIdstring (uuid)

Nach Kategorie filtern

countrystring

Nach Land filtern

createdAtFromstring (date-time)

Beginn des Erstellungszeitraums (ISO 8601)

createdAtTostring (date-time)

Ende des Erstellungszeitraums (ISO 8601)

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/companies
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/companies" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "success": true,
  "data": [
    {
      "id": "clx1abc2d0001abcdef123456",
      "name": "Samsung",
      "description": "Samsung Electronics",
      "url": "https://samsung.com",
      "country": "South Korea",
      "categoryId": "cat-uuid-001",
      "lastUsedAt": "2026-04-06T10:00:00.000Z",
      "createdAt": "2026-01-15T08:00:00.000Z",
      "products": [
        {
          "id": "prod-001",
          "name": "Galaxy S25"
        }
      ],
      "competitors": [
        {
          "id": "comp-001",
          "name": "Apple"
        }
      ],
      "keywords": [],
      "category": {
        "id": "cat-uuid-001",
        "name": "Electronics"
      }
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Erfolgreiche Antwort

Unternehmen erstellen

/api/v1/companies

Erstellt ein Unternehmen. Das Limit hängt vom Tarif ab.

Anfragetext

namestringerforderlich
descriptionstring
urlstring
categoryIdstring
countrystring

ISO 3166-1 alpha-2 ("AE"). Alte Namen wie "russia" werden akzeptiert und normalisiert. regionTargets wird bevorzugt; dieses Feld ist veraltet.

synonymsstring[]

Synonyme/alternative Namen (max. 20)

regionTargetsobject[]

Messländer und -städte. VOLLSTÄNDIGER Zustand: alte Ziele werden neu erstellt. Das primäre Ziel bestimmt Land und Sprache der automatischen Anfragegenerierung.

defaultLanguageIdstring

Sprache generierter Anfragen (GET /api/v1/geo/languages).

defaultResponseLanguageIdstring

Sprache, in der das KI-System antworten soll.

defaultLocalestring

BCP-47, z.B. "ar-AE".

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/companies
1
2
3
4
5
6
7
8
9
10
11
12
13
curl -X POST "https://app.brandfound.ai/api/v1/companies" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Samsung",
  "description": "Samsung Electronics — мировой лидер в области электроники",
  "url": "https://samsung.com",
  "country": "South Korea",
  "synonyms": [
    "Samsung Electronics",
    "Самсунг"
  ]
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Samsung",
    "description": "Samsung Electronics — мировой лидер в области электроники",
    "url": "https://samsung.com",
    "categoryId": null,
    "country": "South Korea",
    "synonyms": [
      "Samsung Electronics",
      "Самсунг"
    ],
    "isAutoGenerationEnabled": true,
    "lastUsedAt": null,
    "createdAt": "2026-04-07T12:00:00.000Z",
    "updatedAt": "2026-04-07T12:00:00.000Z"
  }
}

Erfolgreiche Antwort

Unternehmen abrufen

/api/v1/companies/{id}

Liefert vollständige Unternehmensdaten einschließlich Produkte, Wettbewerber und Schlüsselwörter.

Anfrageparameter

idstring (uuid)erforderlich

Unternehmens-ID

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
GET/api/v1/companies/{id}
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/companies/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Samsung",
    "description": "Samsung Electronics — мировой лидер в области электроники",
    "url": "https://samsung.com",
    "categoryId": null,
    "country": "South Korea",
    "synonyms": [
      "Samsung Electronics",
      "Самсунг"
    ],
    "isAutoGenerationEnabled": true,
    "lastUsedAt": "2026-04-06T18:00:00.000Z",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-04-06T18:00:00.000Z",
    "products": [
      {
        "id": "prod-001",
        "name": "Galaxy S25",
        "description": "Flagship smartphone 2026",
        "url": "https://samsung.com/galaxy-s25",
        "keywords": [
          {
            "id": "kw-001",
            "text": "galaxy s25"
          }
        ],
        "competitors": [
          {
            "id": "comp-001",
            "name": "iPhone 16",
            "keywords": [
              {
                "id": "kw-002",
                "text": "iphone 16"
              }
            ]
          }
        ]
      }
    ],
    "competitors": [
      {
        "id": "comp-002",
        "name": "Apple",
        "url": "https://apple.com",
        "keywords": [
          {
            "id": "kw-003",
            "text": "apple"
          }
        ]
      }
    ],
    "keywords": [
      {
        "id": "kw-004",
        "text": "samsung"
      }
    ],
    "category": {
      "id": "cat-001",
      "name": "Электроника"
    }
  }
}

Erfolgreiche Antwort

Unternehmen aktualisieren

/api/v1/companies/{id}

Teilaktualisierung eines Unternehmens. Nur zu ändernde Felder senden. Regionalisierung: regionTargets definiert Messländer und -städte. Das primäre Ziel bestimmt Land und Sprache der automatischen Anfragegenerierung (POST /api/v1/queries/autogenerate). countryId/cityId stammen aus GET /api/v1/geo/countries bzw. /api/v1/geo/cities, defaultLanguageId aus /api/v1/geo/languages. regionTargets im Body ersetzt den VOLLSTÄNDIGEN Zustand; alte Ziele werden neu erstellt. isAutoGenerationEnabled ist veraltet: true wird IGNORIERT. Das Feld gehörte zu einem entfernten Scheduler, der Anfragen generierte und sofort kostenpflichtige Abfragen startete.

Anfrageparameter

idstring (uuid)erforderlich

Unternehmens-ID

Anfragetext

namestring
descriptionstring
urlstring
categoryIdstring
countrystring

ISO 3166-1 alpha-2 ("AE"). Alte Namen wie "russia" werden akzeptiert und normalisiert. regionTargets wird bevorzugt; dieses Feld ist veraltet.

synonymsstring[]
isAutoGenerationEnabledboolean

VERALTET; true wird IGNORIERT. Dieses Feld gehörte zu einem entfernten Scheduler, der Anfragen generierte und zugleich kostenpflichtige Abfragen startete. Generierung ohne Abfrage: POST /api/v1/queries/autogenerate.

regionTargetsobject[]

Messländer und -städte. VOLLSTÄNDIGER Zustand: alte Ziele werden neu erstellt. Das primäre Ziel bestimmt Land und Sprache der automatischen Anfragegenerierung.

defaultLanguageIdstring

Sprache generierter Anfragen (GET /api/v1/geo/languages).

defaultResponseLanguageIdstring

Sprache, in der das KI-System antworten soll.

defaultLocalestring

BCP-47, z.B. "ar-AE".

autogenQueryTypesstring[]

Typen automatisch generierter Anfragen. Standard: commercial, informational, comparative, reputational. Ohne comparative werden keine Vergleichsanfragen ("X vs Y") generiert.

autogenQueriesPerRuninteger

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
PUT/api/v1/companies/{id}
1
2
3
4
5
6
7
8
9
10
11
12
curl -X PUT "https://app.brandfound.ai/api/v1/companies/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Samsung Electronics",
  "description": "Updated description",
  "synonyms": [
    "Samsung",
    "Самсунг",
    "삼성"
  ]
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Samsung Electronics",
    "description": "Updated description",
    "url": "https://samsung.com",
    "categoryId": null,
    "country": "South Korea",
    "synonyms": [
      "Samsung",
      "Самсунг",
      "삼성"
    ],
    "isAutoGenerationEnabled": true,
    "lastUsedAt": "2026-04-06T18:00:00.000Z",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-04-07T14:00:00.000Z"
  }
}

Erfolgreiche Antwort

Unternehmen archivieren

/api/v1/companies/{id}

Archiviert ein Unternehmen. Die Daten bleiben erhalten, das Unternehmen verschwindet aus Listen.

Anfrageparameter

idstring (uuid)erforderlich

Unternehmens-ID

Antworten

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
DELETE/api/v1/companies/{id}
1
2
3
curl -X DELETE "https://app.brandfound.ai/api/v1/companies/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
// No Content

Erfolgreich gelöscht

Branchen auflisten

/api/v1/companies/categories

Zulässige categoryId-Werte beim Erstellen oder Aktualisieren eines Unternehmens.

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/companies/categories
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/companies/categories" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "name": "example_name"
    }
  ]
}

Erfolgreiche Antwort

Produkte

Produkte verwalten

Produkte auflisten

/api/v1/products

Liefert Produkte mit verknüpften Unternehmen, Schlüsselwörtern und Wettbewerbern.

Anfrageparameter

offsetinteger= 0

Offset für die Paginierung

limitinteger= 20

Einträge pro Seite

sortBystring= createdAt
createdAtupdatedAtname
sortOrderstring= desc

Sortierreihenfolge

ascdesc
companyIdstring (uuid)

Nach Unternehmen filtern

searchstring

Suchtext, ohne Beachtung der Groß-/Kleinschreibung

createdAtFromstring (date-time)

Beginn des Erstellungszeitraums (ISO 8601)

createdAtTostring (date-time)

Ende des Erstellungszeitraums (ISO 8601)

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/products
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/products" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "success": true,
  "data": [
    {
      "id": "prod-001",
      "name": "Galaxy S25",
      "description": "Flagship smartphone",
      "url": "https://samsung.com/galaxy-s25",
      "createdAt": "2026-02-01T10:00:00.000Z",
      "company": {
        "id": "comp-uuid",
        "name": "Samsung"
      },
      "keywords": [],
      "competitors": [
        {
          "id": "comp-001",
          "name": "iPhone 16"
        }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Erfolgreiche Antwort

Produkt erstellen

/api/v1/products

Erstellt ein neues Produkt für ein Unternehmen.

Anfragetext

namestringerforderlich
companyIdstringerforderlich
descriptionstring
urlstring

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/products
1
2
3
4
5
6
7
8
9
curl -X POST "https://app.brandfound.ai/api/v1/products" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Galaxy S25",
  "companyId": "clx1abc2d0001abcdef123456",
  "description": "Flagship smartphone 2026",
  "url": "https://samsung.com/galaxy-s25"
}'
1
2
3
4
5
6
7
8
9
10
11
12
{
  "success": true,
  "data": {
    "id": "prod-002",
    "name": "Galaxy S25",
    "description": "Flagship smartphone 2026",
    "url": "https://samsung.com/galaxy-s25",
    "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "createdAt": "2026-04-07T12:00:00.000Z",
    "updatedAt": "2026-04-07T12:00:00.000Z"
  }
}

Erfolgreiche Antwort

Produkt abrufen

/api/v1/products/{id}

Liefert vollständige Produktdaten einschließlich Schlüsselwörter und Wettbewerber.

Anfrageparameter

idstring (uuid)erforderlich

Produkt-ID

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
GET/api/v1/products/{id}
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/products/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
  "success": true,
  "data": {
    "id": "prod-001",
    "name": "Galaxy S25",
    "description": "Flagship smartphone 2026",
    "url": "https://samsung.com/galaxy-s25",
    "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-04-06T18:00:00.000Z",
    "company": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Samsung"
    },
    "keywords": [
      {
        "id": "kw-001",
        "text": "galaxy s25"
      }
    ],
    "competitors": [
      {
        "id": "comp-001",
        "name": "iPhone 16",
        "url": "https://apple.com/iphone-16",
        "keywords": [
          {
            "id": "kw-002",
            "text": "iphone 16"
          }
        ]
      }
    ]
  }
}

Erfolgreiche Antwort

Produkt aktualisieren

/api/v1/products/{id}

Teilaktualisierung eines Produkts.

Anfrageparameter

idstring (uuid)erforderlich

Produkt-ID

Anfragetext

namestring
descriptionstring
urlstring

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
PUT/api/v1/products/{id}
1
2
3
4
5
6
7
curl -X PUT "https://app.brandfound.ai/api/v1/products/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Galaxy S25 Ultra",
  "description": "Updated flagship"
}'
1
2
3
4
5
6
7
8
9
10
11
12
{
  "success": true,
  "data": {
    "id": "prod-001",
    "name": "Galaxy S25 Ultra",
    "description": "Updated flagship",
    "url": "https://samsung.com/galaxy-s25",
    "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-04-07T14:00:00.000Z"
  }
}

Erfolgreiche Antwort

Produkt archivieren

/api/v1/products/{id}

Archiviert ein Produkt. Die Daten bleiben erhalten, das Produkt verschwindet aus Listen.

Anfrageparameter

idstring (uuid)erforderlich

Produkt-ID

Antworten

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
DELETE/api/v1/products/{id}
1
2
3
curl -X DELETE "https://app.brandfound.ai/api/v1/products/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
// No Content

Erfolgreich gelöscht

Wettbewerber

Wettbewerber verwalten

Wettbewerber auflisten

/api/v1/competitors

Liefert Wettbewerber mit verknüpften Unternehmen, Produkten und Schlüsselwörtern.

Anfrageparameter

offsetinteger= 0

Offset für die Paginierung

limitinteger= 20

Einträge pro Seite

sortBystring= createdAt
createdAtupdatedAtname
sortOrderstring= desc

Sortierreihenfolge

ascdesc
companyIdstring (uuid)

Nach Unternehmen filtern

productIdstring (uuid)

Nach Produkt filtern

searchstring

Suchtext, ohne Beachtung der Groß-/Kleinschreibung

createdAtFromstring (date-time)

Beginn des Erstellungszeitraums (ISO 8601)

createdAtTostring (date-time)

Ende des Erstellungszeitraums (ISO 8601)

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/competitors
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/competitors" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "success": true,
  "data": [
    {
      "id": "comp-001",
      "name": "Apple",
      "url": "https://apple.com",
      "createdAt": "2026-01-20T10:00:00.000Z",
      "company": {
        "id": "comp-uuid",
        "name": "Samsung"
      },
      "product": null,
      "keywords": []
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Erfolgreiche Antwort

Wettbewerber erstellen

/api/v1/competitors

Erstellt einen Wettbewerber, der einem Unternehmen oder einem bestimmten Produkt zugeordnet werden kann.

Anfragetext

namestringerforderlich
companyIdstringerforderlich
productIdstring
urlstring

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/competitors
1
2
3
4
5
6
7
8
curl -X POST "https://app.brandfound.ai/api/v1/competitors" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Apple",
  "companyId": "clx1abc2d0001abcdef123456",
  "url": "https://apple.com"
}'
1
2
3
4
5
6
7
8
9
10
11
12
{
  "success": true,
  "data": {
    "id": "comp-003",
    "name": "Apple",
    "url": "https://apple.com",
    "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "productId": null,
    "createdAt": "2026-04-07T12:00:00.000Z",
    "updatedAt": "2026-04-07T12:00:00.000Z"
  }
}

Erfolgreiche Antwort

Wettbewerber abrufen

/api/v1/competitors/{id}

Liefert vollständige Wettbewerberdaten einschließlich Schlüsselwörter.

Anfrageparameter

idstring (uuid)erforderlich

Wettbewerber-ID

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
GET/api/v1/competitors/{id}
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/competitors/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "success": true,
  "data": {
    "id": "comp-001",
    "name": "Apple",
    "url": "https://apple.com",
    "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "productId": null,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-04-06T18:00:00.000Z",
    "company": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Samsung"
    },
    "product": null,
    "keywords": [
      {
        "id": "kw-003",
        "text": "apple"
      },
      {
        "id": "kw-005",
        "text": "apple inc"
      }
    ]
  }
}

Erfolgreiche Antwort

Wettbewerber aktualisieren

/api/v1/competitors/{id}

Aktualisiert den Namen und/oder die URL eines Wettbewerbers.

Anfrageparameter

idstring (uuid)erforderlich

Wettbewerber-ID

Anfragetext

namestring
urlstring

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
PUT/api/v1/competitors/{id}
1
2
3
4
5
6
7
curl -X PUT "https://app.brandfound.ai/api/v1/competitors/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Apple Inc.",
  "url": "https://www.apple.com"
}'
1
2
3
4
5
6
7
8
9
10
11
12
{
  "success": true,
  "data": {
    "id": "comp-001",
    "name": "Apple Inc.",
    "url": "https://www.apple.com",
    "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "productId": null,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-04-07T14:00:00.000Z"
  }
}

Erfolgreiche Antwort

Wettbewerber archivieren

/api/v1/competitors/{id}

Archiviert einen Wettbewerber. Die Daten bleiben erhalten, er verschwindet aus Listen.

Anfrageparameter

idstring (uuid)erforderlich

Wettbewerber-ID

Antworten

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
DELETE/api/v1/competitors/{id}
1
2
3
curl -X DELETE "https://app.brandfound.ai/api/v1/competitors/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
// No Content

Erfolgreich gelöscht

Keywords

Intents (keywords): erstellen, umbenennen, archivieren/löschen, wiederherstellen sowie gesammelt mit Unternehmen, Produkten oder Wettbewerbern verknüpfen bzw. lösen.

Suchintentionen auflisten

/api/v1/keywords

Liefert Intents (keywords) des aktuellen Workspaces. Als Ziel kann genau eines von companyId, productId oder competitorId dienen. state steuert den Archivfilter: active (Standard), archived oder all.

Anfrageparameter

offsetinteger= 0

Offset für die Paginierung

limitinteger= 20

Einträge pro Seite

sortBystring= createdAt
createdAtname
sortOrderstring= desc

Sortierreihenfolge

ascdesc
statestring= active

Statusfilter: active (nicht archiviert, Standard), archived (nur archiviert), all.

activearchivedall
searchstring

Teilzeichenfolge in name, ohne Beachtung der Groß-/Kleinschreibung.

companyIdstring (uuid)

Nur Intents mit aktiver Verknüpfung zu diesem Unternehmen.

productIdstring (uuid)

Nur Intents mit aktiver Verknüpfung zu diesem Produkt.

competitorIdstring (uuid)

Nur Intents mit aktiver Verknüpfung zu diesem Wettbewerber.

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/keywords
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/keywords" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "name": "example_name",
      "userId": "example_userId",
      "createdAt": "2026-01-15T12:00:00Z",
      "archivedAt": "2026-01-15T12:00:00Z",
      "companyKeywords": [
        {
          "id": "example_id",
          "companyId": "example_companyId",
          "company": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ],
      "productKeywords": [
        {
          "id": "example_id",
          "productId": "example_productId",
          "product": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ],
      "competitorKeywords": [
        {
          "id": "example_id",
          "competitorId": "example_competitorId",
          "competitor": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "limit": 1,
    "offset": 1,
    "hasMore": true
  }
}

Erfolgreiche Antwort

Suchintention erstellen oder wiederverwenden

/api/v1/keywords

Find-or-create anhand von (name, userId). Vorhandene Intents werden wiederverwendet und gegebenenfalls aus dem Archiv geholt. Optionales attach: genau eines von { companyId | productId | competitorId } verknüpft den Intent in derselben Transaktion mit dem Ziel.

Anfragetext

namestringerforderlich
attachobject

Ziel zum Verknüpfen/Lösen. Muss GENAU EINES der Felder enthalten.

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/keywords
1
2
3
4
5
6
7
8
9
curl -X POST "https://app.brandfound.ai/api/v1/keywords" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "best AI smartphone 2026",
  "attach": {
    "productId": "0d7e6b3f-1a2c-4f5e-9876-abcdef012345"
  }
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{
  "success": true,
  "data": {
    "keyword": {
      "id": "example_id",
      "name": "example_name",
      "userId": "example_userId",
      "createdAt": "2026-01-15T12:00:00Z",
      "archivedAt": "2026-01-15T12:00:00Z",
      "companyKeywords": [
        {
          "id": "example_id",
          "companyId": "example_companyId",
          "company": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ],
      "productKeywords": [
        {
          "id": "example_id",
          "productId": "example_productId",
          "product": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ],
      "competitorKeywords": [
        {
          "id": "example_id",
          "competitorId": "example_competitorId",
          "competitor": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ]
    },
    "attach": "..."
  }
}

Erfolgreiche Antwort

Suchintention abrufen

/api/v1/keywords/{id}

Liefert einen Intent mit aktiven Verknüpfungen zu Unternehmen, Produkten und Wettbewerbern.

Anfrageparameter

idstring (uuid)erforderlich

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
GET/api/v1/keywords/{id}
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/keywords/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
  "success": true,
  "data": {
    "id": "example_id",
    "name": "example_name",
    "userId": "example_userId",
    "createdAt": "2026-01-15T12:00:00Z",
    "archivedAt": "2026-01-15T12:00:00Z",
    "companyKeywords": [
      {
        "id": "example_id",
        "companyId": "example_companyId",
        "company": {
          "id": "example_id",
          "name": "example_name"
        }
      }
    ],
    "productKeywords": [
      {
        "id": "example_id",
        "productId": "example_productId",
        "product": {
          "id": "example_id",
          "name": "example_name"
        }
      }
    ],
    "competitorKeywords": [
      {
        "id": "example_id",
        "competitorId": "example_competitorId",
        "competitor": {
          "id": "example_id",
          "name": "example_name"
        }
      }
    ]
  }
}

Erfolgreiche Antwort

Suchintention umbenennen

/api/v1/keywords/{id}

Nur name kann bearbeitet werden. Archivierte Intents müssen vor dem Umbenennen wiederhergestellt werden.

Anfrageparameter

idstring (uuid)erforderlich

Anfragetext

namestringerforderlich

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
PUT/api/v1/keywords/{id}
1
2
3
4
5
6
curl -X PUT "https://app.brandfound.ai/api/v1/keywords/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "best AI smartphone 2026"
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
  "success": true,
  "data": {
    "id": "example_id",
    "name": "example_name",
    "userId": "example_userId",
    "createdAt": "2026-01-15T12:00:00Z",
    "archivedAt": "2026-01-15T12:00:00Z",
    "companyKeywords": [
      {
        "id": "example_id",
        "companyId": "example_companyId",
        "company": {
          "id": "example_id",
          "name": "example_name"
        }
      }
    ],
    "productKeywords": [
      {
        "id": "example_id",
        "productId": "example_productId",
        "product": {
          "id": "example_id",
          "name": "example_name"
        }
      }
    ],
    "competitorKeywords": [
      {
        "id": "example_id",
        "competitorId": "example_competitorId",
        "competitor": {
          "id": "example_id",
          "name": "example_name"
        }
      }
    ]
  }
}

Erfolgreiche Antwort

Suchintention archivieren oder löschen

/api/v1/keywords/{id}

Archiviert standardmäßig den Intent und alle Verknüpfungen (Soft-Delete), umkehrbar über POST /restore. ?permanent=true löscht ihn physisch aus der Datenbank; er muss bereits archiviert sein oder archivierte Verknüpfungen besitzen. ?dryRun=true liefert nur einen Bericht über betroffene Daten.

Anfrageparameter

idstring (uuid)erforderlich
permanentboolean= false

true löscht unwiderruflich aus der Datenbank. Archivzustand erforderlich.

dryRunboolean= false

true liefert nur einen Bericht ohne Änderungen.

Antworten

204

Erfolgreich gelöscht

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
DELETE/api/v1/keywords/{id}
1
2
3
curl -X DELETE "https://app.brandfound.ai/api/v1/keywords/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
{
  "success": true,
  "data": {
    "keywordId": "example_keywordId",
    "archivedAt": "2026-01-15T12:00:00Z",
    "archivedLinks": {
      "company": 0,
      "product": 0,
      "competitor": 0
    },
    "mode": "archive",
    "dryRun": true,
    "wouldArchive": {
      "keyword": true,
      "links": {
        "company": 0,
        "product": 0,
        "competitor": 0
      }
    },
    "wouldDelete": {
      "keyword": true,
      "links": {
        "company": 0,
        "product": 0,
        "competitor": 0
      },
      "mentionRefs": 0
    },
    "alreadyArchived": true,
    "keyword": {
      "id": "example_id",
      "name": "example_name",
      "userId": "example_userId",
      "createdAt": "2026-01-15T12:00:00Z",
      "archivedAt": "2026-01-15T12:00:00Z",
      "companyKeywords": [
        {
          "id": "example_id",
          "companyId": "example_companyId",
          "company": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ],
      "productKeywords": [
        {
          "id": "example_id",
          "productId": "example_productId",
          "product": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ],
      "competitorKeywords": [
        {
          "id": "example_id",
          "competitorId": "example_competitorId",
          "competitor": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ]
    }
  }
}

Erfolgreiche Antwort

Archivierte Suchintention wiederherstellen

/api/v1/keywords/{id}/restore

Entfernt archivedAt vom Keyword und seinen archivierten Verknüpfungen, sofern die übergeordneten Entitäten (company/product/competitor) noch bestehen. Verknüpfungen zu gelöschten Zielen bleiben archiviert.

Anfrageparameter

idstring (uuid)erforderlich

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/keywords/{id}/restore
1
2
3
curl -X POST "https://app.brandfound.ai/api/v1/keywords/{id}/restore" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
{
  "success": true,
  "data": {
    "keywordId": "example_keywordId",
    "restoredLinks": {
      "company": 0,
      "product": 0,
      "competitor": 0
    }
  }
}

Erfolgreiche Antwort

Suchintentionen gesammelt zuordnen

/api/v1/keywords/attach

Führt pro name find-or-create anhand von (name, userId) aus und stellt eine aktive Zielverknüpfung sicher. Archivierte Verknüpfungen werden wiederhergestellt. Genau eines von companyId/productId/competitorId ist erforderlich.

Anfragetext

targetobjecterforderlich

Ziel zum Verknüpfen/Lösen. Muss GENAU EINES der Felder enthalten.

namesstring[]erforderlich

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/keywords/attach
1
2
3
4
5
6
7
8
9
10
11
12
curl -X POST "https://app.brandfound.ai/api/v1/keywords/attach" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "productId": "0d7e6b3f-1a2c-4f5e-9876-abcdef012345"
  },
  "names": [
    "best 2026 AI phone",
    "battery life smartphone"
  ]
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "success": true,
  "data": {
    "target": {
      "companyId": "example_companyId",
      "productId": "example_productId",
      "competitorId": "example_competitorId"
    },
    "attached": [
      {
        "keywordId": "example_keywordId",
        "name": "example_name"
      }
    ],
    "alreadyAttached": [
      {
        "keywordId": "example_keywordId",
        "name": "example_name"
      }
    ],
    "reactivated": [
      {
        "keywordId": "example_keywordId",
        "name": "example_name"
      }
    ]
  }
}

Erfolgreiche Antwort

Zuordnungen von Suchintentionen gesammelt entfernen

/api/v1/keywords/detach

Archiviert aktive keyword↔target-Verknüpfungen. Der Intent bleibt bestehen und kann andere Ziele haben. Genau eines von companyId/productId/competitorId ist erforderlich.

Anfragetext

targetobjecterforderlich

Ziel zum Verknüpfen/Lösen. Muss GENAU EINES der Felder enthalten.

keywordIdsstring[]erforderlich

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/keywords/detach
1
2
3
4
5
6
7
8
9
10
11
curl -X POST "https://app.brandfound.ai/api/v1/keywords/detach" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "productId": "0d7e6b3f-1a2c-4f5e-9876-abcdef012345"
  },
  "keywordIds": [
    "7b2f1d4e-8c9a-4e5b-b6c2-3d7a1f8e9c4b"
  ]
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "success": true,
  "data": {
    "target": {
      "companyId": "example_companyId",
      "productId": "example_productId",
      "competitorId": "example_competitorId"
    },
    "detached": [
      "example"
    ],
    "notAttached": [
      "example"
    ]
  }
}

Erfolgreiche Antwort

Anfragen

Anfragen an KI-Assistenten verwalten

Anfragen auflisten

/api/v1/queries

Liefert Anfragen an KI-Assistenten mit Antwortanzahl. Erweiterte Filter nach Stimmung, Clustern, Regionen, Favoriten, Suchbereich und Wertebereichen der Stimmungsmetriken. Den Abfragestatus zeigen queue.status und answersCount. providers enthält die tatsächlich abgefragten KI-Systeme. Details einzelner Ausführungen: GET /api/v1/queries/queue.

Anfrageparameter

offsetinteger= 0

Offset für die Paginierung

limitinteger= 20

Einträge pro Seite

sortBystring= createdAt
createdAttextupdatedAt
sortOrderstring= desc

Sortierreihenfolge

ascdesc
companyIdstring (uuid)

Nach Unternehmen filtern

productIdstring (uuid)

Nach Produkt filtern

typestring

Anfragetyp (general, comparative, negative usw.). Mehrfachwerte: ?type=comparative&type=neutral

originstring

Anfrageursprung. Mehrfachwerte: ?origin=manual&origin=auto

manualauto
hasAnswersstring

Vorhandensein von Antworten

truefalse
languagestring

Anfragesprache (ru, en usw.). Mehrfachwerte: ?language=ru&language=en

searchTextstring

Im Anfragetext suchen

providerstring

Nach KI-Anbieter der Antwort filtern

sourceIdstring

Nach Antwortquellen-ID filtern. Mehrfachwerte: ?sourceId=id1&sourceId=id2

labelSlugstring

Nach Cluster-/Label-Slug filtern

regionstring

Anfrageregion. Mehrfachwerte: ?region=RU&region=US

isFavoritestring

Nur favorisierte Anfragen

truefalse
sentimentstring

Nach Stimmung der Erwähnungen in Antworten filtern

positiveneutralnegative
searchFieldstring= query

Suchbereich für searchText: Anfragetext, Antworten oder Quellen

queryanswersources
labelFilterModestring= or

Cluster-Filterlogik: any (or) oder all (and)

orand
labelstring

Cluster-Slug. Mehrfachwerte: ?label=slug1&label=slug2

createdAtFromstring (date-time)

Beginn des Erstellungszeitraums (ISO 8601)

createdAtTostring (date-time)

Ende des Erstellungszeitraums (ISO 8601)

showArchivedstring

Archivierte Anfragen anzeigen (Standard: false)

truefalse

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/queries
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/queries" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "success": true,
  "data": [
    {
      "id": "query-001",
      "text": "Какой лучший смартфон 2026 года?",
      "type": "comparative",
      "origin": "manual",
      "language": "ru",
      "region": "russia",
      "createdAt": "2026-04-01T10:00:00.000Z",
      "company": {
        "id": "comp-uuid",
        "name": "Samsung"
      },
      "product": {
        "id": "prod-001",
        "name": "Galaxy S25"
      },
      "_count": {
        "answers": 4
      }
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Erfolgreiche Antwort

Anfrage erstellen

/api/v1/queries

Erstellt eine Anfrage und reiht sie standardmäßig sofort zur Abfrage ein. Kostenpflichtig: Jede erhaltene Antwort jedes KI-Systems verbraucht FoxCoin (Preise: GET /api/v1/billing/balance). Eine Anfrage an fünf Systeme entspricht fünf Antworten. Mit dispatch: false wird nur die Anfrage erstellt, ohne FoxCoin auszugeben. providers wählt die KI-Systeme (Slugs: GET /api/v1/sources). Ohne Angabe gelten die Kontovorgaben, bei unkonfigurierten Konten ausschließlich ChatGPT. Für Massenerstellung mit Clustern: POST /api/v1/queries/setup. region (ISO 3166-1 alpha-2) und language legen die Region fest; ohne region gilt das Unternehmensland. geoOverride und resolvedGeoSnapshot sind schreibgeschützte Server-Snapshots für Clusteranfragen mit geografischen Zielen. Im POST-Body sind sie nicht erlaubt; unbekannte Felder ergeben400. Das Antwortfeld dispatch zeigt die Einreihung: dispatched=false mit nichtleerem error bedeutet, dass die Anfrage erstellt, aber die Abfrage nicht gestartet wurde.

Anfragetext

textstringerforderlich
companyIdstringerforderlich
productIdstring
typestring= neutral

Alte Werte werden akzeptiert: negative → reputational, general → neutral.

neutralcommercialinformationalcomparativereputationalbranded
languagestring= ru

ISO 639-1-Antwortsprache (ru, en, ar, hi, vi, ms, ...). Der Prompt enthält eine ausdrückliche Vorgabe mit dem Sprachnamen aus dem Verzeichnis. Standard: ru.

regionstring

Anfrageland, ISO 3166-1 alpha-2 (AE, SA, RU). Ohne Angabe gilt das primäre regionTarget des Unternehmens, danach RU. Alte Namen wie "russia" werden normalisiert. Kein geografisches Targeting der Ergebnisse; dient Filtern und Analysen.

providersstring[]

Abzufragende KI-Systeme. Ohne Angabe gelten die Kontovorgaben; bei unkonfigurierten Konten ausschließlich ChatGPT.

dispatchboolean= true

false erstellt die Anfrage OHNE kostenpflichtige Einreihung.

labelsstring[]

Clusternamen; Erstellung oder Wiederverwendung anhand des Slugs.

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
402application/json

Unzureichendes FoxCoin-Guthaben

HTTP_402
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/queries
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
curl -X POST "https://app.brandfound.ai/api/v1/queries" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "лучшие сервисы threat intelligence для банков",
  "companyId": "e08cf948-88b4-4aac-949e-6c1cc3b4f427",
  "type": "comparative",
  "language": "en",
  "region": "AE",
  "providers": [
    "chatgpt",
    "gemini",
    "perplexity"
  ]
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "success": true,
  "data": {
    "id": "8a5bd522-975a-4ba5-8974-04ac3785a69a",
    "text": "лучшие сервисы threat intelligence для банков",
    "type": "comparative",
    "origin": "manual",
    "language": "ru",
    "region": "RU",
    "companyId": "e08cf948-88b4-4aac-949e-6c1cc3b4f427",
    "productId": null,
    "providers": [
      "chatgpt",
      "perplexity",
      "gemini"
    ],
    "createdAt": "2026-08-04T12:00:00.000Z",
    "dispatch": {
      "dispatched": true,
      "providers": [
        "chatgpt",
        "perplexity",
        "gemini"
      ],
      "runStatus": "PENDING",
      "error": null
    }
  }
}

Erfolgreiche Antwort

Anfrage abrufen

/api/v1/queries/{id}

Liefert eine Anfrage mit KI-Antworten und gefundenen Erwähnungen.

Anfrageparameter

idstring (uuid)erforderlich

Anfrage-ID

includeAnswersstring= true

Antworten mit Erwähnungen einschließen (Standard: true)

truefalse

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
GET/api/v1/queries/{id}
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/queries/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
  "success": true,
  "data": {
    "id": "query-001",
    "text": "Какой лучший смартфон 2026 года?",
    "type": "comparative",
    "origin": "manual",
    "language": "ru",
    "region": "russia",
    "createdAt": "2026-04-01T10:00:00.000Z",
    "company": {
      "id": "comp-uuid",
      "name": "Samsung"
    },
    "product": null,
    "answers": [
      {
        "id": "ans-001",
        "content": "По мнению экспертов, Samsung Galaxy S25 Ultra и Apple iPhone 16 Pro...",
        "createdAt": "2026-04-01T10:01:00.000Z",
        "source": {
          "id": "src-001",
          "name": "ChatGPT",
          "type": "chatgpt"
        },
        "mentions": [
          {
            "id": "mention-001",
            "type": "company",
            "sentiment": 1,
            "position": 1,
            "context": "Samsung Galaxy S25 Ultra",
            "isOurs": true,
            "company": {
              "id": "comp-uuid",
              "name": "Samsung"
            },
            "product": null,
            "keywords": []
          }
        ]
      }
    ]
  }
}

Erfolgreiche Antwort

Anfrage archivieren

/api/v1/queries/{id}

Archiviert eine Anfrage. Die Daten bleiben erhalten und können wiederhergestellt werden.

Anfrageparameter

idstring (uuid)erforderlich

Anfrage-ID

Antworten

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
DELETE/api/v1/queries/{id}
1
2
3
curl -X DELETE "https://app.brandfound.ai/api/v1/queries/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
// No Content

Erfolgreich gelöscht

Abfrage ändern

/api/v1/queries/{id}

Ändert Text, Typ, Sprache, Region, Produkt, Favoritenstatus und Cluster einer Anfrage. Eine Textänderung löst KEINE neue KI-Abfrage aus; vorhandene Antworten bleiben verknüpft. Für eine erneute Abfrage erstellen Sie eine neue Anfrage. Strikter Body: unbekanntes Feld →400.

Anfrageparameter

idstring (uuid)erforderlich

Anfragetext

textstring
typestring
neutralcommercialinformationalcomparativereputationalbranded
languagestring
regionstring

ISO 3166-1 alpha-2.

productIdstring

null löst die Produktzuordnung.

isFavoriteboolean
labelsstring[]

VOLLSTÄNDIGE Clusterliste; Verknüpfungen werden neu aufgebaut.

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
PATCH/api/v1/queries/{id}
1
2
3
4
5
6
7
8
9
10
curl -X PATCH "https://app.brandfound.ai/api/v1/queries/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "region": "AE",
  "language": "en",
  "labels": [
    "Threat Intelligence"
  ]
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "success": true,
  "data": {
    "id": "example_id",
    "text": "example_text",
    "type": "neutral",
    "origin": "manual",
    "language": "example_language",
    "region": "example_region",
    "companyId": "example_companyId",
    "productId": "example_productId",
    "createdAt": "2026-01-15T12:00:00Z",
    "updatedAt": "2026-01-15T12:00:00Z",
    "providers": [
      "example"
    ],
    "answersCount": 1,
    "queue": {
      "pending": 1,
      "running": 1,
      "retrying": 1,
      "onHold": 1,
      "failed": 1,
      "cancelled": 1,
      "total": 1,
      "inQueue": 1,
      "status": "in_progress"
    }
  }
}

Erfolgreiche Antwort

Abfragen in der Warteschlange auflisten

/api/v1/queries/queue

Abfragestatus mit einer Ausführung je Anfrage-KI-Paar. Unterscheidet laufende, fehlgeschlagene und wegen Guthabenmangels pausierte Ausführungen; die Antwortanzahl allein genügt dafür nicht.

Anfrageparameter

statusstring= queued,onHold,failed

Statusgruppen, kommagetrennt. Standardmäßig alle drei.

companyIdstring (uuid)

Auf ein Unternehmen beschränken; ohne Angabe alle Kontounternehmen.

queryIdstring (uuid)

Ausführungen einer einzelnen Anfrage

providerstring

Nach KI-System filtern

chatgptgeminiperplexitygrokdeepseekgigachatyandex_alicealice_chatgoogle_ai_mode
includeArchivedboolean= false

Ausführungen archivierter Anfragen einschließen

limitinteger= 50

Seitengröße

offsetinteger= 0

Offset

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
GET/api/v1/queries/queue
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/queries/queue" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "queryId": "example_queryId",
      "queryText": "example_queryText",
      "companyId": "example_companyId",
      "provider": "chatgpt",
      "status": "PENDING",
      "attempts": 1,
      "maxAttempts": 1,
      "scheduledAt": "2026-01-15T12:00:00Z",
      "startedAt": "2026-01-15T12:00:00Z",
      "completedAt": "2026-01-15T12:00:00Z",
      "retryAfter": "2026-01-15T12:00:00Z",
      "answerId": "example_answerId",
      "error": "example_error"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 1,
    "offset": 1,
    "hasMore": true
  }
}

Erfolgreiche Antwort

Warteschlangenübersicht und Kostenschätzung

/api/v1/queries/queue/summary

Ausführungszähler, Kosten der aktuellen Warteschlange und FoxCoin-Guthaben in einer Anfrage. queuedTotal>0 bedeutet laufende Abfragen. onHold>0 bedeutet Guthabenmangel; diese Ausführungen starten auch nach einer Aufladung nicht automatisch neu.

Anfrageparameter

companyIdstring (uuid)

Auf ein Unternehmen beschränken

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
GET/api/v1/queries/queue/summary
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/queries/queue/summary" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "success": true,
  "data": {
    "pending": 1,
    "running": 1,
    "retrying": 1,
    "onHold": 1,
    "failed": 1,
    "cancelled": 1,
    "queuedTotal": 1,
    "queuedQueries": 1,
    "estimatedCostFc": 1,
    "balanceFc": 1,
    "costPerAnswerFc": 1,
    "billingEnabled": true
  }
}

Erfolgreiche Antwort

Abfragen mit ausgewählten KI-Modellen gesammelt erstellen

/api/v1/queries/setup

Erstellt Cluster und Abfragen in einer Transaktion und stellt sie sofort in die Abfragewarteschlange. Mit providers wählen Sie KI-Modelle explizit aus; ohne dieses Feld gelten die Kontoeinstellungen. Für eine einzelne Abfrage verwenden Sie POST /api/v1/queries, das ebenfalls providers akzeptiert. Kostenpflichtig: Jede empfangene Antwort jedes KI-Modells kostet FoxCoin (siehe GET /api/v1/billing/balance). Maximal 500 Abfragen pro Aufruf.

Anfragetext

companyIdstring

Ohne Angabe gilt preferredCompanyId des Schlüssels (GET /api/v1/context).

clusterIdstring

Bestehender Cluster zur Vererbung geografischer Einstellungen; gilt für alle clusters-Einträge ohne eigene clusterId.

providersstring[]

Abzufragende KI-Modelle (Slugs aus GET /api/v1/sources). Ohne dieses Feld gelten die Kontoeinstellungen; ein unkonfiguriertes Konto verwendet ChatGPT. Die Auswahl über providers wird auch von POST /api/v1/queries unterstützt.

clustersobject[]erforderlich

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
402application/json

Unzureichendes FoxCoin-Guthaben

HTTP_402
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/queries/setup
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
curl -X POST "https://app.brandfound.ai/api/v1/queries/setup" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "companyId": "e08cf948-88b4-4aac-949e-6c1cc3b4f427",
  "providers": [
    "chatgpt",
    "perplexity",
    "gemini"
  ],
  "clusters": [
    {
      "name": "Threat Intelligence",
      "queries": [
        {
          "text": "best threat intelligence vendors for banks in UAE. Answer in English.",
          "type": "comparative",
          "language": "en",
          "region": "AE"
        }
      ]
    }
  ]
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "success": true,
  "data": {
    "clustersCreated": 1,
    "queriesCreated": 1,
    "providerRunsCreated": 1,
    "dispatchError": "example_dispatchError",
    "clusters": [
      {
        "id": "example_id",
        "name": "example_name",
        "slug": "example_slug",
        "queryIds": [
          "example"
        ]
      }
    ]
  }
}

Erfolgreiche Antwort

Abfragen wieder in die Warteschlange stellen

/api/v1/queries/queue/resume

Setzt pausierte Ausführungen fort. **Warum:** Bei unzureichenden FoxCoin wird der Status ON_HOLD_NO_FUNDS gesetzt. Worker übernehmen solche Ausführungen nicht; Aufladen allein reaktiviert sie NICHT. Nach 45 Tagen setzt der Scheduler sie auf CANCELLED. Die Fortsetzung muss immer ausdrücklich über diese Methode erfolgen. **Ursache:** Anfragen wurden bei unzureichendem Guthaben erstellt. Die Prüfung erfolgt beim Einreihen und beim Ausführen; daher können Teile einer Anfrage bereits abgeschlossen und andere pausiert sein. Prüfung über `GET /api/v1/queries/queue/summary` → `onHold` oder queue.status=`on_hold_no_funds`. **402 ist kein endgültiger Fehler:** Das Guthaben reicht nicht für die gesamte Menge. Laden Sie auf oder wiederholen Sie mit `force: true`; bezahlbare Ausführungen laufen, die übrigen pausieren erneut.

Anfragetext

runIdsstring[]

Gezielt nach Ausführungs-IDs

scopestring

Alle pausierten Ausführungen

onHold
companyIdstring

Scope auf ein Unternehmen beschränken

forceboolean= false

Auch bei unzureichendem Guthaben für die gesamte Menge fortsetzen

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
402application/json

FoxCoin-Guthaben reicht nicht für die gesamte Menge

HTTP_402
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/queries/queue/resume
1
2
3
4
5
6
curl -X POST "https://app.brandfound.ai/api/v1/queries/queue/resume" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "scope": "onHold"
}'
1
2
3
4
5
6
{
  "success": true,
  "data": {
    "resumed": 1
  }
}

Erfolgreiche Antwort

Abfragen aus der Warteschlange entfernen

/api/v1/queries/queue/cancel

Storniert noch nicht begonnene Ausführungen: wartende (PENDING, RETRYING) und pausierte. RUNNING wird niemals verändert, da der Worker sie bereits verarbeitet und ein Abbruch zu Race Conditions führen könnte. **Anwendung:** Unnötige Massenabfragen vor der Abbuchung stoppen oder dauerhaft pausierte Reste entfernen. Gebühren entstehen erst mit Eingang einer Antwort; stornierte Ausführungen sind kostenlos. Der Abbruch ist umkehrbar: über `POST /api/v1/queries/queue/resume` mit der `runId` erneut einreihen.

Anfragetext

runIdsstring[]
queryIdsstring[]

Alle stornierbaren Ausführungen dieser Anfragen

scopestring

onHold: nur pausiert; queued: nur aktive Warteschlange

onHoldqueued
companyIdstring

Scope auf ein Unternehmen beschränken

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/queries/queue/cancel
1
2
3
4
5
6
7
curl -X POST "https://app.brandfound.ai/api/v1/queries/queue/cancel" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "scope": "queued",
  "companyId": "e08cf948-88b4-4aac-949e-6c1cc3b4f427"
}'
1
2
3
4
5
6
{
  "success": true,
  "data": {
    "cancelled": 1
  }
}

Erfolgreiche Antwort

Automatische Anfragen

Automatische Themenauswahl: Anfragen als Entwürfe generieren und freigeben. Generierung (1 FoxCoin pro Anfrage) und kostenpflichtige KI-Abfrage (10 FoxCoin pro Antwort) sind getrennte Schritte.

Abfragevorschläge ohne KI-Abfrage generieren

/api/v1/queries/autogenerate

Der Dienst erstellt passende Anfragen als ENTWÜRFE. KI-Systeme werden dabei NICHT abgefragt. Ersetzt isAutoGenerationEnabled, das Generierung und kostenpflichtige Abfrage untrennbar auslöste. Hier startet die Abfrage erst über POST /api/v1/query-drafts/approve. Kosten:1 FoxCoin pro tatsächlich geliefertem Anfrageentwurf. Abfragen kosten separat10 FoxCoin je Antwort (Anfrage × KI-System). Sprache/Land: Ohne language/region gelten die Unternehmenseinstellungen (regionTargets, PUT /api/v1/companies/{id}), danach ru/RU. Für mehrere Länder targets angeben: eine Aufgabe pro Land, standardmäßig dessen Amtssprache (AE→ar, IN→hi). Typen: Ohne types gilt Company.autogenQueryTypes, standardmäßig commercial, informational, comparative, reputational. Vergleiche „X vs Y“ entstehen nur, wenn comparative ausgewählt und Wettbewerber angelegt sind. Standardmäßig sofortige 202-Antwort, Generierung im Hintergrund. Fortschritt über GET derselben Adresse mit clientToken. Kurzform region/language/city/includeDistricts und targets schließen sich aus. Gemeinsam ergeben sie400, da außerhalb von targets keine Zuordnung einer Stadt zu einem einzelnen Land möglich ist.

Anfragetext

companyIdstring

Ohne Angabe gilt preferredCompanyId des Schlüssels.

productIdstring
countintegererforderlich

Anzahl zu generierender Anfragen PRO Ziel.1 FoxCoin je Anfrage.

typesstring[]

Anfragetypen; count wird gleichmäßig verteilt. Ohne Angabe gilt Company.autogenQueryTypes, standardmäßig einschließlich comparative.

clustersstring[]

Themen zur Gruppierung der Anfragen.

userWishesstring
namestring

Aufgabenname, sichtbar im UI und in GET.

languagestring

ISO 639-1. Ohne Angabe Unternehmenssprache. Nur OHNE targets.

regionstring

ISO 3166-1 alpha-2. Ohne Angabe primäres Unternehmensland aus regionTargets, danach RU. Alte Namen wie "russia" erlaubt. Nur OHNE targets.

citystring

Nur OHNE targets.

includeDistrictsboolean

Nur OHNE targets.

targetsobject[]

Mehrländermessung: eine Aufgabe pro Land. Kosten entsprechen der Summe aller target-count-Werte. Schließt die Kurzform aus: region/language/city/includeDistricts neben targets →400. Innerhalb von targets besitzt jedes Land eigene Stadt- und Spracheinstellungen.

waitboolean= false

true wartet bis zur abgeschlossenen Generierung. Nur für kleine Mengen; 100+ Anfragen können Minuten dauern.

clientTokenstring

Eigener Aufgabenmarker zum späteren Abruf des Fortschritts.

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
402application/json

Unzureichende FoxCoin; required und balance stehen im Fehler-Body.

HTTP_402
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
503application/json

Automatische Generierung ist serverseitig nicht konfiguriert.

HTTP_503
POST/api/v1/queries/autogenerate
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
curl -X POST "https://app.brandfound.ai/api/v1/queries/autogenerate" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "companyId": "e08cf948-88b4-4aac-949e-6c1cc3b4f427",
  "count": 50,
  "types": [
    "commercial",
    "informational",
    "comparative"
  ],
  "clusters": [
    "Threat Intelligence",
    "Endpoint Protection"
  ],
  "targets": [
    {
      "region": "AE"
    },
    {
      "region": "IN"
    },
    {
      "region": "RU",
      "language": "ru"
    }
  ]
}'
1
2
3
4
{
  "success": true,
  "data": {}
}

Erfolgreiche Antwort

Status der Abfragegenerierung

/api/v1/queries/autogenerate

Fortschritt der über POST /api/v1/queries/autogenerate gestarteten Aufgaben. Bis status=OK abfragen, anschließend Entwürfe über GET /api/v1/query-drafts laden. Entwürfe laufender Aufgaben (RUNNING) können absichtlich noch nicht freigegeben werden, damit keine halbfertige Menge bestätigt wird.

Anfrageparameter

runIdstring (uuid)

Bestimmte Aufgabe.

clientTokenstring

Aufgabe anhand des Client-Markers aus der POST-Antwort.

limitinteger= 20

Anzahl der zuletzt erstellten Aufgaben.

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
GET/api/v1/queries/autogenerate
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/queries/autogenerate" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "name": "example_name",
      "status": "PENDING",
      "requested": 1,
      "generated": 1,
      "companyId": "example_companyId",
      "productId": "example_productId",
      "clientToken": "example_clientToken",
      "language": "example_language",
      "region": "example_region",
      "city": "example_city",
      "types": [
        "example"
      ],
      "clusters": [
        "example"
      ],
      "createdAt": "2026-01-15T12:00:00Z",
      "completedAt": "2026-01-15T12:00:00Z",
      "error": "example_error"
    }
  ]
}

Erfolgreiche Antwort

Abfragegenerierung stoppen

/api/v1/queries/autogenerate/cancel

Echter Abbruch: Nicht gestartete Teilmengen werden nicht ausgeführt; berechnet werden nur bereits gelieferte Entwürfe. Der Lauf wird CANCELLED. Vorhandene Entwürfe bleiben erhalten und können freigegeben werden.

Anfragetext

runIdstringerforderlich

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/queries/autogenerate/cancel
1
2
3
4
5
6
curl -X POST "https://app.brandfound.ai/api/v1/queries/autogenerate/cancel" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "runId": "8a5bd522-975a-4ba5-8974-04ac3785a69a"
}'
1
2
3
4
5
6
{
  "success": true,
  "data": {
    "cancelled": true
  }
}

Erfolgreiche Antwort

Abfrageentwürfe auflisten

/api/v1/query-drafts

Entwürfe sind kostenlos speicherbar und lösen keine Abfrage aus. Erst POST /api/v1/query-drafts/approve macht daraus Anfragen.

Anfrageparameter

statusstring

PENDING wartet auf eine Entscheidung. Standardmäßig alle.

PENDINGAPPROVEDREJECTEDEXPIRED
companyIdstring (uuid)

Nach Unternehmen filtern.

typestring

Nach Anfragetyp filtern.

neutralcommercialinformationalcomparativereputationalbranded
pageinteger= 1

Seitennummer ab 1.

limitinteger= 50

Seitengröße.

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
GET/api/v1/query-drafts
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/query-drafts" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "success": true,
  "data": {
    "drafts": [
      {
        "id": "example_id",
        "text": "example_text",
        "type": "neutral",
        "language": "example_language",
        "region": "example_region",
        "labels": [
          "example"
        ],
        "companyId": "example_companyId",
        "companyName": "example_companyName",
        "productId": "example_productId",
        "productName": "example_productName",
        "generationRunId": "example_generationRunId",
        "taskName": "example_taskName",
        "status": "PENDING",
        "createdAt": "2026-01-15T12:00:00Z"
      }
    ],
    "total": 1,
    "counts": {}
  }
}

Erfolgreiche Antwort

Entwürfe bestätigen und Abfragen starten

/api/v1/query-drafts/approve

KOSTENPFLICHTIGER SCHRITT: Freigegebene Entwürfe werden Anfragen und an ausgewählte KI-Systeme gesendet:10 FoxCoin je Antwort (Anfrage × System).50 Entwürfe ×3 Systeme =150 Antworten =1500 FoxCoin. Zuerst mit dryRun:true aufrufen und dem Nutzer die Kostenschätzung zeigen. Idempotent: Wiederholte Aufrufe mit denselben draftIds erzeugen keine doppelten Anfragen und fragen nicht erneut ab. Entwürfe laufender Generierungsaufgaben werden als skippedRunning übersprungen; warten Sie auf status=OK.

Anfragetext

draftIdsstring[]erforderlich
providersstring[]erforderlich

Abzufragende KI-Systeme. Jedes erhöht die Kosten entsprechend.

dryRunboolean

true liefert nur eine Schätzung, ohne Erstellung oder Abbuchung.

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
402application/json

Unzureichende FoxCoin; required und balance stehen im Fehler-Body.

HTTP_402
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/query-drafts/approve
1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl -X POST "https://app.brandfound.ai/api/v1/query-drafts/approve" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "draftIds": [
    "8a5bd522-975a-4ba5-8974-04ac3785a69a"
  ],
  "providers": [
    "chatgpt",
    "gemini",
    "perplexity"
  ],
  "dryRun": true
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "success": true,
  "data": {
    "dryRun": true,
    "toApprove": 1,
    "estimatedAnswersCostFc": 1,
    "approved": 1,
    "createdQueries": 1,
    "skippedDuplicates": 1,
    "skippedRunning": 1,
    "dispatch": {},
    "balance": 1
  }
}

Erfolgreiche Antwort

Entwürfe ablehnen

/api/v1/query-drafts/reject

Weiche Ablehnung: Der Entwurf bleibt für Abrechnungsprüfungen als REJECTED gespeichert. Keine Abfrage wird ausgeführt. Generierungsgebühren werden nicht erstattet, da die Fragen bereits erstellt wurden.

Anfragetext

draftIdsstring[]erforderlich

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/query-drafts/reject
1
2
3
4
5
6
7
8
curl -X POST "https://app.brandfound.ai/api/v1/query-drafts/reject" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "draftIds": [
    "8a5bd522-975a-4ba5-8974-04ac3785a69a"
  ]
}'
1
2
3
4
5
6
{
  "success": true,
  "data": {
    "rejected": 1
  }
}

Erfolgreiche Antwort

KI-Antworten

KI-Antworten gesammelt abrufen: Links, Erwähnungen und Stimmung.

KI-Antworten gesammelt abrufen

/api/v1/answers

Ersetzt einzelne GET /api/v1/queries/{id}-Aufrufe: bis zu 200 Antworten pro Seite mit Links, Erwähnungen und Stimmung. links enthält aufbereitete Zitate JEDES KI-Systems. Nicht mit answer.sources verwechseln: Das rohe Scraper-Payload ist nur bei Alice Search befüllt und keine Zitatliste. brandDomainCited zeigt, ob die Unternehmensdomain zitiert wurde. Erwähnungsfelder: position ist der ZEICHENOFFSET im Antworttext. Das Array ist danach sortiert; die Nennungsreihenfolge ist der RANG im Array, nicht position selbst. sentiment (1/0/-1) und sentimentScore (-1..1) stammen aus der Stimmung der GESAMTEN Antwort und sind für deren Erwähnungen identisch. sentimentScore=null, wenn noch keine Analyse vorliegt. isOurs=false bedeutet Wettbewerber. Array-Parameter werden wiederholt: ?companyId=a&companyId=b.

Anfrageparameter

companyIdstring[]

Unternehmen, mehrere möglich.

productIdstring[]

Produkte, mehrere möglich.

queryIdstring[]

Nur Antworten dieser Anfragen.

sourceIdstring[]

KI-Systeme nach ID (GET /api/v1/sources).

providerstring[]

KI-Systeme nach Slug.

typestring[]

Typ der zugehörigen Anfrage.

labelstring[]

Cluster-Slugs.

regionstring[]

Anfrageregion, ISO 3166-1 alpha-2. Alte Regionsnamen werden ebenfalls erkannt.

languagestring[]

Anfragesprache.

createdAtFromstring (date-time)

Erstellungsdatum der ANTWORT, ab (ISO 8601).

createdAtTostring (date-time)

Erstellungsdatum der ANTWORT, bis (ISO 8601).

hasLinksboolean

true: nur Antworten mit Links; false: nur ohne.

mentionsOursboolean

true: nur Antworten mit Erwähnung der Unternehmensmarke.

showArchivedboolean= false

true: Antworten archivierter Anfragen einschließen.

includestring= content,tonality

Zusätzliche Inhalte, kommagetrennt: content, links, mentions, tonality.

limitinteger= 50

Seitengröße.

offsetinteger= 0

Offset.

sortBystring= createdAt

Sortierfeld.

createdAtdate
sortOrderstring= desc

Sortierrichtung.

ascdesc

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
GET/api/v1/answers
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/answers" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "createdAt": "2026-01-15T12:00:00Z",
      "date": "2026-01-15T12:00:00Z",
      "query": {
        "id": "example_id",
        "text": "example_text",
        "type": "example_type",
        "language": "example_language",
        "region": "example_region",
        "archived": true,
        "labels": [
          {}
        ]
      },
      "company": {},
      "product": {},
      "source": {
        "id": "example_id",
        "name": "example_name",
        "type": "example_type"
      },
      "mentionsCount": 1,
      "ourMentionsCount": 1,
      "linksCount": 1,
      "brandDomainCited": true,
      "content": "example_content",
      "links": [
        {
          "url": "example_url",
          "title": "example_title",
          "domain": "example_domain",
          "position": 1,
          "inAnswer": true,
          "inSources": true,
          "context": "example_context"
        }
      ],
      "mentions": [
        {
          "id": "example_id",
          "isOurs": true,
          "type": "example_type",
          "position": 1,
          "sentiment": 1,
          "sentimentLabel": "example_sentimentLabel",
          "sentimentScore": 1,
          "context": "example_context",
          "isLink": true,
          "linkUrl": "example_linkUrl",
          "linkDomain": "example_linkDomain"
        }
      ]
    }
  ]
}

Erfolgreiche Antwort

Geografie

Verzeichnisse für Länder, Regionen, Städte und Sprachen.

Länder auflisten

/api/v1/geo/countries

Verzeichnis-IDs werden für regionTargets und defaultLanguageId von Unternehmen/Clustern verwendet; iso2 für region bei Anfragen und Autogenerierung.

Anfrageparameter

qstring

Nach Name suchen.

continentstring

Nach Kontinent filtern.

EUROPEASIANORTH_AMERICASOUTH_AMERICAAFRICAOCEANIAANTARCTICA
limitinteger= 250

Maximale Eintragsanzahl.

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
GET/api/v1/geo/countries
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/geo/countries" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "success": true,
  "data": {
    "data": [
      {
        "id": "example_id",
        "iso2": "example_iso2",
        "iso3": "example_iso3",
        "nameRu": "example_nameRu",
        "nameEn": "example_nameEn",
        "flagEmoji": "example_flagEmoji",
        "defaultLanguage": "example_defaultLanguage",
        "defaultTimezone": "example_defaultTimezone",
        "continent": "example_continent"
      }
    ],
    "total": 1
  }
}

Erfolgreiche Antwort

Regionen eines Landes auflisten

/api/v1/geo/regions

Regionen (Bundesländer, Provinzen) eines Landes. countryId oder countryIso2 ist erforderlich.

Anfrageparameter

countryIso2string

Zweistelliger Ländercode.

countryIdstring (uuid)

Länder-UUID.

qstring

Nach Name suchen.

limitinteger= 100

Maximale Eintragsanzahl.

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
GET/api/v1/geo/regions
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/geo/regions" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
{
  "success": true,
  "data": {}
}

Erfolgreiche Antwort

Städte eines Landes auflisten

/api/v1/geo/cities

Städte eines Landes. countryId oder countryIso2 erforderlich. cityId wird in regionTargets des Unternehmens und targets des Clusters verwendet.

Anfrageparameter

countryIso2string

Zweistelliger Ländercode.

countryIdstring (uuid)

Länder-UUID.

regionIdstring (uuid)

Regions-UUID.

qstring

Nach Name suchen.

limitinteger= 50

Maximale Eintragsanzahl.

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
GET/api/v1/geo/cities
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/geo/cities" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
{
  "success": true,
  "data": {}
}

Erfolgreiche Antwort

Sprachen auflisten

/api/v1/geo/languages

Verzeichnis-IDs werden für regionTargets und defaultLanguageId von Unternehmen/Clustern verwendet; iso2 für region bei Anfragen und Autogenerierung.

Anfrageparameter

qstring

Nach Name oder Code suchen.

limitinteger= 200

Maximale Eintragsanzahl.

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
GET/api/v1/geo/languages
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/geo/languages" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "success": true,
  "data": {
    "data": [
      {
        "id": "example_id",
        "iso639_1": "example_iso639_1",
        "nameNative": "example_nameNative",
        "nameEn": "example_nameEn"
      }
    ],
    "total": 1
  }
}

Erfolgreiche Antwort

Abfrage-Cluster

Anfrage-Tags und Cluster: Auflistung mit optionalem Unternehmensfilter sowie Erstellung mit regionalen Einstellungen.

Abfragecluster auflisten

/api/v1/query-labels

Liefert Anfrage-Tags/Cluster des aktuellen Workspaces mit Anfragezahlen. companyId beschränkt auf Cluster mit Anfragen dieses Unternehmens; queryCount zählt nur dessen Anfragen. lite=true liefert { items: [{ id, name, slug, queryCount }] } ohne Statistiken und sampleQueries.

Anfrageparameter

companyIdstring (uuid)

Unternehmensfilter: nur Cluster mit dessen Anfragen; queryCount zählt nur diese Anfragen.

litestring

lite=true liefert { items: [{ id, name, slug, queryCount }] } ohne Statistiken.

truefalse
offsetinteger= 0

Offset für die Paginierung

limitinteger= 20

Einträge pro Seite

qstring

Teilzeichenfolge im Tag-Namen, unabhängig von Groß-/Kleinschreibung.

sortstring= queryCount:desc

Sortierung im Format field:direction.

queryCount:descqueryCount:ascname:ascname:desccreatedAt:desccreatedAt:asclastUsedAt:desclastUsedAt:asc
hasQueriesstring

with: nur Cluster mit Anfragen; without: nur leere Cluster.

withwithout
minCountinteger

Mindestzahl an Anfragen im Cluster.

maxCountinteger

Höchstzahl an Anfragen im Cluster.

createdFromstring (date-time)

Tags, die frühestens an diesem Datum erstellt wurden.

createdTostring (date-time)

Tags, die spätestens an diesem Datum erstellt wurden.

lastUsedFromstring (date-time)

Tags mit lastUsedAt frühestens an diesem Datum.

lastUsedTostring (date-time)

Tags mit lastUsedAt spätestens an diesem Datum.

includestring

include=targets lädt geografische Cluster-Ziele (country/city) hinzu.

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/query-labels
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/query-labels" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "example_id",
        "name": "example_name",
        "slug": "example_slug",
        "createdAt": "2026-01-15T12:00:00Z",
        "lastUsedAt": "2026-01-15T12:00:00Z",
        "queryCount": 1,
        "lastQueryAt": "2026-01-15T12:00:00Z"
      }
    ],
    "totalCount": 1,
    "pageInfo": {
      "limit": 1,
      "offset": 1,
      "hasMore": true
    },
    "stats": {},
    "filters": {}
  }
}

Erfolgreiche Antwort

Regionalen Abfragecluster erstellen oder aktualisieren

/api/v1/query-labels

Find-or-create anhand von (slug, userId). Ein vorhandener Cluster wird aktualisiert (Name, geografische Einstellungen), targets werden neu erstellt. Optionale companyId/productId werden akzeptiert, aber noch nicht in QueryLabel gespeichert.

Anfragetext

namestringerforderlich
slugstring
descriptionstring
companyIdstring
productIdstring
defaultLanguageIdstring
defaultLocalestring
defaultResponseLanguageIdstring
geoScopestring
GLOBALCOUNTRYREGIONCITY
injectLocationModestring
NONEAPPEND_PARENSAPPEND_NATURALPREPENDAI_REWRITE
autogenStrategystring
SHAREDPER_TARGETPER_TARGET_LOCALIZED
targetsobject[]

Antworten

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
409application/json

Konflikt: Ressource existiert bereits.

CONFLICT
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/query-labels
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl -X POST "https://app.brandfound.ai/api/v1/query-labels" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Example",
  "slug": "",
  "description": "",
  "companyId": "",
  "productId": "",
  "defaultLanguageId": "",
  "defaultLocale": "",
  "defaultResponseLanguageId": "",
  "geoScope": "GLOBAL",
  "injectLocationMode": "NONE",
  "autogenStrategy": "SHARED",
  "targets": null
}'
1
2
3
4
5
6
7
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validierungsfehler der Eingabedaten"
  }
}

Validierungsfehler der Eingabedaten

Erwähnungen

Markenerwähnungen anzeigen

Erwähnungen auflisten

/api/v1/mentions

Liefert Markenerwähnungen in KI-Antworten mit vollständigem Kontext.

Anfrageparameter

offsetinteger= 0

Offset für die Paginierung

limitinteger= 20

Einträge pro Seite

sortBystring= createdAt
createdAtpositionsentiment
sortOrderstring= desc

Sortierreihenfolge

ascdesc
timeRangestring

Zeitraum

24h7d30d90dall
createdAtFromstring (date-time)

Beginn des Erstellungszeitraums (ISO 8601)

createdAtTostring (date-time)

Ende des Erstellungszeitraums (ISO 8601)

companyIdstring (uuid)

Nach Unternehmen filtern

productIdstring (uuid)

Nach Produkt filtern

competitorIdstring (uuid)

Nach Wettbewerber filtern

answerIdstring (uuid)

Nach bestimmter Antwort filtern

typestring

Erwähnungstyp

companyproductkeywordcompetitor
sentimentstring

Stimmung

positiveneutralnegative
searchstring

Suchtext, ohne Beachtung der Groß-/Kleinschreibung

isOursstring

Nur eigene Marke (true) oder nur Wettbewerber (false)

truefalse

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/mentions
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/mentions" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{
  "success": true,
  "data": [
    {
      "id": "mention-001",
      "type": "company",
      "sentiment": 1,
      "position": 1,
      "context": "Samsung Galaxy S25 Ultra является одним из лучших смартфонов...",
      "isOurs": true,
      "createdAt": "2026-04-01T10:01:00.000Z",
      "answer": {
        "id": "ans-001",
        "content": "По мнению экспертов...",
        "createdAt": "2026-04-01T10:01:00.000Z",
        "source": {
          "id": "src-001",
          "name": "ChatGPT",
          "type": "chatgpt"
        },
        "query": {
          "id": "query-001",
          "text": "Какой лучший смартфон?",
          "type": "comparative"
        }
      },
      "company": {
        "id": "comp-uuid",
        "name": "Samsung"
      },
      "product": null,
      "competitor": null,
      "keywords": []
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Erfolgreiche Antwort

Analytik

Analysen: Wettbewerber, Stimmung, Links und Markensichtbarkeit

Wettbewerbsanalytik

/api/v1/analytics/competitors

Umfassender Vergleich Ihres Unternehmens mit Wettbewerbern anhand von KI-Erwähnungen. Filter nach Cluster-Slugs, KI-Anbietern und Zeitraum.

Anfrageparameter

timeRangestring= 30d

Zeitraum

24h7d30dall
fromstring (date-time)

Beginn des benutzerdefinierten Zeitraums (ISO 8601)

tostring (date-time)

Ende des benutzerdefinierten Zeitraums (ISO 8601)

companyIdstring (uuid)

Unternehmens-ID

productIdstring (uuid)

Produkt-ID

sourceIdstring[]

KI-Anbieter-IDs

labelIdstring[]

Cluster-/Label-IDs

labelSlugstring

Cluster-Slug. Mehrfachwerte: ?labelSlug=slug1&labelSlug=slug2

labelFilterModestring= or

Label-Filtermodus

orand
includeDemostring

Demodaten einschließen

truefalse

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/analytics/competitors
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/competitors" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
{
  "success": true,
  "data": {
    "ourCompany": {
      "name": "Samsung",
      "mentions": 150,
      "mentionsBrand": 120,
      "mentionsLink": 30,
      "sentiment": 0.72,
      "brandMentionRate": 0.8
    },
    "competitors": [
      {
        "name": "Apple",
        "mentions": 180,
        "mentionsBrand": 160,
        "mentionsLink": 20,
        "sentiment": 0.65,
        "categories": [],
        "brandMentionRate": 0.89
      }
    ],
    "overall": {
      "ourMentions": 150,
      "competitorMentions": 180,
      "leader": "Apple"
    },
    "productBreakdown": [],
    "sourceBreakdown": [
      {
        "name": "ChatGPT",
        "ourAnswers": 50,
        "ourMentions": 80,
        "competitorBreakdown": [],
        "totalAnswers": 120
      }
    ],
    "shareOfVoice": {
      "ourCompany": 0.45,
      "competitors": [
        {
          "name": "Apple",
          "share": 0.55
        }
      ],
      "totalAnswers": 200
    },
    "exclusiveBreakdown": {
      "onlyUs": 60,
      "shared": 40,
      "onlyCompetitors": 50,
      "total": 150,
      "byCompetitor": []
    },
    "timeline": [
      {
        "date": "2026-04-01",
        "ourMentions": 10,
        "competitorMentions": 12,
        "totalAnswers": 30
      }
    ]
  }
}

Erfolgreiche Antwort

Erwähnungsvorschau

/api/v1/analytics/competitors/preview

Liefert einzelne KI-Antworten mit Erwähnungen zur Detailanalyse. Unterstützt Clusterfilter, Demodaten, benutzerdefinierte Zeiträume und Label-Filterlogik. companyId ist erforderlich, damit Kontounternehmen nicht zusammengefasst werden. Fehlt der Parameter, gilt preferredCompanyId des Schlüssels (GET /api/v1/context).

Anfrageparameter

sidestringerforderlich

Seite: eigenes Unternehmen oder Wettbewerber

ourcompetitor
competitorNamestring

Wettbewerbername (bei side=competitor)

mentionTypestring= both

Erwähnungstyp

brandlinkboth
offsetinteger= 0

Offset für die Paginierung

limitinteger= 20

Einträge pro Seite

timeRangestring
24h7d30dall
companyIdstring (uuid)
productIdstring (uuid)
sourceIdstring[]
labelIdstring[]
includeMentionsstring

Erwähnungen in die Antwort aufnehmen

truefalse
includeDemostring

Demodaten einschließen

truefalse
labelFilterModestring= or

Cluster-Filterlogik

orand
fromstring (date-time)

Zeitraumbeginn (ISO 8601)

tostring (date-time)

Zeitraumende (ISO 8601)

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/analytics/competitors/preview
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/competitors/preview" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "mention-001",
        "isOurs": true,
        "type": "company",
        "sentiment": 1,
        "position": 1,
        "context": "Samsung Galaxy S25 Ultra",
        "company": {
          "id": "c1",
          "name": "Samsung"
        },
        "product": null,
        "competitor": null,
        "answer": {
          "id": "ans-001",
          "content": "По мнению экспертов...",
          "source": {
            "name": "ChatGPT",
            "type": "chatgpt"
          }
        }
      }
    ],
    "total": 1,
    "offset": 0,
    "limit": 20,
    "hasMore": false
  }
}

Erfolgreiche Antwort

Tonalitätsanalytik

/api/v1/analytics/tonality

Umfassende Stimmungsanalyse von KI-Antworten: Qualitätsmetriken, Zeitverlauf sowie problematische und beste Antworten.

Anfrageparameter

timeRangestring= 30d
24h7d30d90d
companyIdstring (uuid)
productIdstring (uuid)
queryTypestring

Anfragetyp

neutralcomparativenegative
sentimentstring

Nach Stimmung filtern

positiveneutralnegative
sourceIdstring[]

KI-Anbieter

labelSlugstring[]

Cluster/Labels nach Slug

labelFilterModestring= or
orand
fromstring (date-time)
tostring (date-time)
includeDemostring
truefalse

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/analytics/tonality
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/tonality" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
  "success": true,
  "data": {
    "summary": {
      "totalAnswers": 200,
      "avgOverallScore": 7.5,
      "sentimentDistribution": {
        "positive": 120,
        "neutral": 50,
        "negative": 30
      }
    },
    "metrics": {
      "relevanceToBrand": 8.2,
      "factualityConfidence": 7.8,
      "helpfulness": 7.5,
      "preferenceForBrand": 6.9,
      "recommendationStrength": 7.1,
      "fairness": 8,
      "evidenceSupport": 7.3,
      "informativeness": 7.6,
      "completeness": 7.4,
      "impactOnBrand": 7
    },
    "timeline": [
      {
        "date": "2026-04-01",
        "positive": 10,
        "neutral": 5,
        "negative": 2,
        "avgScore": 7.8,
        "count": 17
      }
    ],
    "topSources": [
      {
        "sourceName": "ChatGPT",
        "count": 80,
        "avgScore": 7.9
      }
    ],
    "queryTypes": [
      {
        "type": "neutral",
        "count": 100,
        "avgScore": 7.8,
        "positive": 70,
        "neutral": 20,
        "negative": 10
      }
    ],
    "problematicAnswers": [],
    "bestAnswers": [],
    "brandAnalytics": {
      "monthlyTrend": [],
      "correlations": [],
      "insights": []
    }
  }
}

Erfolgreiche Antwort

Link-Analytik

/api/v1/analytics/links

Linkanalyse aus KI-Antworten: Top-Domains, Zitate nach Anbieter und Zeitverlauf. Filter nach Stimmung, Clustern, Anfragetyp, Impact-/Overall-Score-Schwellen und benutzerdefiniertem Zeitraum. companyId ist erforderlich, damit Kontounternehmen nicht zusammengefasst werden. Fehlt der Parameter, gilt preferredCompanyId des Schlüssels (GET /api/v1/context).

Anfrageparameter

timeRangestring
24h7d30dall
companyIdstring (uuid)
productIdstring (uuid)
includeDemostring
truefalse
labelSlugstring[]
sortDomainsBystring

Domain-Sortierung

sentimentstring

Nach Stimmung filtern

positiveneutralnegative
minImpactnumber

Mindestwert für Impact Score

minOverallnumber

Mindestwert für Overall Score

presetstring

Filtervoreinstellung

queryTypestring

Anfragetyp

neutralnegativecomparative
labelstring

Cluster-Slug

labelFilterModestring= or

Filterlogik

orand
fromstring (date-time)

Zeitraumbeginn

tostring (date-time)

Zeitraumende

chartOnlystring

Nur Diagrammdaten

truefalse
citationModestring

Zitiermodus

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/analytics/links
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/links" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "success": true,
  "data": {
    "topDomains": [
      {
        "domain": "samsung.com",
        "name": "Samsung",
        "trustRank": 95,
        "linkCount": 45,
        "mentionCount": 120,
        "sentiment": 0.8
      }
    ],
    "citationsByProvider": [
      {
        "provider": "chatgpt",
        "entityName": "Samsung",
        "isOurs": true,
        "citations": 30
      }
    ],
    "timeline": [
      {
        "date": "2026-04-01",
        "linkCount": 15
      }
    ]
  }
}

Erfolgreiche Antwort

Top-Domains

/api/v1/analytics/links/top-domains

Liefert die meistzitierten Domains in KI-Antworten. Filter nach Stimmung, Anfragetyp, Impact-/Overall-Score-Schwellen und Demodaten. companyId ist erforderlich, damit Kontounternehmen nicht zusammengefasst werden. Fehlt der Parameter, gilt preferredCompanyId des Schlüssels (GET /api/v1/context).

Anfrageparameter

timeRangestring
24h7d30dall
companyIdstring (uuid)
productIdstring (uuid)
limitinteger= 10

Anzahl der Domains

includeDemostring

Demodaten einschließen

truefalse
sentimentstring

Nach Stimmung filtern

positiveneutralnegative
minImpactnumber

Mindestwert für Impact Score

minOverallnumber

Mindestwert für Overall Score

queryTypestring

Anfragetyp

neutralnegativecomparative

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/analytics/links/top-domains
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/links/top-domains" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "success": true,
  "data": [
    {
      "domain": "samsung.com",
      "name": "Samsung",
      "trustRank": 95,
      "linkCount": 45,
      "mentionCount": 120,
      "sentiment": 0.8
    },
    {
      "domain": "apple.com",
      "name": "Apple",
      "trustRank": 97,
      "linkCount": 52,
      "mentionCount": 140,
      "sentiment": 0.75
    }
  ]
}

Erfolgreiche Antwort

Markensichtbarkeit

/api/v1/analytics/brand-visibility

Zeitverlauf der Markensichtbarkeit gegenüber Wettbewerbern mit einstellbarer Granularität. Filter nach Clustern (IDs/Slugs), KI-Anbietern und Filterlogik.

Anfrageparameter

granularitystring= day

Zeitliche Granularität

dayweekmonth
timeRangestring
24h7d30dall
companyIdstring (uuid)
productIdstring (uuid)
includeDemostring
truefalse
fromstring (date-time)
tostring (date-time)
labelIdstring

Cluster-ID. Mehrfachwerte: ?labelId=id1&labelId=id2

labelSlugstring

Cluster-Slug

labelFilterModestring= or

Filterlogik

orand
sourceIdstring

KI-Quellen-ID

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/analytics/brand-visibility
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/brand-visibility" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "success": true,
  "data": {
    "timeline": [
      {
        "period": "2026-04-01",
        "periodLabel": "1 апр",
        "our": 15,
        "competitors": {
          "Apple": 18,
          "Google": 12
        }
      }
    ],
    "summary": {
      "trend": "growing"
    }
  }
}

Erfolgreiche Antwort

Zeitlicher Verlauf der Zitierungen

/api/v1/analytics/links/citation-timeline

Täglicher Anteil der Antworten, die uns gegenüber Wettbewerbern zitieren. Basiert auf täglichen Aggregaten und unterstützt nur Gesamtzitate; URL- und Domain-Zitate werden dabei nicht unterschieden.

Anfrageparameter

companyIdstring (uuid)

Unternehmen; ohne Angabe gilt preferredCompanyId des Schlüssels.

productIdstring

Produkt

timeRangestring

24h | 7d | 30d | 90d | all

granularitystring

Aufschlüsselung des Zeitverlaufs

tzstring

Zeitzone

sourceIdstring[]

Quellen

labelSlugstring[]

Cluster

labelFilterModestring

AND | OR

includeDemoboolean

Demodaten einschließen

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
GET/api/v1/analytics/links/citation-timeline
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/links/citation-timeline" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Unternehmen und Produkte für Filter

/api/v1/analytics/companies-products

Unternehmen des Kontos mit Produkten als Datenquelle für die Auswahl „Unternehmen → Produkt“. companyId ist NICHT erforderlich: Ohne Angabe werden bewusst alle Unternehmen geliefert.

Anfrageparameter

companyIdstring (uuid)

Auf ein Unternehmen beschränken

includeDemoboolean

Demodaten einschließen

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/analytics/companies-products
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/companies-products" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Werbung

Werbedaten aus KI-Antworten

Werbedaten

/api/v1/advertising

Analyse von Werbe- und Promotion-Blöcken in KI-Antworten. Unterstützt Paginierung, Domain-/URL-Suche, Cluster, Promotion-Typ, Zeitraum und Sortierung. companyId ist erforderlich, damit Kontounternehmen nicht zusammengefasst werden. Fehlt der Parameter, gilt preferredCompanyId des Schlüssels (GET /api/v1/context).

Anfrageparameter

timeRangestring
24h7d30dall
companyIdstring (uuid)
productIdstring (uuid)
includeDemostring
truefalse
pageinteger= 1

Seitennummer

pageSizeinteger= 50

Seitengröße

searchstring

Nach Domain oder URL suchen

searchFieldstring

Suchfeld

domainurltitle
labelstring

Cluster-Slug. Mehrfachwerte: ?label=slug1&label=slug2

promoTypestring

Promotion-Block-Typ

sortBystring

Sortierfeld

sortDirstring

Sortierrichtung

ascdesc
fromstring (date-time)

Zeitraumbeginn (ISO 8601)

tostring (date-time)

Zeitraumende (ISO 8601)

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/advertising
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/advertising" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "success": true,
  "data": {
    "summary": {
      "promoCount": 25,
      "ourPromos": 8,
      "competitorPromos": 17,
      "uniqueDomains": 12
    },
    "topDomains": [
      {
        "domain": "samsung.com",
        "count": 5,
        "isOurs": true
      },
      {
        "domain": "apple.com",
        "count": 8,
        "isOurs": false
      }
    ],
    "timeseries": [
      {
        "date": "2026-04-01",
        "count": 3
      }
    ]
  }
}

Erfolgreiche Antwort

Vorschau der Werbeblöcke

/api/v1/advertising/preview

Details zur Übersicht /api/v1/advertising: welche Promotions in welchen Antworten erschienen.

Anfrageparameter

domainstringerforderlich

Promotion-Domain. ERFORDERLICH, sonst400.

companyIdstring (uuid)

Unternehmen; ohne Angabe gilt preferredCompanyId des Schlüssels.

productIdstring

Produkt

promoTypestring

ours | competitor | other

ourscompetitorother
timeRangestring

24h | 7d | 30d | 90d | all

labelstring[]

Cluster

labelFilterModestring

AND | OR

limitinteger= 20

1..50

offsetinteger= 0

Offset

includeDemoboolean

Demodaten einschließen

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
GET/api/v1/advertising/preview
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/advertising/preview" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Content-Fabrik

Content-Factory: Aufgaben, Tags, Anreicherung, Plan- und Artikelerstellung sowie Insight-Erkennung

Aufgaben auflisten

/api/v1/factory/tasks

Liefert Content-Factory-Aufgaben mit Filtern, Paginierung und Sortierung.

Anfrageparameter

companyIdstring (uuid)

Nach Unternehmen filtern

statusstring[]

Statusfilter, mehrere möglich: ?status=TODO&status=IN_PROGRESS

typestring[]

Nach Aufgabentyp filtern, mehrere möglich

prioritystring[]

Nach Priorität filtern, mehrere möglich

searchstring

In Aufgabentitel und Beschreibung suchen

tagIdstring (uuid)

Nach Tag filtern

aiGeneratedboolean

Nur KI-generierte Aufgaben

sortBystring= createdAt
createdAtupdatedAtprioritystatusposition
sortOrderstring= desc

Sortierreihenfolge

ascdesc
offsetinteger= 0

Offset für die Paginierung

limitinteger= 20

Einträge pro Seite

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/factory/tasks
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/factory/tasks" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "success": true,
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "title": "Написать FAQ по Galaxy S25",
      "status": "TODO",
      "type": "CREATE_FAQ",
      "priority": "HIGH",
      "position": 1,
      "aiGenerated": true,
      "aiReasoning": "Обнаружен content gap по FAQ-запросам",
      "aiConfidence": 0.87,
      "description": "Создать FAQ на основе частых вопросов пользователей",
      "targetKeywords": [
        "galaxy s25 faq",
        "samsung s25 характеристики"
      ],
      "targetProviders": [
        "chatgpt",
        "gemini"
      ],
      "companyId": "clx1abc2d0001abcdef123456",
      "companyName": "Samsung",
      "companyFavicon": "https://samsung.com/favicon.ico",
      "dueDate": "2026-04-20T00:00:00.000Z",
      "tags": [
        {
          "id": "tag-001",
          "name": "FAQ",
          "color": "#6366f1",
          "icon": null,
          "isSystem": false,
          "position": 0
        }
      ],
      "metadata": {},
      "createdAt": "2026-04-07T12:00:00.000Z",
      "updatedAt": "2026-04-07T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Erfolgreiche Antwort

Aufgabe erstellen

/api/v1/factory/tasks

Erstellt eine Content-Factory-Aufgabe.

Anfragetext

titlestringerforderlich

Aufgabentitel

companyIdstringerforderlich

Unternehmens-ID

typestringerforderlich

Aufgabentyp

NEW_ARTICLEOPTIMIZE_PAGECREATE_FAQCOMPARISONGUIDECASE_STUDY
prioritystring= MEDIUM

Priorität

CRITICALHIGHMEDIUMLOW
descriptionstring

Aufgabenbeschreibung

targetKeywordsstring[]

Zielschlüsselwörter (max. 20)

targetProvidersstring[]

Ziel-KI-Anbieter

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/factory/tasks
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
curl -X POST "https://app.brandfound.ai/api/v1/factory/tasks" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Написать FAQ по Galaxy S25",
  "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "CREATE_FAQ",
  "priority": "HIGH",
  "description": "Создать FAQ на основе частых вопросов пользователей",
  "targetKeywords": [
    "galaxy s25 faq",
    "samsung s25 характеристики"
  ],
  "targetProviders": [
    "chatgpt",
    "gemini"
  ]
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
  "success": true,
  "data": {
    "id": "example_id",
    "title": "example_title",
    "status": "IDEA",
    "type": "NEW_ARTICLE",
    "priority": "CRITICAL",
    "position": 1,
    "aiGenerated": true,
    "aiReasoning": "example_aiReasoning",
    "aiConfidence": 1,
    "description": "example_description",
    "targetKeywords": [
      "example"
    ],
    "targetProviders": [
      "example"
    ],
    "companyId": "example_companyId",
    "companyName": "example_companyName",
    "companyFavicon": "example_companyFavicon",
    "dueDate": "2026-01-15T12:00:00Z",
    "tags": [
      {
        "id": "example_id",
        "name": "example_name",
        "color": "example_color",
        "icon": "example_icon",
        "isSystem": true,
        "position": 1,
        "taskCount": 1
      }
    ],
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00Z",
    "updatedAt": "2026-01-15T12:00:00Z"
  }
}

Erfolgreiche Antwort

Aufgabe abrufen

/api/v1/factory/tasks/{id}

Liefert vollständige Informationen zur Content-Factory-Aufgabe.

Anfrageparameter

idstring (uuid)erforderlich

Aufgaben-ID

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
GET/api/v1/factory/tasks/{id}
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/factory/tasks/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
  "success": true,
  "data": {
    "id": "example_id",
    "title": "example_title",
    "status": "IDEA",
    "type": "NEW_ARTICLE",
    "priority": "CRITICAL",
    "position": 1,
    "aiGenerated": true,
    "aiReasoning": "example_aiReasoning",
    "aiConfidence": 1,
    "description": "example_description",
    "targetKeywords": [
      "example"
    ],
    "targetProviders": [
      "example"
    ],
    "companyId": "example_companyId",
    "companyName": "example_companyName",
    "companyFavicon": "example_companyFavicon",
    "dueDate": "2026-01-15T12:00:00Z",
    "tags": [
      {
        "id": "example_id",
        "name": "example_name",
        "color": "example_color",
        "icon": "example_icon",
        "isSystem": true,
        "position": 1,
        "taskCount": 1
      }
    ],
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00Z",
    "updatedAt": "2026-01-15T12:00:00Z"
  }
}

Erfolgreiche Antwort

Aufgabe aktualisieren

/api/v1/factory/tasks/{id}

Teilaktualisierung einer Content-Factory-Aufgabe.

Anfrageparameter

idstring (uuid)erforderlich

Aufgaben-ID

Anfragetext

statusstring
IDEABACKLOGTODOIN_PROGRESSREVIEWDONEDISMISSED
prioritystring
CRITICALHIGHMEDIUMLOW
titlestring
descriptionstring
tagIdsstring[]

Array zu verknüpfender Tag-IDs

targetKeywordsstring[]
targetProvidersstring[]
dueDatestring

Aufgabenfrist

metadataobject

Beliebige Aufgabenmetadaten

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
PATCH/api/v1/factory/tasks/{id}
1
2
3
4
5
6
7
8
9
10
11
curl -X PATCH "https://app.brandfound.ai/api/v1/factory/tasks/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "IN_PROGRESS",
  "priority": "HIGH",
  "tagIds": [
    "tag-001",
    "tag-002"
  ]
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
  "success": true,
  "data": {
    "id": "example_id",
    "title": "example_title",
    "status": "IDEA",
    "type": "NEW_ARTICLE",
    "priority": "CRITICAL",
    "position": 1,
    "aiGenerated": true,
    "aiReasoning": "example_aiReasoning",
    "aiConfidence": 1,
    "description": "example_description",
    "targetKeywords": [
      "example"
    ],
    "targetProviders": [
      "example"
    ],
    "companyId": "example_companyId",
    "companyName": "example_companyName",
    "companyFavicon": "example_companyFavicon",
    "dueDate": "2026-01-15T12:00:00Z",
    "tags": [
      {
        "id": "example_id",
        "name": "example_name",
        "color": "example_color",
        "icon": "example_icon",
        "isSystem": true,
        "position": 1,
        "taskCount": 1
      }
    ],
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00Z",
    "updatedAt": "2026-01-15T12:00:00Z"
  }
}

Erfolgreiche Antwort

Aufgabe archivieren

/api/v1/factory/tasks/{id}

Archiviert eine Aufgabe. Daten bleiben erhalten; der Status wird DISMISSED.

Anfrageparameter

idstring (uuid)erforderlich

Aufgaben-ID

Antworten

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
DELETE/api/v1/factory/tasks/{id}
1
2
3
curl -X DELETE "https://app.brandfound.ai/api/v1/factory/tasks/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
// No Content

Erfolgreich gelöscht

Aufgabe anreichern

/api/v1/factory/tasks/{id}/enrich

RAG-Suche in der Quellenbasis, Wettbewerbsanalyse und KI-Empfehlungen.

Anfrageparameter

idstring (uuid)erforderlich

Aufgaben-ID

Anfragetext

topicstringerforderlich

Thema zur Anreicherung

descriptionstring

Zusätzliche Beschreibung

keywordsstring[]

Schlüsselwörter für die RAG-Suche

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/factory/tasks/{id}/enrich
1
2
3
4
5
6
7
8
9
10
11
12
curl -X POST "https://app.brandfound.ai/api/v1/factory/tasks/{id}/enrich" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "topic": "Samsung Galaxy S25 FAQ",
  "description": "Часто задаваемые вопросы о Galaxy S25",
  "keywords": [
    "galaxy s25",
    "samsung",
    "характеристики"
  ]
}'
1
2
3
4
{
  "success": true,
  "data": {}
}

Erfolgreiche Antwort

Plan generieren

/api/v1/factory/tasks/{id}/plan

Erstellt anhand angereicherter Daten einen Artikelplan mit Struktur, Überschriften, Kernaussagen und Tonalität.

Anfrageparameter

idstring (uuid)erforderlich

Aufgaben-ID

Anfragetext

promptstring

Zusätzliche Anweisungen zur Planerstellung

topicIdstring

ID des gewählten Themas (aus suggest topics)

topicTitlestring

Thementitel

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/factory/tasks/{id}/plan
1
2
3
4
5
6
7
8
curl -X POST "https://app.brandfound.ai/api/v1/factory/tasks/{id}/plan" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Сфокусируйся на сравнении с iPhone 16",
  "topicId": "topic-001",
  "topicTitle": "Samsung Galaxy S25 vs iPhone 16: полное сравнение"
}'
1
2
3
4
5
6
7
8
9
10
{
  "success": true,
  "data": {
    "plan": {},
    "usage": {
      "inputTokens": 1,
      "outputTokens": 1
    }
  }
}

Erfolgreiche Antwort

Artikel generieren

/api/v1/factory/tasks/{id}/article

Artikelerstellung anhand eines Plans per SSE-Streaming. Content-Type: text/event-stream.

Anfrageparameter

idstring (uuid)erforderlich

Aufgaben-ID

Anfragetext

planIdstring

Plan-ID für die Artikelerstellung

articleLengthstring= medium

Artikellänge: short (~1000 Wörter), medium (~2000), long (~3500)

shortmediumlong

Antworten

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/factory/tasks/{id}/article
1
2
3
4
5
6
7
curl -X POST "https://app.brandfound.ai/api/v1/factory/tasks/{id}/article" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "planId": "plan-001",
  "articleLength": "medium"
}'
1
2
3
4
5
6
7
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Nicht authentifiziert: Token fehlt oder ist ungültig."
  }
}

Nicht authentifiziert: Token fehlt oder ist ungültig.

Inhaltsversionen

/api/v1/factory/tasks/{id}/versions

Liefert Inhaltsversionen (Pläne, Artikel, Briefings) einer Aufgabe.

Anfrageparameter

idstring (uuid)erforderlich

Aufgaben-ID

typestring

Nach Inhaltstyp filtern

planarticlebrief
planIdstring

Nach Plan-ID filtern

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
GET/api/v1/factory/tasks/{id}/versions
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/factory/tasks/{id}/versions" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "type": "plan",
      "version": 1,
      "content": {},
      "createdAt": "2026-01-15T12:00:00Z"
    }
  ]
}

Erfolgreiche Antwort

Aufgabenanalytik

/api/v1/factory/tasks/{id}/analytics

Liefert Aufgabenanalysen: Statistiken zu Anreicherung, Generierungen und Veröffentlichungen.

Anfrageparameter

idstring (uuid)erforderlich

Aufgaben-ID

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
GET/api/v1/factory/tasks/{id}/analytics
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/factory/tasks/{id}/analytics" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
{
  "success": true,
  "data": {}
}

Erfolgreiche Antwort

Themen vorschlagen

/api/v1/factory/tasks/{id}/topics

Generiert zehn Themen aus den Aufgabendaten.

Anfrageparameter

idstring (uuid)erforderlich

Aufgaben-ID

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/factory/tasks/{id}/topics
1
2
3
curl -X POST "https://app.brandfound.ai/api/v1/factory/tasks/{id}/topics" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "title": "example_title",
      "description": "example_description",
      "keywords": [
        "example"
      ],
      "score": 1
    }
  ]
}

Erfolgreiche Antwort

Tags auflisten

/api/v1/factory/tags

Liefert alle Content-Factory-Tags mit Aufgabenanzahl.

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/factory/tags
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/factory/tags" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "success": true,
  "data": [
    {
      "id": "tag-001",
      "name": "FAQ",
      "color": "#6366f1",
      "icon": null,
      "isSystem": false,
      "position": 0,
      "taskCount": 5
    },
    {
      "id": "tag-002",
      "name": "SEO",
      "color": "#10b981",
      "icon": "search",
      "isSystem": true,
      "position": 1,
      "taskCount": 12
    }
  ]
}

Erfolgreiche Antwort

Tag erstellen

/api/v1/factory/tags

Erstellt einen Tag für Content-Factory-Aufgaben.

Anfragetext

namestringerforderlich

Tag-Name

colorstring

HEX-Farbe, z.B. #6366f1

iconstring

Tag-Symbol (optional)

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
409application/json

Konflikt: Ressource existiert bereits.

CONFLICT
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/factory/tags
1
2
3
4
5
6
7
8
curl -X POST "https://app.brandfound.ai/api/v1/factory/tags" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "FAQ",
  "color": "#6366f1",
  "icon": "help-circle"
}'
1
2
3
4
5
6
7
8
9
10
11
12
{
  "success": true,
  "data": {
    "id": "example_id",
    "name": "example_name",
    "color": "example_color",
    "icon": "example_icon",
    "isSystem": true,
    "position": 1,
    "taskCount": 1
  }
}

Erfolgreiche Antwort

Tag aktualisieren

/api/v1/factory/tags/{id}

Teilaktualisierung eines Content-Factory-Tags.

Anfrageparameter

idstring (uuid)erforderlich

Tag-ID

Anfragetext

namestring
colorstring
iconstring
positioninteger

Sortierposition

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
409application/json

Konflikt: Ressource existiert bereits.

CONFLICT
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
PATCH/api/v1/factory/tags/{id}
1
2
3
4
5
6
7
8
curl -X PATCH "https://app.brandfound.ai/api/v1/factory/tags/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "FAQ Updated",
  "color": "#8b5cf6",
  "position": 2
}'
1
2
3
4
5
6
7
8
9
10
11
12
{
  "success": true,
  "data": {
    "id": "example_id",
    "name": "example_name",
    "color": "example_color",
    "icon": "example_icon",
    "isSystem": true,
    "position": 1,
    "taskCount": 1
  }
}

Erfolgreiche Antwort

Tag löschen

/api/v1/factory/tags/{id}

Löscht einen Tag. System-Tags können nicht gelöscht werden.

Anfrageparameter

idstring (uuid)erforderlich

Tag-ID

Antworten

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
403application/json

Zugriff verweigert

FORBIDDEN
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
DELETE/api/v1/factory/tags/{id}
1
2
3
curl -X DELETE "https://app.brandfound.ai/api/v1/factory/tags/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
// No Content

Erfolgreich gelöscht

Veröffentlichungen auflisten

/api/v1/factory/publications

Liefert paginierte Veröffentlichungen der Content-Factory.

Anfrageparameter

companyIdstring (uuid)

Nach Unternehmen filtern

offsetinteger= 0

Offset für die Paginierung

limitinteger= 20

Einträge pro Seite

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/factory/publications
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/factory/publications" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "success": true,
  "data": [
    {
      "id": "pub-001",
      "url": "https://samsung.com/blog/galaxy-s25-faq",
      "platform": "blog",
      "publishedAt": "2026-04-10T12:00:00.000Z",
      "planId": "plan-001",
      "planTitle": "FAQ по Galaxy S25",
      "notes": null,
      "taskId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "taskTitle": "Написать FAQ по Galaxy S25",
      "companyId": "clx1abc2d0001abcdef123456"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Erfolgreiche Antwort

Insights erkennen

/api/v1/factory/insights

Startet15 Detektortypen: Inhaltslücken, Wettbewerbserfolge, unbesetzte Themen, Reputationsrisiken usw.

Anfragetext

companyIdstringerforderlich

Unternehmens-ID

insightTypestring

Insight-Typ; ohne Angabe werden alle Detektoren gestartet.

CONTENT_GAPCOMPETITOR_WINWHITE_SPACEREPUTATION_RISKKEYWORD_OPPORTUNITYTRENDING_TOPICPROVIDER_BIASSEASONAL_OPPORTUNITYFAQ_OPPORTUNITYCOMPARISON_OPPORTUNITYGUIDE_OPPORTUNITYCASE_STUDY_OPPORTUNITYOPTIMIZATION_NEEDEDAUTHORITY_BUILDING
limitinteger

Maximale Anzahl an Insights

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/factory/insights
1
2
3
4
5
6
7
8
curl -X POST "https://app.brandfound.ai/api/v1/factory/insights" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "insightType": "CONTENT_GAP",
  "limit": 10
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "success": true,
  "data": {
    "company": "Samsung",
    "insightsFound": 5,
    "tasksCreated": 3,
    "savedTaskIds": [
      "task-001",
      "task-002",
      "task-003"
    ],
    "byType": {
      "CONTENT_GAP": 2,
      "COMPETITOR_WIN": 1,
      "WHITE_SPACE": 2
    }
  }
}

Erfolgreiche Antwort

Factory-Einstellungen

/api/v1/factory/settings

Liefert die aktuellen Content-Factory-Einstellungen des Nutzers.

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/factory/settings
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/factory/settings" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
{
  "success": true,
  "data": {}
}

Erfolgreiche Antwort

Einstellungen aktualisieren

/api/v1/factory/settings

Aktualisiert Content-Factory-Einstellungen per Deep Merge.

Anfragetext

settingsobjecterforderlich

Einstellungsobjekt für Deep Merge mit bestehenden Werten

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
PATCH/api/v1/factory/settings
1
2
3
4
5
6
7
8
9
10
11
12
13
curl -X PATCH "https://app.brandfound.ai/api/v1/factory/settings" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "settings": {
    "defaultPriority": "MEDIUM",
    "autoEnrich": true,
    "preferredProviders": [
      "chatgpt",
      "gemini"
    ]
  }
}'
1
2
3
4
{
  "success": true,
  "data": {}
}

Erfolgreiche Antwort

Markenprofil abrufen

/api/v1/factory/brand-card

Liest das Markenprofil als Baum von Markdown-Dokumenten mit Markenwissen für die Inhaltserstellung. Drei Modi: ohne Zusatzparameter das gesamte Profil als Markdown (Manifest → Kerndateien → verlinkte Dateien → übrige; private Blöcke ```private entfernt; ca. 12 000 Zeichen). mode=index liefert Manifest und Dateien mit path, id, isCore sowie ausgehenden Links. path=... liefert eine Datei: content behält Links [Name](brandcard://id) unverändert; links löst jedes Linkziel in einen Pfad auf.

Anfrageparameter

companyIdstring (uuid)erforderlich

Unternehmens-ID

modestring

index liefert Manifest und Dateiliste statt des vollständigen Profils.

index
pathstring

Dateipfad wie im Index, z.B. "main / settings.md". Liefert eine Datei; Groß-/Kleinschreibung egal.

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
GET/api/v1/factory/brand-card
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/factory/brand-card" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
{
  "success": true,
  "data": {}
}

Erfolgreiche Antwort

Datei des Markenprofils erstellen oder aktualisieren

/api/v1/factory/brand-card

Erstellt oder überschreibt eine Markenprofildatei vollständig anhand ihres Pfads. Fehlende Ordner werden erstellt; ohne Erweiterung wird .md ergänzt. Verweise auf andere Profildateien verwenden [Name](brandcard://<id aus dem Index>). Sie bleiben bei Umbenennen/Verschieben stabil und erhöhen die Generierungspriorität der Zieldatei. Vorhandene brandcard://-Links unverändert erhalten. Persönliche Notizen und Optionen in ```private-Blöcke setzen; diese werden nicht an KI-Systeme gesendet.

Anfragetext

companyIdstringerforderlich

Unternehmens-ID

pathstringerforderlich

Dateipfad mit durch "/" getrennten Segmenten, z.B. "products / pricing.md"

contentstringerforderlich

Vollständiger Markdown-Inhalt, ersetzt den bestehenden Dateiinhalt.

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/factory/brand-card
1
2
3
4
5
6
7
8
curl -X POST "https://app.brandfound.ai/api/v1/factory/brand-card" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "companyId": "9f1c0e2a-…",
  "path": "products / pricing.md",
  "content": "# Прайс\n\nТариф Лайт — 1900 ₽/мес.\n\nСм. также: [Настройки](brandcard://b7e2…)"
}'
1
2
3
4
5
6
7
{
  "success": true,
  "data": {
    "path": "example_path",
    "created": true
  }
}

Erfolgreiche Antwort

Datei oder Ordner des Markenprofils löschen

/api/v1/factory/brand-card

Löscht eine Datei oder einen Ordner aus dem Markenprofil; Ordner werden rekursiv gelöscht. Systemstruktur (instruction.md, README.md, Kerndateien) ist nicht löschbar, aber per POST editierbar. Links zu gelöschten Dateien werden ungültig: im Index aus links entfernt, beim Dateilesen mit path=null geliefert.

Anfrageparameter

companyIdstring (uuid)erforderlich

Unternehmens-ID

pathstringerforderlich

Datei- oder Ordnerpfad wie im Index

Antworten

204

Erfolgreich gelöscht

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
DELETE/api/v1/factory/brand-card
1
2
3
curl -X DELETE "https://app.brandfound.ai/api/v1/factory/brand-card" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
{
  "success": true,
  "data": {
    "deleted": true,
    "path": "example_path"
  }
}

Erfolgreiche Antwort

Guthaben und Ausgaben

FoxCoin-Guthaben und Transaktionsverlauf

FoxCoin-Guthaben und Preise

/api/v1/billing/balance

Guthaben, Umsatz und Operationspreise. Das Wallet gilt für das gesamte Konto; Teammitglieder nutzen das Guthaben des Eigentümers. Die Preisliste verhindert fest codierte Integrationspreise.

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/billing/balance
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/billing/balance" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "success": true,
  "data": {
    "balance": 1,
    "totalEarned": 1,
    "totalSpent": 1,
    "billingEnabled": true,
    "pricing": {
      "coinToRub": 1,
      "minTopUpRub": 1,
      "answer": 1,
      "generatedQuery": 1,
      "brandCardGeneration": 1,
      "taskEnrichment": 1,
      "contentPlan": 1,
      "articleGeneration": 1,
      "topicSuggestion": 1,
      "factCheck": 1
    }
  }
}

Erfolgreiche Antwort

Transaktionsverlauf

/api/v1/billing/transactions

Wallet-Transaktionsprotokoll. Bei Antwortgebühren zeigt query die belastete Anfrage.

Anfrageparameter

typestring

Nach Transaktionstyp filtern

ANSWER_CHARGEQUERY_GENERATIONBRAND_CARD_GENERATIONTASK_ENRICHMENTARTICLE_GENERATIONCONTENT_PLANTOPIC_SUGGESTIONFACT_CHECKTOPUPBONUSREFUNDMANUAL_ADJUSTMENTSUBSCRIPTION_CREDITAPI_CALL_FREE
fromstring (date-time)

Zeitraumbeginn als ISO-Datum, einschließlich

tostring (date-time)

Zeitraumende als ISO-Datum, einschließlich

limitinteger= 50

Seitengröße

offsetinteger= 0

Offset

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/billing/transactions
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/billing/transactions" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "amount": 1,
      "type": "ANSWER_CHARGE",
      "description": "example_description",
      "referenceId": "example_referenceId",
      "referenceType": "example_referenceType",
      "balanceAfter": 1,
      "metadata": {},
      "createdAt": "2026-01-15T12:00:00Z",
      "query": {
        "text": "example_text",
        "origin": "example_origin",
        "companyName": "example_companyName"
      }
    }
  ],
  "meta": {
    "total": 1,
    "limit": 1,
    "offset": 1,
    "hasMore": true
  }
}

Erfolgreiche Antwort

Nachschlagewerke

Verzeichnisse und Schlüsselkontext

KI-Modelle auflisten

/api/v1/sources

Verfügbare Assistenten und Standardauswahl. value entspricht den providers-Werten in POST /api/v1/queries/setup. Unbekannte Namen werden beim Einreihen stillschweigend verworfen.

Anfrageparameter

includeUnpollableboolean= false

claude einschließen (alte Warteschlange, im aktuellen Ablauf nicht abgefragt)

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/sources
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/sources" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
{
  "success": true,
  "data": [
    {
      "value": "chatgpt",
      "label": "example_label",
      "pollable": true,
      "defaultForAccount": true
    }
  ]
}

Erfolgreiche Antwort

Kontext des API-Schlüssels abrufen

/api/v1/context

Empfohlener Integrationsstart: Konto des Schlüssels, Berechtigungen, verfügbare Unternehmen und Produkte sowie Standardunternehmen.

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/context
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/context" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{
  "success": true,
  "data": {
    "accountId": "example_accountId",
    "userId": "example_userId",
    "defaultCompanyId": "example_defaultCompanyId",
    "companies": [
      {
        "id": "example_id",
        "name": "example_name",
        "isDefault": true,
        "products": [
          {
            "id": "example_id",
            "name": "example_name"
          }
        ]
      }
    ],
    "apiKey": {
      "name": "example_name",
      "scopes": [
        "example"
      ],
      "expiresAt": "2026-01-15T12:00:00Z",
      "source": "example_source"
    },
    "tokenAccountId": "example_tokenAccountId",
    "activeAccountId": "example_activeAccountId",
    "availableWorkspaces": [
      {
        "accountId": "example_accountId",
        "role": "owner",
        "ownerName": "example_ownerName",
        "ownerEmail": "example_ownerEmail",
        "companiesCount": 0,
        "isCurrent": true,
        "teamRoleName": "example_teamRoleName",
        "teamRoleKey": "example_teamRoleKey"
      }
    ]
  }
}

Erfolgreiche Antwort

KI-Traffic

Website-Besuche aus KI-Antworten (Yandex Metrica)

KI-Traffic

/api/v1/analytics/metrika/ai-traffic

Website-Besuche aus KI-Antworten: Anzahl je System und zeitliche Entwicklung. Auf das Konto beschränkt; fremde integrationId wird ignoriert. Leere Ergebnisse bedeuten meist fehlende Metrica-Anbindung; prüfen Sie /api/v1/integrations/metrika/status.

Anfrageparameter

integrationIdstring (uuid)

Metrica-Zähler; ohne Angabe alle verbundenen Zähler des Kontos.

timeRangestring

24h | 7d | 30d | 90d | all

fromstring

Zeitraumbeginn als ISO-Datum

tostring

Zeitraumende als ISO-Datum

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/analytics/metrika/ai-traffic
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/metrika/ai-traffic" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Besucher aus KI-Modellen

/api/v1/analytics/metrika/visitors

Besuche aus KI-Quellen und Website-Verhalten: Seitentiefe, Ziele und Wiederbesuche. Auf das Konto beschränkt; fremde integrationId wird ignoriert. Leere Ergebnisse bedeuten meist fehlende Metrica-Anbindung; prüfen Sie /api/v1/integrations/metrika/status.

Anfrageparameter

integrationIdstring (uuid)

Metrica-Zähler; ohne Angabe alle verbundenen Zähler des Kontos.

timeRangestring

24h | 7d | 30d | 90d | all

fromstring

Zeitraumbeginn als ISO-Datum

tostring

Zeitraumende als ISO-Datum

hasGoalsboolean

Nur Besuche mit erreichten Zielen

includeSyntheticboolean

Synthetischen Traffic einschließen

pvMininteger

Mindestzahl an Seitenaufrufen

pvMaxinteger

Höchstzahl an Seitenaufrufen

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/analytics/metrika/visitors
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/metrika/visitors" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

KI-Traffic-Funnel

/api/v1/analytics/metrika/traffic-funnel

Weg vom Klick aus einer KI-Antwort bis zur Zielaktion. Auf das Konto beschränkt; fremde integrationId wird ignoriert. Leere Ergebnisse bedeuten meist fehlende Metrica-Anbindung; prüfen Sie /api/v1/integrations/metrika/status.

Anfrageparameter

integrationIdstring (uuid)

Metrica-Zähler; ohne Angabe alle verbundenen Zähler des Kontos.

timeRangestring

24h | 7d | 30d | 90d | all

fromstring

Zeitraumbeginn als ISO-Datum

tostring

Zeitraumende als ISO-Datum

hasGoalsboolean

Nur Besuche mit erreichten Zielen

includeSyntheticboolean

Synthetischen Traffic einschließen

pvMininteger

Mindestzahl an Seitenaufrufen

pvMaxinteger

Höchstzahl an Seitenaufrufen

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/analytics/metrika/traffic-funnel
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/metrika/traffic-funnel" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Zusammenhang zwischen Erwähnungen und Traffic

/api/v1/analytics/metrika/correlation

Vergleicht Markenerwähnungen mit tatsächlichen Besuchen: Führt mehr Sichtbarkeit zu mehr Traffic? Auf das Konto beschränkt; fremde integrationId wird ignoriert. Leere Ergebnisse bedeuten meist fehlende Metrica-Anbindung; prüfen Sie /api/v1/integrations/metrika/status.

Anfrageparameter

companyIdstring (uuid)

Unternehmen; ohne Angabe gilt preferredCompanyId des Schlüssels.

integrationIdstring (uuid)

Metrica-Zähler; ohne Angabe alle verbundenen Zähler des Kontos.

timeRangestring

24h | 7d | 30d | 90d | all

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/analytics/metrika/correlation
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/metrika/correlation" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Metrika-Ziele

/api/v1/analytics/metrika/goals

Zielverzeichnis des Zählers zur Erklärung von hasGoals in anderen Methoden. Auf das Konto beschränkt; fremde integrationId wird ignoriert. Leere Ergebnisse bedeuten meist fehlende Metrica-Anbindung; prüfen Sie /api/v1/integrations/metrika/status.

Anfrageparameter

integrationIdstring (uuid)

Metrica-Zähler; ohne Angabe alle verbundenen Zähler des Kontos.

includeInactiveboolean

Inaktive Ziele einschließen

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/analytics/metrika/goals
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/metrika/goals" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Übersicht des synthetischen Traffics

/api/v1/analytics/metrika/synthetic/summary

Anteil von Bots und nichtorganischen Besuchen, damit diese KI-Traffic-Ergebnisse nicht verzerren. Auf das Konto beschränkt; fremde integrationId wird ignoriert. Leere Ergebnisse bedeuten meist fehlende Metrica-Anbindung; prüfen Sie /api/v1/integrations/metrika/status.

Anfrageparameter

integrationIdstring (uuid)

Metrica-Zähler; ohne Angabe alle verbundenen Zähler des Kontos.

timeRangestring

24h | 7d | 30d | 90d | all

fromstring

Zeitraumbeginn als ISO-Datum

tostring

Zeitraumende als ISO-Datum

filterstring

Klassifikationsfilter

hasGoalsboolean

Nur Besuche mit erreichten Zielen

pvMininteger

Mindestzahl an Seitenaufrufen

pvMaxinteger

Höchstzahl an Seitenaufrufen

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/analytics/metrika/synthetic/summary
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/metrika/synthetic/summary" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Synthetische Besuche auflisten

/api/v1/analytics/metrika/synthetic/list

Paginierte Details zur Übersicht: einzelne Besuche mit Merkmalen synthetischen Traffics. Auf das Konto beschränkt; fremde integrationId wird ignoriert. Leere Ergebnisse bedeuten meist fehlende Metrica-Anbindung; prüfen Sie /api/v1/integrations/metrika/status.

Anfrageparameter

integrationIdstring (uuid)

Metrica-Zähler; ohne Angabe alle verbundenen Zähler des Kontos.

timeRangestring

24h | 7d | 30d | 90d | all

fromstring

Zeitraumbeginn als ISO-Datum

tostring

Zeitraumende als ISO-Datum

filterstring

Klassifikationsfilter

qstring

Suche

qScopestring

Suchbereich

hasRevenueboolean

Nur mit Umsatz

returningOnlyboolean

Nur wiederkehrende Besucher

pageinteger

Seite

pageSizeinteger

Seitengröße

sortBystring

Sortierfeld

sortOrderstring

asc | desc

hasGoalsboolean

Nur Besuche mit erreichten Zielen

pvMininteger

Mindestzahl an Seitenaufrufen

pvMaxinteger

Höchstzahl an Seitenaufrufen

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/analytics/metrika/synthetic/list
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/metrika/synthetic/list" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Verbundene Zähler

/api/v1/integrations/metrika/list

Einstieg in KI-Traffic: liefert integrationId für die übrigen Methoden dieses Bereichs.

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/integrations/metrika/list
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/integrations/metrika/list" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Integrationsstatus

/api/v1/integrations/metrika/status

Zeigt Metrica-Verbindung, letzte Synchronisierung und Ablauf des Zugriffs. Erklärt leere Ergebnisse anderer Methoden dieses Bereichs.

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/integrations/metrika/status
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/integrations/metrika/status" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Commerce

Produktkarten in KI-Antworten

Commerce-Analyse

/api/v1/analytics/commerce

Produktkarten neben KI-Antworttexten. view=summary zeigt Antwortanteil mit Karten und Entwicklung nach System; sellers zeigt Top-Verkäufer und Domains; brands vergleicht eigene Markenkarten mit Wettbewerbern; cards liefert eine paginierte Liste.

Anfrageparameter

viewstring= summary

summary | sellers | brands | cards

summarysellersbrandscards
companyIdstring (uuid)

Unternehmen; ohne Angabe gilt preferredCompanyId des Schlüssels.

productIdstring[]

Mehrere Werte möglich

timeRangestring

24h | 7d | 30d | 90d | all

granularitystring

Aufschlüsselung des Zeitverlaufs

tzstring

Zeitzone

labelIdstring[]

Cluster

labelSlugstring[]

Cluster nach Slug

labelFilterModestring

AND | OR

sourceIdstring[]

Quellen

queryTypestring[]

Anfragetypen

includeDemoboolean

Demodaten einschließen

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
GET/api/v1/analytics/commerce
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/commerce" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Verfolgte Produkte

/api/v1/commerce/products

Produktkatalog zum Abgleich mit Antwortkarten. Ohne Katalog zeigt Commerce Verkäufer und Domains, aber keinen Vergleich eigener und fremder Produkte.

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/commerce/products
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/commerce/products" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Produkt hinzufügen

/api/v1/commerce/products

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/commerce/products
1
2
3
curl -X POST "https://app.brandfound.ai/api/v1/commerce/products" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Monitoring

Regelmäßige Abfragen nach Zeitplan

Überwachte Abfragen auflisten

/api/v1/favorite-queries

Liste der für regelmäßige Abfragen eingerichteten Anfragen.

Anfrageparameter

searchstring

Textsuche

activeboolean

Nur aktivierte

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
GET/api/v1/favorite-queries
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/favorite-queries" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Überwachung einer Abfrage starten

/api/v1/favorite-queries

POST /api/v1/queries fragt KI-Systeme nur EINMAL ab. Regelmäßige Abfragen sind eine eigene Entität, die hier erstellt wird. Das Anlegen startet noch keine Abfrage. Im zweiten Schritt muss über POST /api/v1/favorite-queries/{id}/assignments ein Zeitplan gesetzt werden. Jede geplante Abfrage ist kostenpflichtig:10 FoxCoin pro Antwort JEDES KI-Systems. Ein 60-Minuten-Intervall mit drei Systemen ergibt72 Antworten täglich. Bei Guthabenmangel pausieren Abfragen und werden nicht automatisch fortgesetzt (POST /api/v1/queries/queue/resume).

Anfragetext

textstringerforderlich
typestringerforderlich
companyIdstring
productIdstring
languagestring= ru
regionstring= RU
isActiveboolean= true
tagsstring[]

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/favorite-queries
1
2
3
4
5
6
7
8
9
10
curl -X POST "https://app.brandfound.ai/api/v1/favorite-queries" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "best threat intelligence vendors for banks in UAE",
  "type": "comparative",
  "companyId": "e08cf948-88b4-4aac-949e-6c1cc3b4f427",
  "language": "en",
  "region": "AE"
}'
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Überwachungseintrag abrufen

/api/v1/favorite-queries/{id}

Anfrageparameter

idstring (uuid)erforderlich

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
GET/api/v1/favorite-queries/{id}
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/favorite-queries/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Überwachungseintrag ändern

/api/v1/favorite-queries/{id}

Text, Unternehmen, Tags und isActive. Mit isActive:false ohne Löschen deaktivieren.

Anfrageparameter

idstring (uuid)erforderlich

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
PATCH/api/v1/favorite-queries/{id}
1
2
3
curl -X PATCH "https://app.brandfound.ai/api/v1/favorite-queries/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Überwachung einer Abfrage beenden

/api/v1/favorite-queries/{id}

Löscht den Eintrag samt Zeitplan; es erfolgt keine weitere geplante Abfrage. Vorhandene Antworten und Erwähnungen bleiben erhalten, da sie zur Anfrage und nicht zum Abonnement gehören.

Anfrageparameter

idstring (uuid)erforderlich

Antworten

204

Erfolgreich gelöscht

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
DELETE/api/v1/favorite-queries/{id}
1
2
3
curl -X DELETE "https://app.brandfound.ai/api/v1/favorite-queries/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Abfragezeitplan abrufen

/api/v1/favorite-queries/{id}/assignments

Anfrageparameter

idstring (uuid)erforderlich

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
GET/api/v1/favorite-queries/{id}/assignments
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/favorite-queries/{id}/assignments" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Abfragezeitplan festlegen

/api/v1/favorite-queries/{id}/assignments

Startpunkt regelmäßiger Abfragen: Ein Eintrag ohne Zeitplan bleibt inaktiv. Pro Eintrag gilt ein Zeitplan; erneuter Aufruf überschreibt ihn. Jede geplante Abfrage ist kostenpflichtig:10 FoxCoin pro Antwort JEDES KI-Systems. Ein 60-Minuten-Intervall mit drei Systemen ergibt72 Antworten täglich. Bei Guthabenmangel pausieren Abfragen und werden nicht automatisch fortgesetzt (POST /api/v1/queries/queue/resume).

Anfrageparameter

idstring (uuid)erforderlich

Anfragetext

providersstring[]erforderlich

Liste: GET /api/v1/sources

frequencyMinutesintegererforderlich

Intervall zwischen Abfragen

isEnabledboolean= true

Pausieren, ohne den Zeitplan zu löschen

timezonestring= Europe/Moscow

Zeitzone für daysOfWeek und hoursWindow

daysOfWeekinteger[]

1..7; leer bedeutet täglich.

hoursWindowobject

Stundenfenster; außerhalb finden keine Abfragen statt.

modelobject

Zuordnung „KI-System → Modell“

Antworten

200

Erfolgreiche Antwort

400application/json

Validierungsfehler der Eingabedaten

VALIDATION_ERROR
401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/favorite-queries/{id}/assignments
1
2
3
4
5
6
7
8
9
10
11
12
curl -X POST "https://app.brandfound.ai/api/v1/favorite-queries/{id}/assignments" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "providers": [
    "chatgpt",
    "perplexity",
    "gemini"
  ],
  "frequencyMinutes": 1440,
  "timezone": "Europe/Moscow"
}'
1
2
3
{
  "success": true
}

Erfolgreiche Antwort

Abfrage jetzt ausführen

/api/v1/favorite-queries/{id}/run-now

Sofortige zusätzliche Abfrage, ohne den Zeitplan abzuwarten oder zu verschieben. Es gelten die üblichen Kosten.

Anfrageparameter

idstring (uuid)erforderlich

Antworten

200

Erfolgreiche Antwort

401application/json

Nicht authentifiziert: Token fehlt oder ist ungültig.

UNAUTHORIZED
404application/json

Ressource nicht gefunden

NOT_FOUND
429application/json

Anfragelimit überschritten: IP 120 Anfragen/Minute, pro Nutzer 60 Anfragen/Minute.

RATE_LIMIT_EXCEEDED
POST/api/v1/favorite-queries/{id}/run-now
1
2
3
curl -X POST "https://app.brandfound.ai/api/v1/favorite-queries/{id}/run-now" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
{
  "success": true
}

Erfolgreiche Antwort