Audience Suite REST API Referenz

Authentifizierung

Alle geschuetzten Endpunkte erwarten einen Bearer Token. Der Status-Endpunkt ist bewusst unauthentifiziert, damit Load Balancer ihn als Healthcheck nutzen koennen.

Authorization: Bearer YOUR_API_TOKEN

Production Base URL

https://api.audience-suite.de

Staging Base URL

https://api-staging.audience-suite.de

API Tester

Base URL API Token Endpunkt

Antwort

Noch keine Anfrage gesendet.

Status

GET/api/status

Healthcheck ohne Authentifizierung.

{
  "status": "ok",
  "service": "audience-suite-api",
  "uptime": 175.883477544,
  "timestamp": "2026-05-03T21:44:13.065Z"
}

Projekte

GET/api/projects

Listet alle Projekte des authentifizierten Nutzers.

[
  {
    "projectId": "proj_demo123",
    "type": "Project",
    "projectType": "files",
    "state": "Finished",
    "name": "Demo Analyseprojekt",
    "description": "Auswertung von Interviews und Frageboegen",
    "context": "",
    "createdAt": "2026-01-08T14:44:35.026Z",
    "data": {
      "iconColor": "bg-blue-500",
      "iconName": "Briefcase"
    },
    "options": {
      "profileCount": 1,
      "files": [
        {
          "name": "Interview 01.docx",
          "lastModified": 1766161526004,
          "size": 18159359,
          "type": "einzelinterview"
        }
      ],
      "categories": [
        {
          "categoryName": "Person und Kontext",
          "categoryDescription": "Informationen zur Person und zum Arbeitsumfeld."
        }
      ],
      "projectContext": "Kurzbeschreibung des Analysekontexts.",
      "imageStyle": "realistic",
      "identityId": "eu-central-1:identity-demo"
    }
  }
]

Profile

GET/api/projects/:projectId/profiles

Listet alle Zielgruppenprofile eines Projekts. Die Antwort ist ein Array; jedes Element hat dieselbe Struktur wie der Detail-Endpunkt.

Parameter	Typ	Beschreibung	Pflicht
`projectId`	string	Projekt-ID, z. B. `proj_demo123`	Ja

GET/api/projects/:projectId/profiles/:profileId

Liefert ein einzelnes Profil inklusive Kategorien, Quellen, Kernaussagen, Eigenschaften, Werten und User-Needs.

{
    "projectId": "proj_demo123",
    "profileId": "prof_demo456",
  "name": "Alex Beispiel",
  "beschreibung": "",
  "createdAt": "2026-01-08T15:15:55.876Z",
  "schwartz_values": {
    "Macht": 3,
    "Universalismus": 2,
    "Tradition": 2,
    "Wohltätigkeit": 5,
    "Selbstbestimmung": 3,
    "Hedonismus": 2,
    "Stimulation": 3,
    "Leistung": 3,
    "Konformität": 2,
    "Sicherheit": 3
  },
  "userNeeds": {
    "Keep me engaged": 5,
    "Educate me": 4,
    "Give me perspective": 4,
    "Inspire me": 3,
    "Help me": 4,
    "Connect me": 5,
    "Update me": 4,
    "Divert me": 1
  },
  "eigenschaften": [
    {
      "name": "Anpassungsfähigkeit",
      "description": "Reagiert flexibel auf neue Situationen und Anforderungen."
    }
  ],
  "kernwerte": [
    {
      "name": "Innovation",
      "description": "Sucht nach neuen Loesungen, um Prozesse zu verbessern."
    }
  ],
  "categories": [
    {
      "name": "Person und Kontext",
      "sources": ["Interview 01.docx", "Fragebogen.csv"],
      "items": [
        {
          "typ": "aussage",
          "text": "Legt grossen Wert auf kollegiale Beratung in einem vertraulichen Rahmen."
        },
        {
          "typ": "quote",
          "text": "Persoenliche Kontakte und eine starke Community sind fuer mich essenziell."
        }
      ]
    }
  ]
}

Feeds & Plaene

GET/api/projects/:projectId/profiles/:profileId/feeds

Listet Content-Feeds eines Profils. Wenn noch keine Feeds erzeugt wurden, wird ein leeres Array geliefert.

[]

GET/api/projects/:projectId/profiles/:profileId/schedules

Listet Redaktions- oder Veröffentlichungsplaene eines Profils. Wenn noch keine Plaene existieren, wird ein leeres Array geliefert.

[]

Knowledge Search

GET/api/projects/:projectId/search?q=:query&limit=:limit

Durchsucht die ChromaDB-Wissensbasis eines Projekts. limit ist optional und wird serverseitig auf maximal 20 begrenzt.

Parameter	Ort	Typ	Pflicht
`projectId`	Path	string	Ja
`q`	Query	string	Ja
`limit`	Query	number	Nein

Erfolgsantwort

[
  {
    "id": ["chunk_demo_001"],
    "text": ["Relevanter Ausschnitt aus Interview oder Fragebogen."],
    "metadata": [
      {
        "type": "insight",
        "projectId": "proj_demo123",
        "source": "Interview 01.docx"
      }
    ]
  }
]

Fehlerantwort bei nicht erreichbarer ChromaDB

{
  "error": "Failed to connect to chromadb. Make sure your server is running and try again."
}

Analyse-Jobs

POST/api/projects/:projectId/jobs/analysis

Startet eine reine Analyse mit multipart/form-data. Erwartet mindestens ein Feld file.

{
  "jobId": "job_demo001",
  "creditCost": 2
}

POST/api/projects/:projectId/jobs/profile

Startet eine Analyse mit Profilgenerierung. Erwartet file und profileCount.

{
  "jobId": "job_demo002",
  "creditCost": 10
}

GET/api/projects/:projectId/jobs

Listet Jobs eines Projekts.

[
  {
    "type": "Job",
    "projectId": "proj_demo123",
    "jobId": "job_demo001",
    "jobType": "file",
    "jobMode": "analyze-only",
    "status": "Finished",
    "creditCost": 2,
    "createdAt": "2026-03-15T17:18:10.994Z",
    "updatedAt": "2026-03-15T17:30:26.578Z",
    "config": {
      "profileCount": 0,
      "projectContext": "Demo-Kontext",
      "identityId": "eu-central-1:identity-demo",
      "jobMode": "analyze-only",
      "imageStyle": "realistic",
      "files": [
        {
          "name": "Interview 01.docx",
          "lastModified": 1691839900000,
          "s3Key": "users/user_demo/projects/proj_demo123/readonly/Interview 01.docx",
          "size": 22271,
          "type": "einzelinterview"
        }
      ],
      "categories": [
        {
          "categoryName": "Demografie",
          "description": "Alter, Rolle und weitere Basisdaten."
        }
      ]
    }
  }
]

GET/api/projects/:projectId/jobs/:jobId

Liefert denselben Job-Datensatz als einzelnes Objekt. Bei unbekannter ID wird 404 mit {"error":"Job not found"} geliefert.