{"openapi":"3.1.0","info":{"title":"UGC VZ Public API","version":"1.0.0","description":"Oeffentliche REST-API des UGC-VZ-Creator-Verzeichnisses (DACH). Kein API-Key noetig. Gleiche Faehigkeiten wie der MCP-Server unter /api/mcp und der A2A-Endpunkt unter /a2a. Suchergebnisse und Profile enthalten NIEMALS private Kontaktdaten - Kontaktdaten erhaelt die Brand erst nach einer bewussten Kontaktanfrage (requestOutreach) per E-Mail. Dokumentation: https://ugc-vz.de/developers","contact":{"name":"UGC VZ","email":"hi@ugc-vz.de","url":"https://ugc-vz.de/developers"},"termsOfService":"https://ugc-vz.de/agb"},"servers":[{"url":"https://ugc-vz.de"}],"paths":{"/api/v1/creators/search":{"post":{"operationId":"searchCreators","summary":"Creator-Verzeichnis durchsuchen","description":"Durchsucht das UGC-VZ-Verzeichnis realer UGC-Creator im deutschsprachigen Raum. query ist Freitext und der Hauptpfad (z. B. \"Fitness-Creatorin ab 30 fuer TikTok-Produktvideo\"); ein Sprachmodell strukturiert die Anfrage serverseitig. Optional: city (Substring), topics (mind. ein Treffer), human_verification_level_min (0 = self_reported, 1 = self_reported_with_portfolio; Stufen sind aus Profildaten abgeleitet, siehe get_vocab). Ergebnis enthaelt NIEMALS private Kontaktdaten. Fuer Details zu einem Treffer get_creator verwenden; fuer eine Kontaktanfrage request_outreach.","tags":["creators"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":3,"maxLength":500},"max_results":{"type":"integer","minimum":1,"maximum":10},"city":{"type":"string","maxLength":80},"topics":{"maxItems":10,"type":"array","items":{"type":"string","maxLength":60}},"human_verification_level_min":{"type":"integer","minimum":0,"maximum":2}},"required":["query"]}}}},"responses":{"200":{"description":"Suchergebnis mit oeffentlichen Kurzprofilen.","content":{"application/json":{"schema":{"type":"object","properties":{"creators":{"type":"array","items":{"$ref":"#/components/schemas/CreatorSummary"}},"totalCount":{"type":"integer"},"reasoning":{"type":"string"}}}}}},"400":{"description":"Ungueltige Anfrage (Validierungsfehler).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate-Limit erreicht. Retry-After beachten.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Interner Fehler.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/creators/{publicId}":{"get":{"operationId":"getCreator","summary":"Oeffentliches Creator-Profil abrufen","description":"Liefert das oeffentliche Profil eines einzelnen UGC-Creators zu einer creator_public_id aus einem vorherigen search_creators-Ergebnis: Name, Stadt, Themen, Branchen, bevorzugter Content, Ausruestung, Erfahrung seit, Honorar- und Reichweitentext, Portfolio-Links, Social-Accounts sowie die human_verification-Stufe. Gibt NIEMALS private Kontaktdaten wie E-Mail oder echten Namen zurueck - diese erhaelt die Brand erst nach request_outreach per E-Mail von UGC VZ. Vor request_outreach verwenden, um einen Treffer aus search_creators naeher zu pruefen.","tags":["creators"],"parameters":[{"name":"publicId","in":"path","required":true,"description":"Oeffentliche Creator-ID im Format UGC-XXXXXXXXXX (10 Hex-Zeichen), aus einem Suchergebnis.","schema":{"type":"string","pattern":"^UGC-[A-F0-9]{10}$"}}],"responses":{"200":{"description":"Oeffentliches Creator-Profil (ohne private Kontaktdaten).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Ungueltige Anfrage (Validierungsfehler).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Ressource nicht gefunden.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate-Limit erreicht. Retry-After beachten.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Interner Fehler.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/outreach":{"post":{"operationId":"requestOutreach","summary":"Kontaktanfrage ausloesen (sendet echte E-Mails!)","description":"ACHTUNG: Dieser Endpunkt loest eine ECHTE Kontaktanfrage aus - UGC VZ versendet daraufhin E-Mails mit Creator-Kontaktdaten an die angegebene Brand-Adresse. KEIN Test-Endpunkt; nicht spekulativ oder zu Testzwecken aufrufen. Loest eine bewusste Brand-Anfrage aus. UGC VZ gibt daraufhin die Kontaktdaten der ausgewaehlten Creator per E-Mail an die Brand weiter. Pflicht: name, email, creator_public_ids aus vorheriger Suche. Gibt request_id fuer get_outreach_status zurueck. Vor diesem Aufruf muessen die Creator ueber search_creators oder get_creator ermittelt worden sein; request_outreach selbst liefert keine Creator-Details und keine privaten Kontaktdaten zurueck, sondern nur die request_id. message und search_query sind optionale Freitextfelder mit Kontext fuer UGC VZ. Typischer Ablauf: search_creators -> get_creator -> request_outreach -> get_outreach_status. Nur fuer ernsthafte, eigene Anfragen aufrufen: der Aufruf loest einen echten E-Mail-Versand aus, name und email muessen der anfragenden Brand tatsaechlich gehoeren. Keine Massenanfragen, keine Testaufrufe. Es gelten die Nutzungsbedingungen unter https://ugc-vz.de/agb (Ziffer 10).","tags":["outreach"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","maxLength":120,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"creator_public_ids":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","pattern":"^UGC-[A-F0-9]{10}$"}},"message":{"type":"string","maxLength":1000},"search_query":{"type":"string","maxLength":500}},"required":["name","email","creator_public_ids"]}}}},"responses":{"202":{"description":"Anfrage angenommen. Status ueber status_url abrufbar.","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"status_url":{"type":"string"}},"required":["request_id"]}}}},"400":{"description":"Ungueltige Anfrage (Validierungsfehler).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate-Limit erreicht. Retry-After beachten.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Interner Fehler.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/outreach/{requestId}":{"get":{"operationId":"getOutreachStatus","summary":"Status einer Kontaktanfrage abrufen","description":"Liefert den aktuellen Status einer zuvor mit request_outreach ausgeloesten Kontaktanfrage anhand der request_id: submitted (eingegangen, noch nicht bearbeitet), working (E-Mail-Versand laeuft), completed (Kontaktdaten wurden per E-Mail zugestellt) oder failed (Versand fehlgeschlagen oder 48 Stunden ohne Zustellung). Gibt NIEMALS private Kontaktdaten selbst zurueck, nur den Lebenszyklus-Status samt Zeitstempeln. Nach request_outreach wiederholt aufrufen, bis der Status completed oder failed ist.","tags":["outreach"],"parameters":[{"name":"requestId","in":"path","required":true,"description":"request_id aus der Antwort von requestOutreach.","schema":{"type":"string","maxLength":80}}],"responses":{"200":{"description":"Lebenszyklus-Status der Anfrage.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string"},"state":{"type":"string","enum":["submitted","working","completed","failed"]},"submittedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["requestId","state"]}}}},"400":{"description":"Ungueltige Anfrage (Validierungsfehler).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Ressource nicht gefunden.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate-Limit erreicht. Retry-After beachten.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Interner Fehler.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/vocab":{"get":{"operationId":"getVocab","summary":"Gueltiges Suchvokabular abrufen","description":"Liefert das aktuell gueltige Vokabular fuer search_creators: haeufigste Themen (topics), Branchen und Staedte aus aktiven Creator-Profilen sowie die Definition der human_verification-Stufen (0 = self_reported, 1 = self_reported_with_portfolio, 2 = reserviert, wird derzeit nicht vergeben) und einen Hinweis zur Preisgestaltung. Enthaelt keine Creator- oder Kontaktdaten. Vor einer ersten search_creators-Anfrage oder bei Unsicherheit ueber gueltige Filterwerte (city, topics, human_verification_level_min) aufrufen.","tags":["meta"],"responses":{"200":{"description":"Themen, Branchen, Staedte und human_verification-Stufen.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Ungueltige Anfrage (Validierungsfehler).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate-Limit erreicht. Retry-After beachten.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Interner Fehler.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"schemas":{"Problem":{"type":"object","description":"Fehlerantwort nach RFC 7807 (application/problem+json).","properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string","description":"Maschinenlesbarer Fehlercode, z. B. validation_failed, not_found, rate_limited."},"resolution":{"type":"string","description":"Hinweis, wie der Fehler behoben werden kann."},"documentation_url":{"type":"string","format":"uri"}},"required":["type","title","status","detail"]},"CreatorSummary":{"type":"object","description":"Oeffentliches Kurzprofil eines Creators aus der Suche. Enthaelt niemals private Kontaktdaten.","properties":{"id":{"type":"string","description":"Oeffentliche Creator-ID im Format UGC-XXXXXXXXXX."},"name":{"type":"string"},"city":{"type":"string"},"reach":{"type":"string","description":"Reichweite als Freitext je Netzwerk."},"totalReach":{"type":"integer"},"networks":{"type":"array","items":{"type":"string"}},"priceRange":{"type":"string"},"humanVerification":{"type":"object","properties":{"level":{"type":"integer"},"name":{"type":"string"}}}},"required":["id","name"]}}},"tags":[{"name":"creators","description":"Oeffentliche Creator-Suche und -Profile."},{"name":"outreach","description":"Kontaktanfragen (loesen echte E-Mails aus)."},{"name":"meta","description":"Vokabular und Hilfsendpunkte."}],"externalDocs":{"description":"Developer-Portal mit MCP-/A2A-Anbindung","url":"https://ugc-vz.de/developers"}}