{"openapi":"3.0.3","externalDocs":{"description":"Menschenlesbare Doku für Drittentwickler (Module, PAT, Scopes)","url":"/docs/http-api-v1"},"info":{"title":"APInterface Core API","version":"1","description":"JSON-API unter /api/v1. Antwort-Header X-Request-Id; Fehler-JSON (HTTP >= 400) enthält zusätzlich requestId im Body. PAT: Authorization: Bearer <apif_…>. Session-JSON (Cookie): mutierende /account/tokens-Aufrufe mit X-CSRF-Token, siehe /settings/api-tokens. CORS (optional): API_CORS_ORIGINS. Modul-Routen optional unter /api/v1/modules/{moduleKey}/… (Scope api.modules.invoke). Einstieg für Drittentwickler: siehe externalDocs (/docs/http-api-v1)."},"servers":[{"url":"/","description":"Gleicher Host"}],"tags":[{"name":"meta","description":"Metadaten"},{"name":"identity","description":"PAT-Kontext"},{"name":"tokens","description":"Personal Access Tokens"},{"name":"audit","description":"Sicherheits-Audit (Mandant)"},{"name":"usage","description":"Modul-Nutzung (Mandant)"}],"paths":{"/api/v1/openapi.json":{"get":{"tags":["meta"],"summary":"OpenAPI-Beschreibung","responses":{"200":{"description":"OpenAPI 3.0 Dokument"}}}},"/api/v1/health":{"get":{"tags":["meta"],"summary":"API-Liveness","responses":{"200":{"description":"ok, coreVersion"}}}},"/api/v1/meta/build":{"get":{"tags":["meta"],"summary":"Build-/Laufzeitinfos","responses":{"200":{"description":"coreVersion, node"}}}},"/api/v1/meta/scopes":{"get":{"tags":["meta"],"summary":"Bekannte PAT-Scopes","responses":{"200":{"description":"Liste von Scope-Strings"}}}},"/api/v1/me":{"get":{"tags":["identity"],"summary":"Kontext des Bearer-Tokens","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Nutzer, Firma, Token-Metadaten"},"401":{"description":"Nicht autorisiert"},"403":{"description":"Scope api.self.read fehlt"}}}},"/api/v1/account/audit/security":{"get":{"tags":["audit"],"summary":"api_security_audit (Firma)","description":"Session (Firmen-Superuser) oder Bearer api.audit.read. Query limit (Default 50, max 200).","security":[{"bearerAuth":[]},{}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"entries[]"},"401":{"description":"Unauthorized"},"403":{"description":"Scope / Rolle"}}}},"/api/v1/account/tokens":{"get":{"tags":["tokens"],"summary":"Token-Metadaten auflisten","description":"Entweder Session (Firmen-Superuser) oder Bearer mit Scope api.tokens.read (Firma = Token-Mandant).","security":[{"bearerAuth":[]},{}],"responses":{"200":{"description":"Liste tokens[]"},"401":{"description":"Session oder Bearer ungültig"},"403":{"description":"Kein Superuser / Scope fehlt"}}},"post":{"tags":["tokens"],"summary":"Neues PAT anlegen","description":"Session: Firmen-Superuser + X-CSRF-Token. Oder Bearer mit api.tokens.manage (ohne CSRF).","security":[{"bearerAuth":[]},{}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":191},"scopes":{"type":"array","items":{"type":"string"}},"expiresInDays":{"type":"integer","minimum":1,"maximum":1825}}}}}},"responses":{"201":{"description":"token einmalig im Body"},"400":{"description":"Validierung"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden / CSRF"}}}},"/api/v1/company/usage":{"get":{"tags":["usage"],"summary":"Modul-Nutzung (JSON oder CSV)","description":"Session (Firmen-Superuser oder Plattform-Admin mit companyId) oder Bearer api.usage.read. Query: month (YYYY-MM), appKey, moduleKey, from, to, limit; format=csv für CSV.","security":[{"bearerAuth":[]},{}],"parameters":[{"name":"companyId","in":"query","required":false,"schema":{"type":"integer"}},{"name":"month","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["csv"]}}],"responses":{"200":{"description":"JSON oder text/csv"},"400":{"description":"companyId fehlt (Plattform-Admin)"},"401":{"description":"Unauthorized"},"403":{"description":"Scope / Rolle"}}}},"/api/v1/company/usage/export.csv":{"get":{"tags":["usage"],"summary":"Modul-Nutzung als CSV","description":"Wie /company/usage mit format=csv; Session oder Bearer api.usage.read.","security":[{"bearerAuth":[]},{}],"parameters":[{"name":"companyId","in":"query","required":false,"schema":{"type":"integer"}},{"name":"month","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"text/csv"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}},"/api/v1/account/tokens/{id}":{"get":{"tags":["tokens"],"summary":"Ein PAT (Metadaten)","description":"Session (Superuser) oder Bearer api.tokens.read; nur eigene Tokens der Firma.","security":[{"bearerAuth":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Objekt token"},"401":{"description":"Unauthorized"},"403":{"description":"Scope / Rolle"},"404":{"description":"Nicht gefunden"}}},"delete":{"tags":["tokens"],"summary":"PAT widerrufen","description":"Session + CSRF oder Bearer api.tokens.manage.","security":[{"bearerAuth":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Widerrufen"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden / CSRF"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"apif_…","description":"Personal Access Token (PAT)"}}}}