{"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":"Searches the UGC-VZ directory of real, verified UGC creators in the German-speaking region (DACH). query is free text and the main path (e.g. \"fitness creator 30+ for a TikTok product video\"); a language model structures the request server-side. Optional: city (substring), topics (at least one match), human_verification_level_min (0 = self_reported, 1 = self_reported_with_portfolio; levels are derived from profile data, see get_vocab). Results NEVER contain private contact details. Use get_creator for details on a match; request_outreach for a contact request. [DE] 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":"Returns the public profile of a single UGC creator for a creator_public_id from a previous search_creators result: name, city, topics, industries, preferred content, equipment, experience since, fee and reach text, portfolio links, social accounts and the human_verification level. NEVER returns private contact details such as e-mail or real name - the brand receives those from UGC VZ by e-mail only after request_outreach. Use before request_outreach to inspect a match more closely. [DE] 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. Triggers a deliberate brand request. UGC VZ then forwards the contact details of the selected creators to the brand by e-mail. Required: name, email, creator_public_ids from a previous search. Returns request_id for get_outreach_status. Creators must have been found via search_creators or get_creator before this call; request_outreach itself returns no creator details and no private contact data, only the request_id. message and search_query are optional free-text context (the placeholder [Name] is replaced by each creator name). Typical flow: search_creators -> get_creator -> request_outreach -> get_outreach_status. Call only for serious, genuine requests: the call triggers a real e-mail, and name and email must actually belong to the requesting brand. No bulk requests, no test calls. Free allowance: 10 creators per e-mail per 30 days; beyond that the call returns unlock_required - send a short note (project, timeframe, budget) via https://ugc-vz.de/contact and we unlock free of charge. The terms of use at https://ugc-vz.de/agb (section 10) apply. [DE] 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 (Platzhalter [Name] wird je Creator ersetzt). 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. Freikontingent: 10 Creator pro E-Mail und 30 Tage; darueber liefert der Aufruf unlock_required - kurze Nachricht (Projekt, Zeitraum, Budget) ueber https://ugc-vz.de/contact, dann schalten wir kostenlos frei. 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":"Returns the current status of a contact request previously triggered with request_outreach, by request_id: submitted (received, not yet processed), working (e-mail delivery in progress), completed (contact details delivered by e-mail) or failed (delivery failed or 48 hours without delivery). NEVER returns private contact details itself, only the lifecycle status with timestamps. Call repeatedly after request_outreach until the status is completed or failed. [DE] 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":"Returns the currently valid vocabulary for search_creators: most common topics, industries and cities from active creator profiles, the definition of the human_verification levels (0 = self_reported, 1 = self_reported_with_portfolio, 2 = reserved, currently not assigned) and a note on pricing. Contains no creator or contact data. Call before a first search_creators request or when unsure about valid filter values (city, topics, human_verification_level_min). [DE] 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"}}