{"openapi":"3.1.0","info":{"title":"Kantrik Enrich API","version":"1.0.0","summary":"Firmendaten für den Vertrieb (fiktives Produkt)","description":"Fiktive Beispiel-Firma, Demo-Daten. Alle Antworten sind erfunden. Jede Antwort trägt den Header `X-Kantrik-Demo: fictional`."},"servers":[{"url":"https://api.kantrik.com"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Anreicherung"},{"name":"Konto"}],"paths":{"/v1/enrich":{"post":{"operationId":"enrich","tags":["Anreicherung"],"summary":"Bis zu 100 Firmen anreichern","description":"Credits: 1 je Treffer, 3 mit `include_contacts`, 0 ohne Treffer.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichRequest"}}}},"responses":{"200":{"description":"Ergebnisse in der Reihenfolge der Eingabe","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Kantrik-Demo":{"$ref":"#/components/headers/Demo"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichResponse"}}}},"400":{"description":"`bad_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Kein oder ungültiger Schlüssel (`auth_missing_key`, `auth_invalid_key`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`payload_too_large`","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Minutenlimit erreicht (`rate_limited`, mit `Retry-After`) oder Probe-Credits verbraucht (`limit_reached`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/company":{"get":{"operationId":"company","tags":["Anreicherung"],"summary":"Eine Firma nachschlagen","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","maxLength":200}},{"name":"domain","in":"query","required":false,"schema":{"type":"string","maxLength":253}},{"name":"include_contacts","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Ein Ergebnis","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Kantrik-Demo":{"$ref":"#/components/headers/Demo"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyResponse"}}}},"400":{"description":"`bad_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Kein oder ungültiger Schlüssel (`auth_missing_key`, `auth_invalid_key`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Minutenlimit erreicht (`rate_limited`, mit `Retry-After`) oder Probe-Credits verbraucht (`limit_reached`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage":{"get":{"operationId":"usage","tags":["Konto"],"summary":"Verbrauch der laufenden Periode","responses":{"200":{"description":"Verbrauch und Rechnungsvorschau","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Kantrik-Demo":{"$ref":"#/components/headers/Demo"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"description":"Kein oder ungültiger Schlüssel (`auth_missing_key`, `auth_invalid_key`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Minutenlimit erreicht (`rate_limited`, mit `Retry-After`) oder Probe-Credits verbraucht (`limit_reached`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/invoices":{"get":{"operationId":"invoices","tags":["Konto"],"summary":"Ausgestellte Rechnungen","responses":{"200":{"description":"Rechnungen, neueste zuletzt","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Kantrik-Demo":{"$ref":"#/components/headers/Demo"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceList"}}}},"401":{"description":"Kein oder ungültiger Schlüssel (`auth_missing_key`, `auth_invalid_key`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Minutenlimit erreicht (`rate_limited`, mit `Retry-After`) oder Probe-Credits verbraucht (`limit_reached`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/keys":{"get":{"operationId":"listKeys","tags":["Konto"],"summary":"Schlüssel auflisten (nur Kennungen)","responses":{"200":{"description":"Schlüssel","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Kantrik-Demo":{"$ref":"#/components/headers/Demo"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyList"}}}},"401":{"description":"Kein oder ungültiger Schlüssel (`auth_missing_key`, `auth_invalid_key`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Minutenlimit erreicht (`rate_limited`, mit `Retry-After`) oder Probe-Credits verbraucht (`limit_reached`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createKey","tags":["Konto"],"summary":"Neuen Schlüssel anlegen","responses":{"201":{"description":"Der Schlüssel, einmalig sichtbar","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Kantrik-Demo":{"$ref":"#/components/headers/Demo"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyCreated"}}}},"401":{"description":"Kein oder ungültiger Schlüssel (`auth_missing_key`, `auth_invalid_key`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Minutenlimit erreicht (`rate_limited`, mit `Retry-After`) oder Probe-Credits verbraucht (`limit_reached`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/keys/{key_id}":{"delete":{"operationId":"revokeKey","tags":["Konto"],"summary":"Schlüssel sperren","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Gesperrt","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Kantrik-Demo":{"$ref":"#/components/headers/Demo"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyRevoked"}}}},"401":{"description":"Kein oder ungültiger Schlüssel (`auth_missing_key`, `auth_invalid_key`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden`: der letzte Schlüssel bleibt","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Minutenlimit erreicht (`rate_limited`, mit `Retry-After`) oder Probe-Credits verbraucht (`limit_reached`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/plan":{"post":{"operationId":"changePlan","tags":["Konto"],"summary":"Plan wechseln","description":"Wechsel aus der Probe heraus ist die Umstellung auf einen bezahlten Plan. Abgerechnet wird mit dem Plan, der beim Periodenschluss gilt.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanRequest"}}}},"responses":{"200":{"description":"Neuer Plan","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Kantrik-Demo":{"$ref":"#/components/headers/Demo"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanResponse"}}}},"400":{"description":"`bad_request`","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Kein oder ungültiger Schlüssel (`auth_missing_key`, `auth_invalid_key`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Minutenlimit erreicht (`rate_limited`, mit `Retry-After`) oder Probe-Credits verbraucht (`limit_reached`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/openapi.json":{"get":{"operationId":"openapi","tags":["Konto"],"summary":"Diese Beschreibung","security":[],"responses":{"200":{"description":"OpenAPI 3.1","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API-Schlüssel `kk_...` aus der Plattform."}},"headers":{"RequestId":{"description":"Kennung der Anfrage, für den Support","schema":{"type":"string"}},"Demo":{"description":"Immer `fictional`","schema":{"type":"string","enum":["fictional"]}}},"schemas":{"Error":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message","doc_url"],"properties":{"code":{"type":"string","enum":["auth_missing_key","auth_invalid_key","bad_request","payload_too_large","limit_reached","rate_limited","forbidden","not_found","method_not_allowed","internal"]},"message":{"type":"string"},"doc_url":{"type":"string"},"param":{"type":"string"}}},"request_id":{"type":"string"}}},"Company":{"type":"object","description":"Erfundene Firmendaten. Bei einem teilweisen Treffer nur `industry`, `city` und `country`.","properties":{"name":{"type":"string"},"domain":{"type":["string","null"]},"industry":{"type":"string"},"employees":{"type":"string","enum":["1-10","11-50","51-200","201-500","501-1000","1000+"]},"city":{"type":"string"},"country":{"type":"string","enum":["DE","AT","CH"]},"founded":{"type":"integer"},"technologies":{"type":"array","items":{"type":"string"}}}},"Contact":{"type":"object","required":["role","seniority"],"properties":{"role":{"type":"string"},"seniority":{"type":"string","enum":["executive","director","manager"]}}},"EnrichmentResult":{"type":"object","required":["input_index","match","company","contacts"],"properties":{"input_index":{"type":"integer"},"match":{"type":"string","enum":["matched","partial","unmatched"]},"company":{"oneOf":[{"$ref":"#/components/schemas/Company"},{"type":"null"}]},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}}}},"EnrichRequest":{"type":"object","required":["records"],"properties":{"records":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":200},"domain":{"type":"string","maxLength":253}}}},"include_contacts":{"type":"boolean","description":"Ansprechpartner-Rollen mitliefern (3 statt 1 Credit je Treffer)."}}},"EnrichResponse":{"type":"object","required":["request_id","plan","results","credits_used","credits_remaining"],"properties":{"request_id":{"type":"string"},"plan":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/EnrichmentResult"}},"credits_used":{"type":"integer"},"credits_remaining":{"type":"integer","description":"Noch im Plan enthaltene Credits der Periode (0, wenn darüber hinaus nach Verbrauch abgerechnet wird)."}}},"CompanyResponse":{"type":"object","required":["request_id","result","credits_used"],"properties":{"request_id":{"type":"string"},"result":{"$ref":"#/components/schemas/EnrichmentResult"},"credits_used":{"type":"integer"}}},"Usage":{"type":"object","required":["plan","period","credits_used","credits_included","calls","rate_limit_per_minute","invoice_preview"],"properties":{"plan":{"type":"string"},"period":{"type":"string"},"credits_used":{"type":"integer"},"credits_included":{"type":"integer"},"calls":{"type":"integer"},"rate_limit_per_minute":{"type":"integer"},"invoice_preview":{"type":"object","required":["total_cents","base_cents","overage_credits","overage_cents"],"properties":{"total_cents":{"type":"integer"},"base_cents":{"type":"integer"},"overage_credits":{"type":"integer"},"overage_cents":{"type":"integer"}}}}},"Invoice":{"type":"object","required":["invoice_id","period","plan","credits","base_cents","overage_credits","overage_cents","total_cents","issued_at"],"properties":{"invoice_id":{"type":"string"},"period":{"type":"string"},"plan":{"type":"string"},"credits":{"type":"integer"},"base_cents":{"type":"integer"},"overage_credits":{"type":"integer"},"overage_cents":{"type":"integer"},"total_cents":{"type":"integer"},"issued_at":{"type":"string"}}},"InvoiceList":{"type":"object","required":["invoices"],"properties":{"invoices":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}}}},"KeyInfo":{"type":"object","required":["key_id","created_at","revoked"],"properties":{"key_id":{"type":"string"},"created_at":{"type":"string"},"revoked":{"type":"boolean"}}},"KeyList":{"type":"object","required":["keys"],"properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/KeyInfo"}}}},"KeyCreated":{"type":"object","required":["key_id","api_key"],"properties":{"key_id":{"type":"string"},"api_key":{"type":"string","description":"Der Schlüssel wird nur dieses eine Mal angezeigt."}}},"KeyRevoked":{"type":"object","required":["result"],"properties":{"result":{"type":"string","enum":["revoked"]}}},"PlanRequest":{"type":"object","required":["plan"],"properties":{"plan":{"type":"string","enum":["starter","growth","scale","enterprise"]}}},"PlanResponse":{"type":"object","required":["changed","plan"],"properties":{"changed":{"type":"boolean"},"plan":{"type":"string"}}}}},"x-rate-limits-per-minute":{"trial":10,"starter":60,"growth":300,"scale":1000,"enterprise":3000},"x-fictional":true}