{"openapi":"3.1.0","info":{"title":"Telden Public API","version":"2026-04-28","summary":"Stable public API surface for agent and client integrations.","description":"OpenAPI contract for Telden's stable public endpoints. Admin, Inngest, and feature-flagged routes are intentionally excluded."},"jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","servers":[{"url":"https://telden.eu","description":"Production"}],"tags":[{"name":"Health","description":"Service health checks."},{"name":"SKUs","description":"SKU records and per-SKU exports."},{"name":"Documents","description":"Workspace document upload workflows."},{"name":"Imports","description":"CSV and spreadsheet import workflows."},{"name":"Workspace","description":"Workspace administration endpoints for signed-in users."},{"name":"v1","description":"Versioned (v1) Bearer-token API for programmable access."},{"name":"AI","description":"AI-assisted operations including field fill, warnings, and suggestions. AI suggestions require human review and are never auto-approved for compliance output."},{"name":"Exports","description":"Export runs and templates for compliance dossiers and marketplace feeds."}],"components":{"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"sb-access-token","description":"Authenticated Telden web session cookie."},"bearerAuth":{"type":"http","scheme":"bearer","description":"Workspace-scoped Telden token for MCP clients."}},"schemas":{"CreateSkuInput":{"type":"object","properties":{"sku_code":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9_-]+$"},"product_name":{"type":"string","minLength":1,"maxLength":200},"gtin":{"anyOf":[{"type":"string","pattern":"^\\d{8}$|^\\d{12}$|^\\d{13}$|^\\d{14}$"},{"type":"null"}]},"category_code":{"type":"string","maxLength":100},"external_sku_id":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}},"required":["sku_code","product_name"],"additionalProperties":false},"CreateSkuDryRunResponse":{"type":"object","additionalProperties":false,"required":["dry_run","can_create","normalized_sku","category","requirement_profile","plan_limit","blocking_reason"],"properties":{"dry_run":{"type":"boolean","const":true},"can_create":{"type":"boolean"},"normalized_sku":{"type":["object","null"],"additionalProperties":false,"required":["sku_code","product_name","gtin","category_code","external_sku_id"],"properties":{"sku_code":{"type":"string"},"product_name":{"type":"string"},"gtin":{"type":["string","null"]},"category_code":{"type":"string"},"external_sku_id":{"type":["string","null"]}}},"category":{"type":"object","additionalProperties":false,"required":["selected_code","defaulted"],"properties":{"selected_code":{"type":["string","null"]},"defaulted":{"type":"boolean"}}},"requirement_profile":{"type":"object","additionalProperties":false,"required":["would_attach_default","id"],"properties":{"would_attach_default":{"type":"boolean"},"id":{"type":["string","null"]}}},"plan_limit":{"type":["object","null"],"additionalProperties":false,"required":["plan","limit","current_count"],"properties":{"plan":{"type":"string"},"limit":{"type":"integer"},"current_count":{"type":["integer","null"]}}},"blocking_reason":{"type":["object","null"],"additionalProperties":true,"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":["object","string","array","null"]}}}}},"ApiKey":{"type":"object","additionalProperties":false,"required":["id","name","key_prefix","scopes","created_at"],"properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"key_prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"},"revoked_at":{"type":["string","null"],"format":"date-time"}}},"CreateApiKeyInput":{"type":"object","additionalProperties":false,"required":["name","scopes"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"scopes":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string"}},"expires_at":{"type":["string","null"],"format":"date-time"}}},"ErrorEnvelope":{"type":"object","additionalProperties":true,"required":["error","error_code","code","correlation_id"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","doc_url","retryable","support_reference"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code (e.g. UNAUTHORIZED, NOT_FOUND)."},"message":{"type":"string","description":"Human-readable error message."},"details":{"type":"object","additionalProperties":true,"description":"Optional structured details for support."},"doc_url":{"type":"string","format":"uri","description":"URL to the error catalogue entry for this code."},"retryable":{"type":"boolean","description":"Whether the same request may succeed on retry."},"support_reference":{"type":"string","description":"Unique request-level reference for support correlation."}}},"error_code":{"type":"string","description":"Lowercase legacy mirror of error.code for back-compat."},"code":{"type":"string","description":"Back-compat top-level mirror of error_code."},"correlation_id":{"type":"string","description":"Back-compat alias for error.support_reference."},"support_email":{"type":"string","description":"Support contact included on 5xx responses."}}},"ImportBatch":{"type":"object","additionalProperties":true,"required":["id","filename","status","created_at"],"properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"filename":{"type":"string"},"total_rows":{"type":["integer","null"]},"processed_rows":{"type":["integer","null"]},"created_rows":{"type":["integer","null"]},"updated_rows":{"type":["integer","null"]},"skipped_rows":{"type":["integer","null"]},"failed_rows":{"type":["integer","null"]},"error_rows":{"type":["integer","null"]},"status":{"type":"string"},"started_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"ImportEntityResolutionDecision":{"type":"object","additionalProperties":false,"required":["candidate_key","role","action"],"properties":{"candidate_key":{"type":"string","description":"Stable key from the import dry-run entity_candidates item, usually the normalized identity."},"role":{"type":"string","enum":["manufacturer","importer","responsible_person"]},"action":{"type":"string","enum":["link_existing","create_new","ignore","unresolved"]},"entity_id":{"type":"string","description":"Required when action is link_existing."},"proposed_values":{"type":"object","additionalProperties":false,"properties":{"name":{"type":["string","null"]},"address":{"type":["string","null"]},"email":{"type":["string","null"]}}},"source_rows":{"type":"array","items":{"type":"integer"}},"has_conflicts":{"type":"boolean"},"conflicts":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Conflict objects copied from the import dry-run candidate preview."},"reason":{"type":"string"}}},"ImportEntityResolutionRequest":{"type":"object","additionalProperties":false,"required":["decisions"],"properties":{"dry_run":{"type":"boolean"},"decisions":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["candidate_key","role","action"],"properties":{"candidate_key":{"type":"string","description":"Stable key from the import dry-run entity_candidates item, usually the normalized identity."},"role":{"type":"string","enum":["manufacturer","importer","responsible_person"]},"action":{"type":"string","enum":["link_existing","create_new","ignore","unresolved"]},"entity_id":{"type":"string","description":"Required when action is link_existing."},"proposed_values":{"type":"object","additionalProperties":false,"properties":{"name":{"type":["string","null"]},"address":{"type":["string","null"]},"email":{"type":["string","null"]}}},"source_rows":{"type":"array","items":{"type":"integer"}},"has_conflicts":{"type":"boolean"},"conflicts":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Conflict objects copied from the import dry-run candidate preview."},"reason":{"type":"string"}}}}}},"ImportEntityResolutionResponse":{"type":"object","additionalProperties":false,"required":["dry_run","batch_id","valid_decisions","planned"],"properties":{"dry_run":{"type":"boolean"},"batch_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"saved":{"type":"boolean"},"valid_decisions":{"type":"integer"},"planned":{"type":"object","additionalProperties":false,"required":["link_existing","create_new","ignore","unresolved"],"properties":{"link_existing":{"type":"integer"},"create_new":{"type":"integer"},"ignore":{"type":"integer"},"unresolved":{"type":"integer"}}},"decisions":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["candidate_key","role","action"],"properties":{"candidate_key":{"type":"string","description":"Stable key from the import dry-run entity_candidates item, usually the normalized identity."},"role":{"type":"string","enum":["manufacturer","importer","responsible_person"]},"action":{"type":"string","enum":["link_existing","create_new","ignore","unresolved"]},"entity_id":{"type":"string","description":"Required when action is link_existing."},"proposed_values":{"type":"object","additionalProperties":false,"properties":{"name":{"type":["string","null"]},"address":{"type":["string","null"]},"email":{"type":["string","null"]}}},"source_rows":{"type":"array","items":{"type":"integer"}},"has_conflicts":{"type":"boolean"},"conflicts":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Conflict objects copied from the import dry-run candidate preview."},"reason":{"type":"string"}}},"description":"Echoed on dry-run responses so agent clients can preview the normalized decision payload."}}},"Sku":{"type":"object","additionalProperties":true,"required":["id","sku_code","product_name"],"properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"sku_code":{"type":"string"},"product_name":{"type":"string"},"gtin":{"type":["string","null"]},"category_code":{"type":["string","null"]},"review_state":{"type":["string","null"]},"approval_state":{"type":["string","null"]},"blocker_count":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"}}},"SkuBlocker":{"type":"object","additionalProperties":true,"required":["code","severity","message"],"properties":{"code":{"type":"string"},"severity":{"type":"string"},"message":{"type":"string"},"required_fields":{"type":"array","items":{"type":"string"}}}},"SkuExport":{"type":"object","additionalProperties":true,"required":["exported_at","sku","dossier_fields","entities","documents","warnings","issues"],"properties":{"exported_at":{"type":"string","format":"date-time"},"sku":{"type":"object","additionalProperties":true,"required":["id","sku_code","product_name"],"properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"sku_code":{"type":"string"},"product_name":{"type":"string"},"gtin":{"type":["string","null"]},"category_code":{"type":["string","null"]},"review_state":{"type":["string","null"]},"approval_state":{"type":["string","null"]},"blocker_count":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"}}},"dossier_fields":{"type":"array","items":{"type":"object","additionalProperties":true}},"entities":{"type":"array","items":{"type":"object","additionalProperties":true}},"documents":{"type":"array","items":{"type":"object","additionalProperties":true}},"warnings":{"type":"array","items":{"type":"object","additionalProperties":true}},"issues":{"type":"array","items":{"type":"object","additionalProperties":true}},"audit_summary":{"type":"object","additionalProperties":true}}},"AiFillSuggestion":{"type":"object","additionalProperties":false,"required":["field_key","value","confidence","reasoning"],"properties":{"field_key":{"type":"string","description":"The dossier field key this suggestion applies to."},"value":{"type":"string","description":"The suggested value. Must be reviewed by a human before compliance use."},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Model confidence 0.0–1.0. Lower confidence values warrant extra scrutiny."},"reasoning":{"type":"string","maxLength":300,"description":"Brief reasoning behind the suggestion."}}},"ProductResearchRequest":{"type":"object","additionalProperties":false,"required":["sku_id","fields_to_research"],"properties":{"sku_id":{"type":"string"},"fields_to_research":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"string","enum":["manufacturer_website","product_category","ean","hs_code"]}},"context":{"type":"object","additionalProperties":false,"properties":{"product_name":{"type":"string"},"manufacturer_name":{"type":"string"},"sku_code":{"type":"string"}}}}},"ProductResearchFinding":{"type":"object","additionalProperties":false,"required":["field","suggested_value","confidence","source_url","source_snippet","reasoning"],"properties":{"field":{"type":"string","enum":["manufacturer_website","product_category","ean","hs_code"]},"suggested_value":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"source_url":{"type":"string","format":"uri"},"source_snippet":{"type":"string"},"reasoning":{"type":"string"}}},"ProductResearchResponse":{"type":"object","additionalProperties":true,"required":["findings","status","provider_available"],"properties":{"findings":{"type":"array","items":{"$ref":"#/components/schemas/ProductResearchFinding"}},"fields":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["field","status"],"properties":{"field":{"type":"string","enum":["manufacturer_website","product_category","ean","hs_code"]},"status":{"type":"string","enum":["found","not_found","error"]},"error":{"type":"string","enum":["provider_unavailable","search_failed"]}}}},"status":{"type":"string","enum":["partial","complete","not_found"]},"provider_available":{"type":"boolean"},"cached":{"type":"boolean"}}},"ExportRun":{"type":"object","required":["id","template_name","template_format","scope_type","sku_count","status","created_at"],"properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"template_id":{"type":["string","null"]},"template_name":{"type":"string"},"template_version":{"type":["string","null"]},"template_format":{"type":"string"},"scope_type":{"type":"string","enum":["all","view","selected_skus","single_sku"]},"scope_value":{"type":["string","null"]},"sku_count":{"type":"integer"},"dossier_snapshot_hash":{"type":["string","null"]},"status":{"type":"string","enum":["pending","processing","completed","completed_with_warnings","failed"]},"output_url":{"type":["string","null"]},"output_size_bytes":{"type":["integer","null"]},"warning_count":{"type":"integer"},"error_message":{"type":["string","null"]},"started_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"ExportTemplate":{"type":"object","required":["id","name","format","version","status"],"properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"format":{"type":"string","enum":["XML","XLSX","CSV","PDF","ZIP","JSON"]},"version":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","enum":["valid","schema_drift","deprecated"]}}}},"responses":{"BadRequest":{"description":"Invalid request. Body uses the standard error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Authentication is required. Body uses the standard error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"The authenticated user cannot perform this action. Body uses the standard error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"The requested resource was not found. Body uses the standard error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"The request was rate limited. Body uses the standard error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalError":{"description":"Unexpected server error. Body uses the standard error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"AiFillConflict":{"description":"An AI-fill job is already in progress for this SKU.","content":{"application/json":{"schema":{"type":"object","required":["error","job_id","status"],"properties":{"error":{"type":"string"},"job_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","enum":["pending","processing"]}}}}}}}},"paths":{"/api/health":{"get":{"tags":["Health"],"security":[],"summary":"Public liveness probe. No authentication required.","operationId":"getHealth","responses":{"200":{"description":"Service health payload.","content":{"application/json":{"schema":{"type":"object","required":["status","service","time"],"properties":{"status":{"type":"string"},"service":{"type":"string"},"time":{"type":"string","format":"date-time"},"version":{"type":"string"},"environment":{"type":"string"},"git_sha":{"type":"string"}}}}}},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/health/email":{"get":{"tags":["Health"],"security":[{"cookieAuth":[]}],"summary":"Staff-only email readiness probe (Brevo SMTP). Requires staff authentication.","operationId":"getHealthEmail","responses":{"200":{"description":"Email readiness payload.","content":{"application/json":{"schema":{"type":"object","required":["status","service","time","provider","smtp_configured"],"properties":{"status":{"type":"string"},"service":{"type":"string"},"time":{"type":"string","format":"date-time"},"version":{"type":"string"},"environment":{"type":"string"},"git_sha":{"type":"string"},"provider":{"type":"string"},"smtp_configured":{"type":"boolean"},"smtp_reachable":{"type":["boolean","null"]},"jwt_secret_configured":{"type":"boolean"},"public_app_url":{"type":"string"},"public_app_url_configured":{"type":"boolean"},"smtp_from_address":{"type":"string"},"smtp_from_name":{"type":"string"},"smtp_from_name_configured":{"type":"boolean"},"verification_links_enabled":{"type":"boolean"},"smtp_verify_error":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/mcp":{"get":{"tags":["Public API"],"security":[{"bearerAuth":[]}],"summary":"MCP server info and health check (WebStandardStreamableHTTP transport).","operationId":"getMcpInfo","responses":{"200":{"description":"MCP server metadata.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"preview"},"post":{"tags":["Public API"],"security":[{"bearerAuth":[]}],"summary":"Call the read-only Telden MCP server.","operationId":"callMcp","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","number","null"]},"method":{"type":"string"},"params":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"MCP JSON-RPC response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"preview"}},"/api/workspace/api-keys":{"get":{"tags":["Workspace"],"security":[{"cookieAuth":[]}],"summary":"List active workspace API keys.","operationId":"listWorkspaceApiKeys","responses":{"200":{"description":"Active API keys for the current workspace.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"},"post":{"tags":["Workspace"],"security":[{"cookieAuth":[]}],"summary":"Create a workspace API key.","operationId":"createWorkspaceApiKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyInput"}}}},"responses":{"201":{"description":"Created API key. The plaintext key is returned once.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","required":["key"],"properties":{"key":{"type":"string"}}}]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/workspace/api-keys/{id}":{"delete":{"tags":["Workspace"],"security":[{"cookieAuth":[]}],"summary":"Revoke a workspace API key.","operationId":"revokeWorkspaceApiKey","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Revoked API key confirmation.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","revoked"],"properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"revoked":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"},"post":{"tags":["Workspace"],"security":[{"cookieAuth":[]}],"summary":"Rotate a workspace API key (revoke old key and create a new one).","operationId":"rotateWorkspaceApiKey","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"201":{"description":"Rotated API key. The new plaintext key is returned once.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","required":["key"],"properties":{"key":{"type":"string"}}}]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/skus":{"get":{"tags":["SKUs"],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"summary":"List SKUs for the current workspace.","operationId":"listSkus","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Paginated SKU list.","content":{"application/json":{"schema":{"type":"object","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Sku"},"description":"Canonical SKU collection (issue #722, #1084)."},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"},"post":{"tags":["SKUs"],"security":[{"cookieAuth":[]}],"summary":"Create a SKU in the current workspace. Supports dry_run and Idempotency-Key.","operationId":"createSku","parameters":[{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true, validate and describe the operation without committing writes or generating files."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Opaque replay key. Reusing the same key with the same request returns the original response for 24 hours."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSkuInput"}}}},"responses":{"200":{"description":"Dry-run preview. Returned when dry_run=true; no SKU, activity, requirement evaluation, or Inngest event is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSkuDryRunResponse"}}}},"201":{"description":"Created SKU.","content":{"application/json":{"schema":{"type":"object","required":["sku"],"properties":{"sku":{"$ref":"#/components/schemas/Sku"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"SKU code already exists, or Idempotency-Key was reused with different SKU payload content. Body uses the standard error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/skus/{id}":{"get":{"tags":["SKUs"],"security":[{"cookieAuth":[]}],"summary":"Get a SKU with agent-readable blocker and capability flags.","operationId":"getSku","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"SKU detail with blockers and capability flags.","content":{"application/json":{"schema":{"type":"object","required":["sku","blockers","status","can_generate_draft","can_publish"],"properties":{"sku":{"$ref":"#/components/schemas/Sku"},"blockers":{"type":"array","items":{"$ref":"#/components/schemas/SkuBlocker"}},"status":{"type":"string"},"can_generate_draft":{"type":"boolean"},"can_publish":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"},"delete":{"tags":["SKUs"],"security":[{"cookieAuth":[]}],"summary":"Delete a SKU and related records in the current workspace.","operationId":"deleteSku","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"SKU deleted.","content":{"application/json":{"schema":{"type":"object","required":["success","deleted_id"],"properties":{"success":{"type":"boolean"},"deleted_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/skus/{id}/documents":{"get":{"tags":["SKUs"],"security":[{"cookieAuth":[]}],"summary":"List documents linked to a SKU (legacy sku_id column and document_sku join).","operationId":"listSkuDocuments","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Linked documents with extraction embeds.","content":{"application/json":{"schema":{"type":"object","required":["documents"],"additionalProperties":false,"properties":{"documents":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/skus/{id}/approve":{"post":{"tags":["SKUs"],"security":[{"cookieAuth":[]}],"summary":"Approve a SKU for publishing.","operationId":"approveSku","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true, validate and describe the operation without committing writes or generating files."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Opaque replay key. Reusing the same key with the same request returns the original response for 24 hours."}],"responses":{"200":{"description":"SKU approved.","content":{"application/json":{"schema":{"type":"object","required":["sku"],"properties":{"sku":{"$ref":"#/components/schemas/Sku"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Idempotency key was reused with a different request. Body uses the standard error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/skus/{id}/review/complete":{"post":{"tags":["SKUs"],"security":[{"cookieAuth":[]}],"summary":"Mark a SKU review as complete after all issues and extraction conflicts are resolved.","operationId":"completeSkuReview","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true, validate and describe the operation without committing writes or generating files."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Opaque replay key. Reusing the same key with the same request returns the original response for 24 hours."}],"responses":{"200":{"description":"Review marked complete.","content":{"application/json":{"schema":{"type":"object","required":["sku"],"properties":{"sku":{"$ref":"#/components/schemas/Sku"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Idempotency key was reused with a different request. Body uses the standard error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/skus/{id}/publish":{"post":{"tags":["SKUs"],"security":[{"cookieAuth":[]}],"summary":"Publish a safety page for an approved SKU.","operationId":"publishSku","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true, validate and describe the operation without committing writes or generating files."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Opaque replay key. Reusing the same key with the same request returns the original response for 24 hours."}],"responses":{"200":{"description":"Safety page published.","content":{"application/json":{"schema":{"type":"object","required":["output","public_url","revision"],"properties":{"output":{"type":"object","additionalProperties":true},"public_url":{"type":"string"},"revision":{"type":"integer"},"safety_page":{"type":"object","additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Idempotency key was reused with a different request. Body uses the standard error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/skus/{id}/export":{"get":{"tags":["SKUs"],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"summary":"Export one SKU as JSON or CSV. Bearer auth requires the `export` scope (paid/enterprise plans).","operationId":"exportSku","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","csv"]}},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true, validate and describe the operation without committing writes or generating files."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Opaque replay key. Reusing the same key with the same request returns the original response for 24 hours."}],"responses":{"200":{"description":"SKU export payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkuExport"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Insufficient scope (Bearer auth). The API key lacks the `export` scope. Body uses the standard error envelope with code INSUFFICIENT_SCOPE and details.required_scope set to `export`. Cookie-based in-app export is unaffected by scope restrictions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Idempotency key was reused with a different request. Body uses the standard error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/skus/{id}/dossier.zip":{"get":{"tags":["SKUs"],"security":[{"cookieAuth":[]}],"summary":"Download one SKU dossier PDF together with all attached documents as a ZIP archive.","operationId":"downloadSkuDossierZip","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","de","fr","es","it"]}}],"responses":{"200":{"description":"ZIP archive containing dossier.pdf and attached documents.","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/classify":{"post":{"tags":["Documents"],"security":[{"cookieAuth":[]}],"summary":"Classify a file as product CSV, compliance document, or other.","operationId":"classifyFileIntent","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["filename"],"properties":{"filename":{"type":"string"},"mime_type":{"type":"string"},"content_snippet":{"type":"string","maxLength":1500},"snippet_source":{"type":"string","enum":["pdf_first_page","csv_rows","filename_only","html_text","docx_text","plain_text","email_text","xml_text","ocr_text","vision_ocr","office_text","raw_text"]}}}},"multipart/form-data":{"schema":{"type":"object","additionalProperties":false,"required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"File to classify, maximum 20 MB."}}}}}},"responses":{"200":{"description":"Best-effort file classification result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["file_intent","document_type","document_type_confidence","confidence","detected_language","reasoning","signals_used","snippetSource"],"properties":{"file_intent":{"type":"string","enum":["product_csv","compliance_document","other","unknown"]},"document_type":{"type":["string","null"],"enum":["declaration_of_conformity","test_report","risk_assessment","cpsr","safety_data_sheet","manual","certificate","other",null]},"document_type_confidence":{"type":"number","minimum":0,"maximum":1},"confidence":{"type":"number","minimum":0,"maximum":1},"detected_language":{"type":["string","null"]},"reasoning":{"type":"string"},"signals_used":{"type":"array","items":{"type":"string","enum":["filename","mime_type","content_snippet"]}},"content_snippet":{"type":"string","description":"Cached snippet extracted or used for classification."},"snippetSource":{"type":"string","enum":["pdf_first_page","csv_rows","filename_only","html_text","docx_text","plain_text","email_text","xml_text","ocr_text","vision_ocr","office_text","raw_text"]},"degraded":{"type":"boolean","description":"True when classification used fallback, filename-only extraction, or a diagnostic degraded path."},"diagnostic":{"type":"object","additionalProperties":false,"required":["code","message","next_action","source","signals_used","confidence"],"properties":{"code":{"type":"string","enum":["ai_unavailable_fallback","text_extraction_failed_filename_only","scanned_or_empty_text","unsupported_file_type","low_confidence_other"]},"message":{"type":"string"},"next_action":{"type":"string","enum":["choose_document_type","reselect_file","convert_or_ocr_upload_again","confirm_or_choose_type"]},"source":{"type":"string","enum":["pdf_first_page","csv_rows","filename_only","html_text","docx_text","plain_text","email_text","xml_text","ocr_text","vision_ocr","office_text","raw_text"]},"signals_used":{"type":"array","items":{"type":"string","enum":["filename","mime_type","content_snippet"]}},"confidence":{"type":"number","minimum":0,"maximum":1}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"413":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"preview"}},"/api/classify/containers":{"post":{"tags":["Documents"],"security":[{"cookieAuth":[]}],"summary":"Expand supported containers (.zip, .eml, RFC 2822 .msg) and classify each extracted part. Nested .zip/.eml recurse up to recursion_limit (3); encrypted archives, opaque .p7m, and Outlook compound .msg return skipped diagnostics.","operationId":"classifyContainerFiles","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","additionalProperties":false,"required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Container file (.zip, .eml, or RFC 2822 .msg), maximum 20 MB."},"locale":{"type":"string","enum":["en","de","fr","es","it"],"description":"Optional locale for classifier reasoning text."}}}}}},"responses":{"200":{"description":"Per-part classifications plus skipped-part diagnostics.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["source_container","recursion_limit","parts","skipped"],"properties":{"source_container":{"type":"string"},"recursion_limit":{"type":"integer","minimum":1,"maximum":3,"description":"Maximum nested .zip/.eml depth (currently 3). Encrypted archives, opaque .p7m envelopes, and Outlook compound .msg files are reported in skipped with diagnostics instead of being silently omitted."},"parts":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["filename","path_in_container","source_container","recursion_depth","mime_type","classification"],"properties":{"filename":{"type":"string"},"path_in_container":{"type":"string"},"source_container":{"type":"string"},"recursion_depth":{"type":"integer","minimum":0},"mime_type":{"type":"string"},"classification":{"type":"object","additionalProperties":false,"required":["file_intent","document_type","document_type_confidence","confidence","detected_language","reasoning","signals_used","snippetSource"],"properties":{"file_intent":{"type":"string","enum":["product_csv","compliance_document","other","unknown"]},"document_type":{"type":["string","null"],"enum":["declaration_of_conformity","test_report","risk_assessment","cpsr","safety_data_sheet","manual","certificate","other",null]},"document_type_confidence":{"type":"number","minimum":0,"maximum":1},"confidence":{"type":"number","minimum":0,"maximum":1},"detected_language":{"type":["string","null"]},"reasoning":{"type":"string"},"signals_used":{"type":"array","items":{"type":"string","enum":["filename","mime_type","content_snippet"]}},"content_snippet":{"type":"string","description":"Cached snippet extracted or used for classification."},"snippetSource":{"type":"string","enum":["pdf_first_page","csv_rows","filename_only","html_text","docx_text","plain_text","email_text","xml_text","ocr_text","vision_ocr","office_text","raw_text"]},"degraded":{"type":"boolean","description":"True when classification used fallback, filename-only extraction, or a diagnostic degraded path."},"diagnostic":{"type":"object","additionalProperties":false,"required":["code","message","next_action","source","signals_used","confidence"],"properties":{"code":{"type":"string","enum":["ai_unavailable_fallback","text_extraction_failed_filename_only","scanned_or_empty_text","unsupported_file_type","low_confidence_other"]},"message":{"type":"string"},"next_action":{"type":"string","enum":["choose_document_type","reselect_file","convert_or_ocr_upload_again","confirm_or_choose_type"]},"source":{"type":"string","enum":["pdf_first_page","csv_rows","filename_only","html_text","docx_text","plain_text","email_text","xml_text","ocr_text","vision_ocr","office_text","raw_text"]},"signals_used":{"type":"array","items":{"type":"string","enum":["filename","mime_type","content_snippet"]}},"confidence":{"type":"number","minimum":0,"maximum":1}}}}}}}},"skipped":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["filename","path_in_container","source_container","recursion_depth","reason","message","diagnostic"],"properties":{"filename":{"type":"string"},"path_in_container":{"type":"string"},"source_container":{"type":"string"},"recursion_depth":{"type":"integer","minimum":0},"reason":{"type":"string","enum":["encrypted_archive","unsupported_format","recursion_limit_exceeded","opaque_p7m_envelope","non_parseable_msg","parse_failed","empty_container"]},"message":{"type":"string"},"diagnostic":{"type":"object","additionalProperties":false,"required":["file_intent","document_type","document_type_confidence","confidence","detected_language","reasoning","signals_used","snippetSource"],"properties":{"file_intent":{"type":"string","enum":["product_csv","compliance_document","other","unknown"]},"document_type":{"type":["string","null"],"enum":["declaration_of_conformity","test_report","risk_assessment","cpsr","safety_data_sheet","manual","certificate","other",null]},"document_type_confidence":{"type":"number","minimum":0,"maximum":1},"confidence":{"type":"number","minimum":0,"maximum":1},"detected_language":{"type":["string","null"]},"reasoning":{"type":"string"},"signals_used":{"type":"array","items":{"type":"string","enum":["filename","mime_type","content_snippet"]}},"content_snippet":{"type":"string","description":"Cached snippet extracted or used for classification."},"snippetSource":{"type":"string","enum":["pdf_first_page","csv_rows","filename_only","html_text","docx_text","plain_text","email_text","xml_text","ocr_text","vision_ocr","office_text","raw_text"]},"degraded":{"type":"boolean","description":"True when classification used fallback, filename-only extraction, or a diagnostic degraded path."},"diagnostic":{"type":"object","additionalProperties":false,"required":["code","message","next_action","source","signals_used","confidence"],"properties":{"code":{"type":"string","enum":["ai_unavailable_fallback","text_extraction_failed_filename_only","scanned_or_empty_text","unsupported_file_type","low_confidence_other"]},"message":{"type":"string"},"next_action":{"type":"string","enum":["choose_document_type","reselect_file","convert_or_ocr_upload_again","confirm_or_choose_type"]},"source":{"type":"string","enum":["pdf_first_page","csv_rows","filename_only","html_text","docx_text","plain_text","email_text","xml_text","ocr_text","vision_ocr","office_text","raw_text"]},"signals_used":{"type":"array","items":{"type":"string","enum":["filename","mime_type","content_snippet"]}},"confidence":{"type":"number","minimum":0,"maximum":1}}}}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"413":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"preview"}},"/api/documents/bulk":{"post":{"tags":["Documents"],"security":[{"cookieAuth":[]}],"summary":"Upload up to 20 compliance documents in one multipart batch.","operationId":"bulkUploadDocuments","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Opaque replay key. Reusing the same key with the same request returns the original response for 24 hours."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","additionalProperties":false,"required":["files"],"properties":{"files":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","format":"binary"},"description":"Repeated multipart field name `files`, matching browser `<input multiple>` submissions. Supports PDF, image, HTML/text, email, Office, XML, and p7m compliance document formats."},"sku_id":{"type":"string","description":"Optional SKU id. When provided, each uploaded document is linked to this SKU."},"document_type":{"type":"string","enum":["declaration_of_conformity","risk_assessment","cpsr","test_report","safety_data_sheet","certificate","manual","other"],"description":"Optional document type applied to uploaded files. Defaults to `other`."},"classification_confidence":{"type":"number","minimum":0,"maximum":1,"description":"Optional classifier confidence persisted on the uploaded document."},"classification_source":{"type":"string","enum":["rule","llm","manual"],"description":"Optional classifier source persisted on the uploaded document. Defaults to `rule`."},"artifact_kind":{"type":"string","enum":["product_data"],"description":"Optional internal marker for non-proof files that should be extracted as product-data artifacts while remaining `document_type=other`."}}}}}},"responses":{"200":{"description":"Per-file upload results and aggregate summary.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["results","summary"],"properties":{"results":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["filename","status"],"properties":{"filename":{"type":"string"},"status":{"type":"string","enum":["uploaded","duplicate","error","skipped_quota"]},"document_id":{"type":"string","description":"Present for uploaded or duplicate files."},"error_code":{"type":"string","description":"Present when status is error."},"message":{"type":"string"}}}},"summary":{"type":"object","additionalProperties":false,"required":["uploaded","duplicate","error"],"properties":{"uploaded":{"type":"integer"},"duplicate":{"type":"integer"},"error":{"type":"integer"},"skipped_quota":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Idempotency key was reused with a different request. Body uses the standard error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"The batch would exceed the workspace storage limit before any file is processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"preview"}},"/api/upload/orchestrate":{"post":{"tags":["Documents"],"security":[{"cookieAuth":[]}],"summary":"Record upload orchestration audit events for classified files.","operationId":"recordUploadOrchestrationEvent","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["action"],"properties":{"action":{"type":"string","enum":["upload.classified","upload.routed","upload.needs_review"]},"filename":{"type":["string","null"],"maxLength":240},"classification_type":{"type":["string","null"]},"confidence":{"type":["number","null"],"minimum":0,"maximum":1},"destination":{"type":["string","null"],"enum":["documentVault","importWizard","reviewQueue",null]},"reasoning":{"type":["string","null"],"maxLength":500}}}}}},"responses":{"200":{"description":"Audit event recorded.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"preview"}},"/api/imports":{"get":{"tags":["Imports"],"security":[{"cookieAuth":[]}],"summary":"List recent import batches for the current workspace.","operationId":"listImports","responses":{"200":{"description":"Recent import batches.","content":{"application/json":{"schema":{"type":"object","required":["batches"],"properties":{"batches":{"type":"array","items":{"$ref":"#/components/schemas/ImportBatch"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/imports/{batchId}":{"get":{"tags":["Imports"],"security":[{"cookieAuth":[]}],"summary":"Get one import batch summary.","operationId":"getImport","parameters":[{"name":"batchId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Import batch detail.","content":{"application/json":{"schema":{"type":"object","required":["batch"],"properties":{"batch":{"$ref":"#/components/schemas/ImportBatch"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/imports/{batchId}/review":{"get":{"tags":["Imports"],"security":[{"cookieAuth":[]}],"summary":"Get post-import batch review workbench payload for imported SKUs, suggestions, and provenance.","operationId":"getImportBatchReview","parameters":[{"name":"batchId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Import batch review payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"preview"}},"/api/imports/{batchId}/entity-resolution":{"post":{"tags":["Imports"],"security":[{"cookieAuth":[]}],"summary":"Validate and persist linked-entity resolution decisions for an import batch.","operationId":"resolveImportEntities","parameters":[{"name":"batchId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true, validate and describe the operation without committing writes or generating files."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Opaque replay key. Reusing the same key with the same request returns the original response for 24 hours."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportEntityResolutionRequest"}}}},"responses":{"200":{"description":"Entity-resolution validation or persistence result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportEntityResolutionResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Conflicting candidate decisions or idempotency-key reuse. Body uses the standard error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"preview"}},"/api/import":{"post":{"tags":["Imports"],"security":[{"cookieAuth":[]}],"summary":"Upload and process a CSV, TSV, XLSX, XLS, or ODS SKU import.","operationId":"createImport","parameters":[{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true, validate and describe the operation without committing writes or generating files."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Opaque replay key. Reusing the same key with the same request returns the original response for 24 hours."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"format":{"type":"string","enum":["csv","tsv","xlsx","xls","ods"]},"delimiter":{"type":"string","enum":[",",";","\\t","|"]},"encoding":{"type":"string","enum":["utf-8","utf-16le","utf-16be","windows-1252","iso-8859-1","iso-8859-15","macintosh"]},"sheetName":{"type":"string"},"preset":{"type":"string"},"dry_run":{"type":"boolean"},"mapping":{"type":"string","description":"JSON object mapping Telden fields to uploaded column headers."},"entity_decisions":{"type":"string","description":"JSON array of final import entity decisions. Each item targets sku_code plus role (manufacturer, importer, responsible_person) and either links entity_id or creates an entity payload before requirement evaluation."}}}}}},"responses":{"200":{"description":"Import processing result.","content":{"application/json":{"schema":{"type":"object","required":["batch_id","total","created","updated","skipped","failed","status"],"properties":{"dry_run":{"type":"boolean"},"batch_id":{"type":["string","null"],"format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"total":{"type":"integer"},"created":{"type":"integer"},"updated":{"type":"integer"},"skipped":{"type":"integer"},"failed":{"type":"integer"},"status":{"type":"string","enum":["completed","completed_with_warnings","failed"]},"errors":{"type":"array","items":{"type":"string"}},"skippedRows":{"type":"array","items":{"type":"object","additionalProperties":true}},"failedRows":{"type":"array","items":{"type":"object","additionalProperties":true}},"parse_metadata":{"type":"object","additionalProperties":true},"entity_candidates":{"type":"object","description":"Present on dry-run responses when linked-entity source columns are detected.","properties":{"manufacturer":{"type":"array","items":{"type":"object","additionalProperties":true}},"importer":{"type":"array","items":{"type":"object","additionalProperties":true}},"responsible_person":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Idempotency key was reused with a different request. Body uses the standard error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/import/from-url":{"post":{"tags":["Imports"],"security":[{"cookieAuth":[]}],"summary":"Preview a product import from a public shop or catalog URL.","operationId":"previewImportFromUrl","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","dry_run"],"additionalProperties":false,"properties":{"url":{"type":"string","format":"uri","description":"Public http/https shop, catalog, listing, or product detail URL. Localhost, private IP ranges, link-local addresses, metadata service addresses, and unsafe schemes are rejected."},"dry_run":{"type":"boolean","description":"Must be true for URL discovery. Final writes hand off to POST /api/import after human review."},"max_product_pages":{"type":"integer","minimum":0,"maximum":5,"default":5,"description":"Same-origin product detail pages to fetch after the submitted page."},"max_products":{"type":"integer","minimum":1,"maximum":20,"default":20,"description":"Maximum product rows returned in one preview."}}}}}},"responses":{"200":{"description":"URL import preview. No SKUs are created.","content":{"application/json":{"schema":{"type":"object","required":["dry_run","rows","warnings","limits","handoff"],"properties":{"dry_run":{"type":"boolean"},"handoff":{"type":"object","required":["endpoint","method","review_required","idempotency_key_required"],"properties":{"endpoint":{"type":"string","enum":["/api/import"]},"method":{"type":"string","enum":["POST"]},"review_required":{"type":"boolean"},"idempotency_key_required":{"type":"boolean"}}},"rows":{"type":"array","items":{"type":"object","required":["sku_code","product_name","gtin","source_url","field_meta","warnings"],"properties":{"sku_code":{"type":"string"},"product_name":{"type":"string"},"gtin":{"type":"string"},"brand":{"type":"string"},"description":{"type":"string"},"image_url":{"type":"string"},"source_url":{"type":"string","format":"uri"},"field_meta":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"source":{"type":"string","enum":["json-ld","opengraph","microdata","dom"]}}}},"warnings":{"type":"array","items":{"type":"string"}}}}},"warnings":{"type":"array","items":{"type":"string"}},"discovered_urls":{"type":"array","items":{"type":"string","format":"uri"}},"limits":{"type":"object","properties":{"maxProductPages":{"type":"integer","maximum":5},"maxProducts":{"type":"integer","maximum":20},"timeoutMs":{"type":"integer"},"maxResponseBytes":{"type":"integer"},"redirectLimit":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"description":"HTML response exceeded the maximum response-size limit. Body uses the standard error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"preview"}},"/api/v1/skus":{"get":{"tags":["v1"],"security":[{"bearerAuth":[]}],"summary":"List workspace SKUs via Bearer-token auth. Requires API key with skus:read scope.","operationId":"v1ListSkus","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Paginated SKU list.","content":{"application/json":{"schema":{"type":"object","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Sku"}},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/v1/skus/{id}/re-extract":{"post":{"tags":["v1"],"security":[{"bearerAuth":[]}],"summary":"Trigger re-extraction of a SKU's linked documents via Bearer-token auth. Requires API key with extractions:write scope.","operationId":"v1ReExtractSku","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"202":{"description":"Re-extraction triggered.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"preview"}},"/api/v1/documents/{id}/re-extract":{"post":{"tags":["v1"],"security":[{"bearerAuth":[]}],"summary":"Trigger re-extraction of a document via Bearer-token auth. Requires API key with extractions:write scope.","operationId":"v1ReExtractDocument","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"202":{"description":"Re-extraction triggered.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"preview"}},"/api/skus/{id}/fields/{fieldId}/sync-from-entity":{"post":{"tags":["SKUs"],"security":[{"cookieAuth":[]}],"summary":"Copy the current confirmed linked entity value into a dossier field. Supports dry_run and Idempotency-Key.","operationId":"syncSkuDossierFieldFromEntity","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"fieldId","in":"path","required":true,"schema":{"type":"string"},"description":"Dossier field key, for example manufacturer_email."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Updated dossier field row.","content":{"application/json":{"schema":{"type":"object","required":["field"],"properties":{"field":{"type":"object","additionalProperties":true}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/skus/{id}/ai-fill":{"post":{"tags":["AI"],"security":[{"cookieAuth":[]}],"summary":"Trigger AI fill for a SKU's missing dossier fields. Creates a background job and returns immediately. AI suggestions require human review and are never auto-approved for compliance output.","operationId":"triggerAiFill","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"AI-fill job created. Poll GET /job for completion.","content":{"application/json":{"schema":{"type":"object","required":["job_id","status","total_missing"],"properties":{"job_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","enum":["pending"]},"total_missing":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/AiFillConflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/skus/{id}/ai-fill/job":{"get":{"tags":["AI"],"security":[{"cookieAuth":[]}],"summary":"Poll the latest AI-fill job status for a SKU.","operationId":"getAiFillJob","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"AI-fill job status. When completed, includes suggestions array. When failed, includes error_message.","content":{"application/json":{"schema":{"type":"object","required":["job_id","status","created_at"],"properties":{"job_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","enum":["pending","processing","completed","failed","cancelled"]},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"suggestions":{"type":"array","items":{"$ref":"#/components/schemas/AiFillSuggestion"}},"applied_count":{"type":"integer"},"total_missing":{"type":"integer"},"input_tokens":{"type":["integer","null"]},"output_tokens":{"type":["integer","null"]},"error_message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/skus/{id}/ai-fill/cancel":{"post":{"tags":["AI"],"security":[{"cookieAuth":[]}],"summary":"Cancel a running AI-fill job (pending or processing).","operationId":"cancelAiFillJob","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"AI-fill job cancelled.","content":{"application/json":{"schema":{"type":"object","required":["job_id","status"],"properties":{"job_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","enum":["cancelled"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No active AI-fill job to cancel. Body uses the standard error envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/research/product":{"post":{"tags":["AI"],"security":[{"cookieAuth":[]}],"summary":"Research missing product data from public sources and return cited suggestions only.","operationId":"researchProduct","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResearchRequest"}}}},"responses":{"200":{"description":"Cited product research suggestions. Suggestions are never auto-applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"preview"}},"/api/supplier-email/draft":{"post":{"tags":["Supplier email"],"security":[{"cookieAuth":[]}],"summary":"Generate a supplier outreach email draft for missing compliance documents.","operationId":"draftSupplierEmail","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sku_id","entity_id","missing_documents"],"properties":{"sku_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"entity_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"missing_documents":{"type":"array","items":{"type":"string"},"minItems":1},"language":{"type":"string"}}}}}},"responses":{"200":{"description":"Generated email draft.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"subject":{"type":"string"},"body":{"type":"string"},"recipient_email":{"type":"string"},"recipient_name":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/supplier-email/send":{"post":{"tags":["Supplier email"],"security":[{"cookieAuth":[]}],"summary":"Send a supplier outreach email via workspace SMTP.","operationId":"sendSupplierEmail","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sku_id","to_email","subject","body"],"properties":{"sku_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"entity_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"to_email":{"type":"string","format":"email"},"to_name":{"type":["string","null"]},"subject":{"type":"string"},"body":{"type":"string"},"missing_documents":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Email sent and request recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"sent_at":{"type":"string","format":"date-time"},"to_email":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"SMTP is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-stability":"stable"}},"/api/supplier-email/requests":{"get":{"tags":["Supplier email"],"security":[{"cookieAuth":[]}],"summary":"List sent supplier email requests for a SKU.","operationId":"listSupplierEmailRequests","parameters":[{"name":"sku_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Supplier email request rows.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/supplier-email/requests/{id}":{"patch":{"tags":["Supplier email"],"security":[{"cookieAuth":[]}],"summary":"Update supplier email request status.","operationId":"patchSupplierEmailRequest","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["pending","received"]}}}}}},"responses":{"200":{"description":"Updated request row.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"stable"}},"/api/exports":{"get":{"tags":["Exports"],"security":[{"cookieAuth":[]}],"summary":"List past export runs for the current workspace.","operationId":"listExports","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"Recent export runs.","content":{"application/json":{"schema":{"type":"object","required":["runs"],"properties":{"runs":{"type":"array","items":{"$ref":"#/components/schemas/ExportRun"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"preview"},"post":{"tags":["Exports"],"security":[{"cookieAuth":[]}],"summary":"Trigger a new export run with a chosen template and scope.","operationId":"createExport","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["template_id"],"properties":{"template_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"scope_type":{"type":"string","enum":["all","view","selected_skus","single_sku"],"default":"all"},"scope_value":{"type":"string"},"sku_ids":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}}}}}},"responses":{"201":{"description":"Export run created.","content":{"application/json":{"schema":{"type":"object","required":["id","template_name","status"],"properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"template_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"template_name":{"type":"string"},"template_version":{"type":"string"},"template_format":{"type":"string"},"scope_type":{"type":"string"},"scope_value":{"type":"string"},"sku_count":{"type":"integer"},"dossier_snapshot_hash":{"type":"string"},"status":{"type":"string"},"output_url":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"preview"}},"/api/exports/templates":{"get":{"tags":["Exports"],"security":[{"cookieAuth":[]}],"summary":"List available export templates for the current workspace.","operationId":"listExportTemplates","responses":{"200":{"description":"Available export templates.","content":{"application/json":{"schema":{"type":"object","required":["templates"],"properties":{"templates":{"type":"array","items":{"$ref":"#/components/schemas/ExportTemplate"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-stability":"preview"}}}}