{ "openapi": "3.1.0", "info": { "title": "Apophis Orchestrator API", "description": "API HTTP de l'orchestrator Apophis (codename interne d'ExtentAPI). Plan public client (`x-api-key` côté Solution Métier, document `openapi-public.json`). Plan super-admin plateforme (`iamAuth({ requireInternalAdmin: true })`, tenant `internal` + rôle `internal_admin` — exclu de `openapi-public.json`, présent dans `openapi.json`). Plan control consommé par les agents (`x-internal-token`, document `openapi-internal.json`).", "version": "1.0.0", "license": { "name": "Proprietary", "identifier": "LicenseRef-Proprietary" }, "x-audience": "internal" }, "servers": [ { "url": "http://localhost:8080", "description": "Dev (Bun.serve, défaut local)." }, { "url": "https://orchestrator.example", "description": "Remplacer par l'URL prod." } ], "tags": [ { "name": "auth", "description": "Authentification IAM (login, magic-link, refresh, logout, password)." }, { "name": "iam", "description": "Gestion IAM tenant courant (identités, rôles, clés API, sessions, délégations)." }, { "name": "billing", "description": "Crédits prépayés, ledger, pricing-list — surface client + control-plane." }, { "name": "jobs", "description": "Création, lecture, replay, cancellation des jobs de crawl (Scraper)." }, { "name": "page-history", "description": "Historique de contenu par URL (Scraper) — timeline des versions + raw, alimenté transverse." }, { "name": "network", "description": "Composant network — géolocalisation IP (`/v1/network/ip/lookup`) et futures ressources réseau." }, { "name": "webhooks", "description": "Webhooks abonnés aux événements job (Scraper)." }, { "name": "extractions", "description": "Extractions structurées (Extractor) — création, lecture, search, replay, cancel." }, { "name": "extraction-webhooks", "description": "(Legacy tag — voir `webhook-deliveries`.) Webhooks abonnés aux événements extraction (Extractor)." }, { "name": "extractor-configs", "description": "Configurations d'extraction réutilisables (Extractor)." }, { "name": "quotas", "description": "Consultation des quotas effectifs + usage par le tenant courant, et demandes d'augmentation." } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Clé `apo_<43 chars base64url>` créée via `POST /api-clients`. Scopes: `read | write | admin`." }, "internalToken": { "type": "apiKey", "in": "header", "name": "x-internal-token", "description": "Token statique partagé entre orchestrator et agents (`APOPHIS_INTERNAL_TOKEN_PRIMARY`). Rotation zero-downtime via `APOPHIS_INTERNAL_TOKEN_SECONDARY`." } }, "schemas": {} }, "paths": { "/v1/iam/auth/totp/enable": { "post": { "operationId": "postV1IamAuthTotpEnable", "tags": [ "auth" ], "summary": "Enable TOTP", "description": "Returns the otpauth:// URL (for the authenticator QR) and the recovery codes in plaintext — shown ONCE. The User row stores the encrypted secret (APOPHIS_IAM_TOTP_KEY, C4=b) but `totpEnabledAt` stays NULL until /iam/auth/totp/verify confirms the user scanned the QR.", "responses": { "200": { "description": "TOTP enable payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "otpauthUrl": { "type": "string" }, "secret": { "type": "string" }, "recoveryCodes": { "type": "array", "items": { "type": "string" } } }, "required": [ "otpauthUrl", "secret", "recoveryCodes" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "409": { "description": "Conflit d'état (`cannot_replay_`, `idempotency_mismatch`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/auth/totp/verify": { "post": { "operationId": "postV1IamAuthTotpVerify", "tags": [ "auth" ], "summary": "Confirm TOTP", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "TOTP verified + enabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "verified": { "type": "boolean", "const": true }, "verifiedAt": { "type": "string", "format": "date-time" } }, "required": [ "verified", "verifiedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/auth/totp/disable": { "post": { "operationId": "postV1IamAuthTotpDisable", "tags": [ "auth" ], "summary": "Disable TOTP", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentPassword": { "type": "string", "minLength": 1, "maxLength": 1024 }, "totpCode": { "type": "string", "pattern": "^\\d{6}$" }, "recoveryCode": { "type": "string", "minLength": 8, "maxLength": 64 } } } } } }, "responses": { "200": { "description": "TOTP disabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "disabled": { "type": "boolean", "const": true }, "disabledAt": { "type": "string", "format": "date-time" } }, "required": [ "disabled", "disabledAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "409": { "description": "Conflit d'état (`cannot_replay_`, `idempotency_mismatch`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/auth/totp/recovery-codes/regenerate": { "post": { "operationId": "postV1IamAuthTotpRecoveryCodesRegenerate", "tags": [ "auth" ], "summary": "Regenerate recovery codes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentPassword": { "type": "string", "minLength": 1, "maxLength": 1024 }, "totpCode": { "type": "string", "pattern": "^\\d{6}$" }, "recoveryCode": { "type": "string", "minLength": 8, "maxLength": 64 } } } } } }, "responses": { "200": { "description": "Fresh codes returned (shown once).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "regenerated": { "type": "boolean", "const": true }, "regeneratedAt": { "type": "string", "format": "date-time" }, "recoveryCodes": { "type": "array", "items": { "type": "string" } } }, "required": [ "regenerated", "regeneratedAt", "recoveryCodes" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "409": { "description": "Conflit d'état (`cannot_replay_`, `idempotency_mismatch`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/auth/csrf": { "get": { "operationId": "getV1IamAuthCsrf", "tags": [ "auth" ], "summary": "Get a CSRF token", "responses": { "200": { "description": "CSRF token issued and cookie set.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "csrfToken": { "type": "string" } }, "required": [ "csrfToken" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } } } } }, "/v1/iam/auth/login": { "post": { "operationId": "postV1IamAuthLogin", "tags": [ "auth" ], "summary": "Log in", "description": "Anti-enumeration : retourne 401 invalid_credentials que l'email existe ou pas. Set les cookies apophis_at/rt/csrf en cas de succès.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "minLength": 3, "maxLength": 320 }, "password": { "type": "string", "minLength": 1, "maxLength": 1024 }, "totpCode": { "type": "string", "pattern": "^\\d{6}$" }, "recoveryCode": { "type": "string", "minLength": 8, "maxLength": 64 } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "Authentifié.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "sessionId": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "requiresPasswordSetup": { "type": "boolean" }, "csrfToken": { "type": "string" } }, "required": [ "sessionId", "expiresAt", "requiresPasswordSetup", "csrfToken" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "429": { "description": "Rate-limit dépassé. Header `Retry-After` retourné.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/auth/refresh": { "post": { "operationId": "postV1IamAuthRefresh", "tags": [ "auth" ], "summary": "Refresh the session", "description": "Lit le refresh depuis cookie apophis_rt ou body { refreshToken }. Rotation atomique : l'ancien refresh devient inutilisable. Replay détecté = kill toutes les sessions du User.", "responses": { "200": { "description": "Tokens rotated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "sessionId": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "requiresPasswordSetup": { "type": "boolean" }, "csrfToken": { "type": "string" } }, "required": [ "sessionId", "expiresAt", "requiresPasswordSetup", "csrfToken" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "429": { "description": "Rate-limit dépassé. Header `Retry-After` retourné.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/auth/logout": { "post": { "operationId": "postV1IamAuthLogout", "tags": [ "auth" ], "summary": "Log out", "responses": { "200": { "description": "Logged out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "loggedOut": { "type": "boolean", "const": true }, "loggedOutAt": { "type": "string", "format": "date-time" } }, "required": [ "loggedOut", "loggedOutAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } } } } }, "/v1/iam/auth/me": { "get": { "operationId": "getV1IamAuthMe", "tags": [ "auth" ], "summary": "Retrieve the current identity", "responses": { "200": { "description": "Identity snapshot.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "identityId": { "type": "string" }, "tenantId": { "type": "string" }, "displayName": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "isInternalAdmin": { "type": "boolean" }, "requiresPasswordSetup": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "string", "enum": [ "low_recovery_codes" ] } } }, "required": [ "identityId", "tenantId", "displayName", "email", "isInternalAdmin", "requiresPasswordSetup" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/auth/forgot-password": { "post": { "operationId": "postV1IamAuthForgotPassword", "tags": [ "auth" ], "summary": "Request a password reset", "description": "Toujours 200 — même si l'email n'existe pas, on ne révèle pas l'existence.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "minLength": 3, "maxLength": 320 } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Email envoyé si éligible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "requested": { "type": "boolean", "const": true }, "requestedAt": { "type": "string", "format": "date-time" } }, "required": [ "requested", "requestedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "429": { "description": "Rate-limit dépassé. Header `Retry-After` retourné.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/auth/reset-password": { "post": { "operationId": "postV1IamAuthResetPassword", "tags": [ "auth" ], "summary": "Reset the password", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 20, "maxLength": 128 }, "newPassword": { "type": "string", "minLength": 8, "maxLength": 1024 } }, "required": [ "token", "newPassword" ] } } } }, "responses": { "200": { "description": "Password reset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "reset": { "type": "boolean", "const": true }, "resetAt": { "type": "string", "format": "date-time" } }, "required": [ "reset", "resetAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/auth/change-password": { "post": { "operationId": "postV1IamAuthChangePassword", "tags": [ "auth" ], "summary": "Change the password", "description": "Self-service password change. Le user fournit son currentPassword + un newPassword. Verif via bcrypt, hash new, met `passwordChangedAt`, révoque toutes les sessions actives SAUF la courante (kick d'éventuels attackers). Audit `iam.user.password_changed`. Pour reset oubli password, voir `/iam/auth/forgot-password` → `/iam/auth/reset-password`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentPassword": { "type": "string", "minLength": 1, "maxLength": 1024 }, "newPassword": { "type": "string", "minLength": 8, "maxLength": 1024 } }, "required": [ "currentPassword", "newPassword" ] } } } }, "responses": { "200": { "description": "Password changed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "changed": { "type": "boolean", "const": true }, "changedAt": { "type": "string", "format": "date-time" }, "revokedSessions": { "type": "integer" } }, "required": [ "changed", "changedAt", "revokedSessions" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "409": { "description": "Conflit d'état (`cannot_replay_`, `idempotency_mismatch`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/auth/verify-email": { "post": { "operationId": "postV1IamAuthVerifyEmail", "tags": [ "auth" ], "summary": "Verify the email", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 20, "maxLength": 128 } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Email verified.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "verified": { "type": "boolean", "const": true }, "verifiedAt": { "type": "string", "format": "date-time" } }, "required": [ "verified", "verifiedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/auth/magic-link/request": { "post": { "operationId": "postV1IamAuthMagicLinkRequest", "tags": [ "auth" ], "summary": "Request a magic link", "description": "Toujours 200 — même si l'email n'existe pas. Sinon : génère un token sha256 hashé via iamHash() (TTL 15min) et envoie le raw via email. Rate-limit §5.5 : 3/h email, 10/h IP.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "minLength": 3, "maxLength": 320 } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Email envoyé si éligible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "requested": { "type": "boolean", "const": true }, "requestedAt": { "type": "string", "format": "date-time" } }, "required": [ "requested", "requestedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "429": { "description": "Rate-limit dépassé. Header `Retry-After` retourné.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/auth/magic-link/verify": { "post": { "operationId": "postV1IamAuthMagicLinkVerify", "tags": [ "auth" ], "summary": "Verify a magic link", "description": "Single-use : la consommation marque `magicLinkConsumedAt=now()`. Si l'email n'était pas vérifié (verifiedAt IS NULL), met aussi `verifiedAt=now()` dans la même transaction. Mint une session ; si `User.passwordHash IS NULL` le JWT porte `requiresPasswordSetup=true` (C11=a — l'admin-panel force le `/set-password` avant tout autre accès).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 20, "maxLength": 128 } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Session minted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "sessionId": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "requiresPasswordSetup": { "type": "boolean" }, "csrfToken": { "type": "string" } }, "required": [ "sessionId", "expiresAt", "requiresPasswordSetup", "csrfToken" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/auth/set-password": { "post": { "operationId": "postV1IamAuthSetPassword", "tags": [ "auth" ], "summary": "Set the initial password", "description": "C11=a — utilisable UNE FOIS quand `User.passwordHash IS NULL`. Pour les changements de mot de passe ultérieurs, utiliser `/iam/auth/reset-password` via le flow forgot. Refuse 409 si un password est déjà défini.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "newPassword": { "type": "string", "minLength": 8, "maxLength": 1024 } }, "required": [ "newPassword" ] } } } }, "responses": { "200": { "description": "Password set.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "set": { "type": "boolean", "const": true }, "setAt": { "type": "string", "format": "date-time" }, "accessToken": { "type": [ "string", "null" ] } }, "required": [ "set", "setAt", "accessToken" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "409": { "description": "Conflit d'état (`cannot_replay_`, `idempotency_mismatch`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/auth/register": { "post": { "operationId": "postV1IamAuthRegister", "tags": [ "auth" ], "summary": "Register", "description": "Plan §1.13 — registration libre désactivée en V1. Body doit porter un `invitationToken` issu d'`IdentityAccess` ou `Delegation` `status=pending`. Sinon 403 `registration_disabled`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invitationToken": { "type": "string", "minLength": 20, "maxLength": 128 }, "email": { "type": "string", "format": "email", "minLength": 3, "maxLength": 320 }, "password": { "type": "string", "minLength": 8, "maxLength": 1024 }, "firstName": { "type": "string", "maxLength": 80 }, "lastName": { "type": "string", "maxLength": 80 } }, "required": [ "email", "password" ] } } } }, "responses": { "201": { "description": "Inscrit + connecté.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "sessionId": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "requiresPasswordSetup": { "type": "boolean" }, "csrfToken": { "type": "string" } }, "required": [ "sessionId", "expiresAt", "requiresPasswordSetup", "csrfToken" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/users/me/delegations/granted": { "get": { "operationId": "getV1IamUsersMeDelegationsGranted", "tags": [ "iam" ], "summary": "List granted delegations", "responses": { "200": { "description": "Delegations the caller has granted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "delegatorId": { "type": "string" }, "delegateId": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "declined", "revoked", "renounced", "expired" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "invitedAt": { "type": "string", "format": "date-time" }, "respondedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "delegatorDisplayName": { "type": [ "string", "null" ] }, "delegateDisplayName": { "type": [ "string", "null" ] } }, "required": [ "id", "tenantId", "delegatorId", "delegateId", "reason", "status", "expiresAt", "invitedAt", "respondedAt", "revokedAt", "createdAt", "delegatorDisplayName", "delegateDisplayName" ] } } }, "required": [ "items" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/users/me/delegations/received": { "get": { "operationId": "getV1IamUsersMeDelegationsReceived", "tags": [ "iam" ], "summary": "List received delegations", "responses": { "200": { "description": "Delegations the caller has received.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "delegatorId": { "type": "string" }, "delegateId": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "declined", "revoked", "renounced", "expired" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "invitedAt": { "type": "string", "format": "date-time" }, "respondedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "delegatorDisplayName": { "type": [ "string", "null" ] }, "delegateDisplayName": { "type": [ "string", "null" ] } }, "required": [ "id", "tenantId", "delegatorId", "delegateId", "reason", "status", "expiresAt", "invitedAt", "respondedAt", "revokedAt", "createdAt", "delegatorDisplayName", "delegateDisplayName" ] } } }, "required": [ "items" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/users/me/delegations": { "post": { "operationId": "postV1IamUsersMeDelegations", "tags": [ "iam" ], "summary": "Create a delegation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "delegateId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "delegateId", "reason", "expiresAt" ] } } } }, "responses": { "201": { "description": "Delegation created (status=pending).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "delegatorId": { "type": "string" }, "delegateId": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "declined", "revoked", "renounced", "expired" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "invitedAt": { "type": "string", "format": "date-time" }, "respondedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "delegatorDisplayName": { "type": [ "string", "null" ] }, "delegateDisplayName": { "type": [ "string", "null" ] } }, "required": [ "id", "tenantId", "delegatorId", "delegateId", "reason", "status", "expiresAt", "invitedAt", "respondedAt", "revokedAt", "createdAt", "delegatorDisplayName", "delegateDisplayName" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "409": { "description": "Conflit d'état (`cannot_replay_`, `idempotency_mismatch`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "422": { "description": "Validation métier KO (`unsafe_url`, `invalid_bulk_body`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/users/me/delegations/accept": { "post": { "operationId": "postV1IamUsersMeDelegationsAccept", "tags": [ "iam" ], "summary": "Accept a delegation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 20 } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Delegation accepted (status=active).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "delegatorId": { "type": "string" }, "delegateId": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "declined", "revoked", "renounced", "expired" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "invitedAt": { "type": "string", "format": "date-time" }, "respondedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "delegatorDisplayName": { "type": [ "string", "null" ] }, "delegateDisplayName": { "type": [ "string", "null" ] }, "accepted": { "type": "boolean", "const": true }, "acceptedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "delegatorId", "delegateId", "reason", "status", "expiresAt", "invitedAt", "respondedAt", "revokedAt", "createdAt", "delegatorDisplayName", "delegateDisplayName", "accepted", "acceptedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "410": { "description": "Ressource n'est plus disponible (état terminal, contenu purgé).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/users/me/delegations/{id}/decline": { "post": { "operationId": "postV1IamUsersMeDelegationsByIdDecline", "tags": [ "iam" ], "summary": "Decline a delegation", "responses": { "200": { "description": "Delegation declined.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "delegatorId": { "type": "string" }, "delegateId": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "declined", "revoked", "renounced", "expired" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "invitedAt": { "type": "string", "format": "date-time" }, "respondedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "delegatorDisplayName": { "type": [ "string", "null" ] }, "delegateDisplayName": { "type": [ "string", "null" ] }, "declined": { "type": "boolean", "const": true }, "declinedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "delegatorId", "delegateId", "reason", "status", "expiresAt", "invitedAt", "respondedAt", "revokedAt", "createdAt", "delegatorDisplayName", "delegateDisplayName", "declined", "declinedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "410": { "description": "Ressource n'est plus disponible (état terminal, contenu purgé).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/v1/iam/users/me/delegations/{id}": { "delete": { "operationId": "deleteV1IamUsersMeDelegationsById", "tags": [ "iam" ], "summary": "Revoke a delegation", "responses": { "200": { "description": "Delegation revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "delegatorId": { "type": "string" }, "delegateId": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "declined", "revoked", "renounced", "expired" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "invitedAt": { "type": "string", "format": "date-time" }, "respondedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "delegatorDisplayName": { "type": [ "string", "null" ] }, "delegateDisplayName": { "type": [ "string", "null" ] }, "revoked": { "type": "boolean", "const": true } }, "required": [ "id", "tenantId", "delegatorId", "delegateId", "reason", "status", "expiresAt", "invitedAt", "respondedAt", "revokedAt", "createdAt", "delegatorDisplayName", "delegateDisplayName", "revoked" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "410": { "description": "Ressource n'est plus disponible (état terminal, contenu purgé).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/v1/iam/users/me/delegations/{id}/renounce": { "post": { "operationId": "postV1IamUsersMeDelegationsByIdRenounce", "tags": [ "iam" ], "summary": "Renounce a delegation", "responses": { "200": { "description": "Delegation renounced.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "delegatorId": { "type": "string" }, "delegateId": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "declined", "revoked", "renounced", "expired" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "invitedAt": { "type": "string", "format": "date-time" }, "respondedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "delegatorDisplayName": { "type": [ "string", "null" ] }, "delegateDisplayName": { "type": [ "string", "null" ] }, "renounced": { "type": "boolean", "const": true }, "renouncedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "delegatorId", "delegateId", "reason", "status", "expiresAt", "invitedAt", "respondedAt", "revokedAt", "createdAt", "delegatorDisplayName", "delegateDisplayName", "renounced", "renouncedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "410": { "description": "Ressource n'est plus disponible (état terminal, contenu purgé).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/v1/iam/users/me": { "get": { "operationId": "getV1IamUsersMe", "tags": [ "iam" ], "summary": "Retrieve the current user", "responses": { "200": { "description": "User snapshot.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "identityId": { "type": "string" }, "tenantId": { "type": "string" }, "type": { "type": "string", "const": "user" }, "displayName": { "type": "string" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "suspended", "deleted" ] }, "passwordChangedAt": { "type": [ "string", "null" ], "format": "date-time" }, "totpEnabledAt": { "type": [ "string", "null" ], "format": "date-time" }, "defaultRoleId": { "type": [ "string", "null" ] }, "emails": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "isPrimary": { "type": "boolean" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "email", "isPrimary", "verifiedAt" ] } }, "permissions": { "type": "array", "items": { "type": "string" } }, "isInternalAdmin": { "type": "boolean" }, "requiresPasswordSetup": { "type": "boolean" } }, "required": [ "identityId", "tenantId", "type", "displayName", "firstName", "lastName", "avatarUrl", "status", "passwordChangedAt", "totpEnabledAt", "defaultRoleId", "emails", "permissions", "isInternalAdmin", "requiresPasswordSetup" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } }, "patch": { "operationId": "patchV1IamUsersMe", "tags": [ "iam" ], "summary": "Update the current user", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": [ "string", "null" ], "maxLength": 80 }, "lastName": { "type": [ "string", "null" ], "maxLength": 80 }, "avatarUrl": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 } } } } } }, "responses": { "200": { "description": "Profile updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "identityId": { "type": "string" }, "tenantId": { "type": "string" }, "type": { "type": "string", "const": "user" }, "displayName": { "type": "string" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "suspended", "deleted" ] }, "passwordChangedAt": { "type": [ "string", "null" ], "format": "date-time" }, "totpEnabledAt": { "type": [ "string", "null" ], "format": "date-time" }, "defaultRoleId": { "type": [ "string", "null" ] }, "emails": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "isPrimary": { "type": "boolean" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "email", "isPrimary", "verifiedAt" ] } }, "permissions": { "type": "array", "items": { "type": "string" } }, "isInternalAdmin": { "type": "boolean" }, "requiresPasswordSetup": { "type": "boolean" } }, "required": [ "identityId", "tenantId", "type", "displayName", "firstName", "lastName", "avatarUrl", "status", "passwordChangedAt", "totpEnabledAt", "defaultRoleId", "emails", "permissions", "isInternalAdmin", "requiresPasswordSetup" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/users/me/sessions": { "get": { "operationId": "getV1IamUsersMeSessions", "tags": [ "iam" ], "summary": "List sessions", "responses": { "200": { "description": "Sessions list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "ipAddress": { "type": [ "string", "null" ] }, "userAgent": { "type": [ "string", "null" ] }, "lastActivityAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "isCurrent": { "type": "boolean" } }, "required": [ "id", "ipAddress", "userAgent", "lastActivityAt", "expiresAt", "revokedAt", "createdAt", "isCurrent" ] } } }, "required": [ "items" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } }, "delete": { "operationId": "deleteV1IamUsersMeSessions", "tags": [ "iam" ], "summary": "Revoke all sessions", "description": "Useful when the user wants to log out of every other device. The active session (the one that issued this call) stays alive.", "responses": { "200": { "description": "Sessions revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "revoked": { "type": "boolean", "const": true }, "revokedAt": { "type": "string", "format": "date-time" }, "revokedCount": { "type": "integer" } }, "required": [ "revoked", "revokedAt", "revokedCount" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/users/me/sessions/{sid}": { "delete": { "operationId": "deleteV1IamUsersMeSessionsBySid", "tags": [ "iam" ], "summary": "Revoke a session", "responses": { "200": { "description": "Session revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "revoked": { "type": "boolean", "const": true }, "revokedAt": { "type": "string", "format": "date-time" }, "id": { "type": "string" } }, "required": [ "revoked", "revokedAt", "id" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ] } }, "/v1/iam/identities/{id}/api-keys": { "get": { "operationId": "getV1IamIdentitiesByIdApiKeys", "tags": [ "iam" ], "summary": "List API keys", "responses": { "200": { "description": "ApiKey list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "keyPrefix": { "type": "string" }, "roleId": { "type": "string" }, "rateLimitPerMinute": { "type": "integer" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "keyPrefix", "roleId", "rateLimitPerMinute", "lastUsedAt", "expiresAt", "revokedAt", "createdAt" ] } } }, "required": [ "items" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] }, "post": { "operationId": "postV1IamIdentitiesByIdApiKeys", "tags": [ "iam" ], "summary": "Create an API key", "description": "Returns the plaintext key ONCE in `rawKey`. Subsequent reads only expose `keyPrefix`. Re-auth (currentPassword/totpCode) required when the chosen role carries `*:*:*` or `cross_tenant:*:*` (C7).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 500 }, "roleId": { "type": "string", "minLength": 1 }, "rateLimitPerMinute": { "type": "integer", "minimum": 1, "maximum": 5000 }, "expiresAt": { "type": "string", "format": "date-time" }, "currentPassword": { "type": "string", "minLength": 1, "maxLength": 1024 }, "totpCode": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "name", "roleId" ] } } } }, "responses": { "201": { "description": "ApiKey created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "keyPrefix": { "type": "string" }, "roleId": { "type": "string" }, "rateLimitPerMinute": { "type": "integer" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "rawKey": { "type": "string" } }, "required": [ "id", "name", "description", "keyPrefix", "roleId", "rateLimitPerMinute", "lastUsedAt", "expiresAt", "revokedAt", "createdAt", "rawKey" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "422": { "description": "Validation métier KO (`unsafe_url`, `invalid_bulk_body`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/v1/iam/identities/{id}/api-keys/{kid}": { "get": { "operationId": "getV1IamIdentitiesByIdApiKeysByKid", "tags": [ "iam" ], "summary": "Retrieve an API key", "responses": { "200": { "description": "ApiKey detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "keyPrefix": { "type": "string" }, "roleId": { "type": "string" }, "rateLimitPerMinute": { "type": "integer" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "keyPrefix", "roleId", "rateLimitPerMinute", "lastUsedAt", "expiresAt", "revokedAt", "createdAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "kid", "required": true } ] }, "delete": { "operationId": "deleteV1IamIdentitiesByIdApiKeysByKid", "tags": [ "iam" ], "summary": "Revoke an API key", "description": "Idempotent — revoking an already-revoked key is a no-op (still 200).", "responses": { "200": { "description": "ApiKey revoked (idempotent).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "revoked": { "type": "boolean", "const": true }, "revokedAt": { "type": "string", "format": "date-time" }, "apiKeyId": { "type": "string" } }, "required": [ "revoked", "revokedAt", "apiKeyId" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "kid", "required": true } ] }, "patch": { "operationId": "patchV1IamIdentitiesByIdApiKeysByKid", "tags": [ "iam" ], "summary": "Update an API key", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "maxLength": 500 }, "rateLimitPerMinute": { "type": "integer", "minimum": 1, "maximum": 5000 }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "responses": { "200": { "description": "ApiKey patched.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "keyPrefix": { "type": "string" }, "roleId": { "type": "string" }, "rateLimitPerMinute": { "type": "integer" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "keyPrefix", "roleId", "rateLimitPerMinute", "lastUsedAt", "expiresAt", "revokedAt", "createdAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "kid", "required": true } ] } }, "/v1/iam/organizations/{orgIdentityId}/invitations": { "get": { "operationId": "getV1IamOrganizationsByOrgIdentityIdInvitations", "tags": [ "iam" ], "summary": "List invitations", "responses": { "200": { "description": "Invitations pending on this organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "organizationId": { "type": "string" }, "userId": { "type": "string" }, "email": { "type": "string" }, "roleId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "declined", "revoked", "renounced" ] }, "invitedAt": { "type": "string", "format": "date-time" }, "invitationExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "tenantId", "organizationId", "userId", "email", "roleId", "status", "invitedAt", "invitationExpiresAt" ] } } }, "required": [ "items" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "422": { "description": "Validation métier KO (`unsafe_url`, `invalid_bulk_body`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "orgIdentityId", "required": true } ] }, "post": { "operationId": "postV1IamOrganizationsByOrgIdentityIdInvitations", "tags": [ "iam" ], "summary": "Create an invitation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "roleId": { "type": "string", "minLength": 1 }, "firstName": { "type": "string", "maxLength": 80 }, "lastName": { "type": "string", "maxLength": 80 } }, "required": [ "email", "roleId" ] } } } }, "responses": { "201": { "description": "Invitation created + email sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "organizationId": { "type": "string" }, "userId": { "type": "string" }, "email": { "type": "string" }, "roleId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "declined", "revoked", "renounced" ] }, "invitedAt": { "type": "string", "format": "date-time" }, "invitationExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "tenantId", "organizationId", "userId", "email", "roleId", "status", "invitedAt", "invitationExpiresAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "409": { "description": "Conflit d'état (`cannot_replay_`, `idempotency_mismatch`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "422": { "description": "Validation métier KO (`unsafe_url`, `invalid_bulk_body`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "orgIdentityId", "required": true } ] } }, "/v1/iam/organizations/{orgIdentityId}/invitations/{id}/revoke": { "post": { "operationId": "postV1IamOrganizationsByOrgIdentityIdInvitationsByIdRevoke", "tags": [ "iam" ], "summary": "Revoke an invitation", "responses": { "200": { "description": "Invitation revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "organizationId": { "type": "string" }, "userId": { "type": "string" }, "email": { "type": "string" }, "roleId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "declined", "revoked", "renounced" ] }, "invitedAt": { "type": "string", "format": "date-time" }, "invitationExpiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "revoked": { "type": "boolean", "const": true }, "revokedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "organizationId", "userId", "email", "roleId", "status", "invitedAt", "invitationExpiresAt", "revoked", "revokedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "410": { "description": "Ressource n'est plus disponible (état terminal, contenu purgé).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "orgIdentityId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/v1/iam/roles": { "get": { "operationId": "getV1IamRoles", "tags": [ "iam" ], "summary": "List roles", "responses": { "200": { "description": "Role list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "isSystem": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "name", "description", "permissions", "isSystem", "createdAt", "updatedAt" ] } } }, "required": [ "items" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } }, "post": { "operationId": "postV1IamRoles", "tags": [ "iam" ], "summary": "Create a role", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 60 }, "description": { "type": "string", "maxLength": 500 }, "permissions": { "type": "array", "items": { "type": "string", "pattern": "^(?:\\*|[a-z][a-z0-9_]*)(?::(?:\\*|[a-z][a-z0-9_]*)){2}$" }, "minItems": 1, "maxItems": 200 } }, "required": [ "name", "permissions" ] } } } }, "responses": { "201": { "description": "Role created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "isSystem": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "name", "description", "permissions", "isSystem", "createdAt", "updatedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "409": { "description": "Conflit d'état (`cannot_replay_`, `idempotency_mismatch`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/roles/{id}": { "get": { "operationId": "getV1IamRolesById", "tags": [ "iam" ], "summary": "Retrieve a role", "responses": { "200": { "description": "Role detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "isSystem": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "name", "description", "permissions", "isSystem", "createdAt", "updatedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] }, "delete": { "operationId": "deleteV1IamRolesById", "tags": [ "iam" ], "summary": "Delete a role", "description": "Refusé si `isSystem=true`. Refusé si le rôle est encore utilisé par un IdentityAccess, ApiKey, ou User.defaultRole (409 role_in_use).", "responses": { "200": { "description": "Role deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "deletedAt": { "type": "string", "format": "date-time" }, "id": { "type": "string" } }, "required": [ "deleted", "deletedAt", "id" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "409": { "description": "Conflit d'état (`cannot_replay_`, `idempotency_mismatch`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] }, "patch": { "operationId": "patchV1IamRolesById", "tags": [ "iam" ], "summary": "Update a role", "description": "Roles `isSystem=true` cannot be mutated. New permissions revalidated via assertCanonicalPermission(C1=a+C12).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 60 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "permissions": { "type": "array", "items": { "type": "string", "pattern": "^(?:\\*|[a-z][a-z0-9_]*)(?::(?:\\*|[a-z][a-z0-9_]*)){2}$" }, "minItems": 1, "maxItems": 200 } } } } } }, "responses": { "200": { "description": "Role updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "isSystem": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "name", "description", "permissions", "isSystem", "createdAt", "updatedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "409": { "description": "Conflit d'état (`cannot_replay_`, `idempotency_mismatch`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/v1/iam/quotas/me": { "get": { "operationId": "getV1IamQuotasMe", "tags": [ "quotas" ], "summary": "List quotas", "responses": { "200": { "description": "Quotas du tenant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "tenantId": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "category": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "unit": { "type": "string" }, "scope": { "type": "string", "enum": [ "stock", "rate", "concurrent" ] }, "window": { "type": [ "string", "null" ] }, "defaultLimit": { "type": "string" }, "effectiveLimit": { "type": "string" }, "source": { "type": "string", "enum": [ "default", "override" ] }, "current": { "type": [ "string", "null" ] }, "percentUsed": { "type": [ "number", "null" ] } }, "required": [ "key", "category", "label", "description", "unit", "scope", "window", "defaultLimit", "effectiveLimit", "source", "current", "percentUsed" ] } } }, "required": [ "tenantId", "items" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/quotas/me/requests": { "get": { "operationId": "getV1IamQuotasMeRequests", "tags": [ "quotas" ], "summary": "List quota requests (offset/limit)", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false } ], "responses": { "200": { "description": "Demandes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "quotaKey": { "type": "string" }, "requestedBy": { "type": "string" }, "requestedLimit": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn" ] }, "decidedBy": { "type": [ "string", "null" ] }, "decidedAt": { "type": [ "string", "null" ], "format": "date-time" }, "decisionNote": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "quotaKey", "requestedBy", "requestedLimit", "reason", "status", "decidedBy", "decidedAt", "decisionNote", "createdAt", "updatedAt" ] } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "exclusiveMinimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" } }, "required": [ "offset", "limit", "total", "hasMore" ] }, "sort": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "dir": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "field", "dir" ] } } }, "required": [ "items", "pagination" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } }, "post": { "operationId": "postV1IamQuotasMeRequests", "tags": [ "quotas" ], "summary": "Create a quota increase request", "description": "Le tenant ne peut pas avoir 2 demandes `pending` simultanées sur la même clé. La demande arrive ensuite dans le back-office super admin.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quotaKey": { "type": "string", "minLength": 1, "maxLength": 80 }, "requestedLimit": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "reason": { "type": "string", "minLength": 10, "maxLength": 2000 } }, "required": [ "quotaKey", "requestedLimit", "reason" ] } } } }, "responses": { "201": { "description": "Demande créée.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "quotaKey": { "type": "string" }, "requestedBy": { "type": "string" }, "requestedLimit": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn" ] }, "decidedBy": { "type": [ "string", "null" ] }, "decidedAt": { "type": [ "string", "null" ], "format": "date-time" }, "decisionNote": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "quotaKey", "requestedBy", "requestedLimit", "reason", "status", "decidedBy", "decidedAt", "decisionNote", "createdAt", "updatedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "409": { "description": "Conflit d'état (`cannot_replay_`, `idempotency_mismatch`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/iam/quotas/me/requests/{id}": { "delete": { "operationId": "deleteV1IamQuotasMeRequestsById", "tags": [ "quotas" ], "summary": "Withdraw a quota request (D7)", "description": "L'auteur retire sa demande non-actionnée. Verbe API `withdrawn` ; le service interne reste `cancelQuotaIncreaseRequest` et le status DB `cancelled` (mappé vers `withdrawn` à la serialization). Cf. plan D7.", "responses": { "200": { "description": "Demande retirée.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "quotaKey": { "type": "string" }, "requestedBy": { "type": "string" }, "requestedLimit": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn" ] }, "decidedBy": { "type": [ "string", "null" ] }, "decidedAt": { "type": [ "string", "null" ], "format": "date-time" }, "decisionNote": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "withdrawn": { "type": "boolean", "const": true }, "withdrawnAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "quotaKey", "requestedBy", "requestedLimit", "reason", "status", "decidedBy", "decidedAt", "decisionNote", "createdAt", "updatedAt", "withdrawn", "withdrawnAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "409": { "description": "Conflit d'état (`cannot_replay_`, `idempotency_mismatch`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/v1/billing/me": { "get": { "operationId": "getV1BillingMe", "tags": [ "billing" ], "summary": "Retrieve account balance", "responses": { "200": { "description": "Solde.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "tenantId": { "type": "string" }, "balance": { "type": "string" }, "held": { "type": "string" }, "available": { "type": "string" }, "currency": { "type": "string", "const": "EUR" }, "billingMode": { "type": "string", "enum": [ "metered", "unmetered" ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "tenantId", "balance", "held", "available", "currency", "billingMode", "updatedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/billing/me/transactions": { "get": { "operationId": "getV1BillingMeTransactions", "tags": [ "billing" ], "summary": "List transactions (offset/limit)", "description": "Pagination offset/limit. Filtres simples (type, serviceKey). Pour des filtres combinés utiliser `POST /v1/billing/me/transactions/search`. Note : `take` (legacy) → `limit`.", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false }, { "name": "serviceKey", "in": "query", "schema": { "type": "string" }, "required": false } ], "responses": { "200": { "description": "Page de transactions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "allocation", "adjustment", "debit", "refund", "subscription_debit" ] }, "amount": { "type": "string" }, "balanceAfter": { "type": "string" }, "serviceKey": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resourceType": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "amount", "balanceAfter", "serviceKey", "resourceId", "resourceType", "note", "createdAt" ] } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "exclusiveMinimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" } }, "required": [ "offset", "limit", "total", "hasMore" ] }, "sort": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "dir": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "field", "dir" ] } } }, "required": [ "items", "pagination" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/billing/me/transactions/search": { "post": { "operationId": "postV1BillingMeTransactionsSearch", "tags": [ "billing" ], "summary": "Search transactions — filtres combinés (where AST + sort).", "description": "Body `{where?, sort?, pagination?}`. Cf. docs/development/api-design.md §5.b. Note : la résolution `where` est limitée aux champs whitelistés (createdAt, id, type, amount). Le filtre tenantId est imposé server-side.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "where": {}, "sort": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "createdAt", "id", "type", "amount" ] }, "dir": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "field", "dir" ] } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0, "default": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } } } } } } }, "responses": { "200": { "description": "Page de transactions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "allocation", "adjustment", "debit", "refund", "subscription_debit" ] }, "amount": { "type": "string" }, "balanceAfter": { "type": "string" }, "serviceKey": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resourceType": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "amount", "balanceAfter", "serviceKey", "resourceId", "resourceType", "note", "createdAt" ] } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "exclusiveMinimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" } }, "required": [ "offset", "limit", "total", "hasMore" ] }, "sort": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "dir": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "field", "dir" ] } } }, "required": [ "items", "pagination" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "422": { "description": "Validation métier KO (`unsafe_url`, `invalid_bulk_body`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "429": { "description": "Rate-limit dépassé. Header `Retry-After` retourné.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/billing/me/subscription": { "get": { "operationId": "getV1BillingMeSubscription", "tags": [ "billing" ], "summary": "Retrieve current plan subscription + addons", "responses": { "200": { "description": "Souscription en cours.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "unmetered": { "type": "boolean" }, "plan": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "planId": { "type": "string" }, "planSlug": { "type": "string" }, "planName": { "type": "string" }, "pinnedRevisionId": { "type": [ "string", "null" ] }, "billingCycle": { "type": "string", "enum": [ "monthly", "yearly" ] }, "status": { "type": "string", "enum": [ "trial", "active", "past_due", "suspended", "cancelled" ] }, "startedAt": { "type": "string", "format": "date-time" }, "trialEndsAt": { "type": [ "string", "null" ], "format": "date-time" }, "currentPeriodStart": { "type": "string", "format": "date-time" }, "currentPeriodEnd": { "type": "string", "format": "date-time" }, "nextBillingAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "id", "planId", "planSlug", "planName", "pinnedRevisionId", "billingCycle", "status", "startedAt", "trialEndsAt", "currentPeriodStart", "currentPeriodEnd", "nextBillingAt", "cancelAtPeriodEnd" ] }, "addons": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "addonId": { "type": "string" }, "addonSlug": { "type": "string" }, "addonName": { "type": "string" }, "billingCycle": { "type": "string", "enum": [ "monthly", "yearly" ] }, "status": { "type": "string", "enum": [ "trial", "active", "past_due", "suspended", "cancelled" ] }, "startedAt": { "type": "string", "format": "date-time" }, "currentPeriodStart": { "type": "string", "format": "date-time" }, "currentPeriodEnd": { "type": "string", "format": "date-time" }, "nextBillingAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "id", "addonId", "addonSlug", "addonName", "billingCycle", "status", "startedAt", "currentPeriodStart", "currentPeriodEnd", "nextBillingAt", "cancelAtPeriodEnd" ] } }, "reason": { "type": "string", "enum": [ "no_active_plan" ] } }, "required": [ "unmetered", "plan", "addons" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/billing/me/subscription/invoices": { "get": { "operationId": "getV1BillingMeSubscriptionInvoices", "tags": [ "billing" ], "summary": "List subscription debits (recurring plan + addons)", "description": "Pagination offset/limit. Filtre `type=subscription_debit` appliqué server-side.", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false } ], "responses": { "200": { "description": "Page de débits récurrents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "allocation", "adjustment", "debit", "refund", "subscription_debit" ] }, "amount": { "type": "string" }, "balanceAfter": { "type": "string" }, "serviceKey": { "type": [ "string", "null" ] }, "resourceId": { "type": [ "string", "null" ] }, "resourceType": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "amount", "balanceAfter", "serviceKey", "resourceId", "resourceType", "note", "createdAt" ] } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "exclusiveMinimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" } }, "required": [ "offset", "limit", "total", "hasMore" ] }, "sort": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "dir": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "field", "dir" ] } } }, "required": [ "items", "pagination" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/scraper/jobs/{id}/screenshot": { "get": { "operationId": "getV1ScraperJobsByIdScreenshot", "tags": [ "jobs" ], "summary": "Retrieve a job screenshot", "description": "Retourne `{ url, expiresAt, mime, width, height, bytes }` (JSON) par défaut. Avec `?redirect=1`, renvoie un `302 Location: ` consommable directement par un ``. Owner-check côté handler — non-admin sur job d'autrui = 404. Si pas de screenshot disponible (pas demandé OU fail-soft), 404. TTL court par défaut (`APOPHIS_S3_PRESIGN_TTL_SECONDS`, default 300 s) — ne pas cacher la réponse.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "redirect", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Set `1` pour recevoir un 302 redirect au lieu du JSON." }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "URL signée pour télécharger le screenshot.", "content": { "application/json": { "schema": { "type": "object" } } } }, "302": { "description": "Redirect vers la presigned URL." }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "503": { "description": "Dépendance critique (Postgres, Valkey) indisponible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/scraper/jobs/{id}/result/html": { "get": { "operationId": "getV1ScraperJobsByIdResultHtml", "tags": [ "jobs" ], "summary": "Retrieve job HTML", "description": "Retourne `text/html` avec headers sandbox-friendly (`Content-Security-Policy: sandbox`, `X-Frame-Options: SAMEORIGIN`). Owner-check côté handler — non-admin sur job d'autrui = 404. Cap inline 10 MB (au-delà : 413).", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "HTML stocké pour le job.", "content": { "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "413": { "description": "Body au-delà du cap inline (10 MB).", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/v1/scraper/jobs": { "get": { "operationId": "getV1ScraperJobs", "tags": [ "jobs" ], "summary": "List jobs", "description": "Filtres simples (status, domainId). Pagination offset/limit. Sort par défaut: createdAt:desc,id:desc. Pour des filtres combinés (and/or/not, contains, gte…) utiliser `POST /v1/scraper/jobs/search`.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false }, { "name": "sort", "in": "query", "schema": { "type": "string", "example": "createdAt:desc,id:asc" }, "required": false, "description": "Format `field:dir,field:dir`. Fields: createdAt, id, priority, attempts, status." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false }, { "name": "domainId", "in": "query", "schema": { "type": "string" }, "required": false } ], "responses": { "200": { "description": "Page de jobs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "claimed", "done", "failed", "dead" ] }, "priority": { "type": "integer" }, "attempts": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "domainId": { "type": "string" }, "tenantId": { "type": "string" } }, "required": [ "id", "url", "status", "priority", "attempts", "createdAt", "finishedAt", "domainId", "tenantId" ] } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "exclusiveMinimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" } }, "required": [ "offset", "limit", "total", "hasMore" ] }, "sort": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "dir": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "field", "dir" ] } } }, "required": [ "items", "pagination" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } }, "post": { "operationId": "postV1ScraperJobs", "tags": [ "jobs" ], "summary": "Create a job", "description": "Enqueue un crawl pour l'URL fournie. Codes: 201-created. Idempotent via header `Idempotency-Key` (TTL 24 h).", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "priority": { "type": "integer", "minimum": 0, "maximum": 10 }, "webhookUrl": { "type": [ "string", "null" ], "format": "uri" }, "timeoutMs": { "type": "integer", "minimum": 15000, "maximum": 300000 }, "escalation": { "type": "array", "items": { "type": "object", "properties": { "engine": { "type": "string", "enum": [ "http", "camoufox", "brave", "alternate" ] }, "attempts": { "type": "integer", "minimum": 1, "maximum": 5 }, "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 180000 } }, "required": [ "engine", "attempts", "timeoutMs" ] }, "minItems": 1, "maxItems": 8 }, "screenshot": { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg" ] }, "quality": { "type": "integer", "minimum": 1, "maximum": 100 }, "fullPage": { "type": "boolean" }, "loadResources": { "type": "string", "enum": [ "images", "images_fonts", "all" ] } } } ] } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "Job créé et enqueué.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "claimed", "done", "failed", "dead" ] }, "priority": { "type": "integer" }, "attempts": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "domainId": { "type": "string" }, "tenantId": { "type": "string" } }, "required": [ "id", "url", "status", "priority", "attempts", "createdAt", "finishedAt", "domainId", "tenantId" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "422": { "description": "Validation métier KO (`unsafe_url`, `invalid_bulk_body`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "429": { "description": "Rate-limit dépassé. Header `Retry-After` retourné.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/scraper/jobs/bulk": { "post": { "operationId": "postV1ScraperJobsBulk", "tags": [ "jobs" ], "summary": "Create up to 100 jobs", "description": "Partial-success : un item invalide (URL SSRF, schéma KO) part dans `failed[]`, les autres sont créés. Un body invalide globalement (cap dépassé, array vide) renvoie 422. Codes: 201-created (tous OK), 207-partial_success, 422-invalid_bulk_body. Idempotent via `Idempotency-Key`.", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "priority": { "type": "integer", "minimum": 0, "maximum": 10 }, "webhookUrl": { "type": [ "string", "null" ], "format": "uri" }, "timeoutMs": { "type": "integer", "minimum": 15000, "maximum": 300000 }, "escalation": { "type": "array", "items": { "type": "object", "properties": { "engine": { "type": "string", "enum": [ "http", "camoufox", "brave", "alternate" ] }, "attempts": { "type": "integer", "minimum": 1, "maximum": 5 }, "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 180000 } }, "required": [ "engine", "attempts", "timeoutMs" ] }, "minItems": 1, "maxItems": 8 }, "screenshot": { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg" ] }, "quality": { "type": "integer", "minimum": 1, "maximum": 100 }, "fullPage": { "type": "boolean" }, "loadResources": { "type": "string", "enum": [ "images", "images_fonts", "all" ] } } } ] } }, "required": [ "url" ] }, "minItems": 1, "maxItems": 100 } }, "required": [ "jobs" ] } } } }, "responses": { "201": { "description": "Tous les jobs créés.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "processed": { "type": "boolean", "const": true }, "summary": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "created": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "total" ] }, "created": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "claimed", "done", "failed", "dead" ] }, "priority": { "type": "integer" }, "attempts": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "domainId": { "type": "string" }, "tenantId": { "type": "string" } }, "required": [ "id", "url", "status", "priority", "attempts", "createdAt", "finishedAt", "domainId", "tenantId" ] } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "url": { "type": [ "string", "null" ] }, "reason": { "type": "string" } }, "required": [ "index", "url", "reason" ] } } }, "required": [ "processed", "summary" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "207": { "description": "Création partielle (certains items en `failed[]`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "processed": { "type": "boolean", "const": true }, "summary": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "created": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "total" ] }, "created": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "claimed", "done", "failed", "dead" ] }, "priority": { "type": "integer" }, "attempts": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "domainId": { "type": "string" }, "tenantId": { "type": "string" } }, "required": [ "id", "url", "status", "priority", "attempts", "createdAt", "finishedAt", "domainId", "tenantId" ] } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "url": { "type": [ "string", "null" ] }, "reason": { "type": "string" } }, "required": [ "index", "url", "reason" ] } } }, "required": [ "processed", "summary" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "422": { "description": "Validation métier KO (`unsafe_url`, `invalid_bulk_body`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "429": { "description": "Rate-limit dépassé. Header `Retry-After` retourné.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/scraper/jobs/{id}": { "get": { "operationId": "getV1ScraperJobsById", "tags": [ "jobs" ], "summary": "Retrieve a job", "description": "Retourne le job, son `result` (si présent), et les `errors[]` accumulées. Filtré par `tenantId` du caller — les non-admins reçoivent 404 sur les jobs d'autres tenants (pas 403).", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Job trouvé.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "claimed", "done", "failed", "dead" ] }, "priority": { "type": "integer" }, "attempts": { "type": "integer" }, "domainId": { "type": "string" }, "tenantId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "claimedBy": { "type": [ "string", "null" ] }, "claimedAt": { "type": [ "string", "null" ], "format": "date-time" }, "result": { "type": [ "object", "null" ], "properties": { "httpStatus": { "type": "integer" }, "finalUrl": { "type": "string" }, "engineUsed": { "type": "string", "enum": [ "http", "camoufox", "brave", "alternate" ] }, "durationMs": { "type": "integer" }, "byteSize": { "type": "integer" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "challengesSolved": { "type": "array", "items": {} }, "egressIp": { "type": [ "string", "null" ] }, "egressIpVersion": { "type": [ "string", "null" ] }, "egressSource": { "type": [ "string", "null" ] }, "egressProxyRef": { "type": [ "string", "null" ] } }, "required": [ "httpStatus", "finalUrl", "engineUsed", "durationMs", "byteSize", "headers", "challengesSolved", "egressIp", "egressIpVersion", "egressSource", "egressProxyRef" ] }, "errors": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "integer" }, "classification": { "type": "string", "enum": [ "timeout", "network", "rate_limited", "blocked", "soft_blocked", "not_found", "challenge_unresolved", "thin_content", "parse", "unknown", "aborted" ] }, "message": { "type": "string" }, "engineUsed": { "type": [ "string", "null" ], "enum": [ "http", "camoufox", "brave", "alternate", null ] }, "createdAt": { "type": "string", "format": "date-time" }, "egressIp": { "type": [ "string", "null" ] }, "egressIpVersion": { "type": [ "string", "null" ] }, "egressSource": { "type": [ "string", "null" ] }, "egressProxyRef": { "type": [ "string", "null" ] } }, "required": [ "attempt", "classification", "message", "engineUsed", "createdAt", "egressIp", "egressIpVersion", "egressSource", "egressProxyRef" ] } }, "lastError": { "type": [ "object", "null" ], "properties": { "classification": { "type": "string", "enum": [ "timeout", "network", "rate_limited", "blocked", "soft_blocked", "not_found", "challenge_unresolved", "thin_content", "parse", "unknown", "aborted" ] }, "message": { "type": "string" }, "engineUsed": { "type": [ "string", "null" ], "enum": [ "http", "camoufox", "brave", "alternate", null ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "classification", "message", "engineUsed", "createdAt" ] } }, "required": [ "id", "url", "status", "priority", "attempts", "domainId", "tenantId", "createdAt", "finishedAt", "claimedBy", "claimedAt", "result", "errors", "lastError" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/v1/scraper/jobs/search": { "post": { "operationId": "postV1ScraperJobsSearch", "tags": [ "jobs" ], "summary": "Search jobs — filtres combinés (where AST + sort multi-champs).", "description": "Body `{where?, sort?, pagination?}`. Cf. docs/development/api-design.md §5.b. Retourne la même enveloppe `{items, pagination, sort}` que GET /jobs.", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "where": {}, "sort": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "createdAt", "id", "priority", "attempts", "status" ] }, "dir": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "field", "dir" ] } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0, "default": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } } } } } } }, "responses": { "200": { "description": "Page de jobs (même enveloppe que GET).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "claimed", "done", "failed", "dead" ] }, "priority": { "type": "integer" }, "attempts": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "domainId": { "type": "string" }, "tenantId": { "type": "string" } }, "required": [ "id", "url", "status", "priority", "attempts", "createdAt", "finishedAt", "domainId", "tenantId" ] } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "exclusiveMinimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" } }, "required": [ "offset", "limit", "total", "hasMore" ] }, "sort": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "dir": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "field", "dir" ] } } }, "required": [ "items", "pagination" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "422": { "description": "Validation métier KO (`unsafe_url`, `invalid_bulk_body`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "429": { "description": "Rate-limit dépassé. Header `Retry-After` retourné.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/scraper/page-history": { "get": { "operationId": "getV1ScraperPageHistory", "tags": [ "page-history" ], "summary": "Timeline d'historique de contenu d'une URL — versions publiques (mutualisées) ∪ versions privées de l'appelant.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "public", "tenant", "all" ] }, "description": "Filtre un seul pool. Défaut : les deux." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Timeline des versions d'une URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "url": { "type": "string" }, "urlCanonical": { "type": "string" }, "total": { "type": "integer" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "versionId": { "type": "string" }, "scope": { "type": "string", "enum": [ "public", "tenant" ] }, "contentSha256": { "type": "string" }, "rawSha256": { "type": [ "string", "null" ] }, "httpStatus": { "type": "integer" }, "finalUrl": { "type": "string" }, "engineUsed": { "type": "string" }, "firstSeenAt": { "type": "string", "format": "date-time" }, "lastSeenAt": { "type": "string", "format": "date-time" }, "observationCount": { "type": "integer" }, "byteSize": { "type": "integer" }, "changedFromPrevious": { "type": "boolean" }, "egressIpVersion": { "type": [ "string", "null" ] }, "egressGeo": { "type": [ "string", "null" ] } }, "required": [ "versionId", "scope", "contentSha256", "rawSha256", "httpStatus", "finalUrl", "engineUsed", "firstSeenAt", "lastSeenAt", "observationCount", "byteSize", "changedFromPrevious", "egressIpVersion", "egressGeo" ] } } }, "required": [ "url", "urlCanonical", "total", "versions" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/scraper/page-history/{versionId}/content": { "get": { "operationId": "getV1ScraperPageHistoryByVersionIdContent", "tags": [ "page-history" ], "summary": "HTML brut d'une version d'historique (headers sandbox).", "description": "Renvoie le RAW HTML représentatif de la version. 404 si la version vise un scope non visible par l'appelant (pas de 403 qui leak l'existence). `contentSha256 = sha256(normalizeForHistory(body))` ≠ hash du raw servi (`rawSha256`). Cap inline 10 MB (413).", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "RAW HTML de la version.", "content": { "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "413": { "description": "Body au-delà du cap inline (10 MB).", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "versionId", "required": true } ] } }, "/v1/extractor/extractions": { "get": { "operationId": "getV1ExtractorExtractions", "tags": [ "extractions" ], "summary": "List extractions", "description": "Pagination offset/limit. Sort par défaut createdAt:desc,id:desc. Filtres simples (status, type, domainId). Pour des filtres combinés utiliser `POST /v1/extractor/extractions/search`.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false }, { "name": "sort", "in": "query", "schema": { "type": "string", "example": "createdAt:desc,id:asc" }, "required": false }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false }, { "name": "domainId", "in": "query", "schema": { "type": "string" }, "required": false } ], "responses": { "200": { "description": "Page d'extractions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "article", "product" ] }, "status": { "type": "string", "enum": [ "queued", "claimed", "done", "failed", "dead", "cancelled" ] }, "url": { "type": [ "string", "null" ] }, "domainId": { "type": [ "string", "null" ] }, "tenantId": { "type": "string" }, "inputFormat": { "type": "string", "enum": [ "html", "markdown", "text", "json" ] }, "data": { "type": "null" }, "metadata": { "type": "null" }, "errorMessage": { "type": [ "string", "null" ] }, "errorClass": { "type": [ "string", "null" ], "enum": [ "parse_error", "sanitize_fail", "llm_request", "llm_validation", "llm_timeout", "llm_unavailable", "invalid_input", "input_stash_lost", "cancelled_by_admin", "unknown", null ] }, "attempts": { "type": "integer", "minimum": 0, "default": 0 }, "cacheHits": { "type": "integer", "minimum": 0, "default": 0 }, "recycleCount": { "type": "integer", "minimum": 0, "default": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "type", "status", "url", "domainId", "tenantId", "inputFormat", "createdAt", "finishedAt" ] } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "exclusiveMinimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" } }, "required": [ "offset", "limit", "total", "hasMore" ] }, "sort": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "dir": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "field", "dir" ] } } }, "required": [ "items", "pagination" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } }, "post": { "operationId": "postV1ExtractorExtractions", "tags": [ "extractions" ], "summary": "Create an extraction", "description": "Sanitize content, compute cacheKey, lookup or insert. Codes: 200-cache_hit (sibling `cache.hit=true`), 202-queued (cache miss enqueued).", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "article", "product" ] }, "format": { "type": "string", "enum": [ "html", "markdown", "text", "json" ], "default": "html" }, "content": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": {} } ] }, "url": { "type": "string", "format": "uri" }, "domain": { "type": "string" }, "webhookUrl": { "type": "string", "format": "uri" }, "webhookEventTypes": { "type": "array", "items": { "type": "string", "enum": [ "done", "failed", "dead" ] } }, "forceRefresh": { "type": "boolean" }, "options": { "type": "object", "properties": { "useLlm": { "type": "boolean" }, "llmModel": { "type": "string" }, "llmPromptOverride": { "type": "string", "maxLength": 8000 }, "llmMode": { "type": "string", "enum": [ "fill-missing", "correct" ] } } } }, "required": [ "type", "content" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Cache hit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "article", "product" ] }, "status": { "type": "string", "enum": [ "queued", "claimed", "done", "failed", "dead", "cancelled" ] }, "url": { "type": [ "string", "null" ] }, "domainId": { "type": [ "string", "null" ] }, "tenantId": { "type": "string" }, "inputFormat": { "type": "string", "enum": [ "html", "markdown", "text", "json" ] }, "data": { "type": "null" }, "metadata": { "type": "null" }, "errorMessage": { "type": [ "string", "null" ] }, "errorClass": { "type": [ "string", "null" ], "enum": [ "parse_error", "sanitize_fail", "llm_request", "llm_validation", "llm_timeout", "llm_unavailable", "invalid_input", "input_stash_lost", "cancelled_by_admin", "unknown", null ] }, "attempts": { "type": "integer", "minimum": 0, "default": 0 }, "cacheHits": { "type": "integer", "minimum": 0, "default": 0 }, "recycleCount": { "type": "integer", "minimum": 0, "default": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "type", "status", "url", "domainId", "tenantId", "inputFormat", "createdAt", "finishedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "202": { "description": "Cache miss enqueued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "article", "product" ] }, "status": { "type": "string", "enum": [ "queued", "claimed", "done", "failed", "dead", "cancelled" ] }, "url": { "type": [ "string", "null" ] }, "domainId": { "type": [ "string", "null" ] }, "tenantId": { "type": "string" }, "inputFormat": { "type": "string", "enum": [ "html", "markdown", "text", "json" ] }, "data": { "type": "null" }, "metadata": { "type": "null" }, "errorMessage": { "type": [ "string", "null" ] }, "errorClass": { "type": [ "string", "null" ], "enum": [ "parse_error", "sanitize_fail", "llm_request", "llm_validation", "llm_timeout", "llm_unavailable", "invalid_input", "input_stash_lost", "cancelled_by_admin", "unknown", null ] }, "attempts": { "type": "integer", "minimum": 0, "default": 0 }, "cacheHits": { "type": "integer", "minimum": 0, "default": 0 }, "recycleCount": { "type": "integer", "minimum": 0, "default": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "type", "status", "url", "domainId", "tenantId", "inputFormat", "createdAt", "finishedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "413": { "description": "Payload trop volumineux.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "422": { "description": "Validation métier KO (`unsafe_url`, `invalid_bulk_body`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "429": { "description": "Rate-limit dépassé. Header `Retry-After` retourné.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/extractor/extractions/{id}": { "get": { "operationId": "getV1ExtractorExtractionsById", "tags": [ "extractions" ], "summary": "Retrieve an extraction", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Extraction trouvée.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "article", "product" ] }, "status": { "type": "string", "enum": [ "queued", "claimed", "done", "failed", "dead", "cancelled" ] }, "url": { "type": [ "string", "null" ] }, "domainId": { "type": [ "string", "null" ] }, "tenantId": { "type": "string" }, "inputFormat": { "type": "string", "enum": [ "html", "markdown", "text", "json" ] }, "data": { "type": "null" }, "metadata": { "type": "null" }, "errorMessage": { "type": [ "string", "null" ] }, "errorClass": { "type": [ "string", "null" ], "enum": [ "parse_error", "sanitize_fail", "llm_request", "llm_validation", "llm_timeout", "llm_unavailable", "invalid_input", "input_stash_lost", "cancelled_by_admin", "unknown", null ] }, "attempts": { "type": "integer", "minimum": 0, "default": 0 }, "cacheHits": { "type": "integer", "minimum": 0, "default": 0 }, "recycleCount": { "type": "integer", "minimum": 0, "default": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "type", "status", "url", "domainId", "tenantId", "inputFormat", "createdAt", "finishedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] }, "delete": { "operationId": "deleteV1ExtractorExtractionsById", "tags": [ "extractions" ], "summary": "Cancel an extraction (DELETE = cancel sur ressource async)", "description": "Cf. guideline §6.d : DELETE sur ressource async = cancel ; la row reste accessible en GET avec `status='cancelled'`. Claimed rows = signal pubsub Valkey (best-effort). Code: 200. Idempotent si déjà terminal.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Extraction annulée (ou no-op idempotent si déjà terminale).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "cancelled": { "type": "boolean" }, "cancelledAt": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "cancelled", "cancelledAt", "id", "status" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/v1/extractor/extractions/search": { "post": { "operationId": "postV1ExtractorExtractionsSearch", "tags": [ "extractions" ], "summary": "Search extractions — filtres combinés (where AST + sort).", "description": "Body `{where?, sort?, pagination?}`. Cf. docs/development/api-design.md §5.b. Retourne la même enveloppe `{items, pagination, sort}` que GET /.", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "where": {}, "sort": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "createdAt", "id", "status", "type", "finishedAt" ] }, "dir": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "field", "dir" ] } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0, "default": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } } } } } } }, "responses": { "200": { "description": "Page d'extractions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "article", "product" ] }, "status": { "type": "string", "enum": [ "queued", "claimed", "done", "failed", "dead", "cancelled" ] }, "url": { "type": [ "string", "null" ] }, "domainId": { "type": [ "string", "null" ] }, "tenantId": { "type": "string" }, "inputFormat": { "type": "string", "enum": [ "html", "markdown", "text", "json" ] }, "data": { "type": "null" }, "metadata": { "type": "null" }, "errorMessage": { "type": [ "string", "null" ] }, "errorClass": { "type": [ "string", "null" ], "enum": [ "parse_error", "sanitize_fail", "llm_request", "llm_validation", "llm_timeout", "llm_unavailable", "invalid_input", "input_stash_lost", "cancelled_by_admin", "unknown", null ] }, "attempts": { "type": "integer", "minimum": 0, "default": 0 }, "cacheHits": { "type": "integer", "minimum": 0, "default": 0 }, "recycleCount": { "type": "integer", "minimum": 0, "default": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "type", "status", "url", "domainId", "tenantId", "inputFormat", "createdAt", "finishedAt" ] } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "exclusiveMinimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" } }, "required": [ "offset", "limit", "total", "hasMore" ] }, "sort": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "dir": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "field", "dir" ] } } }, "required": [ "items", "pagination" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "422": { "description": "Validation métier KO (`unsafe_url`, `invalid_bulk_body`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "429": { "description": "Rate-limit dépassé. Header `Retry-After` retourné.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/extractor/configs": { "get": { "operationId": "getV1ExtractorConfigs", "tags": [ "extractor-configs" ], "summary": "List extractor configs", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false } ], "responses": { "200": { "description": "Liste des configs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": [ "string", "null" ] }, "scope": { "type": "string" }, "type": { "type": [ "string", "null" ], "enum": [ "article", "product", null ] }, "domainId": { "type": [ "string", "null" ] }, "urlPattern": { "type": [ "string", "null" ] }, "priority": { "type": "integer" }, "enabled": { "type": "boolean" }, "payload": { "type": "object", "properties": { "selectors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "css": { "type": "string" }, "attr": { "type": "string" }, "json": { "type": "string" }, "textOnly": { "type": "boolean" }, "trim": { "type": "boolean" } } } } }, "llm": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "model": { "type": "string" }, "temperature": { "type": "number" }, "promptOverride": { "type": "string", "maxLength": 8000 }, "mode": { "type": "string", "enum": [ "fill-missing", "correct" ] } } }, "fields": { "type": "array", "items": { "type": "string" } }, "postProcess": { "type": "object", "additionalProperties": {} } }, "additionalProperties": true }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "scope", "type", "domainId", "urlPattern", "priority", "enabled", "payload", "notes", "createdAt", "updatedAt" ] } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "exclusiveMinimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" } }, "required": [ "offset", "limit", "total", "hasMore" ] }, "sort": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "dir": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "field", "dir" ] } } }, "required": [ "items", "pagination" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } }, "post": { "operationId": "postV1ExtractorConfigs", "tags": [ "extractor-configs" ], "summary": "Create an extractor config", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "generic", "type", "domain", "url" ] }, "type": { "type": "string", "enum": [ "article", "product" ] }, "domainId": { "type": "string" }, "urlPattern": { "type": "string" }, "tenantId": { "type": [ "string", "null" ] }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 0 }, "enabled": { "type": "boolean", "default": true }, "payload": { "type": "object", "properties": { "selectors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "css": { "type": "string" }, "attr": { "type": "string" }, "json": { "type": "string" }, "textOnly": { "type": "boolean" }, "trim": { "type": "boolean" } } } } }, "llm": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "model": { "type": "string" }, "temperature": { "type": "number" }, "promptOverride": { "type": "string", "maxLength": 8000 }, "mode": { "type": "string", "enum": [ "fill-missing", "correct" ] } } }, "fields": { "type": "array", "items": { "type": "string" } }, "postProcess": { "type": "object", "additionalProperties": {} } }, "additionalProperties": true, "default": {} }, "notes": { "type": "string", "maxLength": 1000 } }, "required": [ "scope" ] } } } }, "responses": { "201": { "description": "Config créée.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": [ "string", "null" ] }, "scope": { "type": "string" }, "type": { "type": [ "string", "null" ], "enum": [ "article", "product", null ] }, "domainId": { "type": [ "string", "null" ] }, "urlPattern": { "type": [ "string", "null" ] }, "priority": { "type": "integer" }, "enabled": { "type": "boolean" }, "payload": { "type": "object", "properties": { "selectors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "css": { "type": "string" }, "attr": { "type": "string" }, "json": { "type": "string" }, "textOnly": { "type": "boolean" }, "trim": { "type": "boolean" } } } } }, "llm": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "model": { "type": "string" }, "temperature": { "type": "number" }, "promptOverride": { "type": "string", "maxLength": 8000 }, "mode": { "type": "string", "enum": [ "fill-missing", "correct" ] } } }, "fields": { "type": "array", "items": { "type": "string" } }, "postProcess": { "type": "object", "additionalProperties": {} } }, "additionalProperties": true }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "scope", "type", "domainId", "urlPattern", "priority", "enabled", "payload", "notes", "createdAt", "updatedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "422": { "description": "Validation métier KO (`unsafe_url`, `invalid_bulk_body`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/extractor/configs/{id}": { "get": { "operationId": "getV1ExtractorConfigsById", "tags": [ "extractor-configs" ], "summary": "Retrieve an extractor config", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Config trouvée.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": [ "string", "null" ] }, "scope": { "type": "string" }, "type": { "type": [ "string", "null" ], "enum": [ "article", "product", null ] }, "domainId": { "type": [ "string", "null" ] }, "urlPattern": { "type": [ "string", "null" ] }, "priority": { "type": "integer" }, "enabled": { "type": "boolean" }, "payload": { "type": "object", "properties": { "selectors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "css": { "type": "string" }, "attr": { "type": "string" }, "json": { "type": "string" }, "textOnly": { "type": "boolean" }, "trim": { "type": "boolean" } } } } }, "llm": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "model": { "type": "string" }, "temperature": { "type": "number" }, "promptOverride": { "type": "string", "maxLength": 8000 }, "mode": { "type": "string", "enum": [ "fill-missing", "correct" ] } } }, "fields": { "type": "array", "items": { "type": "string" } }, "postProcess": { "type": "object", "additionalProperties": {} } }, "additionalProperties": true }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "scope", "type", "domainId", "urlPattern", "priority", "enabled", "payload", "notes", "createdAt", "updatedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] }, "delete": { "operationId": "deleteV1ExtractorConfigsById", "tags": [ "extractor-configs" ], "summary": "Delete an extractor config", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "deletedAt": { "type": "string", "format": "date-time" }, "id": { "type": "string" } }, "required": [ "deleted", "deletedAt", "id" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] }, "patch": { "operationId": "patchV1ExtractorConfigsById", "tags": [ "extractor-configs" ], "summary": "Update an extractor config", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "enum": [ "article", "product", null ] }, "domainId": { "type": [ "string", "null" ] }, "urlPattern": { "type": [ "string", "null" ] }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000 }, "enabled": { "type": "boolean" }, "payload": { "type": "object", "properties": { "selectors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "css": { "type": "string" }, "attr": { "type": "string" }, "json": { "type": "string" }, "textOnly": { "type": "boolean" }, "trim": { "type": "boolean" } } } } }, "llm": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "model": { "type": "string" }, "temperature": { "type": "number" }, "promptOverride": { "type": "string", "maxLength": 8000 }, "mode": { "type": "string", "enum": [ "fill-missing", "correct" ] } } }, "fields": { "type": "array", "items": { "type": "string" } }, "postProcess": { "type": "object", "additionalProperties": {} } }, "additionalProperties": true }, "notes": { "type": [ "string", "null" ], "maxLength": 1000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Config patchée.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": [ "string", "null" ] }, "scope": { "type": "string" }, "type": { "type": [ "string", "null" ], "enum": [ "article", "product", null ] }, "domainId": { "type": [ "string", "null" ] }, "urlPattern": { "type": [ "string", "null" ] }, "priority": { "type": "integer" }, "enabled": { "type": "boolean" }, "payload": { "type": "object", "properties": { "selectors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "css": { "type": "string" }, "attr": { "type": "string" }, "json": { "type": "string" }, "textOnly": { "type": "boolean" }, "trim": { "type": "boolean" } } } } }, "llm": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "model": { "type": "string" }, "temperature": { "type": "number" }, "promptOverride": { "type": "string", "maxLength": 8000 }, "mode": { "type": "string", "enum": [ "fill-missing", "correct" ] } } }, "fields": { "type": "array", "items": { "type": "string" } }, "postProcess": { "type": "object", "additionalProperties": {} } }, "additionalProperties": true }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "scope", "type", "domainId", "urlPattern", "priority", "enabled", "payload", "notes", "createdAt", "updatedAt" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "404": { "description": "Ressource introuvable (ou hors-tenant).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "422": { "description": "Validation métier KO (`unsafe_url`, `invalid_bulk_body`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/v1/network/ip/lookup": { "get": { "operationId": "getV1NetworkIpLookup", "tags": [ "network" ], "summary": "Géolocalise une IP (pays). `?include=sources` (admin) ⇒ breakdown du vote.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Résultat de géolocalisation (light).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "ip": { "type": "string" }, "found": { "type": "boolean" }, "country": { "type": [ "string", "null" ] }, "countryName": { "type": [ "string", "null" ] } }, "required": [ "ip", "found", "country", "countryName" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "402": { "description": "Solde de crédits insuffisant (`insufficient_credit`). Cf. billing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "422": { "description": "Validation métier KO (`unsafe_url`, `invalid_bulk_body`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "503": { "description": "Dépendance critique (Postgres, Valkey) indisponible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } }, "/v1/network/ip/lookup/me": { "get": { "operationId": "getV1NetworkIpLookupMe", "tags": [ "network" ], "summary": "Géolocalise l'IP de l'appelant (dérivée via trust-proxy + X-Forwarded-For).", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Résultat de géolocalisation (light).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "ip": { "type": "string" }, "found": { "type": "boolean" }, "country": { "type": [ "string", "null" ] }, "countryName": { "type": [ "string", "null" ] } }, "required": [ "ip", "found", "country", "countryName" ] }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "key": { "type": "string" }, "ageSeconds": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "hit" ] }, "timing": { "type": "object", "properties": { "totalMs": { "type": "integer", "minimum": 0 }, "dbMs": { "type": "integer", "minimum": 0 }, "externalMs": { "type": "integer", "minimum": 0 } }, "required": [ "totalMs" ] }, "deprecation": { "type": "object", "properties": { "sunset": { "type": "string", "format": "date-time" }, "successor": { "type": "string" }, "note": { "type": "string" } }, "required": [ "sunset" ] } }, "required": [ "status", "code", "data" ] } } } }, "400": { "description": "Requête mal formée (`validation_error`, `invalid_idempotency_key`, `invalid_sort_field`, `invalid_filter`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "401": { "description": "Authentification manquante ou invalide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "402": { "description": "Solde de crédits insuffisant (`insufficient_credit`). Cf. billing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "403": { "description": "Scope insuffisant (`forbidden`, `no_active_plan`, `service_disabled_on_plan`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "422": { "description": "Validation métier KO (`unsafe_url`, `invalid_bulk_body`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } }, "503": { "description": "Dépendance critique (Postgres, Valkey) indisponible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "requestId" ], "additionalProperties": {} } }, "required": [ "status", "code", "error" ] } } } } } } } } }