{ "components": { "schemas": { "AccountClosure": { "additionalProperties": false, "properties": { "case_id": { "format": "uuid", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "confirmed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "due_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "scope": { "enum": [ "account", "workspace" ], "type": "string" }, "status": { "type": "string" } }, "required": [], "type": "object" }, "AccountClosureInput": { "additionalProperties": false, "properties": { "confirm": { "const": true, "type": "boolean" }, "current_password": { "type": "string" }, "request_id": { "type": "string" }, "scope": { "enum": [ "account", "workspace" ], "type": "string" } }, "required": [ "scope", "current_password", "confirm", "request_id" ], "type": "object" }, "AccountClosureList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/AccountClosure" }, "type": "array" }, "now": { "format": "date-time", "type": "string" }, "total": { "type": "integer" } }, "required": [], "type": "object" }, "AccountClosureReview": { "additionalProperties": false, "properties": { "acknowledge_finance": { "type": "boolean" }, "approve": { "type": "boolean" }, "decision": { "type": "string" } }, "required": [ "approve", "decision" ], "type": "object" }, "AccountCorrection": { "additionalProperties": false, "properties": { "current_password": { "type": "string" }, "email": { "format": "email", "type": "string" }, "name": { "maxLength": 120, "type": "string" } }, "required": [ "name", "current_password" ], "type": "object" }, "Activation": { "additionalProperties": false, "example": { "created_at": "2026-10-18T00:00:00Z", "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "device_name": "Office PC", "generation": 1, "id": "44444444-4444-4444-8444-444444444444", "last_seen_at": "2026-10-18T00:00:00Z", "license_id": "33333333-3333-4333-8333-333333333333", "product_id": "11111111-1111-4111-8111-111111111111", "released_at": null, "status": "active", "virtual_machine": false }, "properties": { "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "device_id": { "description": "Product-scoped device fingerprint, usually 64 lowercase hex characters, derived by the SDK.", "type": "string" }, "device_name": { "description": "Human-readable device label, not a security identity.", "type": "string" }, "generation": { "description": "Activation generation used to invalidate old device credentials.", "type": "integer" }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "last_seen_at": { "description": "Last device activity timestamp observed by the server, UTC.", "format": "date-time", "type": "string" }, "lease_expires_at": { "anyOf": [ { "description": "Floating-seat lease expiry; expired seats can be reclaimed.", "format": "date-time", "type": "string" }, { "description": "Floating-seat lease expiry; expired seats can be reclaimed.", "type": "null" } ], "description": "Floating-seat lease expiry; expired seats can be reclaimed." }, "license_id": { "description": "License UUID, distinct from the lv_lic_ secret.", "format": "uuid", "type": "string" }, "product_id": { "description": "Product UUID in the current workspace.", "format": "uuid", "type": "string" }, "released_at": { "anyOf": [ { "description": "Release timestamp; null until released.", "format": "date-time", "type": "string" }, { "description": "Release timestamp; null until released.", "type": "null" } ], "description": "Release timestamp; null until released." }, "session_id": { "description": "Floating instance session identifier; may be omitted for node-locked licenses.", "type": "string" }, "status": { "description": "Current resource state; see the enum and operation notes.", "enum": [ "active", "released" ], "type": "string" }, "virtual_machine": { "description": "Whether the SDK detected a virtual machine.", "type": "boolean" } }, "required": [ "id", "product_id", "license_id", "device_id", "virtual_machine", "device_name", "status", "generation", "created_at", "last_seen_at", "released_at" ], "type": "object" }, "ActivationList": { "additionalProperties": false, "properties": { "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/Activation" }, "type": "array" }, "limit": { "description": "Page size, default 25, range 1–100.", "type": "integer" }, "offset": { "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "type": "integer" }, "total": { "description": "Total matching records, not the current page length.", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "AdminPlanList": { "additionalProperties": false, "properties": { "currencies": { "items": { "pattern": "^[A-Z]{3}$", "type": "string" }, "type": "array" }, "items": { "items": { "$ref": "#/components/schemas/Price" }, "type": "array" }, "settings": { "$ref": "#/components/schemas/DefaultPlan" } }, "required": [], "type": "object" }, "AttemptList": { "additionalProperties": false, "properties": { "items": { "anyOf": [ { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/WebhookAttempt" }, "type": "array" }, { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "type": "null" } ], "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type." } }, "required": [], "type": "object" }, "Audit": { "additionalProperties": false, "properties": { "action": { "description": "Audit action identifier, such as product.create or license.renew.", "type": "string" }, "actor_id": { "description": "UUID of the account responsible for the action.", "format": "uuid", "type": "string" }, "actor_kind": { "description": "Action source: session, api_key, or system.", "enum": [ "session", "api_key", "system" ], "type": "string" }, "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "type": "string" }, "resource_id": { "description": "UUID of the affected resource.", "maxLength": 36, "type": "string" } }, "required": [ "id", "action", "resource_id", "created_at" ], "type": "object" }, "AuditList": { "additionalProperties": false, "properties": { "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/Audit" }, "type": "array" }, "limit": { "description": "Page size, default 25, range 1–100.", "type": "integer" }, "offset": { "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "type": "integer" } }, "required": [ "items", "limit", "offset" ], "type": "object" }, "AutoRenewal": { "additionalProperties": false, "properties": { "amount_cents": { "description": "Amount in hundredths; ledger entries may be positive credits or negative debits.", "minimum": 0, "type": "integer" }, "currency": { "description": "Three-letter uppercase currency code, such as USD.", "type": "string" }, "enabled": { "description": "Whether the webhook endpoint is enabled.", "type": "boolean" }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "description": "Stable billing plan identifier from the published catalog.", "type": "string" }, "plan_name": { "description": "Display name of the plan.", "type": "string" }, "policy_version": { "description": "Service policy revision accepted when automatic renewal was saved.", "type": "string" }, "price_version": { "description": "Frozen pricing revision; stale input may cause PLAN_VERSION_CONFLICT.", "type": "string" }, "status": { "description": "Current resource state; see the enum and operation notes.", "enum": [ "disabled", "enabled", "insufficient_balance", "price_changed", "plan_changed", "plan_unavailable", "account_unavailable" ], "type": "string" }, "term_months": { "description": "Number of months in the purchased term.", "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "updated_at": { "description": "Last update timestamp in UTC.", "format": "date-time", "type": "string" }, "version": { "description": "Automatic renewal configuration revision.", "type": "string" } }, "required": [ "mode", "enabled", "plan", "plan_name", "currency", "price_version", "term_months", "amount_cents", "status", "version", "updated_at" ], "type": "object" }, "AutoRenewalInput": { "additionalProperties": false, "properties": { "currency": { "type": "string" }, "enabled": { "type": "boolean" }, "expected_version": { "type": "string" }, "overage_accepted": { "description": "Separate explicit authorisation of displayed chargeable overage.", "type": "boolean" }, "plan": { "type": "string" }, "policy_version": { "description": "Currently published immutable policy version. Required for consent-protected actions after the operator publishes a policy, in either payment environment.", "type": "string" }, "price_version": { "type": "string" }, "term_months": { "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "terms_accepted": { "description": "Explicit unchecked-by-default acceptance.", "type": "boolean" } }, "required": [ "enabled", "expected_version" ], "type": "object" }, "AutoRenewalResult": { "additionalProperties": false, "properties": { "next_renewal_at": { "anyOf": [ { "description": "Expected next renewal timestamp in UTC; may be null if disabled or unnecessary.", "format": "date-time", "type": "string" }, { "description": "Expected next renewal timestamp in UTC; may be null if disabled or unnecessary.", "type": "null" } ], "description": "Expected next renewal timestamp in UTC; may be null if disabled or unnecessary." }, "setting": { "$ref": "#/components/schemas/AutoRenewal", "description": "Current automatic renewal configuration." } }, "required": [ "setting", "next_renewal_at" ], "type": "object" }, "BatchInput": { "additionalProperties": false, "properties": { "days": { "description": "Required for renew: additional validity days, 1–36500; unused by other operations.", "maximum": 36500, "minimum": 1, "type": "integer" }, "duration_days": { "description": "Common duration for create entries that omit duration_days. Each entry can override it. Required for timed/trial entries without their own duration; omit for perpetual creation.", "maximum": 36500, "minimum": 1, "type": [ "integer", "null" ] }, "entries": { "description": "Required for create: 1–100 customer entries; omit for other operations.", "items": { "additionalProperties": false, "properties": { "customer": { "description": "Vendor-defined customer label, distinct from the customer portal email.", "maxLength": 120, "type": "string" }, "customer_email": { "description": "Linked customer portal email; empty when unassigned.", "maxLength": 254, "type": "string" }, "duration_days": { "description": "Per-license creation duration; overrides BatchInput.duration_days. Omit to use the common creation duration.", "maximum": 36500, "minimum": 1, "type": [ "integer", "null" ] } }, "required": [], "type": "object" }, "maxItems": 100, "minItems": 1, "type": "array" }, "ids": { "description": "Required for renew, revoke and apply_policy: 1–100 distinct license UUIDs; omit for create.", "items": { "format": "uuid", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "operation": { "description": "Operation name; batches support create/renew/revoke/apply_policy and offline requests activate/deactivate.", "enum": [ "create", "renew", "revoke", "apply_policy" ], "type": "string" }, "policy_id": { "description": "Required for create and apply_policy: target licensing policy UUID.", "format": "uuid", "type": "string" }, "preview_token": { "description": "Encrypted preview confirmation token required for apply_policy; valid 600 seconds and invalidated by resource changes.", "type": "string", "writeOnly": true }, "product_id": { "description": "Required for create: product UUID for the new licenses.", "format": "uuid", "type": "string" }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "request_id", "operation" ], "type": "object" }, "BatchItem": { "additionalProperties": false, "example": { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" }, "properties": { "customer": { "description": "Vendor-defined customer label, distinct from the customer portal email.", "type": "string" }, "customer_email": { "description": "Linked customer portal email; empty when unassigned.", "type": "string" }, "duration_days": { "description": "Per-license days from first activation. Required 1–36500 for timed/trial issuance; absent/null for perpetual. Never stored in the policy.", "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "format": "date-time", "type": "string" }, { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "type": "null" } ], "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry." }, "first_activated_at": { "anyOf": [ { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "format": "date-time", "type": "string" }, { "description": "First successful activation timestamp; null before activation and unchanged by renewal or transfer.", "type": "null" } ], "description": "First successful activation timestamp; null before activation and unchanged by renewal or transfer." }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "license_key": { "description": "Full customer license key supplied at activation. Product initialization code and example downloads do not contain this secret. Offline requests use the SDK-provided credential.", "type": "string" }, "operation": { "description": "Operation name; batches support create/renew/revoke/apply_policy and offline requests activate/deactivate.", "enum": [ "create", "renew", "revoke", "apply_policy" ], "type": "string" } }, "required": [ "id" ], "type": "object" }, "BatchResult": { "additionalProperties": false, "properties": { "count": { "description": "Count in the current group, or number of records processed by a batch.", "type": "integer" }, "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/BatchItem" }, "type": "array" }, "operation": { "description": "Operation name; batches support create/renew/revoke/apply_policy and offline requests activate/deactivate.", "enum": [ "create", "renew", "revoke", "apply_policy" ], "type": "string" }, "request_id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } }, "required": [ "request_id", "operation", "items", "count" ], "type": "object" }, "BillingEmailPreview": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "link": { "format": "uri", "type": "string" }, "reply_to": { "description": "Public support email and Reply-To for billing mail. Empty hides contact. It does not change the existing SMTP From address or create an inbox.", "maxLength": 254, "type": "string" }, "subject": { "type": "string" }, "to": { "format": "email", "type": "string" } }, "required": [ "id", "to", "subject", "body", "link" ], "type": "object" }, "BillingEmailTestInput": { "additionalProperties": false, "properties": { "kind": { "enum": [ "purchase_success", "expiry_reminder", "auto_renewal_success", "auto_renewal_problem" ], "type": "string" }, "locale": { "default": "zh", "enum": [ "zh", "zh-hant", "en", "es", "hi", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" }, "to": { "format": "email", "type": "string" } }, "required": [ "kind", "to" ], "type": "object" }, "BillingJob": { "additionalProperties": false, "properties": { "attempts": { "description": "Cumulative task attempt count.", "type": "integer" }, "available_at": { "description": "Earliest UTC time the task may run.", "format": "date-time", "type": "string" }, "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "last_error": { "description": "Most recent failure category; may be empty.", "type": "string" }, "month": { "description": "UTC month YYYY-MM; omitted query values use the current month. Billing jobs require a closed month.", "type": "string" }, "status": { "description": "Current resource state; see the enum and operation notes.", "enum": [ "pending", "running", "done", "failed" ], "type": "string" } }, "required": [ "id", "month", "status" ], "type": "object" }, "BillingJobList": { "additionalProperties": false, "properties": { "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/BillingJob" }, "type": "array" }, "limit": { "description": "Page size, default 25, range 1–100.", "type": "integer" }, "offset": { "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "type": "integer" }, "total": { "description": "Total matching records, not the current page length.", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "BillingNotificationPreference": { "additionalProperties": false, "properties": { "auto_renewal_problem": { "default": true, "type": "boolean" }, "auto_renewal_success": { "default": true, "type": "boolean" }, "expiry_reminder": { "default": true, "type": "boolean" }, "locale": { "enum": [ "zh", "zh-hant", "en", "es", "hi", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" }, "purchase_success": { "default": true, "type": "boolean" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [ "purchase_success", "expiry_reminder", "auto_renewal_success", "auto_renewal_problem", "locale", "version", "updated_at" ], "type": "object" }, "BillingNotificationPreferenceInput": { "additionalProperties": false, "properties": { "auto_renewal_problem": { "default": true, "type": "boolean" }, "auto_renewal_success": { "default": true, "type": "boolean" }, "expected_version": { "description": "Version from GET; empty for a not-yet-saved preference. A stale value returns BILLING_EMAIL_PREFERENCE_CONFLICT.", "type": "string" }, "expiry_reminder": { "default": true, "type": "boolean" }, "locale": { "enum": [ "zh", "zh-hant", "en", "es", "hi", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" }, "purchase_success": { "default": true, "type": "boolean" } }, "required": [ "expected_version" ], "type": "object" }, "BillingNotificationPreferencesResult": { "additionalProperties": false, "properties": { "platform": { "$ref": "#/components/schemas/BillingNotificationSettings" }, "preferences": { "$ref": "#/components/schemas/BillingNotificationPreference" }, "recipient": { "format": "email", "type": "string" } }, "required": [ "preferences", "platform", "recipient" ], "type": "object" }, "BillingNotificationSettings": { "additionalProperties": false, "properties": { "auto_renewal_problem": { "default": true, "type": "boolean" }, "auto_renewal_success": { "default": true, "type": "boolean" }, "expiry_reminder": { "default": true, "type": "boolean" }, "purchase_success": { "default": true, "type": "boolean" }, "reminder_days": { "default": [ 7 ], "description": "Thresholds before continuous coverage ends, in 24-hour days. Stored ascending. A late-started worker selects only the nearest remaining threshold, not every missed reminder.", "items": { "maximum": 90, "minimum": 1, "type": "integer" }, "maxItems": 10, "minItems": 1, "type": "array", "uniqueItems": true }, "support_email": { "description": "Public support email and Reply-To for billing mail. Empty hides contact. It does not change the existing SMTP From address or create an inbox.", "maxLength": 254, "type": "string" }, "version": { "type": "string" } }, "required": [ "purchase_success", "expiry_reminder", "auto_renewal_success", "auto_renewal_problem", "reminder_days", "support_email", "version" ], "type": "object" }, "BillingNotificationSettingsInput": { "additionalProperties": false, "properties": { "auto_renewal_problem": { "default": true, "type": "boolean" }, "auto_renewal_success": { "default": true, "type": "boolean" }, "expected_version": { "description": "Version from GET. A stale value returns BILLING_EMAIL_SETTINGS_CONFLICT.", "type": "string" }, "expiry_reminder": { "default": true, "type": "boolean" }, "purchase_success": { "default": true, "type": "boolean" }, "reminder_days": { "default": [ 7 ], "description": "Thresholds before continuous coverage ends, in 24-hour days. Stored ascending. A late-started worker selects only the nearest remaining threshold, not every missed reminder.", "items": { "maximum": 90, "minimum": 1, "type": "integer" }, "maxItems": 10, "minItems": 1, "type": "array", "uniqueItems": true }, "support_email": { "description": "Public support email and Reply-To for billing mail. Empty hides contact. It does not change the existing SMTP From address or create an inbox.", "maxLength": 254, "type": "string" } }, "required": [ "expected_version" ], "type": "object" }, "BundleInput": { "additionalProperties": false, "properties": { "language": { "description": "SDK language identifier for the download bundle.", "enum": [ "go", "java", "c", "cpp", "csharp", "python", "javascript", "rust", "ruby" ], "type": "string" } }, "required": [ "language" ], "type": "object" }, "BuyPlan": { "additionalProperties": false, "properties": { "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "overage_accepted": { "description": "Separate explicit authorisation of displayed chargeable overage.", "type": "boolean" }, "plan": { "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "policy_version": { "description": "Currently published immutable policy version. Required for consent-protected actions after the operator publishes a policy, in either payment environment.", "type": "string" }, "price_version": { "type": "string" }, "renewal": { "default": false, "description": "Explicit advance renewal. Payment is collected now and prepaid coverage is extended immediately. The next quota cycle follows existing paid or gifted coverage. No reset of current use. Renew the latest paid plan and currency; expired customers may also buy normally.", "type": "boolean" }, "request_id": { "maxLength": 80, "type": "string" }, "term_months": { "default": 1, "description": "Contract duration. Omission defaults to one month. Changing duration on a reused request_id returns 409.", "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "terms_accepted": { "description": "Explicit unchecked-by-default acceptance.", "type": "boolean" } }, "required": [ "plan", "currency", "price_version", "request_id" ], "type": "object" }, "CSRF": { "additionalProperties": false, "properties": { "csrf_token": { "type": "string" } }, "required": [ "csrf_token" ], "type": "object" }, "CancelCustomerRefund": { "additionalProperties": false, "properties": { "confirm_service_stays_cancelled": { "description": "Required when service cancellation has already executed before review. An explicit scoped pending application can be withdrawn without stopping or restoring service.", "type": "boolean" } }, "type": "object" }, "ChangePassword": { "additionalProperties": false, "properties": { "current_password": { "description": "12–128 UTF-8 bytes, not characters", "type": "string", "writeOnly": true }, "password": { "description": "12–128 UTF-8 bytes, not characters", "type": "string", "writeOnly": true }, "password_confirmation": { "description": "Required and must match password exactly", "type": "string", "writeOnly": true } }, "required": [ "current_password", "password", "password_confirmation" ], "type": "object" }, "ClosureExportCredential": { "additionalProperties": false, "properties": { "download_url": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "export_deadline": { "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "ClosureExportLogin": { "additionalProperties": false, "properties": { "current_password": { "type": "string" }, "email": { "format": "email", "type": "string" } }, "required": [ "email", "current_password" ], "type": "object" }, "CommerceNotice": { "additionalProperties": false, "properties": { "body": { "description": "Service notice body.", "type": "string" }, "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "effective_at": { "anyOf": [ { "description": "Effective time of the notified change, or null.", "format": "date-time", "type": "string" }, { "description": "Effective time of the notified change, or null.", "type": "null" } ], "description": "Effective time of the notified change, or null." }, "emailed_at": { "anyOf": [ { "description": "Notice email delivery timestamp, or null.", "format": "date-time", "type": "string" }, { "description": "Notice email delivery timestamp, or null.", "type": "null" } ], "description": "Notice email delivery timestamp, or null." }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "kind": { "description": "Ledger-entry or notice category identifier.", "type": "string" }, "read_at": { "anyOf": [ { "description": "Notice read timestamp, or null.", "format": "date-time", "type": "string" }, { "description": "Notice read timestamp, or null.", "type": "null" } ], "description": "Notice read timestamp, or null." }, "reference": { "description": "Related business reference used for tracing.", "type": "string" }, "title": { "description": "Service notice title.", "type": "string" } }, "required": [], "type": "object" }, "CommerceNoticeList": { "additionalProperties": false, "properties": { "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/CommerceNotice" }, "type": "array" } }, "required": [ "items" ], "type": "object" }, "CommercePolicy": { "additionalProperties": false, "properties": { "documents": { "properties": { "privacy": { "type": "string" }, "refunds": { "type": "string" }, "terms": { "type": "string" } }, "type": "object" }, "locale": { "type": "string" }, "pending": { "items": { "additionalProperties": false, "properties": { "created_at": { "format": "date-time", "type": "string" }, "effective_at": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "profile": { "$ref": "#/components/schemas/OperatorProfile" }, "published": { "type": "boolean" }, "ready": { "type": "boolean" }, "version": { "type": "string" } }, "required": [], "type": "object" }, "CommercePolicyInput": { "additionalProperties": false, "properties": { "expected_version": { "type": "string" }, "profile": { "$ref": "#/components/schemas/OperatorProfile" }, "published": { "type": "boolean" } }, "required": [ "profile", "published", "expected_version" ], "type": "object" }, "CommerceResult": { "additionalProperties": true, "type": "object" }, "Confirmation": { "additionalProperties": false, "properties": { "confirm": { "const": true, "type": "boolean" } }, "required": [ "confirm" ], "type": "object" }, "Consumption": { "additionalProperties": false, "properties": { "feature": { "description": "Feature identifier consumed.", "type": "string" }, "limit": { "description": "Feature use limit for this quota period.", "type": "integer" }, "overage": { "description": "Units above limit in this period, not money. The policy controls the feature overage cap.", "type": "integer" }, "period": { "description": "Metering period: YYYY-MM for monthly, YYYY-MM-DD for daily, lifetime for total. Daily/monthly boundaries use UTC.", "type": "string" }, "quantity": { "description": "Units requested for this operation, integer 1–1000000000.", "type": "integer" }, "remaining": { "description": "remaining = max(0, limit - used - reserved), excluding overage units.", "type": "integer" }, "reserved": { "description": "Unexpired reserved units this period, not yet charged.", "type": "integer" }, "reset_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Next reset, UTC ISO 8601; null for lifetime metering." }, "used": { "description": "Committed units this period, excluding reservations.", "type": "integer" } }, "required": [], "type": "object" }, "ConsumptionResult": { "additionalProperties": false, "properties": { "activation_id": { "description": "Device binding or runtime session UUID. Save for future licensing requests; not a license key.", "format": "uuid", "type": "string" }, "consumption": { "$ref": "#/components/schemas/Consumption" }, "heartbeat_seconds": { "anyOf": [ { "const": 0 }, { "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "Current heartbeat interval in seconds; metering does not refresh the signature or timer.", "type": "integer" } }, "required": [ "activation_id", "consumption" ], "type": "object" }, "CustomerAssignment": { "additionalProperties": false, "properties": { "email": { "description": "Blank removes portal linkage", "type": "string" }, "name": { "description": "Human-readable name; see the length constraints.", "maxLength": 120, "type": "string" } }, "required": [ "email" ], "type": "object" }, "CustomerControlsInput": { "additionalProperties": false, "anyOf": [ { "required": [ "device_enabled" ] }, { "required": [ "api_enabled" ] } ], "properties": { "api_enabled": { "type": "boolean" }, "device_enabled": { "type": "boolean" } }, "required": [], "type": "object" }, "CustomerControlsResult": { "additionalProperties": false, "properties": { "api_enabled": { "type": "boolean" }, "device_enabled": { "type": "boolean" } }, "required": [ "device_enabled", "api_enabled" ], "type": "object" }, "CustomerDataExportInput": { "additionalProperties": false, "properties": { "current_password": { "type": "string" }, "reason": { "maxLength": 500, "type": "string" }, "scope": { "enum": [ "account", "workspace" ], "type": "string" } }, "required": [ "scope", "current_password", "reason" ], "type": "object" }, "CustomerLicenses": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "items": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } }, "required": [ "email", "items" ], "type": "object" }, "CustomerOverageConsent": { "additionalProperties": false, "properties": { "overage_accepted": { "description": "Separate explicit authorisation of displayed chargeable overage.", "type": "boolean" }, "policy_version": { "description": "Currently published immutable policy version. Required for consent-protected actions after the operator publishes a policy, in either payment environment.", "type": "string" }, "price_version": { "type": "string" }, "terms_accepted": { "description": "Explicit unchecked-by-default acceptance.", "type": "boolean" } }, "required": [ "price_version", "policy_version", "terms_accepted", "overage_accepted" ], "type": "object" }, "CustomerRefundInput": { "additionalProperties": false, "properties": { "amount": { "type": "string" }, "change_id": { "type": "string" }, "confirm_termination": { "type": "boolean" }, "incident_id": { "type": "string" }, "message": { "type": "string" }, "order_id": { "type": "string" }, "purchase_id": { "type": "string" }, "quote_hash": { "type": "string" }, "quoted_at": { "format": "date-time", "type": "string" }, "reason": { "enum": [ "customer_request", "future", "wallet", "usage_change", "platform_failure", "statutory", "billing_error", "failed_delivery" ], "type": "string" }, "request_id": { "type": "string" }, "scope": { "description": "Explicit scope uses approval-time cancellation; omission permits eligible immediate cancellation after explicit confirmation.", "enum": [ "purchase", "service" ], "type": "string" } }, "required": [ "reason", "message", "request_id" ], "type": "object" }, "CustomerRefundQuote": { "anyOf": [ { "$ref": "#/components/schemas/RefundQuote" }, { "$ref": "#/components/schemas/ScopedRefundPreview" } ] }, "CustomerRefundQuoteInput": { "additionalProperties": false, "properties": { "amount": { "type": "string" }, "change_id": { "type": "string" }, "confirm_termination": { "type": "boolean" }, "incident_id": { "type": "string" }, "message": { "type": "string" }, "order_id": { "type": "string" }, "purchase_id": { "type": "string" }, "quote_hash": { "type": "string" }, "quoted_at": { "format": "date-time", "type": "string" }, "reason": { "enum": [ "customer_request", "future", "wallet", "usage_change", "platform_failure", "statutory", "billing_error", "failed_delivery" ], "type": "string" }, "request_id": { "type": "string" }, "scope": { "description": "Explicit scope uses approval-time cancellation; omission permits eligible immediate cancellation after explicit confirmation.", "enum": [ "purchase", "service" ], "type": "string" } }, "required": [ "reason", "message" ], "type": "object" }, "CustomerReleaseInput": { "additionalProperties": false, "description": "Confirm release before submitting. send_email optionally queues the temporary code to the verified customer address; generation guards a stale device view.", "properties": { "generation": { "minimum": 1, "type": "integer" }, "send_email": { "type": "boolean" } }, "required": [], "type": "object" }, "CustomerReleaseResult": { "additionalProperties": false, "properties": { "email_queued": { "type": "boolean" }, "id": { "format": "uuid", "type": "string" }, "status": { "const": "released", "type": "string" }, "transfer": { "anyOf": [ { "$ref": "#/components/schemas/TransferCode" }, { "type": "null" } ] } }, "required": [ "id", "status", "transfer", "email_queued" ], "type": "object" }, "CustomerSession": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" } }, "required": [], "type": "object" }, "DatabaseStatus": { "additionalProperties": false, "properties": { "connected": { "type": "boolean" }, "database": { "type": "string" }, "host": { "type": "string" }, "open_connections": { "type": "integer" }, "version": { "type": "string" } }, "required": [ "connected", "host", "database" ], "type": "object" }, "DefaultPlan": { "additionalProperties": false, "properties": { "allow_customer_api_overage": { "default": false, "description": "Allows customer API overage choices only. Independent of the device permission. When false, API usage follows administrator rules. Unlimited API remains unlimited.", "type": "boolean" }, "allow_customer_device_overage": { "default": false, "description": "Allows customer device overage choices only. When false, device usage follows administrator rules and saved customer device choices are ignored until re-enabled.", "type": "boolean" }, "default_currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "default_plan": { "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" } }, "required": [ "default_plan", "default_currency" ], "type": "object" }, "DeliveryList": { "additionalProperties": false, "properties": { "items": { "anyOf": [ { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "type": "array" }, { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "type": "null" } ], "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type." }, "limit": { "description": "Page size, default 25, range 1–100.", "type": "integer" }, "offset": { "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "type": "integer" }, "total": { "description": "Total matching records, not the current page length.", "type": "integer" } }, "required": [], "type": "object" }, "DeviceProfile": { "additionalProperties": false, "properties": { "hardware_id": { "description": "SHA-256 of product and hardware identity. Empty if unavailable; policies requiring hardware will reject it.", "type": "string" }, "platform": { "description": "Local OS: windows, linux or darwin (macOS).", "enum": [ "windows", "linux", "darwin" ], "type": "string" }, "system_id": { "description": "SHA-256 of product and system identity: 64 lowercase hex characters.", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "version": { "const": 3, "description": "Device fingerprint protocol version, currently 3.", "type": "integer" }, "virtual_machine": { "description": "Boolean: whether the SDK detects a virtual machine.", "type": "boolean" } }, "required": [ "version", "system_id", "hardware_id", "virtual_machine", "platform" ], "type": "object" }, "DeviceReleaseOperation": { "additionalProperties": false, "properties": { "activation_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "attempts": { "description": "Number of failed processing attempts retained by Licentivo.", "type": "integer" }, "available_at": { "description": "Record creation time in UTC.", "format": "date-time", "type": "string" }, "completed_at": { "anyOf": [ { "description": "Record creation time in UTC.", "format": "date-time", "type": "string" }, { "description": "Time the operation completed; omitted while pending.", "type": "null" } ], "description": "Time the operation completed; omitted while pending." }, "connection_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "created_at": { "description": "Record creation time in UTC.", "format": "date-time", "type": "string" }, "error_code": { "description": "Stable processing or review reason; empty after success.", "type": "string" }, "expected_generation": { "description": "Expected device binding generation, compared inside the revocation transaction.", "minimum": 1, "type": "integer" }, "license_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "operation_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "source": { "description": "Origin of this revocation operation.", "enum": [ "logout", "launch", "admin" ], "type": "string" }, "status": { "description": "Current server-owned lifecycle or processing status.", "enum": [ "pending", "succeeded", "stale", "manual_review" ], "type": "string" } }, "required": [ "operation_id", "license_id", "activation_id", "expected_generation", "source", "status" ], "type": "object" }, "EligibleReleases": { "additionalProperties": false, "properties": { "authorization": { "additionalProperties": true, "type": "object" }, "items": { "items": { "$ref": "#/components/schemas/Release" }, "type": "array" } }, "required": [], "type": "object" }, "Email": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" } }, "required": [ "email" ], "type": "object" }, "EmailChangeConfirmation": { "additionalProperties": false, "properties": { "token": { "maxLength": 2048, "minLength": 32, "type": "string" } }, "required": [ "token" ], "type": "object" }, "Empty": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" }, "EmptyRefundPreviewInput": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" }, "Error": { "additionalProperties": false, "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "properties": { "error": { "additionalProperties": false, "description": "Error object or delivery failure category; see child fields or the current type.", "properties": { "code": { "description": "Stable machine-readable error code.", "type": "string" }, "message": { "description": "Human-readable error message; branch on code instead.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "request_id": { "description": "Server-generated HTTP request UUID for log lookup; not a license ID or idempotency ID.", "format": "uuid", "type": "string" } }, "required": [ "error", "request_id" ], "type": "object" }, "FeatureReservation": { "additionalProperties": false, "properties": { "consumption": { "$ref": "#/components/schemas/Consumption", "description": "Usage receipt: units deducted, cumulative usage, remaining allowance and next reset." }, "expires_at": { "description": "Reservation deadline in UTC; commit before this time.", "format": "date-time", "type": "string" }, "operation_id": { "description": "Original job ID used for the reservation; retain it for retries.", "type": "string" }, "reservation_id": { "description": "Reservation ID; send this value to commit or cancel.", "format": "uuid", "type": "string" }, "status": { "description": "pending: perform the operation; committed: charged; canceled and expired: closed without charge.", "enum": [ "pending", "committed", "canceled", "expired" ], "type": "string" } }, "required": [ "reservation_id", "operation_id", "status", "expires_at", "consumption" ], "type": "object" }, "FeatureUsage": { "additionalProperties": false, "properties": { "feature": { "description": "Metered feature identifier, which must exist in policy features.", "type": "string" }, "license_id": { "description": "License UUID, distinct from the lv_lic_ secret.", "format": "uuid", "type": "string" }, "period": { "description": "Default UTC monthly billing snapshot; meter rules use month/day/lifetime and usage rows use the concrete period key.", "type": "string" }, "quantity": { "description": "Cumulative quantity used for this feature and period.", "type": "integer" }, "updated_at": { "description": "Last update timestamp in UTC.", "format": "date-time", "type": "string" } }, "required": [ "license_id", "feature", "period", "quantity", "updated_at" ], "type": "object" }, "ForumAuthor": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "ForumImage": { "additionalProperties": false, "properties": { "height": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "size": { "type": "integer" }, "url": { "type": "string" }, "width": { "type": "integer" } }, "required": [ "id", "url", "width", "height", "size" ], "type": "object" }, "ForumModerationInput": { "additionalProperties": false, "description": "Platform admin browser session required. Supply at least one field; omitted fields keep their current values. Pinning applies to published or hidden topics and does not restore deleted content.", "minProperties": 1, "properties": { "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "pinned": { "type": "boolean" } }, "required": [], "type": "object" }, "ForumReply": { "additionalProperties": false, "properties": { "author": { "$ref": "#/components/schemas/ForumAuthor" }, "body": { "type": "string" }, "can_delete": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "images": { "items": { "$ref": "#/components/schemas/ForumImage" }, "type": "array" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "body", "author", "images", "created_at", "updated_at", "can_edit", "can_delete" ], "type": "object" }, "ForumReplyInput": { "additionalProperties": false, "properties": { "body": { "maxLength": 12000, "minLength": 1, "type": "string" }, "image_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 6, "type": "array", "uniqueItems": true } }, "required": [ "body" ], "type": "object" }, "ForumTopic": { "additionalProperties": false, "properties": { "author": { "$ref": "#/components/schemas/ForumAuthor" }, "body": { "type": "string" }, "can_delete": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_moderate": { "type": "boolean" }, "category": { "enum": [ "integration", "help", "ideas", "showcase" ], "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "images": { "items": { "$ref": "#/components/schemas/ForumImage" }, "type": "array" }, "language": { "enum": [ "en", "zh", "zh-hant", "hi", "es", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" }, "last_reply_at": { "format": "date-time", "type": "string" }, "locked": { "type": "boolean" }, "pinned": { "type": "boolean" }, "reply_count": { "type": "integer" }, "title": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "title", "body", "category", "language", "locked", "pinned", "author", "images", "reply_count", "created_at", "updated_at", "last_reply_at", "can_edit", "can_delete", "can_moderate" ], "type": "object" }, "ForumTopicDetail": { "additionalProperties": false, "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "replies": { "items": { "$ref": "#/components/schemas/ForumReply" }, "type": "array" }, "topic": { "$ref": "#/components/schemas/ForumTopic" }, "total": { "type": "integer" } }, "required": [ "topic", "replies", "total", "limit", "offset" ], "type": "object" }, "ForumTopicInput": { "additionalProperties": false, "properties": { "body": { "maxLength": 12000, "minLength": 1, "type": "string" }, "category": { "enum": [ "integration", "help", "ideas", "showcase" ], "type": "string" }, "image_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 6, "type": "array", "uniqueItems": true }, "language": { "enum": [ "en", "zh", "zh-hant", "hi", "es", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" }, "title": { "maxLength": 180, "minLength": 2, "type": "string" } }, "required": [ "title", "body", "category", "language" ], "type": "object" }, "ForumTopicList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/ForumTopic" }, "type": "array" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "ForumTranslationInput": { "additionalProperties": false, "properties": { "reply_id": { "format": "uuid", "type": "string" }, "target_language": { "description": "Select a language returned by GET /forum/translation.", "type": "string" } }, "required": [ "target_language" ], "type": "object" }, "ForumTranslationResult": { "additionalProperties": false, "properties": { "body": { "description": "Translated plain text. Render with textContent, never as HTML.", "type": "string" }, "cached": { "type": "boolean" }, "provider": { "type": "string" }, "source_language": { "description": "Detected source language reported by DeepL.", "type": "string" }, "target_language": { "description": "Chosen provider target language.", "type": "string" }, "title": { "description": "Translated topic title; empty for replies.", "type": "string" } }, "required": [ "title", "body", "source_language", "target_language", "cached", "provider" ], "type": "object" }, "Health": { "additionalProperties": false, "properties": { "status": { "enum": [ "ok", "ready" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "ID": { "additionalProperties": false, "properties": { "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "Invite": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" }, "role": { "enum": [ "owner", "read_only" ], "type": "string" } }, "required": [ "email", "name", "role" ], "type": "object" }, "Invited": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "message": { "type": "string" } }, "required": [ "id", "message" ], "type": "object" }, "Invoice": { "additionalProperties": false, "properties": { "active_devices": { "description": "Device count frozen for billing from the default-period occupancy peak. This is neither current occupancy nor a cumulative device-use list.", "type": "integer" }, "base_covered": { "description": "Whether a purchased package already covers the base charge.", "type": "boolean" }, "base_micros": { "description": "Base charge in millionths of the currency unit.", "type": "integer" }, "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "currency": { "description": "Three-letter uppercase currency code, such as USD.", "pattern": "^[A-Z]{3}$", "type": "string" }, "finalized_at": { "anyOf": [ { "description": "Invoice finalization timestamp, or null.", "format": "date-time", "type": "string" }, { "description": "Invoice finalization timestamp, or null.", "type": "null" } ], "description": "Invoice finalization timestamp, or null." }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "included_devices": { "description": "Included active-device allowance.", "type": "integer" }, "month": { "description": "UTC month YYYY-MM; omitted query values use the current month. Billing jobs require a closed month.", "type": "string" }, "overage_devices": { "description": "Devices exceeding the included allowance.", "type": "integer" }, "paid_at": { "anyOf": [ { "description": "Invoice payment timestamp, or null.", "format": "date-time", "type": "string" }, { "description": "Invoice payment timestamp, or null.", "type": "null" } ], "description": "Invoice payment timestamp, or null." }, "payment_mode": { "description": "Payment environment, sandbox or live.", "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "description": "Stable billing plan identifier from the published catalog.", "type": "string" }, "plan_name": { "description": "Display name of the plan.", "type": "string" }, "price_version": { "description": "Frozen pricing revision; stale input may cause PLAN_VERSION_CONFLICT.", "type": "string" }, "refunded_at": { "anyOf": [ { "description": "Invoice refund timestamp, or null.", "format": "date-time", "type": "string" }, { "description": "Invoice refund timestamp, or null.", "type": "null" } ], "description": "Invoice refund timestamp, or null." }, "status": { "description": "Current resource state; see the enum and operation notes.", "enum": [ "draft", "finalized", "void" ], "type": "string" }, "total_cents": { "description": "Invoice total in hundredths; see paid_at for payment status.", "type": "integer" }, "total_micros": { "description": "Invoice total in millionths of the currency unit.", "type": "integer" }, "unit_micros": { "description": "Price per excess active device in millionths.", "type": "integer" }, "voided_at": { "anyOf": [ { "description": "Invoice void timestamp, or null.", "format": "date-time", "type": "string" }, { "description": "Invoice void timestamp, or null.", "type": "null" } ], "description": "Invoice void timestamp, or null." } }, "required": [ "id", "month", "currency", "status", "total_cents" ], "type": "object" }, "InvoiceList": { "additionalProperties": false, "properties": { "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/Invoice" }, "type": "array" }, "limit": { "description": "Page size, default 25, range 1–100.", "type": "integer" }, "offset": { "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "type": "integer" }, "total": { "description": "Total matching records, not the current page length.", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "Key": { "additionalProperties": false, "properties": { "allow_http": { "description": "Allow this key to register or update HTTP Launch site origins, including test-server domains, private IP addresses and internal hostnames. Licentivo API requests still use HTTPS.", "type": "boolean" }, "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "expires_at": { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "format": "date-time", "type": "string" }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "name": { "description": "Human-readable name; see the length constraints.", "type": "string" }, "prefix": { "description": "First 14 characters of the management key; identification only.", "type": "string" }, "revoked": { "description": "Whether revoked; also check expires_at for expiry.", "type": "boolean" }, "scope": { "description": "read allows reads; write allows reads and writes. Writes also require an active Owner creator.", "enum": [ "read", "write" ], "type": "string" } }, "required": [ "id", "prefix", "scope", "revoked", "allow_http" ], "type": "object" }, "KeyBundle": { "additionalProperties": false, "properties": { "keys": { "items": { "$ref": "#/components/schemas/SigningKey" }, "type": "array" }, "product_id": { "format": "uuid", "type": "string" }, "protocol": { "type": "string" }, "runtime_policy_source": { "const": "current_license_policy", "type": "string" } }, "required": [ "product_id", "keys" ], "type": "object" }, "KeyCreate": { "additionalProperties": false, "properties": { "allow_http": { "default": false, "description": "Allow this key to register or update HTTP Launch site origins, including test-server domains, private IP addresses and internal hostnames. Licentivo API requests still use HTTPS.", "type": "boolean" }, "expires_days": { "description": "Days from creation until expiry, 1–365.", "maximum": 365, "minimum": 1, "type": "integer" }, "name": { "description": "Human-readable name; see the length constraints.", "maxLength": 120, "minLength": 1, "type": "string" }, "scope": { "description": "read allows reads; write allows reads and writes. Writes also require an active Owner creator.", "enum": [ "read", "write" ], "type": "string" } }, "required": [ "name", "scope", "expires_days" ], "type": "object" }, "KeyList": { "additionalProperties": false, "properties": { "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/Key" }, "type": "array" }, "limit": { "description": "Page size, default 25, range 1–100.", "type": "integer" }, "offset": { "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "type": "integer" }, "total": { "description": "Total matching records, not the current page length.", "type": "integer" } }, "required": [ "items" ], "type": "object" }, "KeyRotated": { "additionalProperties": false, "example": { "id": "33333333-3333-4333-8333-333333333333", "key": "lv_api_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", "prefix": "lv_api_BBBBBBB" }, "properties": { "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "key": { "description": "Full secret returned on creation or rotation. Owners may also view saved license keys on demand in a browser session. Store privately; the prefix cannot authenticate.", "type": "string" }, "prefix": { "description": "First 14 characters of the management key; identification only.", "type": "string" } }, "required": [ "id", "key", "prefix" ], "type": "object" }, "KeySecret": { "additionalProperties": false, "example": { "expires_at": "2027-01-16T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "key": "lv_api_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "prefix": "lv_api_AAAAAAA" }, "properties": { "allow_http": { "description": "Allow this key to register or update HTTP Launch site origins, including test-server domains, private IP addresses and internal hostnames. Licentivo API requests still use HTTPS.", "type": "boolean" }, "expires_at": { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "format": "date-time", "type": "string" }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "key": { "description": "Shown only at creation/rotation", "type": "string" }, "prefix": { "description": "First 14 characters of the management key; identification only.", "type": "string" } }, "required": [ "id", "key", "prefix" ], "type": "object" }, "KeyUpdate": { "additionalProperties": false, "properties": { "allow_http": { "description": "Allow this key to register or update HTTP Launch site origins, including test-server domains, private IP addresses and internal hostnames. Licentivo API requests still use HTTPS.", "type": "boolean" } }, "required": [ "allow_http" ], "type": "object" }, "KeyUpdated": { "additionalProperties": false, "properties": { "allow_http": { "description": "Allow this key to register or update HTTP Launch site origins, including test-server domains, private IP addresses and internal hostnames. Licentivo API requests still use HTTPS.", "type": "boolean" }, "id": { "description": "Unique record identifier.", "format": "uuid", "type": "string" } }, "required": [ "id", "allow_http" ], "type": "object" }, "LaunchCommerceEvent": { "additionalProperties": false, "properties": { "account_ref": { "description": "Case-sensitive immutable purchase entitlement reference.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "entitlement_ref": { "description": "Case-sensitive immutable purchase entitlement reference.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "environment": { "description": "Commerce environment, pinned in both the connection and signed grant.", "enum": [ "live", "sandbox" ], "type": "string" }, "event_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "launch_product_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "legacy_license_id": { "description": "Only for entitlement.migrated. The existing license, expiry, capabilities and device records are preserved; old keys and device credentials lose runtime access.", "format": "uuid", "type": "string" }, "plan_ref": { "description": "Case-sensitive immutable purchase entitlement reference.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "type": { "description": "Versioned full-snapshot commerce event kind.", "enum": [ "entitlement.created", "entitlement.renewed", "entitlement.upgraded", "entitlement.downgraded", "entitlement.refunded", "entitlement.suspended", "entitlement.expired", "entitlement.resumed", "entitlement.migrated" ], "type": "string" }, "valid_from": { "description": "Record creation time in UTC.", "format": "date-time", "type": "string" }, "valid_until": { "anyOf": [ { "description": "Record creation time in UTC.", "format": "date-time", "type": "string" }, { "description": "Absolute purchase expiry, UTC; null only for a perpetual policy.", "type": "null" } ], "description": "Absolute purchase expiry, UTC; null only for a perpetual policy." }, "version": { "description": "Monotonic full-snapshot version for this entitlement reference, not a delivery attempt number.", "minimum": 1, "type": "integer" } }, "required": [ "event_id", "environment", "type", "entitlement_ref", "account_ref", "launch_product_id", "plan_ref", "version", "valid_from" ], "type": "object" }, "LaunchConnection": { "additionalProperties": false, "properties": { "audience": { "description": "Exact intended recipient of Launch login assertions.", "type": "string" }, "created_at": { "description": "Record creation time in UTC.", "format": "date-time", "type": "string" }, "enabled": { "description": "Whether this trust connection may authorize new runtime use.", "type": "boolean" }, "environment": { "description": "Commerce environment, pinned in both the connection and signed grant.", "enum": [ "live", "sandbox" ], "type": "string" }, "heartbeat_seconds": { "description": "Server-selected online verification interval in seconds.", "type": "integer" }, "id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "issuer": { "description": "Exact trusted Launch origin.", "type": "string" }, "offline_seconds": { "description": "Finite permitted offline interval in seconds; zero requires online verification.", "type": "integer" }, "session_seconds": { "description": "Maximum authorization session lifetime in seconds.", "type": "integer" }, "updated_at": { "description": "Record creation time in UTC.", "format": "date-time", "type": "string" } }, "required": [ "id", "issuer", "audience", "environment", "enabled" ], "type": "object" }, "LaunchConnectionInput": { "additionalProperties": false, "properties": { "audience": { "description": "Exact intended recipient of Launch login assertions.", "maxLength": 255, "minLength": 1, "type": "string" }, "enabled": { "description": "Whether this trust connection may authorize new runtime use.", "type": "boolean" }, "environment": { "description": "Commerce environment, pinned in both the connection and signed grant.", "enum": [ "live", "sandbox" ], "type": "string" }, "heartbeat_seconds": { "default": 600, "description": "Server-selected online verification interval in seconds.", "maximum": 86400, "minimum": 600, "type": "integer" }, "issuer": { "description": "Exact trusted Launch origin without a path or trailing slash. HTTPS is the default. HTTP requires allow_http on the API key making this request; private IPs and internal hostnames are supported. No callback or discovery request is made to this origin.", "format": "uri", "type": "string" }, "offline_seconds": { "default": 0, "description": "0 requires online verification. A positive horizon must be at least 3 × heartbeat_seconds. Permanent offline account grants are disabled.", "maximum": 86400, "minimum": 0, "type": "integer" }, "public_keys": { "additionalProperties": { "description": "Pinned canonical Base64URL Ed25519 public key, 32 bytes.", "type": "string" }, "description": "Complete pinned set of Launch Ed25519 public keys indexed by key ID.", "maxProperties": 16, "minProperties": 1, "type": "object" }, "session_seconds": { "default": 86400, "description": "At least 3 × heartbeat_seconds.", "maximum": 2592000, "minimum": 1800, "type": "integer" } }, "required": [ "issuer", "audience", "environment", "public_keys", "enabled" ], "type": "object" }, "LaunchDeviceReleaseInput": { "additionalProperties": false, "properties": { "account_ref": { "description": "Case-sensitive immutable purchase entitlement reference.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "entitlement_ref": { "description": "Case-sensitive immutable purchase entitlement reference.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "environment": { "description": "Commerce environment, pinned in both the connection and signed grant.", "enum": [ "live", "sandbox" ], "type": "string" }, "expected_generation": { "description": "Expected device binding generation, compared inside the revocation transaction.", "minimum": 1, "type": "integer" }, "operation_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" } }, "required": [ "operation_id", "account_ref", "entitlement_ref", "environment", "expected_generation" ], "type": "object" }, "LaunchEvent": { "additionalProperties": false, "properties": { "applied_at": { "anyOf": [ { "description": "Record creation time in UTC.", "format": "date-time", "type": "string" }, { "description": "Time the snapshot was applied or classified as stale.", "type": "null" } ], "description": "Time the snapshot was applied or classified as stale." }, "attempts": { "description": "Number of failed processing attempts retained by Licentivo.", "type": "integer" }, "available_at": { "description": "Record creation time in UTC.", "format": "date-time", "type": "string" }, "connection_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "created_at": { "description": "Record creation time in UTC.", "format": "date-time", "type": "string" }, "error_code": { "description": "Stable processing or review reason; empty after success.", "type": "string" }, "event_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "status": { "description": "Current server-owned lifecycle or processing status.", "enum": [ "pending", "applied", "stale", "manual_review" ], "type": "string" } }, "required": [ "connection_id", "event_id", "status", "attempts", "available_at" ], "type": "object" }, "LaunchExchangeInput": { "additionalProperties": false, "properties": { "activation_id": { "description": "data.activation_id from the last successful activation. Required for validation, heartbeat, consume and deactivation; omit only on first activate.", "format": "uuid", "type": "string" }, "app_version": { "description": "Current app version, major.minor.patch, e.g. 1.0.0. Required for maintenance or version-range rules. Do not misreport a newer app as an older version.", "pattern": "^$|^(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})$", "type": "string" }, "device_id": { "description": "64-character lowercase hex SHA-256 calculated by the SDK from the product, system and hardware identity. Do not substitute a fixed value.", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "device_name": { "description": "Display name in the dashboard, up to 120 characters. It does not determine device identity.", "maxLength": 120, "type": "string" }, "device_profile": { "$ref": "#/components/schemas/DeviceProfile", "description": "SDK-generated machine profile. Supply as required by policies for hardware identity, VM rejection or hardware migration." }, "environment": { "description": "Commerce environment, pinned in both the connection and signed grant.", "enum": [ "live", "sandbox" ], "type": "string" }, "feature": { "description": "Feature identifier consumed.", "maxLength": 64, "type": "string" }, "identity_token": { "description": "One-use, typed Ed25519 Launch identity JWT; no entitlement claims are trusted as purchase rights.", "maxLength": 12288, "type": "string", "writeOnly": true }, "launch_connection_id": { "description": "launch connection id for this Launch authorization operation.", "format": "uuid", "type": "string" }, "license_key": { "const": "", "description": "Omit or leave empty. Account exchange never uses a long-term license key.", "type": "string" }, "product_id": { "description": "Product UUID; must match the license's product.", "format": "uuid", "type": "string" }, "quantity": { "description": "Units requested for this operation, integer 1–1000000000.", "maximum": 1000000000, "minimum": 1, "type": "integer" }, "request_logout_ticket": { "description": "SDK capability negotiation. Request an unlink-only logout ticket when no ticket is retained for the current binding. Omit it when a valid logout ticket is already retained; steady-state heartbeats avoid an extra ticket lookup.", "type": "boolean" }, "reservation_id": { "description": "Reservation ID; send this value to commit or cancel.", "format": "uuid", "type": "string" }, "reservation_seconds": { "default": 900, "description": "Optional reservation lifetime, 30–3600 seconds; default 900. It ends earlier at the period reset.", "maximum": 3600, "minimum": 30, "type": "integer" }, "session_id": { "description": "Required for floating licenses: generate a UUID per running instance and reuse it for that instance's requests. Optional for device-bound licenses.", "format": "uuid", "type": "string" } }, "required": [ "product_id", "device_id", "identity_token", "launch_connection_id", "environment" ], "type": "object" }, "LaunchPlanMappingInput": { "additionalProperties": false, "properties": { "launch_product_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "policy_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "policy_version": { "description": "Expected current version of the mapped authorization policy.", "minimum": 1, "type": "integer" }, "product_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" } }, "required": [ "launch_product_id", "product_id", "policy_id", "policy_version" ], "type": "object" }, "LaunchSessionRevocation": { "additionalProperties": false, "properties": { "account_ref": { "description": "Case-sensitive immutable purchase entitlement reference.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "completed_at": { "description": "Record creation time in UTC.", "format": "date-time", "type": "string" }, "connection_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "created_at": { "description": "Record creation time in UTC.", "format": "date-time", "type": "string" }, "environment": { "description": "Commerce environment, pinned in both the connection and signed grant.", "enum": [ "live", "sandbox" ], "type": "string" }, "event_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "reason": { "description": "Optional audit reason; empty is equivalent to omission. forced_logout requires session scope; password_changed and account_disabled require account scope.", "enum": [ "", "forced_logout", "password_changed", "account_disabled" ], "type": "string" }, "released_devices": { "description": "Current device binding generations released; newer logins are preserved.", "minimum": 0, "type": "integer" }, "revoked_before": { "description": "Present for account scope. New authentication must have auth_time strictly greater than this UTC cutoff, compared at Unix-second precision. Previously known sid values remain permanently revoked.", "format": "date-time", "type": "string" }, "revoked_credentials": { "description": "Device credentials newly revoked by the original event.", "minimum": 0, "type": "integer" }, "revoked_sessions": { "description": "Authorization sessions newly revoked by the original event.", "minimum": 0, "type": "integer" }, "scope": { "description": "session revokes one Launch sid across every product and device in this connection; account revokes every existing account session and rejects old authentication assertions.", "enum": [ "session", "account" ], "type": "string" }, "sid": { "description": "Required and nonempty for session scope; omit or leave empty for account scope. This is the Launch login sid, not a Licentivo authorization session or device ID.", "pattern": "^[A-Za-z0-9_-]{0,128}$", "type": "string" }, "status": { "const": "succeeded", "description": "Current server-owned lifecycle or processing status.", "type": "string" } }, "required": [ "connection_id", "event_id", "environment", "account_ref", "scope", "status", "revoked_sessions", "revoked_credentials", "released_devices", "created_at", "completed_at" ], "type": "object" }, "LaunchSessionRevocationInput": { "additionalProperties": false, "oneOf": [ { "properties": { "reason": { "enum": [ "", "forced_logout" ] }, "scope": { "const": "session" }, "sid": { "description": "Case-sensitive immutable purchase entitlement reference.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "sid" ] }, { "properties": { "reason": { "enum": [ "", "password_changed", "account_disabled" ] }, "scope": { "const": "account" }, "sid": { "const": "" } } } ], "properties": { "account_ref": { "description": "Case-sensitive immutable purchase entitlement reference.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "environment": { "description": "Optional consistency check. Omit or leave empty to use the connection environment; a nonempty value must match. This field does not change billing or provide free authorization testing.", "enum": [ "", "live", "sandbox" ], "type": "string" }, "event_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "reason": { "description": "Optional audit reason; empty is equivalent to omission. forced_logout requires session scope; password_changed and account_disabled require account scope.", "enum": [ "", "forced_logout", "password_changed", "account_disabled" ], "type": "string" }, "scope": { "description": "session revokes one Launch sid across every product and device in this connection; account revokes every existing account session and rejects old authentication assertions.", "enum": [ "session", "account" ], "type": "string" }, "sid": { "description": "Required and nonempty for session scope; omit or leave empty for account scope. This is the Launch login sid, not a Licentivo authorization session or device ID.", "pattern": "^[A-Za-z0-9_-]{0,128}$", "type": "string" } }, "required": [ "event_id", "account_ref", "scope" ], "type": "object" }, "Lease": { "additionalProperties": false, "properties": { "key_id": { "description": "Signing public-key UUID; must exist in the product's trusted_keys.", "format": "uuid", "type": "string" }, "payload": { "description": "Unpadded Base64URL of the original license JSON bytes. Decoding is only for reading; signature verification is required.", "type": "string" }, "signature": { "description": "Base64URL Ed25519 signature. Verify the text LicenovaLease/v1, one newline and the original decoded payload JSON bytes. Do not reserialize JSON. The decoded signature is 64 bytes.", "type": "string" }, "version": { "const": 1, "description": "Signature envelope protocol version, currently 1.", "type": "integer" } }, "required": [ "version", "key_id", "payload", "signature" ], "type": "object" }, "LeaseClaims": { "additionalProperties": false, "description": "Decode the original signed payload bytes. Without runtime_policy the TTL is capped at 86400 seconds; otherwise enforce the signed policy. Never trust payload without signature/context verification.", "properties": { "activation_id": { "format": "uuid", "type": "string" }, "capabilities": { "$ref": "#/components/schemas/SignedCapabilities" }, "device_id": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "expires_at": { "maximum": 253402300799, "type": "integer" }, "features": { "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "issued_at": { "type": "integer" }, "key_id": { "format": "uuid", "type": "string" }, "license_id": { "format": "uuid", "type": "string" }, "max_devices": { "maximum": 10000, "minimum": 1, "type": "integer" }, "mode": { "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "offline_request_id": { "format": "uuid", "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "runtime_policy": { "$ref": "#/components/schemas/RuntimePolicy" }, "tenant_id": { "format": "uuid", "type": "string" }, "version": { "const": 1, "type": "integer" } }, "required": [], "type": "object" }, "LegalAcceptance": { "additionalProperties": false, "properties": { "accepted_at": { "format": "date-time", "type": "string" }, "api_overage_accepted": { "type": "boolean" }, "device_overage_accepted": { "type": "boolean" }, "digest": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mode": { "type": "string" }, "overage_accepted": { "type": "boolean" }, "price_version": { "type": "string" }, "reference": { "type": "string" }, "scope": { "type": "string" }, "version": { "type": "string" } }, "required": [], "type": "object" }, "LegalAcceptanceList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/LegalAcceptance" }, "type": "array" }, "now": { "format": "date-time", "type": "string" }, "total": { "type": "integer" } }, "required": [], "type": "object" }, "LegalConsent": { "additionalProperties": false, "properties": { "overage_accepted": { "description": "Separate explicit authorisation of displayed chargeable overage.", "type": "boolean" }, "policy_version": { "description": "Currently published immutable policy version. Required for consent-protected actions after the operator publishes a policy, in either payment environment.", "type": "string" }, "terms_accepted": { "description": "Explicit unchecked-by-default acceptance.", "type": "boolean" } }, "required": [], "type": "object" }, "License": { "additionalProperties": false, "description": "Expiry is null until first successful activation. Duration is snapshotted at issuance; reactivation never resets it.", "example": { "created_at": "2026-10-18T00:00:00Z", "customer": "Order #1001", "duration_days": 30, "expires_at": null, "features": [ "export" ], "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key_prefix": "lv_lic_AAAAAAA", "max_devices": 1, "mode": "timed", "policy_id": "22222222-2222-4222-8222-222222222222", "policy_version": 1, "product_id": "11111111-1111-4111-8111-111111111111", "status": "active", "updated_at": "2026-10-18T00:00:00Z" }, "properties": { "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "customer": { "description": "Vendor-defined customer label, distinct from the customer portal email.", "type": "string" }, "duration_days": { "description": "Per-license days from first activation. Required 1–36500 for timed/trial issuance; absent/null for perpetual. Never stored in the policy.", "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "format": "date-time", "type": "string" }, { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "type": "null" } ], "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry." }, "features": { "description": "Up to 32 distinct feature identifiers, each 1–64 ASCII letters, digits, dots, dashes or underscores.", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "first_activated_at": { "anyOf": [ { "description": "First successful activation timestamp; null before activation and unchanged by renewal or transfer.", "format": "date-time", "type": "string" }, { "description": "First successful activation timestamp; null before activation and unchanged by renewal or transfer.", "type": "null" } ], "description": "First successful activation timestamp; null before activation and unchanged by renewal or transfer." }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "key_prefix": { "description": "Short license-key prefix for identification/search, not authentication.", "type": "string" }, "max_devices": { "description": "Maximum concurrent devices or floating seats per license.", "type": "integer" }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "policy_id": { "description": "Policy UUID; must belong to the product at issuance.", "format": "uuid", "type": "string" }, "policy_version": { "description": "Policy revision; send the current value when editing full capabilities to prevent stale writes.", "type": "integer" }, "product_id": { "description": "Product UUID in the current workspace.", "format": "uuid", "type": "string" }, "status": { "description": "Current resource state; see the enum and operation notes.", "enum": [ "active", "expired", "suspended", "revoked" ], "type": "string" }, "updated_at": { "description": "Last update timestamp in UTC.", "format": "date-time", "type": "string" } }, "required": [ "id", "product_id", "key_prefix", "mode", "status" ], "type": "object" }, "LicenseCapabilities": { "additionalProperties": false, "example": { "license_id": "33333333-3333-4333-8333-333333333333", "license_model": "node_locked", "maintenance_days": 0, "maintenance_until": null, "max_version": "", "min_version": "", "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z" }, "properties": { "license_id": { "description": "License UUID, distinct from the lv_lic_ secret.", "format": "uuid", "type": "string" }, "license_model": { "description": "node_locked device binding or floating seats.", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_days": { "description": "Maintenance days from first activation; 0 means no maintenance cutoff.", "type": "integer" }, "maintenance_until": { "anyOf": [ { "description": "Maintenance cutoff for new releases; may be null before activation or when unlimited.", "format": "date-time", "type": "string" }, { "description": "Maintenance cutoff for new releases; may be null before activation or when unlimited.", "type": "null" } ], "description": "Maintenance cutoff for new releases; may be null before activation or when unlimited." }, "max_version": { "description": "Maximum permitted application version; empty means no upper bound.", "type": "string" }, "min_version": { "description": "Minimum permitted application version; empty means no lower bound.", "type": "string" }, "product_id": { "description": "Product UUID in the current workspace.", "format": "uuid", "type": "string" }, "updated_at": { "description": "Last update timestamp in UTC.", "format": "date-time", "type": "string" } }, "required": [ "license_id", "product_id", "license_model", "maintenance_days", "maintenance_until", "min_version", "max_version", "updated_at" ], "type": "object" }, "LicenseCapabilityResult": { "additionalProperties": false, "example": { "customer_email": "buyer@example.com", "license": { "license_id": "33333333-3333-4333-8333-333333333333", "license_model": "node_locked", "maintenance_days": 0, "maintenance_until": null, "max_version": "", "min_version": "", "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z" }, "meter_rules": [], "usage": null }, "properties": { "customer_email": { "description": "Linked customer portal email; empty when unassigned.", "type": "string" }, "license": { "$ref": "#/components/schemas/LicenseCapabilities", "description": "License capability snapshot." }, "meter_rules": { "description": "Feature metering rules; empty means none configured.", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "Whether excess feature usage is allowed.", "type": "boolean" }, "feature": { "description": "Metered feature identifier, which must exist in policy features.", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "Included feature uses per metering period (not a pagination limit).", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "Maximum permitted excess usage; disabled when allow_overage is false.", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "Default UTC monthly billing snapshot; meter rules use month/day/lifetime and usage rows use the concrete period key.", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "type": "array" }, "usage": { "anyOf": [ { "description": "Actual feature usage records; may be null when empty.", "items": { "$ref": "#/components/schemas/FeatureUsage" }, "type": "array" }, { "description": "Actual feature usage records; may be null when empty.", "type": "null" } ], "description": "Actual feature usage records; may be null when empty." } }, "required": [], "type": "object" }, "LicenseCreate": { "additionalProperties": false, "description": "Issue a license with its own duration_days. Timed/trial licenses require 1–36500 days; perpetual licenses require absent/null. The clock starts at first successful activation.", "properties": { "customer": { "description": "Customer name or order reference for dashboard search, up to 254 characters.", "maxLength": 254, "type": "string" }, "customer_email": { "description": "Linked customer portal email; empty when unassigned.", "format": "email", "maxLength": 254, "type": "string" }, "duration_days": { "description": "License duration in days, starting on the first successful activation. Required for timed/trial issuance; omit or null for perpetual licenses. Never inherited from the policy.", "maximum": 36500, "minimum": 1, "type": [ "integer", "null" ] }, "policy_id": { "description": "UUID of a license policy belonging to this product.", "format": "uuid", "type": "string" }, "product_id": { "description": "Product ID (UUID).", "format": "uuid", "type": "string" } }, "required": [ "product_id", "policy_id" ], "type": "object" }, "LicenseKeyReveal": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "key": { "description": "Original full license key, revealed only to a current Owner session.", "type": "string" }, "key_prefix": { "type": "string" } }, "required": [ "id", "key", "key_prefix" ], "type": "object" }, "LicenseList": { "additionalProperties": false, "properties": { "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/License" }, "type": "array" }, "limit": { "description": "Page size, default 25, range 1–100.", "type": "integer" }, "offset": { "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "type": "integer" }, "total": { "description": "Total matching records, not the current page length.", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "LicenseSecret": { "additionalProperties": false, "example": { "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "key_prefix": "lv_lic_AAAAAAA" }, "properties": { "duration_days": { "description": "Valid days from first activation; null for perpetual licenses.", "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "format": "date-time", "type": "string" }, { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "type": "null" } ], "description": "Final license expiration, UTC ISO 8601; null before first activation and for perpetual licenses." }, "first_activated_at": { "anyOf": [ { "description": "First successful activation timestamp; null before activation and unchanged by renewal or transfer.", "format": "date-time", "type": "string" }, { "description": "First successful activation timestamp; null before activation and unchanged by renewal or transfer.", "type": "null" } ], "description": "First successful activation, UTC ISO 8601; null before activation. Device transfer does not reset it." }, "id": { "description": "License record UUID for management queries, renewal or revocation. It is not an activation key.", "format": "uuid", "type": "string" }, "key": { "description": "Full license key beginning with lv_lic_. Shown once on issuance; the vendor must store it privately and give it to the customer.", "type": "string" }, "key_prefix": { "description": "Key prefix for dashboard identification; cannot activate a license.", "type": "string" } }, "required": [ "id", "key", "key_prefix" ], "type": "object" }, "LicenseUpdate": { "additionalProperties": false, "properties": { "customer": { "description": "Vendor-defined customer label, distinct from the customer portal email.", "maxLength": 254, "type": "string" }, "features": { "description": "Up to 32 distinct feature identifiers, each 1–64 ASCII letters, digits, dots, dashes or underscores.", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "max_devices": { "description": "Maximum concurrent devices or floating seats per license.", "maximum": 10000, "minimum": 1, "type": "integer" }, "policy_id": { "description": "Switch this license to a policy for the same product. Requires a current preview_token when the policy changes; preserves the license key, original term and usage.", "format": "uuid", "type": "string" }, "preview_token": { "description": "Token returned by POST /licenses/policy-preview for this license and target policy.", "type": "string" }, "status": { "description": "Current resource state; see the enum and operation notes.", "enum": [ "active", "suspended", "revoked" ], "type": "string" } }, "required": [], "type": "object" }, "LicensingWebhook": { "additionalProperties": false, "properties": { "created_at": { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "format": "date-time", "type": "string" }, "enabled": { "description": "Whether HTTP is allowed, for local development only.", "type": "boolean" }, "events": { "description": "Nonempty, distinct subscribed event types.", "items": { "enum": [ "license.created", "license.updated", "license.renewed", "license.revoked", "license.activate", "license.deactivate", "license.consume", "license.expiring", "license.expired", "license.maintenance_expiring", "license.maintenance_expired" ], "type": "string" }, "type": "array" }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "name": { "description": "Human-readable name; see the length constraints.", "type": "string" }, "updated_at": { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "format": "date-time", "type": "string" }, "url": { "description": "Event receiver URL; use public HTTPS in production.", "type": "string" } }, "required": [ "id", "name", "url", "events", "enabled", "created_at", "updated_at" ], "type": "object" }, "LicensingWebhookInput": { "additionalProperties": false, "properties": { "enabled": { "description": "Whether the webhook endpoint is enabled.", "type": "boolean" }, "events": { "description": "Nonempty, distinct subscribed event types.", "items": { "enum": [ "license.created", "license.updated", "license.renewed", "license.revoked", "license.activate", "license.deactivate", "license.consume", "license.expiring", "license.expired", "license.maintenance_expiring", "license.maintenance_expired" ], "type": "string" }, "type": "array" }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "name": { "description": "Human-readable name; see the length constraints.", "maxLength": 120, "type": "string" }, "secret": { "description": "Webhook verification secret, 32–200 characters when supplied; omitted on update preserves it. Empty output means not reissued.", "maxLength": 200, "minLength": 32, "type": "string", "writeOnly": true }, "url": { "description": "Event receiver URL; use public HTTPS in production.", "format": "uri", "maxLength": 2000, "type": "string" } }, "required": [ "name", "url", "events", "enabled" ], "type": "object" }, "LicensingWebhookList": { "additionalProperties": false, "properties": { "event_types": { "description": "All supported licensing event types.", "items": { "enum": [ "license.created", "license.updated", "license.renewed", "license.revoked", "license.activate", "license.deactivate", "license.consume", "license.expiring", "license.expired", "license.maintenance_expiring", "license.maintenance_expired" ], "type": "string" }, "type": "array" }, "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/LicensingWebhook" }, "type": "array" } }, "required": [], "type": "object" }, "LicensingWebhookSecret": { "additionalProperties": false, "properties": { "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "secret": { "description": "Returned once for new endpoints; empty when preserved", "type": "string" } }, "required": [], "type": "object" }, "LoggedOut": { "additionalProperties": false, "properties": { "logged_out": { "type": "boolean" } }, "required": [ "logged_out" ], "type": "object" }, "Login": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" }, "password": { "description": "12–128 UTF-8 bytes, not characters", "type": "string", "writeOnly": true } }, "required": [ "email", "password" ], "type": "object" }, "LogoutTicket": { "additionalProperties": false, "properties": { "activation_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "expected_generation": { "description": "Expected device binding generation, compared inside the revocation transaction.", "minimum": 1, "type": "integer" }, "operation_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "product_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "release_token": { "description": "Unlink-only capability. Cannot activate, validate, refresh or consume features. Retain only in the SDK logout journal while revocation is pending.", "pattern": "^lv_out_[A-Za-z0-9_-]{43}$", "type": "string" } }, "required": [ "operation_id", "product_id", "activation_id", "expected_generation", "release_token" ], "type": "object" }, "MailConnection": { "additionalProperties": false, "properties": { "check_status": { "enum": [ "verified", "limited" ], "type": "string" }, "delivery_mode": { "enum": [ "file", "smtp", "resend", "brevo", "postmark", "mailgun" ], "type": "string" }, "message": { "type": "string" }, "mode": { "enum": [ "file", "smtp", "resend", "brevo", "postmark", "mailgun" ], "type": "string" }, "ok": { "description": "False for a limited check: credentials and delivery have not been confirmed.", "type": "boolean" }, "status": { "enum": [ "connected" ], "type": "string" } }, "required": [ "status", "mode", "delivery_mode", "ok", "check_status" ], "type": "object" }, "MailInput": { "additionalProperties": false, "description": "Partial update of encrypted platform mail settings. Omitted fields and other provider configurations are preserved; blank API keys and SMTP passwords retain existing secrets. The selected active service must be fully configured. File mode is unavailable in production. Requires a platform-admin session and CSRF token; vendor management API keys cannot change platform mail settings.", "properties": { "from": { "type": "string" }, "host": { "maxLength": 253, "type": "string" }, "mode": { "enum": [ "file", "smtp", "resend", "brevo", "postmark", "mailgun" ], "type": "string" }, "password": { "description": "Omit or leave blank to preserve the existing SMTP password.", "maxLength": 1000, "type": "string", "writeOnly": true }, "port": { "maximum": 65535, "minimum": 1, "type": "integer" }, "providers": { "additionalProperties": false, "properties": { "brevo": { "$ref": "#/components/schemas/MailProviderInput" }, "mailgun": { "$ref": "#/components/schemas/MailgunInput" }, "postmark": { "$ref": "#/components/schemas/MailProviderInput" }, "resend": { "$ref": "#/components/schemas/MailProviderInput" } }, "required": [], "type": "object" }, "tls_mode": { "enum": [ "starttls", "implicit" ], "type": "string" }, "username": { "maxLength": 254, "type": "string" } }, "required": [], "type": "object" }, "MailJob": { "additionalProperties": false, "properties": { "attempts": { "type": "integer" }, "cancel_reason": { "enum": [ "", "platform_disabled", "customer_disabled", "coverage_changed", "reminder_window_changed", "renewal_state_changed", "purchase_unavailable", "workspace_unavailable", "recipient_unavailable", "unknown_notification" ], "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "delivered_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "", "purchase_success", "expiry_reminder", "auto_renewal_success", "auto_renewal_problem", "billing_test" ], "type": "string" }, "mode": { "enum": [ "", "sandbox", "live" ], "type": "string" }, "recipient": { "type": "string" }, "status": { "enum": [ "pending", "running", "delivered", "failed", "cancelled" ], "type": "string" } }, "required": [ "id", "status", "attempts" ], "type": "object" }, "MailJobList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/MailJob" }, "maxItems": 50, "type": "array" } }, "required": [ "items" ], "type": "object" }, "MailProviderInput": { "additionalProperties": false, "properties": { "api_key": { "description": "Provider API key; Postmark uses a Server API Token. Omit or leave blank to preserve the saved secret.", "maxLength": 4096, "type": "string", "writeOnly": true }, "from": { "description": "Verified sender email; required when selecting this provider as active.", "type": "string" } }, "required": [], "type": "object" }, "MailProviderSettings": { "additionalProperties": false, "properties": { "api_key_configured": { "type": "boolean" }, "domain": { "description": "Mailgun sending domain; empty for other providers.", "type": "string" }, "from": { "type": "string" }, "region": { "description": "Mailgun region; empty for other providers.", "enum": [ "", "us", "eu" ], "type": "string" } }, "required": [ "from", "domain", "region", "api_key_configured" ], "type": "object" }, "MailQueued": { "additionalProperties": false, "properties": { "job_id": { "format": "uuid", "type": "string" }, "status": { "enum": [ "pending" ], "type": "string" } }, "required": [ "job_id", "status" ], "type": "object" }, "MailSettings": { "additionalProperties": false, "properties": { "from": { "type": "string" }, "host": { "type": "string" }, "mode": { "enum": [ "file", "smtp", "resend", "brevo", "postmark", "mailgun" ], "type": "string" }, "password_configured": { "type": "boolean" }, "port": { "type": "integer" }, "providers": { "additionalProperties": false, "properties": { "brevo": { "$ref": "#/components/schemas/MailProviderSettings" }, "mailgun": { "$ref": "#/components/schemas/MailProviderSettings" }, "postmark": { "$ref": "#/components/schemas/MailProviderSettings" }, "resend": { "$ref": "#/components/schemas/MailProviderSettings" } }, "required": [ "resend", "brevo", "postmark", "mailgun" ], "type": "object" }, "tls_mode": { "enum": [ "starttls", "implicit" ], "type": "string" }, "username": { "type": "string" } }, "required": [ "mode", "port", "password_configured", "providers" ], "type": "object" }, "MailgunInput": { "additionalProperties": false, "properties": { "api_key": { "description": "Mailgun account API key or domain sending key. Omit or leave blank to preserve the saved secret.", "maxLength": 4096, "type": "string", "writeOnly": true }, "domain": { "description": "Sending domain, required when Mailgun is active; no scheme, path or port.", "maxLength": 253, "type": "string" }, "from": { "description": "Verified sender email; required when Mailgun is active.", "type": "string" }, "region": { "default": "us", "description": "The region hosting the sending domain; US and EU use separate fixed API endpoints.", "enum": [ "us", "eu" ], "type": "string" } }, "required": [], "type": "object" }, "ManagementKeyBundle": { "additionalProperties": false, "properties": { "keys": { "description": "Current and historical signing public keys for the product.", "items": { "$ref": "#/components/schemas/SigningKey" }, "type": "array" }, "product_id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } }, "required": [ "product_id", "keys" ], "type": "object" }, "ManualRefundInput": { "additionalProperties": false, "properties": { "customer_agreement": { "maxLength": 3000, "type": "string" }, "evidence": { "maxLength": 3000, "type": "string" } }, "required": [ "customer_agreement", "evidence" ], "type": "object" }, "Me": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "is_platform_admin": { "type": "boolean" }, "name": { "type": "string" }, "role": { "enum": [ "owner", "read_only" ], "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "tenant_name": { "type": "string" } }, "required": [ "tenant_id", "id", "role", "is_platform_admin" ], "type": "object" }, "Member": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "is_platform_admin": { "type": "boolean" }, "name": { "type": "string" }, "role": { "enum": [ "owner", "read_only" ], "type": "string" }, "status": { "enum": [ "active", "disabled" ], "type": "string" }, "verified": { "type": "boolean" } }, "required": [ "id", "role", "status", "verified" ], "type": "object" }, "MemberList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/Member" }, "type": "array" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "items" ], "type": "object" }, "MemberUpdate": { "additionalProperties": false, "properties": { "role": { "enum": [ "owner", "read_only" ], "type": "string" }, "status": { "enum": [ "active", "disabled" ], "type": "string" } }, "required": [], "type": "object" }, "MonthInput": { "additionalProperties": false, "properties": { "month": { "description": "UTC month YYYY-MM; omitted query values use the current month. Billing jobs require a closed month.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } }, "required": [ "month" ], "type": "object" }, "Notice": { "additionalProperties": false, "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" }, "OfflineReleaseResult": { "additionalProperties": false, "example": { "activation_id": "44444444-4444-4444-8444-444444444444", "deactivated": true }, "properties": { "activation_id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "deactivated": { "description": "Whether HTTP is allowed, for local development only.", "type": "boolean" } }, "required": [ "activation_id", "deactivated" ], "type": "object" }, "OfflineRequest": { "additionalProperties": false, "properties": { "activation_id": { "description": "Device activation or floating-session record UUID.", "format": "uuid", "type": "string" }, "app_version": { "description": "Empty for ordinary activation. Supply the actual published application version only when using version or maintenance restrictions.", "pattern": "^$|^(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})$", "type": "string" }, "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "type": "integer" }, "device_id": { "description": "SDK derives product-scoped OS and hardware identity using LicenovaDevice/v3. Configuration cannot override the current machine.", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "device_name": { "description": "Human-readable device label, not a security identity.", "maxLength": 120, "type": "string" }, "device_profile": { "$ref": "#/components/schemas/DeviceProfile", "description": "SDK-generated device identity; supply all required child fields when present." }, "license_key": { "description": "Original license key; one-use lv_tmp_ code for activate only; then a machine-bound lv_dev_ credential for runtime operations. SDK persists credentials separately from leases.", "pattern": "^lv_(lic|tmp|dev)_[A-Za-z0-9_-]{43}$", "type": "string", "writeOnly": true }, "operation": { "description": "Operation name; batches support create/renew/revoke/apply_policy and offline requests activate/deactivate.", "enum": [ "activate", "deactivate" ], "type": "string" }, "product_id": { "description": "Product UUID in the current workspace.", "format": "uuid", "type": "string" }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" }, "session_id": { "description": "Floating instance session identifier; may be omitted for node-locked licenses.", "format": "uuid", "type": "string" }, "version": { "const": 1, "description": "Policy revision, product major.minor.patch version, or offline protocol version 1, depending on the object.", "type": "integer" } }, "required": [ "version", "request_id", "created_at", "operation", "product_id", "license_key", "device_id" ], "type": "object" }, "OfflineResponse": { "additionalProperties": false, "example": { "operation": "deactivate", "request_id": "55555555-5555-4555-8555-555555555555", "result": { "activation_id": "44444444-4444-4444-8444-444444444444", "deactivated": true }, "version": 1 }, "properties": { "operation": { "description": "Operation name; batches support create/renew/revoke/apply_policy and offline requests activate/deactivate.", "enum": [ "activate", "deactivate" ], "type": "string" }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/RuntimeResult", "description": "Offline operation result: activation returns a signed lease; release returns deactivated." }, { "$ref": "#/components/schemas/OfflineReleaseResult", "description": "Offline operation result: activation returns a signed lease; release returns deactivated." } ], "description": "Offline operation result: activation returns a signed lease; release returns deactivated." }, "version": { "const": 1, "description": "Policy revision, product major.minor.patch version, or offline protocol version 1, depending on the object.", "type": "integer" } }, "required": [ "version", "request_id", "operation", "result" ], "type": "object" }, "OnboardingInput": { "additionalProperties": false, "properties": { "description": { "description": "Product description; may be empty.", "maxLength": 1000, "type": "string" }, "duration_days": { "description": "Duration of the generated test license only; default 7 for timed/trial. Not saved in the generated policy.", "maximum": 36500, "minimum": 1, "type": [ "integer", "null" ] }, "features": { "default": [ "export" ], "description": "Up to 32 distinct feature identifiers, each 1–64 ASCII letters, digits, dots, dashes or underscores.", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "Heartbeat interval in seconds: 0 disables it; otherwise 600–86400. Omission uses server defaults; independent of offline allowance." }, { "description": "Heartbeat interval in seconds: 0 disables it; otherwise 600–86400. Omission uses server defaults; independent of offline allowance.", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "0 explicitly disables periodic heartbeats; otherwise 600–86400 seconds (minimum 10 minutes). Independent of offline allowance.", "type": "integer" }, "license_model": { "default": "node_locked", "description": "node_locked device binding or floating seats.", "enum": [ "node_locked", "floating" ], "type": "string" }, "max_devices": { "default": 1, "description": "Maximum concurrent devices or floating seats per license.", "maximum": 10000, "minimum": 1, "type": "integer" }, "mode": { "default": "trial", "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "name": { "description": "Human-readable name; see the length constraints.", "maxLength": 120, "minLength": 1, "type": "string" }, "offline_mode": { "description": "limited, none, or permanent offline allowance; license expiry still applies.", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "Limited: 1–31536000 seconds and at least 3 × heartbeat_seconds when heartbeats are enabled; none/permanent: 0", "maximum": 31536000, "minimum": 0, "type": "integer" }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "request_id", "name" ], "type": "object" }, "OnboardingResult": { "additionalProperties": false, "example": { "config": { "allow_http": false, "app_version": "1.0.0", "base_url": "https://license.example.com", "cache_path": "", "device_name": "My application", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "product_id": "11111111-1111-4111-8111-111111111111", "trusted_keys": { "66666666-6666-4666-8666-666666666666": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "license_id": "33333333-3333-4333-8333-333333333333", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "next": "Choose a language and download the configured SDK bundle.", "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111" }, "properties": { "config": { "$ref": "#/components/schemas/SDKConfig", "description": "Private test SDK configuration containing a license secret." }, "license_id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "license_key": { "description": "Full customer license key supplied at activation. Product initialization code and example downloads do not contain this secret. Offline requests use the SDK-provided credential.", "type": "string" }, "next": { "description": "Scheduled next-month default plan, or null.", "type": "string" }, "policy_id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "product_id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } }, "required": [ "product_id", "policy_id", "license_id", "license_key", "config", "next" ], "type": "object" }, "OperatorProfile": { "additionalProperties": false, "properties": { "backup_region": { "maxLength": 500, "type": "string" }, "contact": { "maxLength": 500, "type": "string" }, "country": { "maxLength": 500, "type": "string" }, "financial_retention_years": { "description": "Zero or omitted means unconfirmed and is not included in public documents.", "maximum": 30, "minimum": 0, "type": "integer" }, "hosting_provider": { "maxLength": 500, "type": "string" }, "mail_provider": { "maxLength": 500, "type": "string" }, "markets": { "maxLength": 500, "type": "string" }, "operator": { "maxLength": 500, "type": "string" }, "processing_grounds": { "maxLength": 500, "type": "string" }, "server_region": { "maxLength": 500, "type": "string" }, "transfer_safeguards": { "maxLength": 500, "type": "string" } }, "required": [], "type": "object" }, "OriginalRefundInput": { "additionalProperties": false, "properties": { "amount": { "pattern": "^[0-9]+(?:\\.[0-9]{1,2})?$", "type": "string" }, "reason": { "maxLength": 255, "minLength": 1, "type": "string" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "amount", "reason", "request_id" ], "type": "object" }, "OriginalRefundResult": { "additionalProperties": false, "properties": { "case_id": { "format": "uuid", "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/ProviderRefund" }, "type": "array" } }, "type": "object" }, "OveragePlan": { "additionalProperties": false, "properties": { "api_hard_limit": { "description": "Whether runtime calls stop at the API allowance limit.", "type": "boolean" }, "api_unit_micros": { "description": "Price per excess runtime call in millionths.", "minimum": 0, "type": "integer" }, "base_micros": { "description": "Base charge in millionths of the currency unit.", "type": "integer" }, "currency": { "description": "Three-letter uppercase currency code, such as USD.", "type": "string" }, "description": { "description": "Billing offer description.", "type": "string" }, "enabled": { "description": "Whether the billing offer is enabled for purchase.", "type": "boolean" }, "hard_limit": { "description": "Whether new billable devices are rejected at the allowance limit.", "type": "boolean" }, "included_api_calls": { "description": "null = unlimited; 0 = no included successful calls", "maximum": 1000000000000, "minimum": 0, "type": [ "integer", "null" ] }, "included_devices": { "description": "Included active-device allowance.", "type": "integer" }, "name": { "description": "Billing offer display name.", "type": "string" }, "plan": { "description": "Stable billing plan identifier from the published catalog.", "type": "string" }, "price_version": { "description": "Frozen pricing revision; stale input may cause PLAN_VERSION_CONFLICT.", "type": "string" }, "public": { "description": "Whether the billing offer is publicly listed.", "type": "boolean" }, "renewal_only": { "description": "Existing paid or gifted customers may renew in advance or after expiry in the same environment and currency. Hidden from new public purchases.", "type": "boolean" }, "sort_order": { "description": "Billing offer display order.", "type": "integer" }, "terms": { "anyOf": [ { "description": "Available purchase terms and their prices.", "items": { "$ref": "#/components/schemas/PlanTermPrice" }, "type": "array" }, { "description": "Available purchase terms and their prices.", "type": "null" } ], "description": "Available purchase terms and their prices." }, "unit_micros": { "description": "Price per excess active device in millionths.", "type": "integer" }, "updated_at": { "description": "Last update timestamp in UTC.", "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "OveragePreference": { "additionalProperties": false, "properties": { "block_api_overage": { "description": "Whether runtime API calls beyond the included allowance are blocked.", "type": "boolean" }, "block_device_overage": { "description": "Whether new billable devices beyond the included allowance are blocked.", "type": "boolean" }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "sandbox", "live" ], "type": "string" }, "updated_at": { "description": "Last update timestamp in UTC.", "format": "date-time", "type": "string" }, "version": { "description": "Overage preference configuration revision.", "type": "string" } }, "required": [ "mode", "block_device_overage", "block_api_overage", "version", "updated_at" ], "type": "object" }, "OverageSettings": { "additionalProperties": false, "properties": { "customer_api_settings_enabled": { "description": "Whether customers may configure API-overage blocking.", "type": "boolean" }, "customer_device_settings_enabled": { "description": "Whether customers may configure device-overage blocking.", "type": "boolean" }, "plan": { "anyOf": [ { "$ref": "#/components/schemas/OveragePlan", "description": "Stable billing plan identifier from the published catalog." }, { "description": "Stable billing plan identifier from the published catalog.", "type": "null" } ], "description": "Current purchased/default allowance rules used to determine overages, or null when unavailable." }, "preference": { "$ref": "#/components/schemas/OveragePreference", "description": "Saved customer overage preferences." } }, "required": [ "preference", "plan", "customer_device_settings_enabled", "customer_api_settings_enabled" ], "type": "object" }, "OverageSettingsInput": { "additionalProperties": false, "properties": { "block_api_overage": { "type": "boolean" }, "block_device_overage": { "type": "boolean" }, "expected_version": { "description": "Use preference.version from GET. Empty for the first save. Changes from another tab return 409; at least one overage choice is required.", "type": "string" } }, "required": [ "expected_version" ], "type": "object" }, "PaddleCheck": { "additionalProperties": false, "properties": { "connected": { "description": "Whether this channel accepts new checkouts. Historical reconciliation remains available with retained credentials.", "type": "boolean" }, "mode": { "description": "Payment environment. Sandbox and live records are isolated.", "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [ "connected", "mode" ], "type": "object" }, "PaddleOrder": { "additionalProperties": false, "properties": { "amount_cents": { "description": "Frozen full service price in the smallest currency unit; no wallet recharge or mixed payment.", "type": "integer" }, "applied_at": { "anyOf": [ { "description": "UTC time at which the local checkout intent was saved.", "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "UTC time the verified payment activated service or credited a wallet top-up. Null purchase_id and upgrade_id identify a top-up." }, "created_at": { "description": "UTC time at which the local checkout intent was saved.", "format": "date-time", "type": "string" }, "currency": { "description": "Display name of the payment service.", "type": "string" }, "id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" }, "mode": { "description": "Payment environment. Sandbox and live records are isolated.", "enum": [ "sandbox", "live" ], "type": "string" }, "paid_at": { "anyOf": [ { "description": "UTC time at which the local checkout intent was saved.", "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "UTC time at which the backend verified a completed Paddle transaction." }, "purchase_id": { "anyOf": [ { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Existing pending service purchase or renewal; mutually exclusive with upgrade_id." }, "refunded_cents": { "description": "Frozen full service price in the smallest currency unit; no wallet recharge or mixed payment.", "type": "integer" }, "request_id": { "description": "Display name of the payment service.", "type": "string" }, "status": { "description": "Payment lifecycle, including paid_unapplied when collected funds need operator review and refund.", "enum": [ "creating", "created", "completed", "paid_unapplied", "partially_refunded", "refunded" ], "type": "string" }, "transaction_id": { "anyOf": [ { "description": "Display name of the payment service.", "type": "string" }, { "type": "null" } ], "description": "Bound Paddle Billing transaction identifier, or null while the original creation outcome is pending." }, "upgrade_id": { "anyOf": [ { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Existing pending upgrade quote; mutually exclusive with purchase_id." } }, "required": [ "id", "request_id", "mode", "transaction_id", "purchase_id", "upgrade_id", "currency", "amount_cents", "refunded_cents", "status", "paid_at", "applied_at", "created_at" ], "type": "object" }, "PaddleOrderInput": { "additionalProperties": false, "description": "Pay one frozen purchase/upgrade, or create a wallet top-up with amount and currency and no service IDs. A stable request_id returns the original payment; changing its intent, amount or currency is rejected. Only independently verified completed payments credit a wallet or activate service. Top-up returns go to the wallet. An uncertain create result is recovered from its original webhook and is never blindly recreated.", "oneOf": [ { "not": { "anyOf": [ { "required": [ "amount" ] }, { "required": [ "currency" ] } ] }, "properties": { "purchase_id": { "format": "uuid", "type": "string" }, "upgrade_id": { "type": "null" } }, "required": [ "purchase_id" ] }, { "not": { "anyOf": [ { "required": [ "amount" ] }, { "required": [ "currency" ] } ] }, "properties": { "purchase_id": { "type": "null" }, "upgrade_id": { "format": "uuid", "type": "string" } }, "required": [ "upgrade_id" ] }, { "properties": { "purchase_id": { "type": "null" }, "upgrade_id": { "type": "null" } }, "required": [ "amount", "currency" ] } ], "properties": { "amount": { "description": "Required only for a wallet top-up. A decimal display amount within the configured limits. Service orders reject client amounts.", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "type": "string" }, "currency": { "description": "Required only for a wallet top-up and must be enabled for this provider.", "type": "string" }, "overage_accepted": { "description": "Separate explicit authorisation of displayed chargeable overage.", "type": "boolean" }, "policy_version": { "description": "Currently published immutable policy version. Required for consent-protected actions after the operator publishes a policy, in either payment environment.", "type": "string" }, "purchase_id": { "anyOf": [ { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Existing pending service purchase or renewal; mutually exclusive with upgrade_id." }, "request_id": { "description": "Stable caller-generated request key. Replays return the original checkout.", "maxLength": 80, "type": "string" }, "terms_accepted": { "description": "Explicit unchecked-by-default acceptance.", "type": "boolean" }, "upgrade_id": { "anyOf": [ { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Existing pending upgrade quote; mutually exclusive with purchase_id." } }, "required": [ "request_id" ], "type": "object" }, "PaddleOrderList": { "additionalProperties": false, "properties": { "items": { "description": "Records visible to this administrator or workspace.", "items": { "$ref": "#/components/schemas/PaddleOrder" }, "type": "array" }, "total": { "description": "Frozen full service price in the smallest currency unit; no wallet recharge or mixed payment.", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "PaddleOrderResult": { "additionalProperties": false, "properties": { "approval_url": { "description": "Local checkout page that opens the bound Paddle transaction.", "format": "uri", "type": "string" }, "client_token": { "description": "Display name of the payment service.", "type": "string" }, "order": { "$ref": "#/components/schemas/PaddleOrder", "description": "Workspace-scoped Paddle service-payment record." }, "return_url": { "description": "Wallet dashboard URL for a top-up, pricing reconciliation URL for a service payment. A return URL alone never proves payment.", "format": "uri", "type": "string" } }, "required": [ "order", "client_token", "approval_url", "return_url" ], "type": "object" }, "PaddleReconcileInput": { "additionalProperties": false, "properties": { "transaction_id": { "description": "Optional original txn_ ID, used to recover a lost create response. The backend independently verifies its local order, tenant, product, currency and amount. Cannot replace an already bound transaction.", "type": "string" } }, "required": [], "type": "object" }, "PaddleSettings": { "additionalProperties": false, "properties": { "api_key_configured": { "description": "Whether this channel accepts new checkouts. Historical reconciliation remains available with retained credentials.", "type": "boolean" }, "checkout_url": { "description": "Use this approved-domain page as the Paddle default payment link.", "format": "uri", "type": "string" }, "client_token": { "description": "Display name of the payment service.", "type": "string" }, "currencies": { "description": "Distinct currencies accepted by this channel; amounts use two decimal places.", "items": { "description": "Display name of the payment service.", "type": "string" }, "type": "array" }, "enabled": { "description": "Whether this channel accepts new checkouts. Historical reconciliation remains available with retained credentials.", "type": "boolean" }, "maximum_cents": { "description": "Maximum wallet top-up in minor currency units; defaults to 100000 and must not be less than minimum_cents.", "maximum": 100000000, "minimum": 1, "type": "integer" }, "minimum_cents": { "description": "Minimum wallet top-up in minor currency units; defaults to 100.", "maximum": 100000000, "minimum": 1, "type": "integer" }, "mode": { "description": "Payment environment. Sandbox and live records are isolated.", "enum": [ "sandbox", "live" ], "type": "string" }, "product_id": { "description": "Display name of the payment service.", "type": "string" }, "version": { "description": "Display name of the payment service.", "type": "string" }, "webhook_secret_configured": { "description": "Whether this channel accepts new checkouts. Historical reconciliation remains available with retained credentials.", "type": "boolean" }, "webhook_url": { "description": "Register this absolute URL as the Paddle notification destination.", "format": "uri", "type": "string" } }, "required": [ "enabled", "mode", "client_token", "product_id", "currencies", "api_key_configured", "webhook_secret_configured", "version", "webhook_url", "checkout_url" ], "type": "object" }, "PaddleSettingsInput": { "additionalProperties": false, "properties": { "api_key": { "description": "Encrypted at rest. Empty preserves the existing value unless clear_api_key is true.", "maxLength": 1000, "type": "string", "writeOnly": true }, "clear_api_key": { "description": "Whether this channel accepts new checkouts. Historical reconciliation remains available with retained credentials.", "type": "boolean" }, "clear_webhook_secret": { "description": "Whether this channel accepts new checkouts. Historical reconciliation remains available with retained credentials.", "type": "boolean" }, "client_token": { "description": "Display name of the payment service.", "type": "string" }, "currencies": { "description": "Distinct currencies accepted by this channel; amounts use two decimal places.", "items": { "description": "Display name of the payment service.", "type": "string" }, "type": "array" }, "enabled": { "description": "Whether this channel accepts new checkouts. Historical reconciliation remains available with retained credentials.", "type": "boolean" }, "expected_version": { "description": "Display name of the payment service.", "type": "string" }, "maximum_cents": { "description": "Maximum wallet top-up in minor currency units; defaults to 100000 and must not be less than minimum_cents.", "maximum": 100000000, "minimum": 1, "type": "integer" }, "minimum_cents": { "description": "Minimum wallet top-up in minor currency units; defaults to 100.", "maximum": 100000000, "minimum": 1, "type": "integer" }, "mode": { "description": "Payment environment. Sandbox and live records are isolated.", "enum": [ "sandbox", "live" ], "type": "string" }, "product_id": { "description": "Display name of the payment service.", "type": "string" }, "webhook_secret": { "description": "Private endpoint secret used to authenticate the exact raw webhook body.", "maxLength": 1000, "type": "string", "writeOnly": true } }, "required": [ "enabled", "mode", "client_token", "product_id", "currencies", "expected_version" ], "type": "object" }, "PaddleWebhookEvent": { "description": "Unmodified Paddle Billing event, authenticated with Paddle-Signature and independently reconciled through the Paddle API.", "type": "object" }, "PasswordSet": { "additionalProperties": false, "properties": { "password_set": { "type": "boolean" } }, "required": [ "password_set" ], "type": "object" }, "PayPalCheck": { "additionalProperties": false, "properties": { "connected": { "type": "boolean" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [], "type": "object" }, "PayPalInput": { "additionalProperties": false, "properties": { "clear_secret": { "type": "boolean" }, "client_id": { "maxLength": 1000, "type": "string" }, "client_secret": { "description": "Empty preserves saved Secret unless clear_secret=true", "maxLength": 1000, "type": "string", "writeOnly": true }, "currencies": { "items": { "pattern": "^[A-Z]{3}$", "type": "string" }, "type": "array" }, "enabled": { "type": "boolean" }, "expected_version": { "type": "string" }, "maximum_cents": { "maximum": 100000000, "type": "integer" }, "merchant_id": { "maxLength": 64, "type": "string" }, "minimum_cents": { "minimum": 1, "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "webhook_id": { "maxLength": 1000, "type": "string" } }, "required": [ "enabled", "mode", "client_id", "merchant_id", "webhook_id", "currencies", "minimum_cents", "maximum_cents", "expected_version" ], "type": "object" }, "PayPalOrder": { "additionalProperties": false, "properties": { "amount_cents": { "description": "Amount in hundredths; ledger entries may be positive credits or negative debits.", "type": "integer" }, "approval_url": { "description": "PayPal payer-approval URL; not proof of payment.", "format": "uri", "type": "string" }, "capture_id": { "description": "PayPal capture identifier.", "type": [ "string", "null" ] }, "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "credited_at": { "anyOf": [ { "description": "Time the top-up was credited, or null.", "format": "date-time", "type": "string" }, { "description": "Time the top-up was credited, or null.", "type": "null" } ], "description": "Time the top-up was credited, or null." }, "currency": { "description": "Three-letter uppercase currency code, such as USD.", "pattern": "^[A-Z]{3}$", "type": "string" }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "sandbox", "live" ], "type": "string" }, "paypal_order_id": { "description": "PayPal order identifier, distinct from the local record UUID.", "type": [ "string", "null" ] }, "purchase_id": { "description": "Related package purchase UUID.", "type": [ "string", "null" ] }, "refunded_cents": { "description": "Cumulative refunded amount in hundredths.", "type": "integer" }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "type": "string" }, "status": { "description": "Current resource state; see the enum and operation notes.", "enum": [ "creating", "created", "credited", "refunded" ], "type": "string" }, "upgrade_id": { "anyOf": [ { "description": "Related upgrade UUID, or empty.", "format": "uuid", "type": "string" }, { "description": "Related upgrade UUID, or empty.", "type": "null" } ], "description": "Related upgrade UUID, or empty." } }, "required": [], "type": "object" }, "PayPalOrderList": { "additionalProperties": false, "properties": { "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/PayPalOrder" }, "type": "array" }, "limit": { "description": "Page size, default 25, range 1–100.", "type": "integer" }, "offset": { "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "type": "integer" }, "total": { "description": "Total matching records, not the current page length.", "type": "integer" } }, "required": [], "type": "object" }, "PayPalRefund": { "additionalProperties": false, "properties": { "amount_cents": { "description": "Requested original-route cash refund in cents.", "type": "integer" }, "attempts": { "type": "integer" }, "case_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "order_id": { "format": "uuid", "type": "string" }, "paypal_refund_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "type": "string" }, "request_id": { "type": "string" }, "reserved": { "description": "True while the wallet amount is held. A transport timeout retains the hold until the same request is reconciled.", "type": "boolean" }, "status": { "enum": [ "pending", "completed", "failed" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "order_id", "request_id", "mode", "currency", "amount_cents", "reason", "status", "reserved", "attempts", "paypal_refund_id", "created_at", "updated_at" ], "type": "object" }, "PayPalSettings": { "additionalProperties": false, "properties": { "client_id": { "maxLength": 1000, "type": "string" }, "currencies": { "items": { "pattern": "^[A-Z]{3}$", "type": "string" }, "type": "array" }, "enabled": { "type": "boolean" }, "maximum_cents": { "maximum": 100000000, "type": "integer" }, "merchant_id": { "maxLength": 64, "type": "string" }, "minimum_cents": { "minimum": 1, "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "secret_configured": { "type": "boolean" }, "version": { "type": "string" }, "webhook_id": { "maxLength": 1000, "type": "string" }, "webhook_url": { "format": "uri", "type": "string" } }, "required": [], "type": "object" }, "PaymentChannel": { "additionalProperties": false, "properties": { "currencies": { "description": "Distinct currencies accepted by this channel; amounts use two decimal places.", "items": { "description": "Display name of the payment service.", "type": "string" }, "type": "array" }, "enabled": { "description": "Whether this channel accepts new checkouts. Historical reconciliation remains available with retained credentials.", "type": "boolean" }, "mode": { "description": "Payment environment. Sandbox and live records are isolated.", "enum": [ "sandbox", "live" ], "type": "string" }, "name": { "description": "Display name of the payment service.", "type": "string" }, "provider": { "description": "Payment provider: PayPal, Paddle, or Waffo Pancake.", "enum": [ "paypal", "paddle", "waffo" ], "type": "string" }, "version": { "description": "Display name of the payment service.", "type": "string" }, "wallet_topup": { "description": "Whether this channel accepts new checkouts. Historical reconciliation remains available with retained credentials.", "type": "boolean" } }, "required": [ "provider", "name", "enabled", "mode", "currencies", "wallet_topup" ], "type": "object" }, "PaymentChannelInput": { "additionalProperties": false, "properties": { "paddle_enabled": { "description": "Whether this channel accepts new checkouts. Historical reconciliation remains available with retained credentials.", "type": "boolean" }, "paddle_version": { "description": "Display name of the payment service.", "type": "string" }, "paypal_enabled": { "description": "Whether this channel accepts new checkouts. Historical reconciliation remains available with retained credentials.", "type": "boolean" }, "paypal_version": { "description": "Display name of the payment service.", "type": "string" }, "waffo_enabled": { "description": "Optional Waffo switch; omitted fields preserve its current state.", "type": "boolean" }, "waffo_version": { "description": "Required configuration version when changing the Waffo switch.", "type": "string" } }, "required": [ "paypal_enabled", "paddle_enabled", "paypal_version", "paddle_version" ], "type": "object" }, "PaymentChannels": { "additionalProperties": false, "properties": { "items": { "description": "Records visible to this administrator or workspace.", "items": { "$ref": "#/components/schemas/PaymentChannel" }, "type": "array" }, "mode": { "description": "Payment environment. Sandbox and live records are isolated.", "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [ "items", "mode" ], "type": "object" }, "PendingPlan": { "additionalProperties": false, "properties": { "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "currency": { "description": "Three-letter uppercase currency code, such as USD.", "type": "string" }, "effective_month": { "description": "UTC month YYYY-MM when the schedule takes effect.", "type": "string" }, "plan": { "description": "Stable billing plan identifier from the published catalog.", "type": "string" }, "price_version": { "description": "Frozen pricing revision; stale input may cause PLAN_VERSION_CONFLICT.", "type": "string" } }, "required": [], "type": "object" }, "Period": { "additionalProperties": false, "properties": { "base_covered": { "description": "Whether a purchased package already covers the base charge.", "type": "boolean" }, "base_micros": { "description": "Base charge in millionths of the currency unit.", "type": "integer" }, "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "currency": { "description": "Three-letter uppercase currency code, such as USD.", "pattern": "^[A-Z]{3}$", "type": "string" }, "hard_limit": { "description": "Whether new billable devices are rejected at the allowance limit.", "type": "boolean" }, "included_devices": { "description": "Included active-device allowance.", "type": "integer" }, "month": { "description": "UTC month YYYY-MM; omitted query values use the current month. Billing jobs require a closed month.", "type": "string" }, "payment_mode": { "description": "Payment environment, sandbox or live.", "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "description": "Stable billing plan identifier from the published catalog.", "type": "string" }, "plan_name": { "description": "Display name of the plan.", "type": "string" }, "price_version": { "description": "Frozen pricing revision; stale input may cause PLAN_VERSION_CONFLICT.", "type": "string" }, "unit_micros": { "description": "Price per excess active device in millionths.", "type": "integer" } }, "required": [ "month", "plan", "currency", "price_version" ], "type": "object" }, "PlanChange": { "additionalProperties": false, "properties": { "currency": { "description": "Three-letter uppercase currency code, such as USD.", "pattern": "^[A-Z]{3}$", "type": "string" }, "plan": { "description": "Stable billing plan identifier from the published catalog.", "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "price_version": { "description": "Frozen pricing revision; stale input may cause PLAN_VERSION_CONFLICT.", "type": "string" } }, "required": [ "plan", "currency" ], "type": "object" }, "PlanGift": { "additionalProperties": false, "properties": { "batch_id": { "format": "uuid", "type": "string" }, "cancel_reason": { "type": "string" }, "cancelled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "cancelled_by": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "ends_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "purchase_id": { "format": "uuid", "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "status": { "enum": [ "granted", "cancelled" ], "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "value_cents": { "type": "integer" } }, "required": [ "id", "batch_id", "tenant_id", "user_id", "purchase_id", "value_cents", "status", "starts_at", "ends_at", "created_at", "cancelled_at" ], "type": "object" }, "PlanGiftBatch": { "additionalProperties": false, "properties": { "actor_id": { "format": "uuid", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "price_version": { "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "request_id": { "type": "string" }, "start_mode": { "type": "string" }, "tenant_count": { "type": "integer" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "user_count": { "type": "integer" } }, "required": [ "id", "actor_id", "request_id", "plan", "plan_name", "currency", "price_version", "term_months", "mode", "start_mode", "reason", "user_count", "tenant_count", "created_at" ], "type": "object" }, "PlanGiftCancellation": { "additionalProperties": false, "properties": { "cancelled": { "type": "boolean" } }, "required": [ "cancelled" ], "type": "object" }, "PlanGiftInput": { "additionalProperties": false, "properties": { "currency": { "maxLength": 3, "minLength": 3, "type": "string" }, "fingerprint": { "maxLength": 64, "minLength": 64, "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "type": "string" }, "price_version": { "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "request_id": { "maxLength": 80, "minLength": 1, "type": "string" }, "start_mode": { "default": "after_current", "enum": [ "after_current", "immediate" ], "type": "string" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "user_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "user_ids", "term_months", "mode", "start_mode", "reason", "request_id", "fingerprint" ], "type": "object" }, "PlanGiftList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/PlanGiftRow" }, "type": "array" }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "PlanGiftPreview": { "additionalProperties": false, "properties": { "fingerprint": { "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/PlanGiftTarget" }, "type": "array" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "plan_name": { "type": "string" }, "start_mode": { "default": "after_current", "enum": [ "after_current", "immediate" ], "type": "string" }, "tenant_count": { "type": "integer" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "user_count": { "type": "integer" }, "value_cents": { "type": "integer" } }, "required": [ "fingerprint", "plan_name", "value_cents", "user_count", "tenant_count", "mode", "term_months", "start_mode", "items" ], "type": "object" }, "PlanGiftPreviewInput": { "additionalProperties": false, "properties": { "currency": { "maxLength": 3, "minLength": 3, "type": "string" }, "fingerprint": { "maxLength": 64, "minLength": 64, "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "type": "string" }, "price_version": { "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "request_id": { "maxLength": 80, "minLength": 1, "type": "string" }, "start_mode": { "default": "after_current", "enum": [ "after_current", "immediate" ], "type": "string" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "user_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "user_ids", "mode", "reason" ], "type": "object" }, "PlanGiftResult": { "additionalProperties": false, "properties": { "batch": { "$ref": "#/components/schemas/PlanGiftBatch" }, "items": { "items": { "$ref": "#/components/schemas/PlanGift" }, "type": "array" } }, "required": [ "batch", "items" ], "type": "object" }, "PlanGiftRow": { "additionalProperties": false, "properties": { "actor_email": { "type": "string" }, "batch_id": { "format": "uuid", "type": "string" }, "cancel_reason": { "type": "string" }, "cancelled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "cancelled_by": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "email": { "type": "string" }, "ends_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "purchase_id": { "format": "uuid", "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "status": { "enum": [ "granted", "cancelled" ], "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "tenant_name": { "type": "string" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "user_id": { "format": "uuid", "type": "string" }, "value_cents": { "type": "integer" } }, "required": [ "id", "batch_id", "tenant_id", "user_id", "purchase_id", "value_cents", "status", "starts_at", "ends_at", "created_at", "cancelled_at" ], "type": "object" }, "PlanGiftTarget": { "additionalProperties": false, "properties": { "currency": { "type": "string" }, "email": { "type": "string" }, "ends_at": { "format": "date-time", "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "previous_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "price_version": { "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "tenant_name": { "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "value_cents": { "type": "integer" } }, "required": [ "user_id", "email", "tenant_id", "tenant_name", "starts_at", "ends_at", "previous_end", "plan", "plan_name", "currency", "price_version", "value_cents" ], "type": "object" }, "PlanInput": { "additionalProperties": false, "properties": { "api_hard_limit": { "type": "boolean" }, "api_unit_amount": { "description": "Nonnegative decimal per successful API call, six places maximum", "type": "string" }, "base_amount": { "description": "Nonnegative decimal; two places maximum", "type": "string" }, "currency": { "description": "Must be configured; EUR catalog offers are disabled", "pattern": "^[A-Z]{3}$", "type": "string" }, "description": { "maxLength": 1000, "type": "string" }, "enabled": { "type": "boolean" }, "expected_version": { "description": "Current version; empty when creating", "type": "string" }, "hard_limit": { "type": "boolean" }, "included_api_calls": { "description": "null = unlimited; 0 = no included successful calls", "maximum": 1000000000000, "minimum": 0, "type": [ "integer", "null" ] }, "included_devices": { "maximum": 1000000000, "minimum": 0, "type": "integer" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" }, "plan": { "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "public": { "type": "boolean" }, "renewal_only": { "description": "Existing paid or gifted customers may renew in advance or after expiry in the same environment and currency. Hidden from new public purchases.", "type": "boolean" }, "sort_order": { "maximum": 10000, "minimum": 0, "type": "integer" }, "terms": { "description": "Exactly one entry for 1, 3, 6 and 12 months, each with its own availability and total price.", "items": { "$ref": "#/components/schemas/PlanTermInput" }, "maxItems": 4, "minItems": 4, "type": "array" }, "unit_amount": { "description": "Nonnegative decimal; six places maximum", "type": "string" } }, "required": [ "plan", "currency", "name", "base_amount", "unit_amount" ], "type": "object" }, "PlanList": { "additionalProperties": false, "properties": { "billing_unit": { "type": "string" }, "currencies": { "items": { "pattern": "^[A-Z]{3}$", "type": "string" }, "type": "array" }, "default_plan": { "anyOf": [ { "$ref": "#/components/schemas/Price" }, { "type": "null" } ] }, "items": { "items": { "$ref": "#/components/schemas/Price" }, "type": "array" }, "maximum_cents": { "type": "integer" }, "minimum_cents": { "type": "integer" }, "payment_channels": { "description": "Available payment channel configuration. Show only enabled channels matching the active billing environment and purchase currency.", "items": { "$ref": "#/components/schemas/PaymentChannel" }, "type": "array" }, "paypal_enabled": { "type": "boolean" }, "sandbox": { "type": "boolean" }, "timezone": { "type": "string" } }, "required": [], "type": "object" }, "PlanPurchase": { "additionalProperties": false, "properties": { "api_calls": { "description": "For PurchaseList.active: successful calls in the current quota month. Historical items contain lifetime totals.", "type": "integer" }, "api_hard_limit": { "description": "Whether runtime calls stop at the API allowance limit.", "type": "boolean" }, "api_overage_cents": { "description": "Current quota month in the active view; lifetime API overage charges in historical items.", "type": "integer" }, "api_unit_micros": { "description": "Price per excess runtime call in millionths.", "minimum": 0, "type": "integer" }, "base_cents": { "description": "Actual initial charge for the whole contract; zero for a gift. The active effective upgrade view contains the full matching-duration target price.", "type": "integer" }, "cancelled_at": { "anyOf": [ { "description": "Contract cancellation timestamp, or null.", "format": "date-time", "type": "string" }, { "description": "Contract cancellation timestamp, or null.", "type": "null" } ], "description": "Contract cancellation timestamp, or null." }, "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "currency": { "description": "Three-letter uppercase currency code, such as USD.", "pattern": "^[A-Z]{3}$", "type": "string" }, "current_cycle_index": { "description": "Index of the current allowance cycle.", "maximum": 11, "minimum": 0, "type": "integer" }, "current_upgrade_id": { "description": "Empty before an upgrade. Otherwise points to the latest applied PlanUpgrade. The active response includes its effective plan snapshot, while historical purchases retain their original sale price.", "type": "string" }, "cycle_ends_at": { "description": "Current allowance cycle end, UTC.", "format": "date-time", "type": "string" }, "cycle_starts_at": { "description": "Current allowance cycle start, UTC.", "format": "date-time", "type": "string" }, "effective_included_devices": { "description": "Device allowance after the applied upgrade. Original purchase snapshots remain unchanged.", "minimum": 0, "type": "integer" }, "effective_plan": { "description": "Current entitlement after an explicit upgrade overlay. Purchase list keeps original plan/base_cents for cash history; use this field to show the currently effective tier.", "type": "string" }, "effective_plan_name": { "description": "Current entitlement after an explicit upgrade overlay. Purchase list keeps original plan/base_cents for cash history; use this field to show the currently effective tier.", "type": "string" }, "ends_at": { "anyOf": [ { "description": "Package or cycle end timestamp, UTC; may be null before activation.", "format": "date-time", "type": "string" }, { "description": "Package or cycle end timestamp, UTC; may be null before activation.", "type": "null" } ], "description": "Package or cycle end timestamp, UTC; may be null before activation." }, "entitlement_cents": { "description": "Benefit value of the current effective package for upgrade credit, in currency cents. A gifted 99 USD plan has 9900 benefit cents although its original base_cents payment is zero. This value is not refundable cash. Populated on active package views.", "minimum": 0, "type": "integer" }, "gift_batch_id": { "description": "Gift batch identifier; empty for ordinary purchases.", "type": "string" }, "gift_follows_current": { "default": false, "description": "Indicates a gift issued from the customer’s current tier. The gift retains its original entitlement value and zero cash payment. Explicit whole-coverage upgrades apply separate entitlement overlays to every unexpired gift and retain the original cash-zero gift record.", "type": "boolean" }, "hard_limit": { "description": "Whether new billable devices are rejected at the allowance limit.", "type": "boolean" }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "included_api_calls": { "description": "null = unlimited; 0 = no included successful calls", "maximum": 1000000000000, "minimum": 0, "type": [ "integer", "null" ] }, "included_devices": { "description": "Included active-device allowance.", "type": "integer" }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "sandbox", "live" ], "type": "string" }, "overage_cents": { "description": "Current quota month in the active view; lifetime device overage charges in historical items.", "type": "integer" }, "plan": { "description": "Stable billing plan identifier from the published catalog.", "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "plan_name": { "description": "Display name of the plan.", "type": "string" }, "price_version": { "description": "Frozen pricing revision; stale input may cause PLAN_VERSION_CONFLICT.", "type": "string" }, "refunded_cents": { "description": "Cumulative refunded amount in hundredths.", "type": "integer" }, "renewal": { "description": "Whether this is a renewal contract.", "type": "boolean" }, "renewal_of": { "description": "Previous paid or gifted package ID. Keeps the renewal chain and original purchase history.", "type": "string" }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "type": "string" }, "service_credit_basis_cents": { "description": "Amount basis in hundredths for service-credit calculations.", "type": "integer" }, "service_credit_basis_seconds": { "description": "Time basis in seconds for service-credit calculations.", "type": "integer" }, "source": { "description": "Entitlement source, such as purchase or gift.", "enum": [ "purchase", "gift", "auto_renewal" ], "type": "string" }, "starts_at": { "anyOf": [ { "description": "Package or cycle start timestamp, UTC.", "format": "date-time", "type": "string" }, { "description": "Package or cycle start timestamp, UTC.", "type": "null" } ], "description": "Package or cycle start timestamp, UTC." }, "status": { "description": "Current resource state; see the enum and operation notes.", "enum": [ "pending", "active", "cancelled", "expired" ], "type": "string" }, "term_months": { "default": 1, "description": "Number of months in the purchased term.", "enum": [ 1, 3, 6, 12 ], "type": "integer" }, "total_api_calls": { "description": "Cumulative runtime calls across the contract.", "type": "integer" }, "total_api_overage_cents": { "description": "Cumulative contract API overages in hundredths.", "type": "integer" }, "total_device_overage_cents": { "description": "Cumulative contract device overages in hundredths.", "type": "integer" }, "unit_micros": { "description": "Price per excess active device in millionths.", "type": "integer" } }, "required": [], "type": "object" }, "PlanTermInput": { "additionalProperties": false, "properties": { "amount": { "description": "Nonnegative duration total; at most two decimal places. The one-month amount must equal base_amount.", "type": "string" }, "enabled": { "type": "boolean" }, "months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" } }, "required": [ "months", "enabled", "amount" ], "type": "object" }, "PlanTermPrice": { "additionalProperties": false, "properties": { "base_cents": { "description": "Total charge for the selected duration, in currency cents. Monthly quotas are not multiplied by this duration.", "minimum": 0, "type": "integer" }, "enabled": { "description": "Whether the webhook endpoint is enabled.", "type": "boolean" }, "months": { "default": 1, "description": "Number of months in the purchase term.", "enum": [ 1, 3, 6, 12 ], "type": "integer" } }, "required": [ "months", "enabled", "base_cents" ], "type": "object" }, "PlanUpgrade": { "additionalProperties": false, "properties": { "amount_cents": { "description": "Combined payment for every item in parts. Charged once atomically. The parent’s other proration fields describe the current period only; inspect parts for each period’s original value, target value, remaining seconds and individual difference.", "type": "integer" }, "api_hard_limit": { "description": "Whether runtime calls stop at the API allowance limit.", "type": "boolean" }, "api_unit_micros": { "description": "New API overage rate in millionths of currency.", "type": "integer" }, "applied_at": { "anyOf": [ { "description": "Time the upgrade took effect, or null.", "format": "date-time", "type": "string" }, { "description": "Time the upgrade took effect, or null.", "type": "null" } ], "description": "Time the upgrade took effect, or null." }, "base_cents": { "description": "Target monthly price in cents, not the amount due now.", "type": "integer" }, "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "currency": { "description": "Same currency as the current package.", "type": "string" }, "cycle_seconds": { "description": "Length of the original purchased cycle in seconds.", "type": "integer" }, "ends_at": { "description": "Package or cycle end timestamp, UTC; may be null before activation.", "format": "date-time", "type": "string" }, "expires_at": { "description": "15 minutes after creation or original plan expiry, whichever comes first.", "format": "date-time", "type": "string" }, "hard_limit": { "description": "Whether new billable devices are rejected at the allowance limit.", "type": "boolean" }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "included_api_calls": { "anyOf": [ { "description": "Total API allowance for the existing cycle. Null means unlimited. Prior calls still count.", "type": "integer" }, { "description": "Included successful runtime calls; null means unlimited and 0 means none included.", "type": "null" } ], "description": "Included successful runtime calls; null means unlimited and 0 means none included." }, "included_devices": { "description": "Total allowance for the existing cycle; prior device use still counts.", "type": "integer" }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "sandbox", "live" ], "type": "string" }, "parent_id": { "description": "Internal applied entitlement overlays point to the single parent charge. These child records are excluded from customer upgrade history and sales counts.", "format": "uuid", "type": "string" }, "parts": { "description": "All unexpired current and future paid/gifted periods, in date order. Mandatory whole-coverage upgrade; no selectable period subset.", "items": { "$ref": "#/components/schemas/UpgradePart" }, "type": "array" }, "plan": { "description": "Stable billing plan identifier from the published catalog.", "type": "string" }, "plan_name": { "description": "Display name of the plan.", "type": "string" }, "previous_base_cents": { "description": "Effective current monthly price in cents.", "type": "integer" }, "previous_plan_name": { "description": "Plan display name before the upgrade.", "type": "string" }, "previous_upgrade_id": { "description": "The preceding upgrade ID, or empty for the first upgrade. Used to reject stale quotes.", "type": "string" }, "price_version": { "description": "Frozen target price version.", "type": "string" }, "purchase_id": { "description": "Related package purchase UUID.", "format": "uuid", "type": "string" }, "remaining_seconds": { "description": "Seconds remaining at quote creation, rounded up.", "type": "integer" }, "request_id": { "description": "Stable client-generated key. Reusing it with different quote parameters returns 409.", "type": "string" }, "status": { "description": "Current resource state; see the enum and operation notes.", "enum": [ "pending", "applied", "expired" ], "type": "string" }, "unit_micros": { "description": "New per-device overage rate in millionths of currency.", "type": "integer" } }, "required": [ "id", "request_id", "mode", "purchase_id", "previous_upgrade_id", "plan", "plan_name", "previous_plan_name", "currency", "price_version", "previous_base_cents", "base_cents", "amount_cents", "included_devices", "unit_micros", "hard_limit", "included_api_calls", "api_unit_micros", "api_hard_limit", "remaining_seconds", "cycle_seconds", "ends_at", "expires_at", "status", "created_at", "applied_at" ], "type": "object" }, "PlatformOperation": { "additionalProperties": false, "properties": { "action": { "type": "string" }, "actor_email": { "type": "string" }, "actor_id": { "format": "uuid", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "details": { "description": "JSON string containing only explicit administrative changes; never passwords, tokens or payment credentials.", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "request_id": { "type": "string" }, "resource_id": { "type": "string" }, "tenant_id": { "type": "string" }, "user_email": { "type": "string" }, "user_id": { "type": "string" } }, "required": [ "id", "actor_id", "action", "user_id", "tenant_id", "resource_id", "reason", "details", "request_id", "created_at", "actor_email", "user_email" ], "type": "object" }, "PlatformOperationList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/PlatformOperation" }, "type": "array" }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "PlatformOverview": { "additionalProperties": false, "properties": { "at": { "format": "date-time", "type": "string" }, "counts": { "additionalProperties": false, "properties": { "active_packages": { "type": "integer" }, "active_workspaces": { "type": "integer" }, "disabled_users": { "type": "integer" }, "enabled_plans": { "type": "integer" }, "expiring_packages": { "type": "integer" }, "failed_mail": { "type": "integer" }, "gift_packages": { "type": "integer" }, "new_users": { "type": "integer" }, "suspended_workspaces": { "type": "integer" }, "users": { "type": "integer" }, "verified_users": { "type": "integer" } }, "required": [ "users", "verified_users", "disabled_users", "new_users", "active_workspaces", "suspended_workspaces", "active_packages", "expiring_packages", "gift_packages", "failed_mail", "enabled_plans" ], "type": "object" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "paypal_enabled": { "type": "boolean" } }, "required": [ "counts", "mode", "paypal_enabled", "at" ], "type": "object" }, "PlatformReason": { "additionalProperties": false, "properties": { "reason": { "maxLength": 500, "minLength": 1, "type": "string" } }, "required": [ "reason" ], "type": "object" }, "PlatformRevocation": { "additionalProperties": false, "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "type": "object" }, "PlatformUser": { "additionalProperties": false, "properties": { "admin_note": { "description": "Private platform note. Customer profile fields remain unchanged.", "maxLength": 2000, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "email": { "format": "email", "type": "string" }, "email_verified_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "is_platform_admin": { "type": "boolean" }, "last_login_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "note_version": { "type": "string" }, "role": { "enum": [ "owner", "read_only" ], "type": "string" }, "status": { "enum": [ "active", "disabled" ], "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "tenant_name": { "type": "string" }, "tenant_status": { "enum": [ "active", "suspended" ], "type": "string" }, "tenant_updated_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "tenant_id", "tenant_name", "tenant_status", "tenant_updated_at", "email", "name", "role", "status", "is_platform_admin", "email_verified_at", "created_at", "updated_at", "last_login_at", "admin_note", "note_version" ], "type": "object" }, "PlatformUserDetail": { "additionalProperties": false, "properties": { "counts": { "additionalProperties": false, "properties": { "licenses": { "type": "integer" }, "products": { "type": "integer" }, "users": { "type": "integer" } }, "required": [ "users", "products", "licenses" ], "type": "object" }, "payments": { "items": { "additionalProperties": false, "properties": { "currency": { "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "paid_cents": { "type": "integer" }, "refunded_cents": { "type": "integer" } }, "required": [ "mode", "currency", "paid_cents", "refunded_cents" ], "type": "object" }, "type": "array" }, "purchases": { "items": { "$ref": "#/components/schemas/PlanPurchase" }, "type": "array" }, "user": { "$ref": "#/components/schemas/PlatformUser" }, "wallets": { "items": { "$ref": "#/components/schemas/Wallet" }, "type": "array" } }, "required": [ "user", "counts", "wallets", "purchases", "payments" ], "type": "object" }, "PlatformUserList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/PlatformUser" }, "type": "array" }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "PlatformUserUpdate": { "additionalProperties": false, "anyOf": [ { "required": [ "status", "expected_updated_at" ] }, { "required": [ "admin_note", "expected_note_version" ] } ], "properties": { "admin_note": { "maxLength": 2000, "type": "string" }, "expected_note_version": { "type": "string" }, "expected_updated_at": { "format": "date-time", "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "status": { "enum": [ "active", "disabled" ], "type": "string" } }, "required": [ "reason" ], "type": "object" }, "PlatformWorkspaceStatus": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "status": { "enum": [ "active", "suspended" ], "type": "string" } }, "required": [ "id", "status" ], "type": "object" }, "PlatformWorkspaceUpdate": { "additionalProperties": false, "properties": { "expected_updated_at": { "format": "date-time", "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "status": { "enum": [ "active", "suspended" ], "type": "string" } }, "required": [ "status", "reason", "expected_updated_at" ], "type": "object" }, "Policy": { "additionalProperties": false, "example": { "created_at": "2026-10-18T00:00:00Z", "features": [ "export" ], "heartbeat_seconds": 600, "id": "22222222-2222-4222-8222-222222222222", "max_devices": 1, "mode": "timed", "name": "One device", "offline_mode": "limited", "offline_seconds": 86400, "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z", "version": 1 }, "properties": { "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "features": { "description": "Up to 32 distinct feature identifiers, each 1–64 ASCII letters, digits, dots, dashes or underscores.", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "Heartbeat interval in seconds: 0 disables it; otherwise 600–86400. Omission uses server defaults; independent of offline allowance." }, { "description": "Heartbeat interval in seconds: 0 disables it; otherwise 600–86400. Omission uses server defaults; independent of offline allowance.", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "Heartbeat interval while online, in seconds. 0 disables periodic heartbeats. Offline allowance is configured separately.", "type": "integer" }, "id": { "description": "Policy UUID, used as policy_id when issuing a license.", "format": "uuid", "type": "string" }, "max_devices": { "description": "Maximum concurrent devices or floating seats per license.", "type": "integer" }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "name": { "description": "Human-readable name; see the length constraints.", "maxLength": 120, "minLength": 1, "type": "string" }, "offline_mode": { "description": "limited: time-limited offline; none: no offline use; permanent: no extra offline time limit, but license expiration still applies.", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "Allowed offline seconds: 1–31536000 for limited, 0 for none/permanent. This is not the heartbeat interval. New limited-offline policies require offline_seconds \u003e= 3 × heartbeat_seconds when heartbeats are enabled; floating seat leases must also span at least three heartbeat intervals.", "maximum": 31536000, "minimum": 0, "type": "integer" }, "product_id": { "description": "Product UUID in the current workspace.", "format": "uuid", "type": "string" }, "updated_at": { "description": "Last update timestamp in UTC.", "format": "date-time", "type": "string" }, "version": { "description": "Policy revision increments on each edit. When applying to existing licenses, it checks that the preview is still current.", "type": "integer" } }, "required": [ "id", "product_id", "mode", "version" ], "type": "object" }, "PolicyCapabilities": { "additionalProperties": false, "properties": { "allow_vm": { "description": "Whether virtual machines are allowed.", "type": "boolean" }, "device_match": { "description": "system identity matching or hardware identity matching.", "enum": [ "system", "hardware" ], "type": "string" }, "license_model": { "description": "node_locked device binding or floating seats.", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_days": { "description": "Maintenance days from first activation; 0 means no maintenance cutoff.", "maximum": 36500, "minimum": 0, "type": "integer" }, "max_version": { "description": "Maximum permitted application version; empty means no upper bound.", "type": "string" }, "meter_rules": { "description": "Feature metering rules; empty means none configured.", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "Whether excess feature usage is allowed.", "type": "boolean" }, "feature": { "description": "Metered feature identifier, which must exist in policy features.", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "Included feature uses per metering period (not a pagination limit).", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "Maximum permitted excess usage; disabled when allow_overage is false.", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "Default UTC monthly billing snapshot; meter rules use month/day/lifetime and usage rows use the concrete period key.", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "maxItems": 32, "type": "array" }, "min_version": { "description": "Minimum permitted application version; empty means no lower bound.", "type": "string" }, "policy_id": { "description": "Policy UUID; must belong to the product at issuance.", "format": "uuid", "type": "string" }, "policy_version": { "description": "Policy revision; send the current value when editing full capabilities to prevent stale writes.", "type": "integer" }, "product_id": { "description": "Product UUID in the current workspace.", "format": "uuid", "type": "string" }, "require_hardware": { "description": "Whether a usable hardware identity is required.", "type": "boolean" }, "self_release_limit": { "description": "Allowed self-service releases per rolling 30 days, 0–100; 0 disables them.", "maximum": 100, "minimum": 0, "type": "integer" }, "session_seconds": { "description": "Floating-seat lease seconds without heartbeat, 20–86400; must satisfy the policy runtime constraints.", "maximum": 86400, "minimum": 20, "type": "integer" }, "updated_at": { "description": "Last update timestamp in UTC.", "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "PolicyCapabilitiesInput": { "additionalProperties": false, "description": "Defines issuance mode, device/seat limits, features and runtime rules. No validity duration is stored in a policy. policy_version is required to prevent stale edits.", "properties": { "allow_vm": { "description": "Whether virtual machines are allowed.", "type": "boolean" }, "device_match": { "description": "system identity matching or hardware identity matching.", "enum": [ "system", "hardware" ], "type": "string" }, "features": { "description": "Up to 32 distinct feature identifiers, each 1–64 ASCII letters, digits, dots, dashes or underscores.", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "Heartbeat interval in seconds: 0 disables it; otherwise 600–86400. Omission uses server defaults; independent of offline allowance." }, { "description": "Heartbeat interval in seconds: 0 disables it; otherwise 600–86400. Omission uses server defaults; independent of offline allowance.", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "0 explicitly disables periodic heartbeats; otherwise 600–86400 seconds (minimum 10 minutes). Independent of offline allowance.", "type": "integer" }, "license_model": { "description": "node_locked device binding or floating seats.", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_days": { "description": "Maintenance days from first activation; 0 means no maintenance cutoff.", "maximum": 36500, "minimum": 0, "type": "integer" }, "max_devices": { "description": "Maximum concurrent devices or floating seats per license.", "maximum": 10000, "minimum": 1, "type": "integer" }, "max_version": { "description": "Maximum permitted application version; empty means no upper bound.", "type": "string" }, "meter_rules": { "description": "Feature metering rules; empty means none configured.", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "Whether excess feature usage is allowed.", "type": "boolean" }, "feature": { "description": "Metered feature identifier, which must exist in policy features.", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "Included feature uses per metering period (not a pagination limit).", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "Maximum permitted excess usage; disabled when allow_overage is false.", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "Default UTC monthly billing snapshot; meter rules use month/day/lifetime and usage rows use the concrete period key.", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "maxItems": 32, "type": "array" }, "min_version": { "description": "Minimum permitted application version; empty means no lower bound.", "type": "string" }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "name": { "description": "Human-readable name; see the length constraints.", "maxLength": 120, "minLength": 1, "type": "string" }, "offline_mode": { "description": "limited, none, or permanent offline allowance; license expiry still applies.", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "Limited: 1–31536000 seconds and at least 3 × heartbeat_seconds when heartbeats are enabled; none/permanent: 0", "maximum": 31536000, "minimum": 0, "type": "integer" }, "policy_version": { "description": "Policy revision; send the current value when editing full capabilities to prevent stale writes.", "minimum": 1, "type": "integer" }, "require_hardware": { "description": "Whether a usable hardware identity is required.", "type": "boolean" }, "self_release_limit": { "description": "Allowed self-service releases per rolling 30 days, 0–100; 0 disables them.", "maximum": 100, "minimum": 0, "type": "integer" }, "session_seconds": { "description": "Floating-seat lease seconds without heartbeat, 20–86400; must satisfy the policy runtime constraints.", "maximum": 86400, "minimum": 20, "type": "integer" } }, "required": [ "policy_version" ], "type": "object" }, "PolicyCreate": { "additionalProperties": false, "description": "Defines issuance mode, device/seat limits, features and runtime rules. No validity duration is stored in a policy. ", "properties": { "allow_vm": { "description": "Whether virtual machines are allowed.", "type": "boolean" }, "device_match": { "description": "system identity matching or hardware identity matching.", "enum": [ "system", "hardware" ], "type": "string" }, "features": { "description": "Allowed feature identifiers, e.g. [\"export\"]. They must match your application's CheckFeature arguments.", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "Heartbeat interval in seconds: 0 disables it; otherwise 600–86400. Omission uses server defaults; independent of offline allowance." }, { "description": "Heartbeat interval in seconds: 0 disables it; otherwise 600–86400. Omission uses server defaults; independent of offline allowance.", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "Heartbeat interval while online, in seconds. 0 disables periodic heartbeats. Offline allowance is configured separately.", "type": "integer" }, "license_model": { "description": "node_locked device binding or floating seats.", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_days": { "description": "Maintenance days from first activation; 0 means no maintenance cutoff.", "maximum": 36500, "minimum": 0, "type": "integer" }, "max_devices": { "description": "Device limit per license, 1–10000; in floating mode this is the concurrent-seat limit.", "maximum": 10000, "minimum": 1, "type": "integer" }, "max_version": { "description": "Maximum permitted application version; empty means no upper bound.", "type": "string" }, "meter_rules": { "description": "Feature metering rules; empty means none configured.", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "Whether excess feature usage is allowed.", "type": "boolean" }, "feature": { "description": "Metered feature identifier, which must exist in policy features.", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "Included feature uses per metering period (not a pagination limit).", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "Maximum permitted excess usage; disabled when allow_overage is false.", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "Default UTC monthly billing snapshot; meter rules use month/day/lifetime and usage rows use the concrete period key.", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "maxItems": 32, "type": "array" }, "min_version": { "description": "Minimum permitted application version; empty means no lower bound.", "type": "string" }, "mode": { "description": "License type: perpetual, timed or trial. This is not a billing-plan subscription type.", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "name": { "description": "Policy name, for example 30-day Pro.", "maxLength": 120, "minLength": 1, "type": "string" }, "offline_mode": { "description": "limited: time-limited offline; none: no offline use; permanent: no extra offline time limit, but license expiration still applies.", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "Allowed offline seconds: 1–31536000 for limited, 0 for none/permanent. This is not the heartbeat interval. New limited-offline policies require offline_seconds \u003e= 3 × heartbeat_seconds when heartbeats are enabled; floating seat leases must also span at least three heartbeat intervals.", "maximum": 31536000, "minimum": 0, "type": "integer" }, "product_id": { "description": "Product ID (UUID).", "format": "uuid", "type": "string" }, "require_hardware": { "description": "Whether a usable hardware identity is required.", "type": "boolean" }, "self_release_limit": { "description": "Allowed self-service releases per rolling 30 days, 0–100; 0 disables them.", "maximum": 100, "minimum": 0, "type": "integer" }, "session_seconds": { "description": "Floating-seat lease seconds without heartbeat, 20–86400; must satisfy the policy runtime constraints.", "maximum": 86400, "minimum": 20, "type": "integer" } }, "required": [ "product_id", "name", "mode", "max_devices" ], "type": "object" }, "PolicyList": { "additionalProperties": false, "properties": { "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/Policy" }, "type": "array" }, "limit": { "description": "Page size, default 25, range 1–100.", "type": "integer" }, "offset": { "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "type": "integer" }, "total": { "description": "Total matching records, not the current page length.", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "PolicyPreview": { "additionalProperties": false, "properties": { "changes": { "description": "Per-license before/after comparison and blocking reason.", "items": { "additionalProperties": false, "properties": { "active": { "description": "Current signing key flag; in a policy preview, the active device/session count.", "type": "integer" }, "after": { "additionalProperties": false, "description": "Entitlements after applying the target policy; lifetime remains unchanged.", "properties": { "duration_days": { "description": "Per-license days from first activation. Required 1–36500 for timed/trial issuance; absent/null for perpetual. Never stored in the policy.", "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "format": "date-time", "type": "string" }, { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "type": "null" } ], "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry." }, "features": { "description": "Up to 32 distinct feature identifiers, each 1–64 ASCII letters, digits, dots, dashes or underscores.", "items": { "type": "string" }, "type": "array" }, "license_model": { "description": "node_locked device binding or floating seats.", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_until": { "anyOf": [ { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "format": "date-time", "type": "string" }, { "description": "Maintenance cutoff for new releases; may be null before activation or when unlimited.", "type": "null" } ], "description": "Maintenance cutoff for new releases; may be null before activation or when unlimited." }, "max_devices": { "description": "Maximum concurrent devices or floating seats per license.", "type": "integer" }, "max_version": { "description": "Maximum permitted application version; empty means no upper bound.", "type": "string" }, "meter_rules": { "description": "Feature metering rules; empty means none configured.", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "Whether excess feature usage is allowed.", "type": "boolean" }, "feature": { "description": "Metered feature identifier, which must exist in policy features.", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "Page size, default 25, range 1–100.", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "Maximum permitted excess usage; disabled when allow_overage is false.", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "Default UTC monthly billing snapshot; meter rules use month/day/lifetime and usage rows use the concrete period key.", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "maxItems": 32, "type": "array" }, "min_version": { "description": "Minimum permitted application version; empty means no lower bound.", "type": "string" }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "perpetual", "timed", "trial" ], "type": "string" } }, "required": [ "mode", "max_devices", "features", "expires_at", "duration_days", "license_model", "meter_rules", "maintenance_until", "min_version", "max_version" ], "type": "object" }, "before": { "additionalProperties": false, "description": "Current issued entitlements and license lifetime.", "properties": { "capabilities": { "$ref": "#/components/schemas/LicenseCapabilities", "description": "License capability snapshot." }, "duration_days": { "description": "Per-license days from first activation. Required 1–36500 for timed/trial issuance; absent/null for perpetual. Never stored in the policy.", "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "format": "date-time", "type": "string" }, { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "type": "null" } ], "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry." }, "features": { "description": "Up to 32 distinct feature identifiers, each 1–64 ASCII letters, digits, dots, dashes or underscores.", "items": { "type": "string" }, "type": "array" }, "max_devices": { "description": "Maximum concurrent devices or floating seats per license.", "type": "integer" }, "meter_rules": { "description": "Feature metering rules; empty means none configured.", "items": { "additionalProperties": false, "properties": { "allow_overage": { "description": "Whether excess feature usage is allowed.", "type": "boolean" }, "feature": { "description": "Metered feature identifier, which must exist in policy features.", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "limit": { "description": "Page size, default 25, range 1–100.", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "max_overage": { "description": "Maximum permitted excess usage; disabled when allow_overage is false.", "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "period": { "description": "Default UTC monthly billing snapshot; meter rules use month/day/lifetime and usage rows use the concrete period key.", "enum": [ "month", "day", "lifetime" ], "type": "string" } }, "required": [ "feature", "limit", "period" ], "type": "object" }, "maxItems": 32, "type": "array" }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "perpetual", "timed", "trial" ], "type": "string" } }, "required": [ "mode", "max_devices", "features", "expires_at", "duration_days", "capabilities", "meter_rules" ], "type": "object" }, "blocked_reason": { "description": "Reason the change is blocked; empty means no current blocker.", "type": "string" }, "customer": { "description": "Vendor-defined customer label, distinct from the customer portal email.", "type": "string" }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } }, "required": [ "id", "customer", "before", "after", "blocked_reason", "active" ], "type": "object" }, "type": "array" }, "expires_in": { "const": 600, "description": "Preview token lifetime in seconds, currently 600.", "type": "integer" }, "note": { "description": "Additional guidance for the developer.", "type": "string" }, "policy_version": { "description": "Policy revision; send the current value when editing full capabilities to prevent stale writes.", "type": "integer" }, "preview_token": { "description": "Encrypted preview confirmation token required for apply_policy; valid 600 seconds and invalidated by resource changes.", "type": "string" } }, "required": [ "changes", "policy_version", "preview_token", "expires_in", "note" ], "type": "object" }, "PolicySyncResult": { "additionalProperties": false, "properties": { "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "synced_licenses": { "description": "Number of linked, non-revoked licenses synchronized in the same transaction.", "minimum": 0, "type": "integer" } }, "required": [ "id", "synced_licenses" ], "type": "object" }, "PolicyUpdate": { "additionalProperties": false, "description": "Defines issuance mode, device/seat limits, features and runtime rules. No validity duration is stored in a policy. ", "properties": { "features": { "description": "Up to 32 distinct feature identifiers, each 1–64 ASCII letters, digits, dots, dashes or underscores.", "items": { "pattern": "^[A-Za-z0-9_.-]{1,64}$", "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "Heartbeat interval in seconds: 0 disables it; otherwise 600–86400. Omission uses server defaults; independent of offline allowance." }, { "description": "Heartbeat interval in seconds: 0 disables it; otherwise 600–86400. Omission uses server defaults; independent of offline allowance.", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "0 explicitly disables periodic heartbeats; otherwise 600–86400 seconds (minimum 10 minutes). Independent of offline allowance.", "type": "integer" }, "max_devices": { "description": "Maximum concurrent devices or floating seats per license.", "maximum": 10000, "minimum": 1, "type": "integer" }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "perpetual", "timed", "trial" ], "type": "string" }, "name": { "description": "Human-readable name; see the length constraints.", "maxLength": 120, "minLength": 1, "type": "string" }, "offline_mode": { "description": "limited, none, or permanent offline allowance; license expiry still applies.", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "Limited: 1–31536000 seconds and at least 3 × heartbeat_seconds when heartbeats are enabled; none/permanent: 0", "maximum": 31536000, "minimum": 0, "type": "integer" } }, "required": [], "type": "object" }, "PreviewInput": { "additionalProperties": false, "properties": { "ids": { "description": "Distinct license UUIDs to process, 1–100.", "items": { "format": "uuid", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "policy_id": { "description": "Policy UUID; must belong to the product at issuance.", "format": "uuid", "type": "string" } }, "required": [ "policy_id", "ids" ], "type": "object" }, "Price": { "additionalProperties": false, "properties": { "api_hard_limit": { "description": "Whether runtime calls stop at the API allowance limit.", "type": "boolean" }, "api_unit_micros": { "description": "Price per excess runtime call in millionths.", "minimum": 0, "type": "integer" }, "base_micros": { "description": "Base charge in millionths of the currency unit.", "type": "integer" }, "currency": { "description": "Three-letter uppercase currency code, such as USD.", "type": "string" }, "description": { "description": "Billing offer description.", "type": "string" }, "enabled": { "description": "Whether the billing offer is enabled for purchase.", "type": "boolean" }, "hard_limit": { "description": "Whether new billable devices are rejected at the allowance limit.", "type": "boolean" }, "included_api_calls": { "description": "null = unlimited; 0 = no included successful calls", "maximum": 1000000000000, "minimum": 0, "type": [ "integer", "null" ] }, "included_devices": { "description": "Included active-device allowance.", "type": "integer" }, "name": { "description": "Billing offer display name.", "type": "string" }, "plan": { "description": "Stable billing plan identifier from the published catalog.", "type": "string" }, "price_version": { "description": "Frozen pricing revision; stale input may cause PLAN_VERSION_CONFLICT.", "type": "string" }, "public": { "description": "Whether the billing offer is publicly listed.", "type": "boolean" }, "renewal_only": { "description": "Existing paid or gifted customers may renew in advance or after expiry in the same environment and currency. Hidden from new public purchases.", "type": "boolean" }, "sort_order": { "description": "Billing offer display order.", "type": "integer" }, "terms": { "description": "Available purchase terms and their prices.", "items": { "$ref": "#/components/schemas/PlanTermPrice" }, "type": "array" }, "unit_micros": { "description": "Price per excess active device in millionths.", "type": "integer" }, "updated_at": { "description": "Last update timestamp in UTC.", "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "Product": { "additionalProperties": false, "example": { "created_at": "2026-10-18T00:00:00Z", "description": "Desktop reporting software", "id": "11111111-1111-4111-8111-111111111111", "name": "Report app", "status": "active", "updated_at": "2026-10-18T00:00:00Z" }, "properties": { "created_at": { "description": "Creation timestamp, UTC ISO 8601.", "format": "date-time", "type": "string" }, "description": { "description": "Product description.", "type": "string" }, "id": { "description": "Product UUID used in SDK configuration and policy creation.", "format": "uuid", "type": "string" }, "name": { "description": "Product name.", "maxLength": 120, "minLength": 1, "type": "string" }, "status": { "description": "active allows activation; disabled rejects runtime licensing requests.", "enum": [ "active", "disabled" ], "type": "string" }, "updated_at": { "description": "Last update timestamp, UTC ISO 8601.", "format": "date-time", "type": "string" } }, "required": [ "id", "name", "status" ], "type": "object" }, "ProductCreate": { "additionalProperties": false, "properties": { "description": { "description": "Optional software description, up to 1000 characters.", "maxLength": 1000, "type": "string" }, "name": { "description": "Software name, 1–120 characters.", "maxLength": 120, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, "ProductList": { "additionalProperties": false, "properties": { "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/Product" }, "type": "array" }, "limit": { "description": "Page size, default 25, range 1–100.", "type": "integer" }, "offset": { "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "type": "integer" }, "total": { "description": "Total matching records, not the current page length.", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "ProductUpdate": { "additionalProperties": false, "properties": { "description": { "description": "Product description; may be empty.", "maxLength": 1000, "type": "string" }, "name": { "description": "Human-readable name; see the length constraints.", "maxLength": 120, "minLength": 1, "type": "string" }, "status": { "description": "Current resource state; see the enum and operation notes.", "enum": [ "active", "disabled" ], "type": "string" } }, "required": [], "type": "object" }, "ProviderRefund": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 0, "type": "integer" }, "attempted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "attempts": { "minimum": 0, "type": "integer" }, "case_id": { "format": "uuid", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "last_error": { "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "order_id": { "format": "uuid", "type": "string" }, "provider": { "enum": [ "waffo", "paddle" ], "type": "string" }, "provider_refund_id": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "reserved": { "type": "boolean" }, "settled_cents": { "minimum": 0, "type": "integer" }, "status": { "enum": [ "created", "submitting", "pending", "unknown", "completed", "failed" ], "type": "string" }, "submitted_cents": { "minimum": 0, "type": "integer" }, "unapplied": { "type": "boolean" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "PurchaseList": { "additionalProperties": false, "properties": { "active": { "anyOf": [ { "$ref": "#/components/schemas/PlanPurchase", "description": "Current signing key flag; in a policy preview, the active device/session count." }, { "description": "Current signing key flag; in a policy preview, the active device/session count.", "type": "null" } ], "description": "Current effective purchased package contract, or null." }, "active_devices": { "description": "Current registered product/device occupancy, independent of monthly device-use history. Ordinary registrations remain counted while offline until released. Floating sessions count only while their leases are valid and deduplicate by hardware, falling back to device identity. Release or final floating-session expiry returns capacity; valid registrations continue across quota-month boundaries. Isolated SDK trial registrations are excluded.", "type": "integer" }, "coverage_ends_at": { "anyOf": [ { "description": "End of continuous paid package coverage, or null.", "format": "date-time", "type": "string" }, { "description": "End of continuous paid package coverage, or null.", "type": "null" } ], "description": "Total prepaid coverage end, including paid advance renewals and scheduled gifts. The active package still reports its own current quota period." }, "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/PlanPurchase" }, "type": "array" }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "sandbox", "live" ], "type": "string" }, "renewal_package": { "anyOf": [ { "$ref": "#/components/schemas/PlanPurchase", "description": "Latest paid contract eligible for renewal, or null." }, { "description": "Latest paid contract eligible for renewal, or null.", "type": "null" } ], "description": "Latest paid or gifted coverage, including its applied upgrade. Use this effective plan and currency to select manual or automatic renewal. Null until a package has been opened." }, "total": { "description": "Total matching records, not the current page length.", "type": "integer" } }, "required": [], "type": "object" }, "RechargeInput": { "additionalProperties": false, "description": "Link purchase_id OR upgrade_id, never both. A confirmed payment credits the wallet and settles that purchase/upgrade when its quote is still valid. Late upgrade payments stay in the wallet.", "properties": { "amount": { "description": "Decimal recharge value, two places maximum", "type": "string" }, "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "overage_accepted": { "description": "Separate explicit authorisation of displayed chargeable overage.", "type": "boolean" }, "policy_version": { "description": "Currently published immutable policy version. Required for consent-protected actions after the operator publishes a policy, in either payment environment.", "type": "string" }, "purchase_id": { "format": "uuid", "type": [ "string", "null" ] }, "request_id": { "maxLength": 80, "type": "string" }, "terms_accepted": { "description": "Explicit unchecked-by-default acceptance.", "type": "boolean" }, "upgrade_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } }, "required": [ "currency", "amount", "request_id" ], "type": "object" }, "RecoverOriginalRefund": { "additionalProperties": false, "properties": { "confirm_unpaid_manual": { "const": true, "type": "boolean" }, "expected_updated_at": { "format": "date-time", "type": "string" } }, "required": [ "confirm_unpaid_manual" ], "type": "object" }, "RefundHistory": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/RefundHistoryItem" }, "type": "array" }, "limit": { "minimum": 0, "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "offset": { "minimum": 0, "type": "integer" }, "total": { "minimum": 0, "type": "integer" } }, "type": "object" }, "RefundHistoryItem": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 0, "type": "integer" }, "case_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "id": { "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "order_id": { "type": "string" }, "provider": { "enum": [ "paypal", "waffo", "paddle" ], "type": "string" }, "provider_refund_id": { "type": "string" }, "reason": { "type": "string" }, "settled_cents": { "minimum": 0, "type": "integer" }, "status": { "type": "string" } }, "type": "object" }, "RefundInboxItem": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 0, "type": "integer" }, "cancellation_scope": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "customer_email": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "manual_refund_pending": { "type": "boolean" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "order_id": { "type": "string" }, "pending_review": { "type": "boolean" }, "purchase_id": { "type": "string" }, "reason": { "type": "string" }, "refund_totals": { "description": "JSON-encoded per-currency amounts for scoped cancellations.", "type": "string" }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "scope": { "enum": [ "wallet", "service" ], "type": "string" }, "source": { "enum": [ "wallet_request", "support_case" ], "type": "string" }, "status": { "type": "string" }, "tenant_name": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "RefundInboxList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/RefundInboxItem" }, "type": "array" }, "limit": { "minimum": 0, "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "offset": { "minimum": 0, "type": "integer" }, "summary": { "additionalProperties": false, "properties": { "pending_review": { "minimum": 0, "type": "integer" }, "service_pending_review": { "minimum": 0, "type": "integer" }, "wallet_pending_review": { "minimum": 0, "type": "integer" } }, "type": "object" }, "total": { "minimum": 0, "type": "integer" } }, "type": "object" }, "RefundInput": { "additionalProperties": false, "properties": { "amount": { "description": "Positive refund amount in the capture currency; cannot exceed remaining captured funds or available unspent wallet credit.", "pattern": "^[0-9]+(?:\\.[0-9]{1,2})?$", "type": "string" }, "reason": { "maxLength": 255, "minLength": 1, "type": "string" }, "request_id": { "maxLength": 80, "minLength": 1, "type": "string" } }, "required": [ "amount", "reason", "request_id" ], "type": "object" }, "RefundList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/PayPalRefund" }, "type": "array" }, "total": { "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "RefundQuote": { "additionalProperties": false, "properties": { "amount_cents": { "type": "integer" }, "automatic_entitlement_cancellation": { "type": "boolean" }, "currency": { "type": "string" }, "purchase_id": { "format": "uuid", "type": "string" }, "quoted_at": { "format": "date-time", "type": "string" }, "requires_confirmation": { "type": "boolean" } }, "required": [], "type": "object" }, "RefundReview": { "additionalProperties": false, "properties": { "amount": { "type": "string" }, "amounts": { "items": { "additionalProperties": false, "properties": { "amount": { "type": "string" }, "purchase_id": { "format": "uuid", "type": "string" } }, "required": [ "purchase_id", "amount" ], "type": "object" }, "type": "array" }, "approve": { "type": "boolean" }, "decision": { "maxLength": 3000, "type": "string" }, "expected_updated_at": { "format": "date-time", "type": "string" }, "quote_hash": { "type": "string" }, "quoted_at": { "format": "date-time", "type": "string" } }, "required": [ "approve", "decision" ], "type": "object" }, "Register": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" }, "overage_accepted": { "description": "Separate explicit authorisation of displayed chargeable overage.", "type": "boolean" }, "password": { "description": "12–128 UTF-8 bytes, not characters", "type": "string", "writeOnly": true }, "password_confirmation": { "description": "Required and must match password exactly", "type": "string", "writeOnly": true }, "policy_version": { "description": "Currently published immutable policy version. Required for consent-protected actions after the operator publishes a policy, in either payment environment.", "type": "string" }, "tenant_name": { "maxLength": 120, "minLength": 1, "type": "string" }, "terms_accepted": { "description": "Explicit unchecked-by-default acceptance.", "type": "boolean" } }, "required": [ "email", "password", "password_confirmation", "name", "tenant_name" ], "type": "object" }, "Release": { "additionalProperties": false, "example": { "channel": "stable", "created_at": "2026-10-18T00:00:00Z", "download_url": "", "id": "33333333-3333-4333-8333-333333333333", "notes": "Initial release", "product_id": "11111111-1111-4111-8111-111111111111", "published_at": "2026-10-18T00:00:00Z", "sha256": "", "version": "1.0.0" }, "properties": { "channel": { "description": "Release channel, stable or preview; defaults to stable.", "type": "string" }, "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "download_url": { "description": "HTTPS download URL; sha256 is required when a URL is supplied.", "type": "string" }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "notes": { "description": "Release notes.", "type": "string" }, "product_id": { "description": "Product UUID in the current workspace.", "format": "uuid", "type": "string" }, "published_at": { "description": "Release publication timestamp, UTC; defaults to server time.", "format": "date-time", "type": "string" }, "sha256": { "description": "Download file SHA-256, 64 lowercase hex characters, distinct from the signing algorithm.", "type": "string" }, "version": { "description": "Policy revision, product major.minor.patch version, or offline protocol version 1, depending on the object.", "type": "string" } }, "required": [ "id", "product_id", "version", "channel", "notes", "download_url", "sha256", "published_at", "created_at" ], "type": "object" }, "ReleaseInput": { "additionalProperties": false, "properties": { "channel": { "description": "Release channel, stable or preview; defaults to stable.", "enum": [ "stable", "preview" ], "type": "string" }, "download_url": { "description": "HTTPS download URL; sha256 is required when a URL is supplied.", "format": "uri", "maxLength": 2000, "type": "string" }, "notes": { "description": "Release notes.", "maxLength": 10000, "type": "string" }, "published_at": { "description": "Release publication timestamp, UTC; defaults to server time.", "format": "date-time", "type": "string" }, "sha256": { "description": "Download file SHA-256, 64 lowercase hex characters, distinct from the signing algorithm.", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "version": { "description": "Policy revision, product major.minor.patch version, or offline protocol version 1, depending on the object.", "pattern": "^(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})$", "type": "string" } }, "required": [ "version" ], "type": "object" }, "ReleaseList": { "additionalProperties": false, "properties": { "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/Release" }, "type": "array" }, "limit": { "description": "Page size, default 25, range 1–100.", "type": "integer" }, "offset": { "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "type": "integer" }, "total": { "description": "Total matching records, not the current page length.", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "type": "object" }, "Renew": { "additionalProperties": false, "properties": { "days": { "description": "Additional days, 1–36500; license and maintenance renewals affect different terms.", "maximum": 36500, "minimum": 1, "type": "integer" } }, "required": [ "days" ], "type": "object" }, "RenewalPlans": { "additionalProperties": false, "properties": { "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/Price" }, "type": "array" }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [ "items", "mode" ], "type": "object" }, "Renewed": { "additionalProperties": false, "example": { "duration_days": 60, "expires_at": null, "id": "33333333-3333-4333-8333-333333333333" }, "properties": { "duration_days": { "description": "Renewals before first activation increase this value. After activation it retains the original duration; use expires_at for the actual deadline.", "maximum": 36500, "minimum": 1, "type": [ "integer", "null" ] }, "expires_at": { "anyOf": [ { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "format": "date-time", "type": "string" }, { "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry.", "type": "null" } ], "description": "License expiry; null for unactivated timed/trial or perpetual licenses. On key objects, credential expiry." }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } }, "required": [ "id", "expires_at", "duration_days" ], "type": "object" }, "ReservationResult": { "additionalProperties": false, "properties": { "activation_id": { "description": "Device binding or runtime session UUID. Save for future licensing requests; not a license key.", "format": "uuid", "type": "string" }, "heartbeat_seconds": { "anyOf": [ { "const": 0 }, { "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "Current heartbeat interval in seconds; metering does not refresh the signature or timer.", "type": "integer" }, "reservation": { "$ref": "#/components/schemas/FeatureReservation" } }, "required": [ "activation_id", "reservation" ], "type": "object" }, "Revenue": { "additionalProperties": false, "properties": { "invoices": { "items": { "additionalProperties": false, "properties": { "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "email": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "month": { "type": "string" }, "paid_at": { "format": "date-time", "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "refunded_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "tenant_name": { "type": "string" }, "total_cents": { "type": "integer" } }, "required": [], "type": "object" }, "type": "array" }, "limit": { "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "month": { "type": "string" }, "offset": { "type": "integer" }, "paddle_totals": { "description": "Gross payments and cumulative refunds for both service purchases and wallet top-ups, grouped by original payment month and currency; not bank settlement.", "items": { "additionalProperties": false, "properties": { "currency": { "description": "Display name of the payment service.", "type": "string" }, "paid_cents": { "description": "Frozen full service price in the smallest currency unit; no wallet recharge or mixed payment.", "type": "integer" }, "refunded_cents": { "description": "Frozen full service price in the smallest currency unit; no wallet recharge or mixed payment.", "type": "integer" } }, "required": [ "currency", "paid_cents", "refunded_cents" ], "type": "object" }, "type": "array" }, "paid_users": { "type": "integer" }, "purchase_total": { "type": "integer" }, "purchases": { "items": { "additionalProperties": false, "properties": { "api_calls": { "type": "integer" }, "api_overage_cents": { "type": "integer" }, "base_cents": { "type": "integer" }, "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "email": { "type": "string" }, "ends_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "overage_cents": { "type": "integer" }, "plan": { "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "plan_name": { "type": "string" }, "source": { "enum": [ "purchase", "gift" ], "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "status": { "enum": [ "pending", "active", "cancelled" ], "type": "string" }, "tenant_name": { "type": "string" }, "term_months": { "default": 1, "enum": [ 1, 3, 6, 12 ], "type": "integer" } }, "required": [], "type": "object" }, "type": "array" }, "recharged_users": { "type": "integer" }, "registered_users": { "type": "integer" }, "sales": { "items": { "additionalProperties": false, "properties": { "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "quantity": { "type": "integer" }, "total_cents": { "type": "integer" } }, "required": [], "type": "object" }, "type": "array" }, "sold_subscriptions": { "type": "integer" }, "timezone": { "type": "string" }, "topup_total": { "type": "integer" }, "topups": { "items": { "additionalProperties": false, "properties": { "amount_cents": { "type": "integer" }, "credited_at": { "format": "date-time", "type": "string" }, "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "email": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "provider": { "description": "Original provider of the wallet top-up; refunds remain tied to this provider.", "enum": [ "paypal", "paddle", "waffo" ], "type": "string" }, "refunded_cents": { "type": "integer" }, "status": { "type": "string" }, "tenant_name": { "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "total": { "type": "integer" }, "totals": { "items": { "additionalProperties": false, "properties": { "consumption_cents": { "type": "integer" }, "consumption_refund_cents": { "type": "integer" }, "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "paypal_refund_cents": { "type": "integer" }, "recharge_cents": { "type": "integer" }, "wallet_refund_cents": { "description": "Executed wallet refunds/reversals across PayPal, Paddle and Waffo; excludes temporary refund holds.", "type": "integer" } }, "required": [], "type": "object" }, "type": "array" }, "upgrade_total": { "description": "Number of applied upgrades in the selected environment and reporting period, including free upgrades. Counted separately from initial package sales.", "type": "integer" }, "upgrades": { "items": { "additionalProperties": false, "properties": { "amount_cents": { "description": "Prorated amount actually paid; not the new full monthly price.", "type": "integer" }, "applied_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "email": { "type": "string" }, "ends_at": { "description": "Original package expiry, unchanged by the upgrade.", "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "plan_name": { "description": "Target package name.", "type": "string" }, "previous_plan_name": { "description": "Effective package before this upgrade.", "type": "string" }, "tenant_name": { "type": "string" } }, "required": [ "id", "email", "tenant_name", "plan_name", "previous_plan_name", "currency", "amount_cents", "applied_at", "ends_at" ], "type": "object" }, "type": "array" }, "waffo_totals": { "description": "Gross payments and cumulative refunds for both service purchases and wallet top-ups, grouped by original payment month and currency; not bank settlement.", "items": { "additionalProperties": false, "properties": { "currency": { "description": "Merchant identifier beginning MER_.", "type": "string" }, "paid_cents": { "description": "Frozen full service price in the smallest currency unit; no wallet recharge or mixed payment.", "type": "integer" }, "refunded_cents": { "description": "Frozen full service price in the smallest currency unit; no wallet recharge or mixed payment.", "type": "integer" } }, "required": [ "currency", "paid_cents", "refunded_cents" ], "type": "object" }, "type": "array" } }, "required": [], "type": "object" }, "RuntimeAPIPeriod": { "additionalProperties": false, "properties": { "api_calls": { "description": "Successful metered runtime API calls in scope; management requests are excluded.", "type": "integer" }, "api_hard_limit": { "description": "Whether runtime calls stop at the API allowance limit.", "type": "boolean" }, "api_overage_cents": { "description": "API overage charge in hundredths in this cycle.", "type": "integer" }, "api_unit_micros": { "description": "Price per excess runtime call in millionths.", "minimum": 0, "type": "integer" }, "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "currency": { "description": "Three-letter uppercase currency code, such as USD.", "pattern": "^[A-Z]{3}$", "type": "string" }, "included_api_calls": { "description": "null = unlimited; 0 = no included successful calls", "maximum": 1000000000000, "minimum": 0, "type": [ "integer", "null" ] }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "sandbox", "live" ], "type": "string" }, "month": { "description": "UTC month YYYY-MM; omitted query values use the current month. Billing jobs require a closed month.", "type": "string" }, "plan": { "description": "Stable billing plan identifier from the published catalog.", "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "price_version": { "description": "Frozen pricing revision; stale input may cause PLAN_VERSION_CONFLICT.", "type": "string" } }, "required": [], "type": "object" }, "RuntimeInput": { "additionalProperties": false, "properties": { "activation_id": { "description": "data.activation_id from the last successful activation. Required for validation, heartbeat, consume and deactivation; omit only on first activate.", "format": "uuid", "type": "string" }, "app_version": { "description": "Current app version, major.minor.patch, e.g. 1.0.0. Required for maintenance or version-range rules. Do not misreport a newer app as an older version.", "pattern": "^$|^(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})$", "type": "string" }, "device_id": { "description": "64-character lowercase hex SHA-256 calculated by the SDK from the product, system and hardware identity. Do not substitute a fixed value.", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "device_name": { "description": "Display name in the dashboard, up to 120 characters. It does not determine device identity.", "maxLength": 120, "type": "string" }, "device_profile": { "$ref": "#/components/schemas/DeviceProfile", "description": "SDK-generated machine profile. Supply as required by policies for hardware identity, VM rejection or hardware migration." }, "environment": { "description": "Commerce environment, pinned in both the connection and signed grant.", "enum": [ "live", "sandbox" ], "type": "string" }, "feature": { "description": "Feature identifier consumed.", "maxLength": 64, "type": "string" }, "identity_token": { "description": "One-use, typed Ed25519 Launch identity JWT; no entitlement claims are trusted as purchase rights.", "maxLength": 12288, "type": "string", "writeOnly": true }, "launch_connection_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "license_key": { "description": "Full customer key: lv_lic_ is a regular license key; lv_tmp_ is for initial transfer redemption. After success the SDK uses a machine-bound lv_dev_ credential. Not a vendor management API Key.", "pattern": "^(?:lv_(?:lic|tmp|dev)_[A-Za-z0-9_-]{43})?$", "type": "string", "writeOnly": true }, "product_id": { "description": "Product UUID; must match the license's product.", "format": "uuid", "type": "string" }, "quantity": { "description": "Units requested for this operation, integer 1–1000000000.", "maximum": 1000000000, "minimum": 1, "type": "integer" }, "request_logout_ticket": { "description": "SDK capability negotiation. Request an unlink-only logout ticket when no ticket is retained for the current binding. Omit it when a valid logout ticket is already retained; steady-state heartbeats avoid an extra ticket lookup.", "type": "boolean" }, "reservation_id": { "description": "Reservation ID; send this value to commit or cancel.", "format": "uuid", "type": "string" }, "reservation_seconds": { "default": 900, "description": "Optional reservation lifetime, 30–3600 seconds; default 900. It ends earlier at the period reset.", "maximum": 3600, "minimum": 30, "type": "integer" }, "session_id": { "description": "Required for floating licenses: generate a UUID per running instance and reuse it for that instance's requests. Optional for device-bound licenses.", "format": "uuid", "type": "string" } }, "required": [ "product_id", "license_key", "device_id" ], "type": "object" }, "RuntimePolicy": { "additionalProperties": false, "properties": { "heartbeat_seconds": { "anyOf": [ { "const": 0 }, { "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "Heartbeat interval while online, in seconds. 0 disables periodic heartbeats. Offline allowance is configured separately.", "type": "integer" }, "offline_mode": { "description": "limited: time-limited offline; none: no offline use; permanent: no extra offline time limit, but license expiration still applies.", "enum": [ "limited", "none", "permanent" ], "type": "string" }, "offline_seconds": { "description": "Allowed offline seconds: 1–31536000 for limited, 0 for none/permanent. This is not the heartbeat interval. New limited-offline policies require offline_seconds \u003e= 3 × heartbeat_seconds when heartbeats are enabled; floating seat leases must also span at least three heartbeat intervals.", "maximum": 31536000, "minimum": 0, "type": "integer" } }, "required": [ "heartbeat_seconds", "offline_mode", "offline_seconds" ], "type": "object" }, "RuntimeResult": { "additionalProperties": false, "properties": { "activation_id": { "description": "Device binding or runtime session UUID. Save for future licensing requests; not a license key.", "format": "uuid", "type": "string" }, "deactivated": { "description": "true on successful deactivation. Releases a binding or session; does not delete the license or reset its term.", "type": "boolean" }, "device_key": { "description": "Restricted device credential pinned to the device and binding version. Account-mode credentials also require a live authorization session and entitlement; they cannot reactivate a released binding.", "pattern": "^lv_dev_[A-Za-z0-9_-]{43}$", "type": "string" }, "heartbeat_seconds": { "anyOf": [ { "const": 0, "description": "Heartbeat interval in seconds: 0 disables it; otherwise 600–86400. Omission uses server defaults; independent of offline allowance." }, { "description": "Heartbeat interval in seconds: 0 disables it; otherwise 600–86400. Omission uses server defaults; independent of offline allowance.", "maximum": 86400, "minimum": 600, "type": "integer" } ], "description": "Suggested heartbeat seconds. The top-level field may be omitted for 0; runtime_policy.heartbeat_seconds in the signature is the authoritative policy value.", "type": "integer" }, "lease": { "$ref": "#/components/schemas/Lease", "description": "Server-signed license cache. Accept only after verifying with a pinned trusted public key and checking product/device. Not returned by deactivation or consume." }, "logout_ticket": { "$ref": "#/components/schemas/LogoutTicket", "description": "Unlink-only capability for this exact binding incarnation; keep out of runtime request logs." } }, "required": [ "activation_id" ], "type": "object" }, "SDKConfig": { "additionalProperties": false, "example": { "allow_http": false, "app_version": "", "base_url": "https://www.licentivo.com", "cache_path": "", "device_name": "My application", "license_key": "", "product_id": "11111111-1111-4111-8111-111111111111", "trusted_keys": { "66666666-6666-4666-8666-666666666666": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "properties": { "allow_http": { "description": "Whether HTTP is allowed, for local development only.", "type": "boolean" }, "app_version": { "description": "Current software major.minor.patch version.", "type": "string" }, "base_url": { "description": "License server origin, normally HTTPS, without /api/v1.", "type": "string" }, "cache_path": { "description": "Local cache path; empty lets the SDK choose a private user directory.", "type": "string" }, "device_name": { "description": "Human-readable device label, not a security identity.", "type": "string" }, "license_key": { "description": "Full customer license key supplied at activation. Product initialization code and example downloads do not contain this secret. Offline requests use the SDK-provided credential.", "type": "string" }, "product_id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "trusted_keys": { "additionalProperties": { "type": "string" }, "description": "Map from public-key UUID to Base64URL public key for pinned verification.", "type": "object" } }, "required": [ "base_url", "product_id", "license_key", "app_version", "device_name", "trusted_keys", "cache_path", "allow_http" ], "type": "object" }, "SDKExampleInfo": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "can_configure": { "type": "boolean" }, "duration_days": { "const": 3, "type": "integer" }, "starts_at_first_activation": { "type": "boolean" } }, "required": [], "type": "object" }, "SDKExampleSetting": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "duration_days": { "const": 3, "type": "integer" }, "policy_id": { "description": "Dedicated policy UUID; empty before initial setup.", "type": "string" }, "product_id": { "description": "Dedicated product UUID; empty before initial setup.", "type": "string" } }, "required": [ "available", "duration_days", "product_id", "policy_id" ], "type": "object" }, "SDKExampleSetup": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" } }, "required": [], "type": "object" }, "SDKExampleTrial": { "additionalProperties": false, "properties": { "duration_days": { "const": 3, "type": "integer" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "first_activated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "license_key": { "type": "string" }, "starts_at_first_activation": { "type": "boolean" }, "status": { "type": "string" } }, "required": [], "type": "object" }, "SDKInitializer": { "additionalProperties": false, "example": { "language": "go", "product_id": "11111111-1111-4111-8111-111111111111", "source": "const productID = \"11111111-1111-4111-8111-111111111111\"\nvar trustedKeys = map[string]string{\"66666666-6666-4666-8666-666666666666\": \"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\"}\n", "trusted_keys": { "66666666-6666-4666-8666-666666666666": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "properties": { "language": { "description": "SDK language identifier for the download bundle.", "type": "string" }, "product_id": { "description": "Product UUID in the current workspace.", "format": "uuid", "type": "string" }, "source": { "description": "Public product constants to paste into code; no customer activation secret.", "type": "string" }, "trusted_keys": { "additionalProperties": { "type": "string" }, "description": "Map from public-key UUID to Base64URL public key for pinned verification.", "type": "object" } }, "required": [ "product_id", "trusted_keys", "language", "source" ], "type": "object" }, "ScheduledPlan": { "additionalProperties": false, "properties": { "currency": { "description": "Three-letter uppercase currency code, such as USD.", "type": "string" }, "effective_month": { "description": "UTC month YYYY-MM when the schedule takes effect.", "type": "string" }, "plan": { "description": "Stable billing plan identifier from the published catalog.", "type": "string" }, "sandbox": { "description": "Sandbox environment.", "type": "boolean" } }, "required": [], "type": "object" }, "ScopedRefundPreview": { "additionalProperties": false, "properties": { "affected_purchases": { "items": { "$ref": "#/components/schemas/ScopedRefundPurchase" }, "type": "array" }, "auto_renewal_disabled": { "type": "boolean" }, "auto_renewal_enabled": { "type": "boolean" }, "cancellation_at": { "const": "approval", "type": "string" }, "pending_purchase_ids": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "pending_upgrade_ids": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "quote_hash": { "type": "string" }, "quoted_at": { "format": "date-time", "type": "string" }, "remaining_purchases": { "items": { "$ref": "#/components/schemas/ScopedRefundPurchase" }, "type": "array" }, "request": { "$ref": "#/components/schemas/CustomerRefundInput" }, "scope": { "enum": [ "purchase", "service" ], "type": "string" }, "totals": { "items": { "$ref": "#/components/schemas/ScopedRefundTotal" }, "type": "array" } }, "required": [], "type": "object" }, "ScopedRefundPurchase": { "additionalProperties": false, "properties": { "amount_cents": { "type": "integer" }, "approved_cents": { "type": "integer" }, "currency": { "type": "string" }, "ends_at": { "format": "date-time", "type": "string" }, "maximum_cents": { "type": "integer" }, "plan_name": { "type": "string" }, "purchase_id": { "format": "uuid", "type": "string" }, "requires_review": { "type": "boolean" }, "source": { "type": "string" }, "starts_at": { "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "ScopedRefundTotal": { "additionalProperties": false, "properties": { "amount_cents": { "type": "integer" }, "approved_cents": { "type": "integer" }, "currency": { "type": "string" }, "held_cents": { "type": "integer" }, "manual_cents": { "type": "integer" } }, "required": [], "type": "object" }, "ServiceCompensation": { "additionalProperties": false, "properties": { "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "incident_id": { "description": "Related service incident UUID.", "format": "uuid", "type": "string" }, "intervals": { "description": "Compensated time intervals returned as a JSON string.", "type": "string" }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "type": "string" }, "purchase_id": { "description": "Related package purchase UUID.", "format": "uuid", "type": "string" }, "seconds": { "description": "Seconds added as service compensation.", "type": "integer" } }, "required": [ "id", "incident_id", "mode", "seconds", "purchase_id", "created_at" ], "type": "object" }, "ServiceCompensationList": { "additionalProperties": false, "properties": { "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/ServiceCompensation" }, "type": "array" } }, "required": [ "items" ], "type": "object" }, "ServiceIncident": { "additionalProperties": false, "properties": { "affected_tenants": { "description": "JSON-encoded array of workspace IDs; [] is global.", "type": "string" }, "body": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "emergency": { "type": "boolean" }, "ends_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "kind": { "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [], "type": "object" }, "ServiceIncidentInput": { "additionalProperties": false, "properties": { "affected_tenants": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "body": { "type": "string" }, "emergency": { "type": "boolean" }, "ends_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "expected_version": { "type": "string" }, "id": { "type": "string" }, "kind": { "enum": [ "maintenance", "incident" ], "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "title": { "type": "string" } }, "required": [ "kind", "title", "body", "starts_at" ], "type": "object" }, "ServiceIncidentList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/ServiceIncident" }, "type": "array" }, "now": { "format": "date-time", "type": "string" }, "total": { "type": "integer" } }, "required": [], "type": "object" }, "SignedCapabilities": { "additionalProperties": false, "properties": { "app_version": { "description": "app version for this Launch authorization operation.", "pattern": "^(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})\\.(0|[1-9][0-9]{0,8})$", "type": "string" }, "binding_version": { "description": "Signed device binding generation, associated with the authorization session.", "minimum": 1, "type": "integer" }, "environment": { "description": "Commerce environment, pinned in both the connection and signed grant.", "enum": [ "live", "sandbox" ], "type": "string" }, "launch_connection_id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "license_model": { "description": "license model for this Launch authorization operation.", "enum": [ "node_locked", "floating" ], "type": "string" }, "maintenance_until": { "description": "maintenance until for this Launch authorization operation.", "type": "integer" }, "session_expires_at": { "description": "session expires at for this Launch authorization operation.", "maximum": 253402300799, "type": "integer" }, "session_id": { "description": "session id for this Launch authorization operation.", "format": "uuid", "type": "string" }, "version_released_at": { "description": "version released at for this Launch authorization operation.", "type": "integer" } }, "required": [ "license_model" ], "type": "object" }, "SigningKey": { "additionalProperties": false, "properties": { "active": { "description": "Current signing key flag; in a policy preview, the active device/session count.", "type": "boolean" }, "algorithm": { "const": "Ed25519", "description": "Signing algorithm, currently Ed25519.", "type": "string" }, "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "key_id": { "description": "Product signing key UUID used to select a verification key.", "format": "uuid", "type": "string" }, "public_key": { "description": "Base64URL-encoded Ed25519 public key; no private material.", "type": "string" }, "retired_at": { "anyOf": [ { "description": "Key retirement timestamp; null for current keys. Retired public keys remain available for verification.", "format": "date-time", "type": "string" }, { "description": "Key retirement timestamp; null for current keys. Retired public keys remain available for verification.", "type": "null" } ], "description": "Key retirement timestamp; null for current keys. Retired public keys remain available for verification." } }, "required": [ "key_id", "public_key", "active" ], "type": "object" }, "StateResult": { "additionalProperties": false, "example": { "id": "33333333-3333-4333-8333-333333333333", "status": "pending" }, "properties": { "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "status": { "description": "Current resource state; see the enum and operation notes.", "type": "string" } }, "required": [ "id", "status" ], "type": "object" }, "Subscription": { "additionalProperties": false, "properties": { "current": { "$ref": "#/components/schemas/Period", "description": "Default billing snapshot for the current UTC month." }, "next": { "anyOf": [ { "$ref": "#/components/schemas/PendingPlan", "description": "Scheduled next-month default plan, or null." }, { "description": "Scheduled next-month default plan, or null.", "type": "null" } ], "description": "Scheduled next-month default plan, or null." }, "sandbox": { "description": "This subscription preview returns true. Determine the actual payment environment from billing/payment settings, not this preview flag.", "type": "boolean" } }, "required": [], "type": "object" }, "Summary": { "additionalProperties": false, "properties": { "active_licenses": { "description": "Active, non-expired license count, including pending first activation.", "type": "integer" }, "licenses": { "description": "Number of non-archived licenses.", "type": "integer" }, "policies": { "description": "Number of non-archived policies.", "type": "integer" }, "products": { "description": "Product count in summary; per-product device usage groups in usage responses.", "type": "integer" } }, "required": [ "products", "policies", "licenses", "active_licenses" ], "type": "object" }, "SupportCase": { "additionalProperties": false, "properties": { "amount_cents": { "type": "integer" }, "approved_cents": { "type": "integer" }, "cancellation_preview": { "description": "JSON-encoded cancellation preview.", "type": "string" }, "cancellation_scope": { "type": "string" }, "change_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "decision": { "type": "string" }, "first_response_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "held_cents": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "incident_id": { "type": "string" }, "kind": { "type": "string" }, "manual_cents": { "type": "integer" }, "manual_refund_pending": { "type": "boolean" }, "mode": { "type": "string" }, "order_id": { "type": "string" }, "purchase_id": { "type": "string" }, "reason": { "type": "string" }, "refund_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "refund_totals": { "description": "JSON-encoded per-currency totals; never sum different currencies.", "type": "string" }, "request_id": { "type": "string" }, "response_due_at": { "format": "date-time", "type": "string" }, "review_due_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "scope_ids": { "type": "string" }, "status": { "type": "string" }, "subject": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [], "type": "object" }, "SupportCaseDetail": { "additionalProperties": false, "properties": { "case": { "$ref": "#/components/schemas/SupportCase" }, "messages": { "items": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "case_id": { "format": "uuid", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "staff": { "type": "boolean" }, "user_id": { "format": "uuid", "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "original_refund_receipts": { "items": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 0, "type": "integer" }, "currency": { "type": "string" }, "intent_id": { "format": "uuid", "type": "string" }, "refund_id": { "type": "string" } }, "type": "object" }, "type": "array" }, "original_refunds": { "items": { "$ref": "#/components/schemas/ProviderRefund" }, "type": "array" }, "refund_payments": { "items": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 0, "type": "integer" }, "currency": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "provider": { "type": "string" }, "provider_order_id": { "type": "string" }, "refunded_cents": { "minimum": 0, "type": "integer" }, "status": { "type": "string" } }, "type": "object" }, "type": "array" }, "refund_provider": { "type": "string" }, "refund_unverified": { "type": "boolean" }, "refunds": { "items": { "$ref": "#/components/schemas/PayPalRefund" }, "type": "array" } }, "required": [], "type": "object" }, "SupportCaseInput": { "additionalProperties": false, "properties": { "body": { "maxLength": 10000, "type": "string" }, "kind": { "enum": [ "support", "privacy", "appeal" ], "type": "string" }, "request_id": { "maxLength": 80, "type": "string" }, "subject": { "maxLength": 200, "type": "string" } }, "required": [ "subject", "body", "request_id" ], "type": "object" }, "SupportCaseList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/SupportCase" }, "type": "array" }, "now": { "format": "date-time", "type": "string" }, "total": { "type": "integer" } }, "required": [], "type": "object" }, "SupportContact": { "additionalProperties": false, "properties": { "email": { "description": "Public support email and Reply-To for billing mail. Empty hides contact. It does not change the existing SMTP From address or create an inbox.", "maxLength": 254, "type": "string" } }, "required": [ "email" ], "type": "object" }, "SupportReadInput": { "additionalProperties": false, "properties": { "last_message_id": { "format": "uuid", "type": "string" } }, "required": [ "last_message_id" ], "type": "object" }, "SupportReply": { "additionalProperties": false, "properties": { "body": { "maxLength": 10000, "type": "string" }, "expected_updated_at": { "format": "date-time", "type": "string" }, "status": { "enum": [ "", "reviewing", "awaiting_info", "resolved" ], "type": "string" } }, "required": [ "body" ], "type": "object" }, "SupportUnread": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "case_id": { "format": "uuid", "type": "string" }, "unread_messages": { "type": "integer" } }, "required": [], "type": "object" }, "type": "array" }, "unread_cases": { "type": "integer" }, "unread_messages": { "type": "integer" }, "unread_notices": { "type": "integer" } }, "required": [], "type": "object" }, "SystemSettings": { "additionalProperties": false, "properties": { "database": { "$ref": "#/components/schemas/DatabaseStatus" }, "environment": { "type": "string" }, "mail": { "$ref": "#/components/schemas/MailSettings" }, "public_url": { "format": "uri", "type": "string" } }, "required": [ "mail", "database" ], "type": "object" }, "TLSCertificateInfo": { "additionalProperties": false, "properties": { "algorithm": { "type": "string" }, "chain_length": { "maximum": 10, "minimum": 1, "type": "integer" }, "domains": { "items": { "type": "string" }, "type": "array" }, "fingerprint_sha256": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "issuer": { "type": "string" }, "not_after": { "format": "date-time", "type": "string" }, "not_before": { "format": "date-time", "type": "string" }, "self_signed": { "type": "boolean" }, "serial_number": { "type": "string" }, "subject": { "type": "string" } }, "required": [ "domains", "subject", "issuer", "not_before", "not_after", "fingerprint_sha256", "serial_number", "algorithm", "chain_length", "self_signed" ], "type": "object" }, "TLSCertificateInput": { "additionalProperties": false, "properties": { "certificate_pem": { "description": "PEM leaf certificate followed by its intermediate certificates, in order. Must match public_url. Only local development permits a self-signed certificate.", "maxLength": 32768, "type": "string", "writeOnly": true }, "expected_version": { "description": "Use version from GET /system/tls. Required for updates; concurrent replacement returns 409.", "type": "string" }, "private_key_pem": { "description": "Matching unencrypted PEM key (PKCS#8, RSA or EC). Never returned by any response.", "maxLength": 16384, "type": "string", "writeOnly": true } }, "required": [ "certificate_pem", "private_key_pem" ], "type": "object" }, "TLSCertificateResult": { "additionalProperties": false, "properties": { "certificate": { "$ref": "#/components/schemas/TLSCertificateInfo" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [ "certificate", "version", "updated_at" ], "type": "object" }, "TLSCertificateUpdateInput": { "additionalProperties": false, "properties": { "certificate_pem": { "description": "PEM leaf certificate followed by its intermediate certificates, in order. Must match public_url. Only local development permits a self-signed certificate.", "maxLength": 32768, "type": "string", "writeOnly": true }, "expected_version": { "description": "Use version from GET /system/tls. Required for updates; concurrent replacement returns 409.", "type": "string" }, "private_key_pem": { "description": "Matching unencrypted PEM key (PKCS#8, RSA or EC). Never returned by any response.", "maxLength": 16384, "type": "string", "writeOnly": true } }, "required": [ "certificate_pem", "private_key_pem", "expected_version" ], "type": "object" }, "TLSStatus": { "additionalProperties": false, "properties": { "address": { "type": "string" }, "certificate": { "anyOf": [ { "$ref": "#/components/schemas/TLSCertificateInfo" }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "http_redirect_address": { "type": "string" }, "public_url": { "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "version": { "type": "string" } }, "required": [ "enabled", "public_url", "address", "http_redirect_address", "certificate", "version", "updated_at" ], "type": "object" }, "TestMail": { "additionalProperties": false, "properties": { "to": { "format": "email", "type": "string" } }, "required": [ "to" ], "type": "object" }, "Token": { "additionalProperties": false, "properties": { "token": { "maxLength": 100, "minLength": 32, "type": "string", "writeOnly": true } }, "required": [ "token" ], "type": "object" }, "TokenPassword": { "additionalProperties": false, "properties": { "password": { "description": "12–128 UTF-8 bytes, not characters", "type": "string", "writeOnly": true }, "password_confirmation": { "description": "Required and must match password exactly", "type": "string", "writeOnly": true }, "token": { "maxLength": 100, "minLength": 32, "type": "string", "writeOnly": true } }, "required": [ "token", "password", "password_confirmation" ], "type": "object" }, "TransferCode": { "additionalProperties": false, "properties": { "activation_code": { "pattern": "^lv_tmp_[A-Za-z0-9_-]{43}$", "type": "string" }, "activation_id": { "format": "uuid", "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "license_id": { "format": "uuid", "type": "string" } }, "required": [ "activation_id", "activation_code", "expires_at", "license_id" ], "type": "object" }, "TranslationCheck": { "additionalProperties": false, "properties": { "connected": { "type": "boolean" }, "languages": { "items": { "$ref": "#/components/schemas/TranslationLanguage" }, "type": "array" }, "provider_usage": { "additionalProperties": false, "properties": { "character_count": { "type": "integer" }, "character_limit": { "type": "integer" } }, "required": [ "character_count", "character_limit" ], "type": "object" } }, "required": [ "connected", "languages", "provider_usage" ], "type": "object" }, "TranslationLanguage": { "additionalProperties": false, "properties": { "lang": { "description": "BCP 47 target code returned by DeepL v3, such as en-US or zh-Hant.", "type": "string" }, "name": { "type": "string" }, "usable_as_target": { "type": "boolean" } }, "required": [ "lang", "name", "usable_as_target" ], "type": "object" }, "TranslationOptions": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "languages": { "items": { "$ref": "#/components/schemas/TranslationLanguage" }, "type": "array" }, "provider": { "type": "string" } }, "required": [ "enabled", "languages", "provider" ], "type": "object" }, "TranslationSettings": { "additionalProperties": false, "properties": { "checked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "key_configured": { "type": "boolean" }, "languages": { "items": { "$ref": "#/components/schemas/TranslationLanguage" }, "type": "array" }, "local_usage": { "$ref": "#/components/schemas/TranslationUsage" }, "monthly_limit": { "description": "Local monthly character budget, independent of DeepL account quota and billing dates.", "type": "integer" }, "requests_per_minute": { "type": "integer" }, "tier": { "enum": [ "free", "pro" ], "type": "string" }, "version": { "type": "string" } }, "required": [ "enabled", "tier", "key_configured", "monthly_limit", "requests_per_minute", "languages", "checked_at", "version", "local_usage" ], "type": "object" }, "TranslationSettingsInput": { "additionalProperties": false, "properties": { "api_key": { "description": "Stored encrypted. Empty preserves the saved key unless clear_key is true. Changing key/tier requires another successful connection check.", "maxLength": 1000, "type": "string", "writeOnly": true }, "clear_key": { "type": "boolean" }, "enabled": { "type": "boolean" }, "expected_version": { "type": "string" }, "monthly_limit": { "maximum": 1000000000, "minimum": 1, "type": "integer" }, "requests_per_minute": { "maximum": 60, "minimum": 1, "type": "integer" }, "tier": { "enum": [ "free", "pro" ], "type": "string" } }, "required": [ "enabled", "tier", "monthly_limit", "requests_per_minute", "expected_version" ], "type": "object" }, "TranslationUsage": { "additionalProperties": false, "properties": { "characters": { "description": "Successful billed characters plus conservative reservations for requests with unknown results. Cache hits do not add usage.", "type": "integer" }, "month": { "description": "UTC calendar month YYYY-MM.", "type": "string" } }, "required": [ "month", "characters" ], "type": "object" }, "Trial": { "additionalProperties": false, "properties": { "base_url": { "type": "string" }, "duration_days": { "const": 7, "type": "integer" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "isolated": { "type": "boolean" }, "key": { "type": "string", "writeOnly": true }, "license_id": { "format": "uuid", "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "trusted_keys": { "items": { "$ref": "#/components/schemas/SigningKey" }, "type": "array" } }, "required": [ "product_id", "license_id", "key", "trusted_keys" ], "type": "object" }, "UpgradeList": { "additionalProperties": false, "properties": { "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/PlanUpgrade" }, "type": "array" }, "total": { "description": "Total matching records, not the current page length.", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "UpgradePart": { "additionalProperties": false, "description": "A frozen upgrade calculation for one current or future prepaid period. change.amount_cents is this period’s difference; only the parent quote charges the combined sum.", "properties": { "change": { "$ref": "#/components/schemas/PlanUpgrade", "description": "Pricing and entitlement change for this upgrade part." }, "ends_at": { "description": "Package or cycle end timestamp, UTC; may be null before activation.", "format": "date-time", "type": "string" }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "source": { "description": "Entitlement source, such as purchase or gift.", "enum": [ "purchase", "gift", "auto_renewal" ], "type": "string" }, "starts_at": { "description": "Package or cycle start timestamp, UTC.", "format": "date-time", "type": "string" } }, "required": [ "id", "source", "starts_at", "ends_at", "change" ], "type": "object" }, "UpgradeQuoteInput": { "additionalProperties": false, "properties": { "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "plan": { "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "price_version": { "type": "string" }, "request_id": { "maxLength": 80, "type": "string" } }, "required": [ "plan", "currency", "price_version", "request_id" ], "type": "object" }, "Usage": { "additionalProperties": false, "properties": { "active_devices": { "description": "For the current UTC month: Current registered product/device occupancy, independent of monthly device-use history. Ordinary registrations remain counted while offline until released. Floating sessions count only while their leases are valid and deduplicate by hardware, falling back to device identity. Release or final floating-session expiry returns capacity; valid registrations continue across quota-month boundaries. Isolated SDK trial registrations are excluded. For another UTC month: distinct device-use history recorded in that month.", "type": "integer" }, "api_calls": { "description": "Successful activate, validate, heartbeat and deactivate calls in the selected UTC month and payment environment. Failures, valid idempotent replays, local checks and software feature consumption are excluded. For purchased-package allowance comparisons use purchased.api_calls, which follows the package quota month.", "type": "integer" }, "api_period": { "anyOf": [ { "$ref": "#/components/schemas/RuntimeAPIPeriod", "description": "Default API allowance snapshot for this UTC month; may be null when disabled." }, { "description": "Default API allowance snapshot for this UTC month; may be null when disabled.", "type": "null" } ], "description": "Default UTC-month API allowance; null if unavailable. With a purchased package, use purchased.api_calls and purchased.included_api_calls for the current quota month." }, "billable_devices": { "description": "With no active purchase in the current UTC month, current device occupancy under the default allowance. For closed months or prepaid coverage, the saved default-period billing peak. Estimates use at least the recorded peak; releasing a device does not refund incurred charges.", "type": "integer" }, "estimated_total_cents": { "description": "Estimated default monthly device charge in hundredths of a currency unit.", "type": "integer" }, "estimated_total_micros": { "description": "Estimated default monthly device charge in millionths; not an aggregate of all package charges.", "type": "integer" }, "month": { "description": "UTC month YYYY-MM; omitted query values use the current month. Billing jobs require a closed month.", "type": "string" }, "operations": { "description": "Successful metered call counts grouped by activate, validate, heartbeat and deactivate.", "items": { "additionalProperties": false, "properties": { "count": { "description": "Count in the current group, or number of records processed by a batch.", "type": "integer" }, "operation": { "description": "Operation name; batches support create/renew/revoke/apply_policy and offline requests activate/deactivate.", "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "overage_devices": { "description": "Devices exceeding the included allowance.", "type": "integer" }, "period": { "anyOf": [ { "$ref": "#/components/schemas/Period", "description": "Default UTC monthly billing snapshot; meter rules use month/day/lifetime and usage rows use the concrete period key." }, { "description": "Default UTC monthly billing snapshot; meter rules use month/day/lifetime and usage rows use the concrete period key.", "type": "null" } ], "description": "Frozen default/history UTC billing allowance. Null when no such period exists and the default offer is disabled; an active purchase remains usable." }, "products": { "description": "Product count in summary; per-product device usage groups in usage responses.", "items": { "additionalProperties": false, "properties": { "active_devices": { "description": "Per-product current occupancy for the current UTC month; historical distinct device use for a past UTC month.", "type": "integer" }, "product_id": { "description": "Product UUID in the current workspace.", "format": "uuid", "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "purchased": { "anyOf": [ { "$ref": "#/components/schemas/PlanPurchase", "description": "Current active rolling-month package, or null." }, { "description": "Current active rolling-month package, or null.", "type": "null" } ], "description": "Active package in the current payment environment, returned only for the current UTC month. Headline device quota must use purchased.included_devices, not period.included_devices." }, "purchased_active_devices": { "description": "When purchased is present: Current registered product/device occupancy, independent of monthly device-use history. Ordinary registrations remain counted while offline until released. Floating sessions count only while their leases are valid and deduplicate by hardware, falling back to device identity. Release or final floating-session expiry returns capacity; valid registrations continue across quota-month boundaries. Isolated SDK trial registrations are excluded.", "type": "integer" }, "sandbox": { "description": "Sandbox environment.", "type": "boolean" }, "timezone": { "description": "Usage aggregation timezone, UTC.", "type": "string" }, "warning": { "description": "normal, near_quota or quota_reached for the default device allowance.", "type": "string" } }, "required": [], "type": "object" }, "UsageDevice": { "additionalProperties": false, "properties": { "device_id": { "description": "Product-scoped device fingerprint, usually 64 lowercase hex characters, derived by the SDK.", "type": "string" }, "first_seen_at": { "description": "First device activity timestamp in this UTC month.", "format": "date-time", "type": "string" }, "last_seen_at": { "description": "Last device activity timestamp observed by the server, UTC.", "format": "date-time", "type": "string" }, "month": { "description": "UTC month YYYY-MM; omitted query values use the current month. Billing jobs require a closed month.", "type": "string" }, "product_id": { "description": "Product UUID in the current workspace.", "format": "uuid", "type": "string" } }, "required": [], "type": "object" }, "UsageDeviceList": { "additionalProperties": false, "properties": { "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/UsageDevice" }, "type": "array" }, "limit": { "description": "Page size, default 25, range 1–100.", "type": "integer" }, "offset": { "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "type": "integer" }, "total": { "description": "Total matching records, not the current page length.", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "Verified": { "additionalProperties": false, "properties": { "verified": { "type": "boolean" } }, "required": [ "verified" ], "type": "object" }, "VersionedActivationReleaseInput": { "additionalProperties": false, "properties": { "expected_generation": { "description": "Binding generation displayed in the current device list. Required for Launch account bindings; stale versions never release a newer binding.", "minimum": 1, "type": "integer" }, "operation_id": { "description": "Stable operation UUID for retry recovery. Required for Launch account bindings.", "format": "uuid", "type": "string" } }, "required": [], "type": "object" }, "WaffoCheck": { "additionalProperties": false, "properties": { "connected": { "description": "enabled", "type": "boolean" }, "mode": { "description": "Payment environment. Sandbox and live records are isolated.", "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [ "connected", "mode" ], "type": "object" }, "WaffoOrder": { "additionalProperties": false, "properties": { "amount_cents": { "description": "Frozen full service price in the smallest currency unit; no wallet recharge or mixed payment.", "type": "integer" }, "applied_at": { "anyOf": [ { "description": "UTC deadline for the original checkout creation window.", "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "UTC time the verified payment activated service or credited a wallet top-up. Null purchase_id and upgrade_id identify a top-up." }, "checkout_expires_at": { "description": "UTC deadline for the original checkout creation window.", "format": "date-time", "type": "string" }, "created_at": { "description": "UTC deadline for the original checkout creation window.", "format": "date-time", "type": "string" }, "currency": { "description": "Merchant identifier beginning MER_.", "type": "string" }, "id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" }, "mode": { "description": "Payment environment. Sandbox and live records are isolated.", "enum": [ "sandbox", "live" ], "type": "string" }, "paid_at": { "anyOf": [ { "description": "UTC deadline for the original checkout creation window.", "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "UTC time at which the backend verified a completed Waffo transaction." }, "provider_order_id": { "anyOf": [ { "description": "Merchant identifier beginning MER_.", "type": "string" }, { "type": "null" } ], "description": "Original ORD_ identifier recovered from a verified API response." }, "purchase_id": { "anyOf": [ { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Existing pending service purchase or renewal; mutually exclusive with upgrade_id." }, "refunded_cents": { "description": "Frozen full service price in the smallest currency unit; no wallet recharge or mixed payment.", "type": "integer" }, "request_id": { "description": "Merchant identifier beginning MER_.", "type": "string" }, "status": { "description": "Payment lifecycle, including paid_unapplied when collected funds need operator review and refund.", "enum": [ "creating", "created", "completed", "paid_unapplied", "partially_refunded", "refunded" ], "type": "string" }, "upgrade_id": { "anyOf": [ { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Existing pending upgrade quote; mutually exclusive with purchase_id." } }, "required": [ "id", "request_id", "mode", "provider_order_id", "purchase_id", "upgrade_id", "currency", "amount_cents", "refunded_cents", "status", "checkout_expires_at", "paid_at", "applied_at", "created_at" ], "type": "object" }, "WaffoOrderInput": { "additionalProperties": false, "description": "Pay one frozen purchase/upgrade, or create a wallet top-up with amount and currency and no service IDs. A stable request_id returns the original payment; changing its intent, amount or currency is rejected. Only independently verified completed payments credit a wallet or activate service. Top-up returns go to the wallet. Retries reuse the original provider idempotency key only within its original checkout creation window.", "oneOf": [ { "not": { "anyOf": [ { "required": [ "amount" ] }, { "required": [ "currency" ] } ] }, "properties": { "purchase_id": { "format": "uuid", "type": "string" }, "upgrade_id": { "type": "null" } }, "required": [ "purchase_id" ] }, { "not": { "anyOf": [ { "required": [ "amount" ] }, { "required": [ "currency" ] } ] }, "properties": { "purchase_id": { "type": "null" }, "upgrade_id": { "format": "uuid", "type": "string" } }, "required": [ "upgrade_id" ] }, { "properties": { "purchase_id": { "type": "null" }, "upgrade_id": { "type": "null" } }, "required": [ "amount", "currency" ] } ], "properties": { "amount": { "description": "Required only for a wallet top-up. A decimal display amount within the configured limits. Service orders reject client amounts.", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "type": "string" }, "currency": { "description": "Required only for a wallet top-up and must be enabled for this provider.", "type": "string" }, "overage_accepted": { "description": "Separate explicit authorisation of displayed chargeable overage.", "type": "boolean" }, "policy_version": { "description": "Currently published immutable policy version. Required for consent-protected actions after the operator publishes a policy, in either payment environment.", "type": "string" }, "purchase_id": { "anyOf": [ { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Existing pending service purchase or renewal; mutually exclusive with upgrade_id." }, "request_id": { "description": "Stable caller-generated request key. Replays return the original checkout.", "maxLength": 80, "type": "string" }, "terms_accepted": { "description": "Explicit unchecked-by-default acceptance.", "type": "boolean" }, "upgrade_id": { "anyOf": [ { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Existing pending upgrade quote; mutually exclusive with purchase_id." } }, "required": [ "request_id" ], "type": "object" }, "WaffoOrderList": { "additionalProperties": false, "properties": { "items": { "description": "items", "items": { "$ref": "#/components/schemas/WaffoOrder" }, "type": "array" }, "total": { "description": "Frozen full service price in the smallest currency unit; no wallet recharge or mixed payment.", "type": "integer" } }, "required": [ "items", "total" ], "type": "object" }, "WaffoOrderResult": { "additionalProperties": false, "properties": { "approval_url": { "description": "Short-lived authenticated checkout URL, or empty after payment, expiry, or channel disablement. Never log or cache it.", "type": "string" }, "order": { "$ref": "#/components/schemas/WaffoOrder", "description": "order" }, "return_url": { "description": "Wallet dashboard URL for a top-up, pricing reconciliation URL for a service payment. A return URL alone never proves payment.", "format": "uri", "type": "string" } }, "required": [ "order", "approval_url", "return_url" ], "type": "object" }, "WaffoSettings": { "additionalProperties": false, "properties": { "currencies": { "description": "currencies", "items": { "description": "Merchant identifier beginning MER_.", "type": "string" }, "type": "array" }, "enabled": { "description": "enabled", "type": "boolean" }, "maximum_cents": { "description": "Maximum wallet top-up in minor currency units; defaults to 100000 and must not be less than minimum_cents.", "maximum": 100000000, "minimum": 1, "type": "integer" }, "merchant_id": { "description": "Merchant identifier beginning MER_.", "type": "string" }, "minimum_cents": { "description": "Minimum wallet top-up in minor currency units; defaults to 100.", "maximum": 100000000, "minimum": 1, "type": "integer" }, "mode": { "description": "Payment environment. Sandbox and live records are isolated.", "enum": [ "sandbox", "live" ], "type": "string" }, "private_key_configured": { "description": "enabled", "type": "boolean" }, "product_id": { "description": "Merchant identifier beginning MER_.", "type": "string" }, "store_id": { "description": "Merchant identifier beginning MER_.", "type": "string" }, "version": { "description": "Merchant identifier beginning MER_.", "type": "string" }, "webhook_public_key": { "description": "Merchant identifier beginning MER_.", "type": "string" }, "webhook_url": { "description": "webhook url", "format": "uri", "type": "string" } }, "required": [ "enabled", "mode", "merchant_id", "store_id", "product_id", "currencies", "private_key_configured", "webhook_public_key", "version", "webhook_url" ], "type": "object" }, "WaffoSettingsInput": { "additionalProperties": false, "properties": { "clear_private_key": { "description": "enabled", "type": "boolean" }, "currencies": { "description": "currencies", "items": { "description": "Merchant identifier beginning MER_.", "type": "string" }, "type": "array" }, "enabled": { "description": "enabled", "type": "boolean" }, "expected_version": { "description": "Merchant identifier beginning MER_.", "type": "string" }, "maximum_cents": { "description": "Maximum wallet top-up in minor currency units; defaults to 100000 and must not be less than minimum_cents.", "maximum": 100000000, "minimum": 1, "type": "integer" }, "merchant_id": { "description": "Merchant identifier beginning MER_.", "type": "string" }, "minimum_cents": { "description": "Minimum wallet top-up in minor currency units; defaults to 100.", "maximum": 100000000, "minimum": 1, "type": "integer" }, "mode": { "description": "Payment environment. Sandbox and live records are isolated.", "enum": [ "sandbox", "live" ], "type": "string" }, "private_key": { "description": "RSA signing private key. Encrypted at rest; empty preserves the saved key.", "maxLength": 8192, "type": "string", "writeOnly": true }, "product_id": { "description": "Merchant identifier beginning MER_.", "type": "string" }, "store_id": { "description": "Merchant identifier beginning MER_.", "type": "string" }, "webhook_public_key": { "description": "Optional official webhook public key override. Empty uses the SDK key for the selected environment.", "maxLength": 8192, "type": "string" } }, "required": [ "enabled", "mode", "merchant_id", "store_id", "product_id", "currencies", "expected_version" ], "type": "object" }, "WaffoWebhookEvent": { "description": "Raw Waffo event authenticated with X-Waffo-Signature, the selected environment public key, store, and mode. Payment/refunds are independently verified through the API.", "type": "object" }, "Wallet": { "additionalProperties": false, "properties": { "balance_cents": { "description": "Wallet balance, or balance after the entry, in hundredths.", "type": "integer" }, "currency": { "description": "Three-letter uppercase currency code, such as USD.", "pattern": "^[A-Z]{3}$", "type": "string" }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [], "type": "object" }, "WalletEntry": { "additionalProperties": false, "properties": { "amount_cents": { "description": "Amount in hundredths; ledger entries may be positive credits or negative debits.", "type": "integer" }, "balance_cents": { "description": "Wallet balance, or balance after the entry, in hundredths.", "type": "integer" }, "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "currency": { "description": "Three-letter uppercase currency code, such as USD.", "pattern": "^[A-Z]{3}$", "type": "string" }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "kind": { "description": "plan_upgrade records a paid upgrade. paypal_refund_reserve holds available wallet funds; paypal_refund_release removes that hold; paypal_refund records the confirmed cash refund. Reserve/release movements are not cash payments and cancel out when settlement completes.", "type": "string" }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "sandbox", "live" ], "type": "string" }, "reference": { "description": "Related business reference used for tracing.", "type": "string" } }, "required": [], "type": "object" }, "WalletEntryList": { "additionalProperties": false, "properties": { "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/WalletEntry" }, "type": "array" }, "limit": { "description": "Page size, default 25, range 1–100.", "type": "integer" }, "offset": { "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "type": "integer" }, "total": { "description": "Total matching records, not the current page length.", "type": "integer" } }, "required": [], "type": "object" }, "WalletRefundRequest": { "additionalProperties": false, "properties": { "amount_cents": { "minimum": 1, "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "customer_email": { "description": "Administrator list only.", "type": "string" }, "decision": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "order_id": { "format": "uuid", "type": "string" }, "reason": { "type": "string" }, "refund_id": { "format": "uuid", "type": [ "string", "null" ] }, "refund_status": { "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "review_status": { "enum": [ "pending", "approved", "declined", "cancelled" ], "type": "string" }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending_review", "refund_pending", "refunded", "refund_failed", "declined", "cancelled" ], "type": "string" }, "tenant_name": { "description": "Administrator list only.", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "order_id", "mode", "currency", "amount_cents", "reason", "status", "review_status" ], "type": "object" }, "WalletRefundRequestInput": { "additionalProperties": false, "properties": { "amount": { "description": "Positive amount, capped by both unrefunded order value and current unspent wallet credit.", "pattern": "^[0-9]+(?:\\.[0-9]{1,2})?$", "type": "string" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "reason": { "maxLength": 255, "minLength": 1, "type": "string" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "amount", "reason", "request_id", "mode" ], "type": "object" }, "WalletRefundRequestList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/WalletRefundRequest" }, "type": "array" }, "limit": { "type": "integer" }, "mode": { "enum": [ "sandbox", "live" ], "type": "string" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "items", "total", "mode" ], "type": "object" }, "WalletRefundReview": { "additionalProperties": false, "properties": { "approve": { "type": "boolean" }, "decision": { "maxLength": 1000, "minLength": 1, "type": "string" }, "expected_updated_at": { "format": "date-time", "type": "string" } }, "required": [ "approve", "decision" ], "type": "object" }, "WalletResult": { "additionalProperties": false, "properties": { "currencies": { "description": "Allowed currency codes in this environment.", "items": { "pattern": "^[A-Z]{3}$", "type": "string" }, "type": "array" }, "items": { "description": "Returned records; see items[] for element fields. Some empty collections can be null; see type.", "items": { "$ref": "#/components/schemas/Wallet" }, "type": "array" }, "maximum_cents": { "description": "Maximum recharge for the enabled wallet top-up channel, in minor units.", "type": "integer" }, "minimum_cents": { "description": "Minimum recharge for the enabled wallet top-up channel, in minor units.", "type": "integer" }, "mode": { "description": "License term: perpetual, timed or trial; billing objects use sandbox or live payment mode.", "enum": [ "sandbox", "live" ], "type": "string" }, "payment_channels": { "description": "Available payment channel configuration. Show only enabled channels matching the active billing environment and purchase currency.", "items": { "$ref": "#/components/schemas/PaymentChannel" }, "type": "array" }, "paypal_enabled": { "description": "Whether PayPal is enabled in this payment environment.", "type": "boolean" } }, "required": [], "type": "object" }, "WebhookAttempt": { "additionalProperties": false, "properties": { "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "delivery_id": { "description": "Delivery task UUID for this attempt.", "format": "uuid", "type": "string" }, "duration_ms": { "description": "Delivery duration in milliseconds.", "type": "integer" }, "error": { "description": "Error object or delivery failure category; see child fields or the current type.", "type": "string" }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "number": { "description": "Cumulative attempt sequence number.", "type": "integer" }, "status_code": { "description": "HTTP status for this attempt; may be 0 on transport failure.", "type": "integer" } }, "required": [ "id", "delivery_id", "number", "status_code", "error", "duration_ms", "created_at" ], "type": "object" }, "WebhookDelivery": { "additionalProperties": false, "properties": { "attempts": { "description": "Cumulative task attempt count.", "type": "integer" }, "available_at": { "description": "Earliest UTC time the task may run.", "format": "date-time", "type": "string" }, "created_at": { "description": "Creation time in UTC; offline requests use Unix seconds.", "format": "date-time", "type": "string" }, "delivered_at": { "anyOf": [ { "description": "Successful delivery timestamp, or null.", "format": "date-time", "type": "string" }, { "description": "Successful delivery timestamp, or null.", "type": "null" } ], "description": "Successful delivery timestamp, or null." }, "endpoint_id": { "description": "Webhook endpoint UUID.", "format": "uuid", "type": "string" }, "event_id": { "description": "Original event UUID; use it for receiver deduplication.", "format": "uuid", "type": "string" }, "id": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" }, "last_error": { "description": "Most recent failure category; may be empty.", "type": "string" }, "last_status": { "description": "Most recent HTTP response status; may be 0 if no response arrived.", "type": "integer" }, "status": { "description": "Current resource state; see the enum and operation notes.", "type": "string" } }, "required": [ "id", "endpoint_id", "event_id", "status", "attempts", "available_at", "last_status", "last_error", "delivered_at", "created_at" ], "type": "object" }, "WebhookEvent": { "description": "Exact signed PayPal event, verified with PayPal API", "type": "object" }, "WebhookReceived": { "additionalProperties": false, "properties": { "ignored": { "type": "boolean" }, "received": { "type": "boolean" } }, "required": [], "type": "object" } }, "securitySchemes": { "closureExport": { "description": "Restricted 15-minute download credential, never a dashboard session. Production uses __Host-licentivo_closure_export; always capped at the original closure deadline.", "in": "cookie", "name": "licentivo_closure_export", "type": "apiKey" }, "customerSession": { "description": "Production uses __Host-licenova_customer; buyer identity is independent of the vendor session.", "in": "cookie", "name": "licenova_customer", "type": "apiKey" }, "managementKey": { "bearerFormat": "lv_api_...", "scheme": "bearer", "type": "http" }, "session": { "description": "Production uses __Host-licenova_session", "in": "cookie", "name": "licenova_session", "type": "apiKey" } } }, "info": { "description": "Licentivo management and licensing API. Supports signed runtime grants, node-locked and floating licenses, current activation device quotas, monthly API usage, metered software features, Launch account sessions, prepaid packages, gifts, wallet automatic renewal and whole-coverage upgrades. PayPal, Paddle and Waffo support verified payments and original-route refunds. Customer policies, approval-scoped cancellation, support, compensation, data export and logical account closure are included. Payment environments and currencies are isolated; private credentials are encrypted and never returned.", "title": "Licentivo API", "version": "0.12.0", "x-document-language": "en" }, "openapi": "3.1.0", "paths": { "/api/v1/account/closure-export.zip": { "get": { "description": "Both credential and original closure deadline are rechecked for every request and after generation. Restoring a backup cannot restart the window.", "operationId": "get__api_v1_account_closure_export_zip", "parameters": [], "responses": { "200": { "content": { "application/zip": { "schema": { "format": "binary", "type": "string" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "closureExport": [] } ], "summary": "Download during the 30-day closure window" } }, "/api/v1/account/closure-export/session": { "post": { "description": "Requires the verified original email/password and a confirmed closure still within exactly 30 days. The 15-minute cookie is capped at the original deadline, rate limited, and cannot authorise normal API/dashboard access.", "operationId": "post__api_v1_account_closure_export_session", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosureExportLogin" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ClosureExportCredential" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [], "summary": "Verify a closed account for restricted export" } }, "/api/v1/account/data-export": { "get": { "description": "Owner downloads include workspace business CSVs. A member’s personal archive contains their own profile, posts and requests. Credential secrets/hashes and signing private keys are excluded.", "operationId": "get__api_v1_account_data_export", "parameters": [], "responses": { "200": { "content": { "application/zip": { "schema": { "format": "binary", "type": "string" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Download own personal and authorised data", "x-required-role": "session" } }, "/api/v1/account/deletions": { "get": { "description": "", "operationId": "get__api_v1_account_deletions", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AccountClosureList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Read own logical closure requests", "x-required-role": "session" }, "post": { "description": "Owner closure must select workspace; a member can close only their account. Confirmation revokes sessions/API keys but preserves data. Export is allowed for 30 days after confirmation.", "operationId": "post__api_v1_account_deletions", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountClosureInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AccountClosure" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Request logical account or workspace closure", "x-required-role": "session" } }, "/api/v1/account/deletions/{id}/cancel": { "post": { "description": "", "operationId": "post__api_v1_account_deletions__id__cancel", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Withdraw an unconfirmed closure", "x-required-role": "session" } }, "/api/v1/account/legal-acceptances": { "get": { "description": "", "operationId": "get__api_v1_account_legal_acceptances", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LegalAcceptanceList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Read own legal acceptance receipts", "x-required-role": "session" } }, "/api/v1/account/profile": { "patch": { "description": "Requires the current password. A new login email receives a single-use verification link, valid for 30 minutes. The current verified login email and access remain unchanged until confirmation.", "operationId": "patch__api_v1_account_profile", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCorrection" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Correct own name or request a login email change", "x-required-role": "session" } }, "/api/v1/activate": { "post": { "description": "Authenticated by product_id + license_key + device_id. No cookie/CSRF/vendor key. activation_id required except activate. Each successful request consumes one API call; idempotent replay and failures do not. Overages debit wallet atomically or return API_QUOTA_EXCEEDED/API_BALANCE_INSUFFICIENT. Workspace device quota follows current activations. Release returns capacity; floating lease expiry also returns capacity, while an offline ordinary registration remains counted. Device overage is charged only when the quota-month billing peak increases beyond already paid capacity; release does not refund incurred fees. API usage is separate.", "operationId": "post_api_v1_activate", "parameters": [ { "description": "Generate a new key for each operation; retries keep the same key and body. Maximum 80 characters, no whitespace. Optional for validation and heartbeat.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "Runtime activate" } }, "/api/v1/activations": { "get": { "operationId": "get_api_v1_activations", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Page size, default 25, range 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "license_id", "schema": { "description": "License UUID, distinct from the lv_lic_ secret.", "format": "uuid", "type": "string" } }, { "in": "query", "name": "product_id", "schema": { "description": "Product UUID in the current workspace.", "format": "uuid", "type": "string" } }, { "in": "query", "name": "status", "schema": { "description": "Current resource state; see the enum and operation notes.", "enum": [ "active", "released" ], "type": "string" } }, { "in": "query", "name": "q", "schema": { "description": "Search text; target fields and maximum length depend on the operation.", "maxLength": 120, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "created_at": "2026-10-18T00:00:00Z", "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "device_name": "Office PC", "generation": 1, "id": "44444444-4444-4444-8444-444444444444", "last_seen_at": "2026-10-18T00:00:00Z", "license_id": "33333333-3333-4333-8333-333333333333", "product_id": "11111111-1111-4111-8111-111111111111", "released_at": null, "status": "active", "virtual_machine": false } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ActivationList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List activations", "x-management-reference": { "group": "devices" }, "x-required-scope": "read" } }, "/api/v1/activations/{id}/release": { "post": { "operationId": "post_api_v1_activations_by_id_release", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "expected_generation": 1, "operation_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/VersionedActivationReleaseInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "status": "released" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StateResult", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Release activation", "x-management-reference": { "group": "devices" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/api-keys": { "get": { "operationId": "get_api_v1_api-keys", "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "allow_http": false, "created_at": "2026-10-18T00:00:00Z", "expires_at": "2026-10-18T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "name": "Report app", "prefix": "lv_api_AAAAAAA", "revoked": false, "scope": "read" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/KeyList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "List API keys", "x-management-reference": { "group": "keys" }, "x-required-role": "owner", "x-required-scope": "owner_session" }, "post": { "operationId": "post_api_v1_api-keys", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "description": "Required for cookie-authenticated writes; obtain data.csrf_token from GET /api/v1/auth/csrf and retain the cookies.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "allow_http": false, "expires_days": 90, "name": "Order system", "scope": "write" }, "schema": { "$ref": "#/components/schemas/KeyCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "expires_at": "2027-01-16T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "key": "lv_api_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "prefix": "lv_api_AAAAAAA" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/KeySecret", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "Create API key", "x-management-reference": { "group": "keys" }, "x-required-role": "owner", "x-required-scope": "owner_session" } }, "/api/v1/api-keys/{id}": { "delete": { "operationId": "delete_api_v1_api-keys_by_id", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "description": "Required for cookie-authenticated writes; obtain data.csrf_token from GET /api/v1/auth/csrf and retain the cookies.", "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "Revoke API key", "x-management-reference": { "group": "keys" }, "x-required-role": "owner", "x-required-scope": "owner_session" }, "patch": { "description": "Owner session and CSRF token required. Updates this active key only; rotation preserves the setting. Does not alter existing Launch connections or runtime grants. This setting does not enable HTTP on the Licentivo API.", "operationId": "patch_api_v1_api-keys_by_id", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "description": "Required for cookie-authenticated writes; obtain data.csrf_token from GET /api/v1/auth/csrf and retain the cookies.", "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "allow_http": true }, "schema": { "$ref": "#/components/schemas/KeyUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "allow_http": false, "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/KeyUpdated", "description": "Response data for the completed operation." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "Update HTTP site access", "x-management-reference": { "group": "keys" }, "x-required-role": "owner", "x-required-scope": "owner_session" } }, "/api/v1/api-keys/{id}/rotate": { "post": { "operationId": "post_api_v1_api-keys_by_id_rotate", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "description": "Required for cookie-authenticated writes; obtain data.csrf_token from GET /api/v1/auth/csrf and retain the cookies.", "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "key": "lv_api_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", "prefix": "lv_api_BBBBBBB" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/KeyRotated", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "Rotate API key", "x-management-reference": { "group": "keys" }, "x-required-role": "owner", "x-required-scope": "owner_session" } }, "/api/v1/audit-logs": { "get": { "operationId": "get_api_v1_audit-logs", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Page size, default 25, range 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "action": "license.create", "actor_id": "33333333-3333-4333-8333-333333333333", "actor_kind": "api_key", "created_at": "2026-10-18T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "request_id": "55555555-5555-4555-8555-555555555555", "resource_id": "" } ], "limit": 25, "offset": 0 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AuditList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List audit logs", "x-management-reference": { "group": "usage" }, "x-required-scope": "read" } }, "/api/v1/auth/accept-invitation": { "post": { "operationId": "post_api_v1_auth_accept-invitation", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenPassword" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PasswordSet" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "accept-invitation" } }, "/api/v1/auth/change-password": { "post": { "operationId": "post_api_v1_auth_change-password", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePassword" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PasswordSet" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "Revoke all account credentials and set password" } }, "/api/v1/auth/confirm-email-change": { "post": { "description": "Verify the encrypted single-use challenge. Only successful confirmation changes the login email, verifies it and revokes existing sessions, API keys and authentication links. Expired, replaced or password-invalidated challenges cannot change the account.", "operationId": "post__api_v1_auth_confirm_email_change", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailChangeConfirmation" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [], "summary": "Confirm a new login email" } }, "/api/v1/auth/csrf": { "get": { "operationId": "get_api_v1_auth_csrf", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CSRF" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "Issue session-bound CSRF token" } }, "/api/v1/auth/forgot-password": { "post": { "operationId": "post_api_v1_auth_forgot-password", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Notice" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "forgot-password" } }, "/api/v1/auth/login": { "post": { "operationId": "post_api_v1_auth_login", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Login" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CSRF" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "login" } }, "/api/v1/auth/logout": { "post": { "operationId": "post_api_v1_auth_logout", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LoggedOut" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "Revoke current session" } }, "/api/v1/auth/me": { "get": { "operationId": "get_api_v1_auth_me", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Me" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "Current cookie account" } }, "/api/v1/auth/register": { "post": { "description": " Published terms require policy_version and explicit acceptance in either payment environment. Chargeable service overage additionally requires overage_accepted. Before the first policy publication, draft consent is not recorded and each operation still follows its normal registration, pricing and payment checks.", "operationId": "post_api_v1_auth_register", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Register" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Notice" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "register" } }, "/api/v1/auth/resend-verification": { "post": { "operationId": "post_api_v1_auth_resend-verification", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Notice" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "resend-verification" } }, "/api/v1/auth/reset-password": { "post": { "operationId": "post_api_v1_auth_reset-password", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenPassword" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PasswordSet" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "reset-password" } }, "/api/v1/auth/verify-email": { "post": { "operationId": "post_api_v1_auth_verify-email", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Verified" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "verify-email" } }, "/api/v1/billing/auto-renewal": { "get": { "description": "Session only. PATCH requires workspace Owner. Defaults disabled. Enabling requires enough current-mode, current-currency balance for one renewal, and the reviewed latest paid plan, offered term and price version. Only wallet funds are charged at expiry, never PayPal or a card. A minute worker and runtime mutations process due renewals under a tenant lock. Repeated attempts charge once. Insufficient funds wait for recharge; price, plan or availability changes pause charges pending fresh consent. Disabling cancels future automatic charges, not paid coverage.", "operationId": "get_api_v1_billing_auto_renewal", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "next_renewal_at": null, "setting": { "amount_cents": 0, "currency": "USD", "enabled": true, "mode": "sandbox", "plan": "starter", "plan_name": "Starter", "policy_version": "", "price_version": "example-v1", "status": "disabled", "term_months": 1, "updated_at": "2026-10-18T00:00:00Z", "version": "" } }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AutoRenewalResult", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Read automatic renewal settings", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "patch": { "description": "Session only. PATCH requires workspace Owner. Defaults disabled. Enabling requires enough current-mode, current-currency balance for one renewal, and the reviewed latest paid plan, offered term and price version. Only wallet funds are charged at expiry, never PayPal or a card. A minute worker and runtime mutations process due renewals under a tenant lock. Repeated attempts charge once. Insufficient funds wait for recharge; price, plan or availability changes pause charges pending fresh consent. Disabling cancels future automatic charges, not paid coverage. Published terms require policy_version and explicit acceptance in either payment environment. Chargeable service overage additionally requires overage_accepted. Before the first policy publication, draft consent is not recorded and each operation still follows its normal registration, pricing and payment checks.", "operationId": "patch_api_v1_billing_auto_renewal", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoRenewalInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AutoRenewal" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Enable or disable explicitly consented wallet renewal" } }, "/api/v1/billing/invoices": { "get": { "operationId": "get_api_v1_billing_invoices", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Page size, default 25, range 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "month", "schema": { "description": "UTC month YYYY-MM; omitted query values use the current month. Billing jobs require a closed month.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "active_devices": 0, "base_covered": false, "base_micros": 0, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "finalized_at": null, "id": "33333333-3333-4333-8333-333333333333", "included_devices": 0, "month": "2026-09", "overage_devices": 0, "paid_at": null, "payment_mode": "sandbox", "plan": "starter", "plan_name": "Starter", "price_version": "example-v1", "refunded_at": null, "status": "draft", "total_cents": 0, "total_micros": 0, "unit_micros": 0, "voided_at": null } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/InvoiceList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List invoices", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/invoices/{id}": { "get": { "operationId": "get_api_v1_billing_invoices_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "active_devices": 0, "base_covered": false, "base_micros": 0, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "finalized_at": null, "id": "33333333-3333-4333-8333-333333333333", "included_devices": 0, "month": "2026-09", "overage_devices": 0, "paid_at": null, "payment_mode": "sandbox", "plan": "starter", "plan_name": "Starter", "price_version": "example-v1", "refunded_at": null, "status": "draft", "total_cents": 0, "total_micros": 0, "unit_micros": 0, "voided_at": null }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Invoice", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Read invoice", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/invoices/{id}/export.csv": { "get": { "operationId": "get_api_v1_billing_invoices_by_id_export_csv", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "text/csv": { "example": "invoice_id,month,currency,status,plan,price_version,active_devices,included_devices,overage_devices,base_micros,unit_micros,total_micros,total_cents\n", "schema": { "type": "string" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Export invoice", "x-csv-columns": [ "invoice_id", "month", "currency", "status", "plan", "price_version", "active_devices", "included_devices", "overage_devices", "base_micros", "unit_micros", "total_micros", "total_cents" ], "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/invoices/{id}/finalize": { "post": { "operationId": "post_api_v1_billing_invoices_by_id_finalize", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "status": "finalized" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StateResult", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Finalize invoice", "x-management-reference": { "group": "billing" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/billing/invoices/{id}/pay": { "post": { "description": " Explicit current policy acceptance is required before a new payment. An already paid replay preserves its original receipt.", "operationId": "post_api_v1_billing_invoices_by_id_pay", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalConsent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "Pay confirmed historical invoice from balance", "x-required-role": "owner" } }, "/api/v1/billing/invoices/{id}/void": { "post": { "operationId": "post_api_v1_billing_invoices_by_id_void", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "status": "void" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StateResult", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Void invoice", "x-management-reference": { "group": "billing" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/billing/jobs": { "get": { "operationId": "get_api_v1_billing_jobs", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Page size, default 25, range 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "attempts": 0, "available_at": "2026-10-18T00:00:00Z", "created_at": "2026-10-18T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "last_error": "", "month": "2026-09", "status": "pending" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingJobList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List billing jobs", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "post": { "operationId": "post_api_v1_billing_jobs", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "month": "2026-09" }, "schema": { "$ref": "#/components/schemas/MonthInput" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "data": { "attempts": 0, "available_at": "2026-10-18T00:00:00Z", "created_at": "2026-10-18T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "last_error": "", "month": "2026-09", "status": "pending" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingJob", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Enqueue billing job", "x-management-reference": { "group": "billing" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/billing/jobs/{id}/retry": { "post": { "operationId": "post_api_v1_billing_jobs_by_id_retry", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "status": "pending" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StateResult", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Retry billing job", "x-management-reference": { "group": "billing" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/billing/notification-preferences": { "get": { "description": "Owner session only; management keys are rejected. Defaults enabled for all four types and zh until explicitly saved. Preferences belong to this user and workspace. Reuses the authentication email transport, sender, encrypted persistent queue and retries. Both platform permission and recipient consent must allow a type. Delivery rechecks current consent and event state. Email choices do not grant or revoke consent to debit a wallet. Sandbox messages are labelled. No notifications are created for unpaid pending purchases or gifts.", "operationId": "get__api_v1_billing_notification_preferences", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingNotificationPreferencesResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Read the current owner’s email consent", "x-required-role": "owner" }, "patch": { "description": "Partial update for the session owner; cannot target another user. Locale controls future messages. Existing verification and security mail remain independent. Reuses the authentication email transport, sender, encrypted persistent queue and retries. Both platform permission and recipient consent must allow a type. Delivery rechecks current consent and event state. Email choices do not grant or revoke consent to debit a wallet. Sandbox messages are labelled. No notifications are created for unpaid pending purchases or gifts.", "operationId": "patch__api_v1_billing_notification_preferences", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingNotificationPreferenceInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingNotificationPreference" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Save the current owner’s email consent", "x-required-role": "owner" } }, "/api/v1/billing/overage-consent": { "post": { "description": "", "operationId": "post__api_v1_billing_overage_consent", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerOverageConsent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Explicitly authorise current wallet overage", "x-required-role": "owner" } }, "/api/v1/billing/overage-settings": { "get": { "description": "Current tenant only. Read-only members can view. An unlimited API allowance is never limited by a customer overage preference. A null plan means the default allowance is not available.", "operationId": "get__api_v1_billing_overage_settings", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "customer_api_settings_enabled": false, "customer_device_settings_enabled": false, "plan": null, "preference": { "block_api_overage": false, "block_device_overage": false, "mode": "sandbox", "updated_at": "2026-10-18T00:00:00Z", "version": "" } }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OverageSettings", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Read overage preferences", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "patch": { "description": "Session Owner only. Each supplied choice requires its corresponding administrator permission; an unauthorized field rejects the entire request with 403. Runtime hard limit = administrator limit OR customer blocking preference when that permission is enabled. Does not erase past use or charges. Sandbox and live preferences are independent.", "operationId": "patch__api_v1_billing_overage_settings", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverageSettingsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OveragePreference" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Save independent device and API overage preferences" } }, "/api/v1/billing/paddle/orders": { "get": { "operationId": "get__api_v1_billing_paddle_orders", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderList" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "List Paddle service payments and wallet top-ups", "x-licentivo-access": "session" }, "post": { "operationId": "post__api_v1_billing_paddle_orders", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaddleOrderInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderResult" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Create or recover one Paddle service payment", "x-licentivo-access": "owner" } }, "/api/v1/billing/paddle/orders/{id}": { "get": { "operationId": "get__api_v1_billing_paddle_orders__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderResult" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Read owned checkout transaction and public client token", "x-licentivo-access": "session" } }, "/api/v1/billing/paddle/orders/{id}/reconcile": { "post": { "operationId": "post__api_v1_billing_paddle_orders__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaddleReconcileInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderResult" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Verify payment and fulfill the purchased service once", "x-licentivo-access": "owner" } }, "/api/v1/billing/paypal/orders": { "get": { "operationId": "get_api_v1_billing_paypal_orders", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Page size, default 25, range 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "amount_cents": 0, "approval_url": "", "capture_id": null, "created_at": "2026-10-18T00:00:00Z", "credited_at": null, "currency": "USD", "id": "33333333-3333-4333-8333-333333333333", "mode": "sandbox", "paypal_order_id": null, "purchase_id": null, "refunded_cents": 0, "request_id": "55555555-5555-4555-8555-555555555555", "status": "creating", "upgrade_id": null } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalOrderList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List recharge orders", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "post": { "description": " Published terms require policy_version and explicit acceptance in either payment environment. Chargeable service overage additionally requires overage_accepted. Before the first policy publication, draft consent is not recorded and each operation still follows its normal registration, pricing and payment checks.", "operationId": "post_api_v1_billing_paypal_orders", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RechargeInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalOrder" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "Create/recover idempotent recharge", "x-required-role": "owner" } }, "/api/v1/billing/paypal/orders/{id}/capture": { "post": { "operationId": "post_api_v1_billing_paypal_orders_by_id_capture", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalOrder" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "Confirm merchant-bound funds once", "x-required-role": "owner" } }, "/api/v1/billing/paypal/orders/{id}/reconcile": { "post": { "operationId": "post_api_v1_billing_paypal_orders_by_id_reconcile", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalOrder" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "Confirm merchant-bound funds once", "x-required-role": "owner" } }, "/api/v1/billing/paypal/orders/{id}/refund-requests": { "post": { "description": "Cookie sessions only; management API keys are not accepted. Customer reads are scoped to their workspace. Customer writes require a verified workspace Owner, without platform administrator permission. Applications do not move or reserve funds. Administrator approval re-checks the current wallet and unrefunded captured value, then uses the existing idempotent original-route refund and reservation flow. Approval does not cancel plans.", "operationId": "post__api_v1_billing_paypal_orders__id__refund_requests", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletRefundRequestInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletRefundRequest" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" } }, "security": [ { "session": [] } ], "summary": "Apply to refund my unspent recharge credit", "x-required-role": "owner" } }, "/api/v1/billing/plans": { "get": { "operationId": "get_api_v1_billing_plans", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "Public administrator-managed price catalog" } }, "/api/v1/billing/purchases": { "get": { "operationId": "get_api_v1_billing_purchases", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Page size, default 25, range 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "active": null, "active_devices": 0, "coverage_ends_at": null, "items": [ { "api_calls": 0, "api_hard_limit": false, "api_overage_cents": 0, "api_unit_micros": 0, "base_cents": 0, "cancelled_at": null, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "current_cycle_index": 0, "current_upgrade_id": "", "cycle_ends_at": "2026-10-18T00:00:00Z", "cycle_starts_at": "2026-10-18T00:00:00Z", "effective_included_devices": 0, "effective_plan": "", "effective_plan_name": "", "ends_at": null, "entitlement_cents": 0, "gift_batch_id": "", "gift_follows_current": false, "hard_limit": false, "id": "33333333-3333-4333-8333-333333333333", "included_api_calls": null, "included_devices": 0, "mode": "sandbox", "overage_cents": 0, "plan": "starter", "plan_name": "Starter", "price_version": "example-v1", "refunded_cents": 0, "renewal": false, "renewal_of": "", "request_id": "55555555-5555-4555-8555-555555555555", "service_credit_basis_cents": 0, "service_credit_basis_seconds": 0, "source": "purchase", "starts_at": null, "status": "pending", "term_months": 1, "total_api_calls": 0, "total_api_overage_cents": 0, "total_device_overage_cents": 0, "unit_micros": 0 } ], "mode": "sandbox", "renewal_package": null, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PurchaseList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List package purchases", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "post": { "description": "Create a purchase with the selected plan, currency, price revision and term. Attempts immediate wallet settlement; insufficient balance returns pending without starting coverage. Set renewal=true to extend an active package. Successful payment schedules service after existing coverage; GET /billing/purchases reports coverage_ends_at. Current quota usage and software license expiry remain unchanged. Retries reuse request_id and cannot double-charge. Published terms require policy_version and explicit acceptance in either payment environment. Chargeable service overage additionally requires overage_accepted. Before the first policy publication, draft consent is not recorded and each operation still follows its normal registration, pricing and payment checks.", "operationId": "post_api_v1_billing_purchases", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyPlan" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanPurchase" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "Buy a package or pay an advance renewal", "x-required-role": "owner" } }, "/api/v1/billing/refund-requests": { "get": { "description": "Cookie sessions only; management API keys are not accepted. Customer reads are scoped to their workspace. Customer writes require a verified workspace Owner, without platform administrator permission. Applications do not move or reserve funds. Administrator approval re-checks the current wallet and unrefunded captured value, then uses the existing idempotent original-route refund and reservation flow. Approval does not cancel plans.", "operationId": "get__api_v1_billing_refund_requests", "parameters": [ { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletRefundRequestList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" } }, "security": [ { "session": [] } ], "summary": "List my workspace refund applications" } }, "/api/v1/billing/refund-requests/{id}/cancel": { "post": { "description": "Cookie sessions only; management API keys are not accepted. Customer reads are scoped to their workspace. Customer writes require a verified workspace Owner, without platform administrator permission. Applications do not move or reserve funds. Administrator approval re-checks the current wallet and unrefunded captured value, then uses the existing idempotent original-route refund and reservation flow. Approval does not cancel plans.", "operationId": "post__api_v1_billing_refund_requests__id__cancel", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletRefundRequest" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" } }, "security": [ { "session": [] } ], "summary": "Withdraw my pending refund application", "x-required-role": "owner" } }, "/api/v1/billing/renewal-plans": { "get": { "description": "Completed purchase and applied-upgrade ownership only. Returns enabled published offers and hidden renewal-only offers for their existing customers. Pending quotes do not establish ownership. Renew using POST /billing/purchases in advance or after expiry.", "operationId": "get__api_v1_billing_renewal_plans", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "api_hard_limit": false, "api_unit_micros": 0, "base_micros": 0, "currency": "USD", "description": "Desktop reporting software", "enabled": true, "hard_limit": false, "included_api_calls": null, "included_devices": 0, "name": "Report app", "plan": "starter", "price_version": "example-v1", "public": false, "renewal_only": false, "sort_order": 0, "terms": [], "unit_micros": 0, "updated_at": "2026-10-18T00:00:00Z" } ], "mode": "sandbox" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RenewalPlans", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List renewal offers", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/subscription": { "get": { "operationId": "get_api_v1_billing_subscription", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "current": { "base_covered": false, "base_micros": 0, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "hard_limit": false, "included_devices": 0, "month": "2026-09", "payment_mode": "sandbox", "plan": "starter", "plan_name": "Starter", "price_version": "example-v1", "unit_micros": 0 }, "next": null, "sandbox": false }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Subscription", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Default allowance is disabled (DEFAULT_PLAN_DISABLED)" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Read monthly subscription", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" }, "patch": { "operationId": "patch_api_v1_billing_subscription", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "currency": "USD", "plan": "starter", "price_version": "example-v1" }, "schema": { "$ref": "#/components/schemas/PlanChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "currency": "USD", "effective_month": "2026-11", "plan": "starter", "sandbox": false }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ScheduledPlan", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Schedule monthly plan", "x-management-reference": { "group": "billing" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/billing/upgrades": { "get": { "description": "", "operationId": "get__api_v1_billing_upgrades", "parameters": [ { "in": "query", "name": "limit", "schema": { "description": "Page size, default 25, range 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "amount_cents": 0, "api_hard_limit": false, "api_unit_micros": 0, "applied_at": null, "base_cents": 0, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "cycle_seconds": 0, "ends_at": "2026-10-18T00:00:00Z", "expires_at": "2026-10-18T00:00:00Z", "hard_limit": false, "id": "33333333-3333-4333-8333-333333333333", "included_api_calls": null, "included_devices": 0, "mode": "sandbox", "parent_id": "33333333-3333-4333-8333-333333333333", "parts": [], "plan": "starter", "plan_name": "Starter", "previous_base_cents": 0, "previous_plan_name": "", "previous_upgrade_id": "", "price_version": "example-v1", "purchase_id": "33333333-3333-4333-8333-333333333333", "remaining_seconds": 0, "request_id": "55555555-5555-4555-8555-555555555555", "status": "pending", "unit_micros": 0 } ], "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/UpgradeList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "422": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "502": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List package upgrades", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/upgrades/quote": { "post": { "description": "Requires a session Owner. The target must use the same currency, with no lower monthly price or device/API allowance. Retains original expiry and usage. The upgrade always includes current and all future prepaid/gifted coverage. Each period credits its original benefit value, prorated for remaining seconds; an unstarted period uses its whole duration. Gift value is not refundable cash. Payment is a single atomic wallet charge; dates and consumed quota remain. Renewals, gifts or cancellations between quote and payment invalidate the quote with UPGRADE_STATE_CONFLICT; a linked late PayPal recharge remains wallet credit. Changed coverage requires a fresh quote.", "operationId": "post__api_v1_billing_upgrades_quote", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpgradeQuoteInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanUpgrade" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." } }, "security": [ { "session": [] } ], "summary": "Preview a prorated plan upgrade without debiting the wallet" } }, "/api/v1/billing/upgrades/{id}/pay": { "post": { "description": "Returns pending without changing the plan when balance is insufficient. Returns applied after charging once. Changed active plan or expired quote returns 409. The upgrade always includes current and all future prepaid/gifted coverage. Each period credits its original benefit value, prorated for remaining seconds; an unstarted period uses its whole duration. Gift value is not refundable cash. Payment is a single atomic wallet charge; dates and consumed quota remain. Renewals, gifts or cancellations between quote and payment invalidate the quote with UPGRADE_STATE_CONFLICT; a linked late PayPal recharge remains wallet credit. Changed coverage requires a fresh quote. Explicit current policy acceptance is required before a new payment. An already paid replay preserves its original receipt.", "operationId": "post__api_v1_billing_upgrades__id__pay", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalConsent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanUpgrade" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." } }, "security": [ { "session": [] } ], "summary": "Confirm and pay a valid upgrade quote once" } }, "/api/v1/billing/waffo/orders": { "get": { "operationId": "get__api_v1_billing_waffo_orders", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderList" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "List Waffo service payments and wallet top-ups", "x-licentivo-access": "session" }, "post": { "operationId": "post__api_v1_billing_waffo_orders", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaffoOrderInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderResult" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Create or recover one Waffo service payment", "x-licentivo-access": "owner" } }, "/api/v1/billing/waffo/orders/{id}": { "get": { "operationId": "get__api_v1_billing_waffo_orders__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderResult" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Read own workspace Waffo checkout", "x-licentivo-access": "session" } }, "/api/v1/billing/waffo/orders/{id}/reconcile": { "post": { "operationId": "post__api_v1_billing_waffo_orders__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderResult" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Verify payment and reconcile service and refunds", "x-licentivo-access": "owner" } }, "/api/v1/billing/wallet": { "get": { "operationId": "get_api_v1_billing_wallet", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "currencies": [], "items": [ { "balance_cents": 0, "currency": "USD", "mode": "sandbox" } ], "maximum_cents": 0, "minimum_cents": 0, "mode": "sandbox", "payment_channels": [], "paypal_enabled": false }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletResult", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Read wallet balances", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/billing/wallet/entries": { "get": { "operationId": "get_api_v1_billing_wallet_entries", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Page size, default 25, range 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "amount_cents": 0, "balance_cents": 0, "created_at": "2026-10-18T00:00:00Z", "currency": "USD", "id": "33333333-3333-4333-8333-333333333333", "kind": "", "mode": "sandbox", "reference": "" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletEntryList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List wallet entries", "x-management-reference": { "group": "billing" }, "x-required-scope": "read" } }, "/api/v1/consume": { "post": { "description": "License-authenticated runtime operation; no vendor cookie or API Key. Feature consumption requires a stable Idempotency-Key; no platform API debit for consume.", "operationId": "post_api_v1_consume", "parameters": [ { "description": "Generate a new key for each operation; retries keep the same key and body. Maximum 80 characters, no whitespace. Optional for validation and heartbeat.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ConsumptionResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "/consume" } }, "/api/v1/consume/cancel": { "post": { "description": "Reserve before the business action; commit only after success; cancel on failure. Retain the same job identifier and request body across retries. A timed-out commit is uncertain: retry commit, never cancel or repeat finished work. Finished reservations return their current status; no platform API debit. Completion emits license.consume; provisional holds do not emit consumption events.", "operationId": "post_api_v1_consume_cancel", "parameters": [ { "description": "Generate a new key for each operation; retries keep the same key and body. Maximum 80 characters, no whitespace. Optional for validation and heartbeat.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ReservationResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "Feature units: cancel" } }, "/api/v1/consume/commit": { "post": { "description": "Reserve before the business action; commit only after success; cancel on failure. Retain the same job identifier and request body across retries. A timed-out commit is uncertain: retry commit, never cancel or repeat finished work. Finished reservations return their current status; no platform API debit. Completion emits license.consume; provisional holds do not emit consumption events.", "operationId": "post_api_v1_consume_commit", "parameters": [ { "description": "Generate a new key for each operation; retries keep the same key and body. Maximum 80 characters, no whitespace. Optional for validation and heartbeat.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ReservationResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "Feature units: commit" } }, "/api/v1/consume/reserve": { "post": { "description": "Reserve before the business action; commit only after success; cancel on failure. Retain the same job identifier and request body across retries. A timed-out commit is uncertain: retry commit, never cancel or repeat finished work. Finished reservations return their current status; no platform API debit. Completion emits license.consume; provisional holds do not emit consumption events.", "operationId": "post_api_v1_consume_reserve", "parameters": [ { "description": "Generate a new key for each operation; retries keep the same key and body. Maximum 80 characters, no whitespace. Optional for validation and heartbeat.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ReservationResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "Feature units: reserve" } }, "/api/v1/customer/activations/{id}/release": { "post": { "operationId": "post_api_v1_customer_activations_by_id_release", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReleaseInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CustomerReleaseResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "customerSession": [] } ], "summary": "/customer/activations/{id}/release" } }, "/api/v1/customer/cases": { "get": { "description": "", "operationId": "get__api_v1_customer_cases", "parameters": [ { "description": "Exclude one request kind before counting and pagination. Use refund to keep refund cases out of the support list; access remains scoped to the current session.", "in": "query", "name": "exclude_kind", "schema": { "maxLength": 24, "type": "string" } }, { "description": "Limit refund cases to wallet top-ups or service cancellation.", "in": "query", "name": "refund_scope", "required": false, "schema": { "enum": [ "wallet", "service" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "List customer requests", "x-required-role": "session" }, "post": { "description": "Stable request_id is scoped to the workspace; changed content cannot reuse it.", "operationId": "post__api_v1_customer_cases", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportCaseInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCase" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Create support, privacy or appeal request", "x-required-role": "session" } }, "/api/v1/customer/cases/unread": { "get": { "description": "Refund chats are excluded. Customers see only authorized workspace tickets; members see their own. Each administrator has an independent read watermark.", "operationId": "get__api_v1_customer_cases_unread", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportUnread" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Read personal ticket and notice unread counts", "x-required-role": "session" } }, "/api/v1/customer/cases/{id}": { "get": { "description": "", "operationId": "get__api_v1_customer_cases__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Read request and replies", "x-required-role": "session" } }, "/api/v1/customer/cases/{id}/messages": { "post": { "description": "Refund cases reject replies with REFUND_REVIEW_WORKFLOW; administrators approve or decline directly. Ordinary support tickets retain replies. Reviewed closures keep their privacy workflow status.", "operationId": "post__api_v1_customer_cases__id__messages", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportReply" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Reply to a support ticket", "x-required-role": "session" } }, "/api/v1/customer/cases/{id}/read": { "post": { "description": "Only messages through the last displayed message are marked read. Newer arrivals remain unread and delayed acknowledgements cannot move the watermark backward.", "operationId": "post__api_v1_customer_cases__id__read", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportReadInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Acknowledge displayed ticket messages", "x-required-role": "session" } }, "/api/v1/customer/compensations": { "get": { "description": "", "operationId": "get__api_v1_customer_compensations", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "created_at": "2026-10-18T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333", "incident_id": "33333333-3333-4333-8333-333333333333", "intervals": "", "mode": "timed", "purchase_id": "33333333-3333-4333-8333-333333333333", "seconds": 0 } ] }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ServiceCompensationList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List service compensation", "x-management-reference": { "group": "service" }, "x-required-role": "session", "x-required-scope": "read" } }, "/api/v1/customer/licenses": { "get": { "operationId": "get_api_v1_customer_licenses", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CustomerLicenses" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "customerSession": [] } ], "summary": "Linked buyer licenses" } }, "/api/v1/customer/login": { "post": { "operationId": "post_api_v1_customer_login", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Notice" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "/customer/login" } }, "/api/v1/customer/logout": { "post": { "operationId": "post_api_v1_customer_logout", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LoggedOut" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "customerSession": [] } ], "summary": "/customer/logout" } }, "/api/v1/customer/notices": { "get": { "description": "", "operationId": "get__api_v1_customer_notices", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "body": "", "created_at": "2026-10-18T00:00:00Z", "effective_at": null, "emailed_at": null, "id": "33333333-3333-4333-8333-333333333333", "kind": "", "read_at": null, "reference": "", "title": "" } ] }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceNoticeList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List service notices", "x-management-reference": { "group": "service" }, "x-required-role": "session", "x-required-scope": "read" } }, "/api/v1/customer/notices/{id}/read": { "post": { "description": "", "operationId": "post__api_v1_customer_notices__id__read", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Mark own notice read", "x-required-role": "session" } }, "/api/v1/customer/offline/respond": { "post": { "operationId": "post_api_v1_customer_offline_respond", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfflineRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OfflineResponse" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "customerSession": [] } ], "summary": "/customer/offline/respond" } }, "/api/v1/customer/refunds": { "post": { "description": "Explicit scope requires confirmation plus the returned quote_hash and quoted_at. Service remains active until administrator approval. Changed state or expired quotes require a fresh preview; conflicting pending applications are rejected. Requests without scope permit eligible immediate cancellation after explicit confirmation. An order_id can also select a paid_unapplied Waffo/Paddle payment with reason=failed_delivery; it does not freeze wallet credit that was never granted.", "operationId": "post__api_v1_customer_refunds", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRefundInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCase" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Submit a refund application for direct review", "x-required-role": "owner" } }, "/api/v1/customer/refunds/quote": { "post": { "description": "Explicit purchase/service scope returns a bounded snapshot hash, affected purchases, per-currency refund estimates and remaining dates. Submission does not terminate service. Gifts have no cash value; paid upgrades remain refundable under review.", "operationId": "post__api_v1_customer_refunds_quote", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRefundQuoteInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CustomerRefundQuote" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Preview cancellation scope, refunds and remaining service", "x-required-role": "owner" } }, "/api/v1/customer/refunds/{id}/cancel": { "post": { "operationId": "post__api_v1_customer_refunds__id__cancel", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelCustomerRefund" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" } }, "security": [ { "session": [] } ], "summary": "Withdraw my remaining unreviewed refund request", "x-required-role": "owner" } }, "/api/v1/customer/verify": { "post": { "operationId": "post_api_v1_customer_verify", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CustomerSession" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "/customer/verify" } }, "/api/v1/deactivate": { "post": { "description": "Authenticated by product_id + license_key + device_id. No cookie/CSRF/vendor key. activation_id required except activate. Each successful request consumes one API call; idempotent replay and failures do not. Overages debit wallet atomically or return API_QUOTA_EXCEEDED/API_BALANCE_INSUFFICIENT. Workspace device quota follows current activations. Release returns capacity; floating lease expiry also returns capacity, while an offline ordinary registration remains counted. Device overage is charged only when the quota-month billing peak increases beyond already paid capacity; release does not refund incurred fees. API usage is separate.", "operationId": "post_api_v1_deactivate", "parameters": [ { "description": "Generate a new key for each operation; retries keep the same key and body. Maximum 80 characters, no whitespace. Optional for validation and heartbeat.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "Runtime deactivate" } }, "/api/v1/demo/trial": { "post": { "operationId": "post_api_v1_demo_trial", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Trial" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "Create one isolated seven-day SDK trial per owner", "x-required-role": "owner" } }, "/api/v1/examples/sdk": { "get": { "operationId": "get_api_v1_examples_sdk", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SDKExampleInfo" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "Public SDK example availability" } }, "/api/v1/examples/sdk/download/{name}": { "get": { "operationId": "get_api_v1_examples_sdk_download_{name}", "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "description": "Language plus .zip, such as csharp.zip", "type": "string" } } ], "responses": { "200": { "content": { "application/zip": { "schema": { "format": "binary", "type": "string" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "Download source with public product settings already in code" } }, "/api/v1/examples/sdk/trial": { "post": { "description": "Requires browser CSRF and an HttpOnly visitor cookie. Each visitor gets a separate license; three days begin at first activation. Repeat claims never extend expiry. Enables export, not pro.", "operationId": "post_api_v1_examples_sdk_trial", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SDKExampleTrial" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "Claim/recover this visitor’s independent three-day trial" } }, "/api/v1/forum/images": { "post": { "operationId": "post__api_v1_forum_images", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "image": { "description": "PNG, JPEG or GIF; at most 5 MB, 4096 × 4096 and 16 million pixels. GIF is stored as a static PNG. Private until attached to a published post.", "format": "binary", "type": "string" } }, "required": [ "image" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ForumImage" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" } }, "security": [ { "session": [] } ], "summary": "Upload a private draft image", "tags": [ "Community" ] } }, "/api/v1/forum/replies/{id}": { "delete": { "operationId": "delete__api_v1_forum_replies__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" } }, "security": [ { "session": [] } ], "summary": "Delete a reply (author or platform admin)", "tags": [ "Community" ] }, "patch": { "operationId": "patch__api_v1_forum_replies__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumReplyInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" } }, "security": [ { "session": [] } ], "summary": "Edit your own reply", "tags": [ "Community" ] } }, "/api/v1/forum/topics": { "get": { "operationId": "get__api_v1_forum_topics", "parameters": [ { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "q", "schema": { "type": "string" } }, { "in": "query", "name": "category", "schema": { "type": "string" } }, { "in": "query", "name": "language", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ForumTopicList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" } }, "security": [], "summary": "List public discussions, pinned first", "tags": [ "Community" ] }, "post": { "operationId": "post__api_v1_forum_topics", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumTopicInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" } }, "security": [ { "session": [] } ], "summary": "Create a discussion (any verified tenant member)", "tags": [ "Community" ] } }, "/api/v1/forum/topics/{id}": { "delete": { "operationId": "delete__api_v1_forum_topics__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" } }, "security": [ { "session": [] } ], "summary": "Delete a discussion (author or platform admin)", "tags": [ "Community" ] }, "get": { "operationId": "get__api_v1_forum_topics__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ForumTopicDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" } }, "security": [], "summary": "Read a public discussion and replies", "tags": [ "Community" ] }, "patch": { "operationId": "patch__api_v1_forum_topics__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumTopicInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" } }, "security": [ { "session": [] } ], "summary": "Edit your own discussion", "tags": [ "Community" ] } }, "/api/v1/forum/topics/{id}/moderation": { "post": { "operationId": "post__api_v1_forum_topics__id__moderation", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumModerationInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" } }, "security": [ { "session": [] } ], "summary": "Pin, unpin, hide or lock discussions (platform admin)", "tags": [ "Community" ] } }, "/api/v1/forum/topics/{id}/replies": { "post": { "operationId": "post__api_v1_forum_topics__id__replies", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumReplyInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error code and request ID; no account details exposed" } }, "security": [ { "session": [] } ], "summary": "Reply to a discussion", "tags": [ "Community" ] } }, "/api/v1/forum/topics/{id}/translate": { "post": { "description": "Anonymous visitors may use this endpoint with a CSRF token. Only published stored forum text is accepted, never arbitrary submitted text. Translation is cached by content and target language. Hidden topics/replies return 404; concurrent translation can return TRANSLATION_PENDING. Originals are preserved.", "operationId": "post__api_v1_forum_topics__id__translate", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumTranslationInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ForumTranslationResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." } }, "security": [], "summary": "Translate a published topic or reply" } }, "/api/v1/forum/translation": { "get": { "description": "", "operationId": "get__api_v1_forum_translation", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TranslationOptions" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." } }, "security": [], "summary": "Get publicly available translation target languages" } }, "/api/v1/heartbeat": { "post": { "description": "Authenticated by product_id + license_key + device_id. No cookie/CSRF/vendor key. activation_id required except activate. Each successful request consumes one API call; idempotent replay and failures do not. Overages debit wallet atomically or return API_QUOTA_EXCEEDED/API_BALANCE_INSUFFICIENT. Validation and heartbeat retry receipts expire after 3600 seconds. While the original authorization remains valid, matching requests within this window replay without another debit. After the window use a new key; a previously used key may be processed as a new request. Activation, deactivation and feature-usage receipts remain durable. Workspace device quota follows current activations. Release returns capacity; floating lease expiry also returns capacity, while an offline ordinary registration remains counted. Device overage is charged only when the quota-month billing peak increases beyond already paid capacity; release does not refund incurred fees. API usage is separate.", "operationId": "post_api_v1_heartbeat", "parameters": [ { "description": "Generate a new key for each operation; retries keep the same key and body. Maximum 80 characters, no whitespace. Optional for validation and heartbeat.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "Runtime heartbeat" } }, "/api/v1/launch/connections": { "get": { "description": "List Launch trust connections. Decisions, retries and scope checks are performed by Licentivo.", "operationId": "launch_get__api_v1_launch_connections", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": {}, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "description": "Result of this operation.", "properties": { "items": { "description": "Matching records in the requested scope.", "items": { "$ref": "#/components/schemas/LaunchConnection" }, "type": "array" } }, "required": [], "type": "object" }, "request_id": { "description": "HTTP request correlation identifier.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Accepted result" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication or identity assertion rejected" }, "403": { "description": "Entitlement, credential, environment or login revoked" }, "409": { "description": "Idempotency, policy, review or binding version conflict" }, "503": { "description": "Temporary failure; retry the original operation" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "List Launch trust connections", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-scope": "read" }, "post": { "description": "Register a Launch issuer and commerce environment. Decisions, retries and scope checks are performed by Licentivo.", "operationId": "launch_post__api_v1_launch_connections", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "audience": "licentivo:launch", "enabled": true, "environment": "live", "issuer": "https://shop.example.test", "public_keys": { "launch-1": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "schema": { "$ref": "#/components/schemas/LaunchConnectionInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "audience": "licentivo:launch", "enabled": true, "environment": "live", "id": "11111111-1111-4111-8111-111111111111", "issuer": "https://shop.example.test" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchConnection", "description": "Result of this operation." }, "request_id": { "description": "HTTP request correlation identifier.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Accepted result" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication or identity assertion rejected" }, "403": { "description": "Entitlement, credential, environment or login revoked" }, "409": { "description": "Idempotency, policy, review or binding version conflict" }, "503": { "description": "Temporary failure; retry the original operation" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Register a Launch issuer and commerce environment", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}": { "put": { "description": "Issuer, audience and environment are immutable. Supply the complete trusted public key set.", "operationId": "launch_put__api_v1_launch_connections_id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "audience": "licentivo:launch", "enabled": true, "environment": "live", "issuer": "https://shop.example.test", "public_keys": { "launch-1": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "schema": { "$ref": "#/components/schemas/LaunchConnectionInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "audience": "licentivo:launch", "enabled": true, "environment": "live", "id": "11111111-1111-4111-8111-111111111111", "issuer": "https://shop.example.test" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchConnection", "description": "Result of this operation." }, "request_id": { "description": "HTTP request correlation identifier.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Accepted result" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication or identity assertion rejected" }, "403": { "description": "Entitlement, credential, environment or login revoked" }, "409": { "description": "Idempotency, policy, review or binding version conflict" }, "503": { "description": "Temporary failure; retry the original operation" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Rotate Launch keys or update runtime limits", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/devices/{activation}/release": { "post": { "description": "Licentivo reserves the 30-day self-release allowance, records the operation and owns retries and manual review. The worker compares the binding version and revokes sessions and credentials under the same transaction locks. Old Launch login sessions cannot exchange another identity assertion on the revoked device.", "operationId": "launch_post__api_v1_launch_connections_id_devices_activation_release", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" } }, { "in": "path", "name": "activation", "required": true, "schema": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_ref": "account_ref_example", "entitlement_ref": "entitlement_ref_example", "environment": "live", "expected_generation": 1, "operation_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/LaunchDeviceReleaseInput" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "data": { "activation_id": "11111111-1111-4111-8111-111111111111", "expected_generation": 1, "license_id": "11111111-1111-4111-8111-111111111111", "operation_id": "11111111-1111-4111-8111-111111111111", "source": "logout", "status": "pending" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeviceReleaseOperation", "description": "Result of this operation." }, "request_id": { "description": "HTTP request correlation identifier.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Accepted result" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication or identity assertion rejected" }, "403": { "description": "Entitlement, credential, environment or login revoked" }, "409": { "description": "Idempotency, policy, review or binding version conflict" }, "503": { "description": "Temporary failure; retry the original operation" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Request a versioned remote account device release", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/entitlements/{entitlement}/devices": { "get": { "description": "Read account devices, authoritative release allowance and operations. Decisions, retries and scope checks are performed by Licentivo.", "operationId": "launch_get__api_v1_launch_connections_id_entitlements_entitlement_devices", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" } }, { "in": "path", "name": "entitlement", "required": true, "schema": { "description": "Case-sensitive immutable purchase entitlement reference.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, { "in": "query", "name": "account_ref", "required": true, "schema": { "description": "Case-sensitive immutable purchase entitlement reference.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, { "in": "query", "name": "environment", "required": true, "schema": { "description": "Commerce environment, pinned in both the connection and signed grant.", "enum": [ "live", "sandbox" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": {}, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "description": "Result of this operation.", "properties": { "can_release": { "description": "Whether this trust connection may authorize new runtime use.", "type": "boolean" }, "items": { "description": "Matching records in the requested scope.", "items": { "additionalProperties": false, "properties": { "device_name": { "description": "Human-readable device label.", "type": "string" }, "generation": { "description": "Current device binding incarnation.", "type": "integer" }, "id": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" }, "last_seen_at": { "description": "Record creation time in UTC.", "format": "date-time", "type": "string" }, "status": { "description": "Current server-owned lifecycle or processing status.", "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "operations": { "description": "Server-owned device release operation history.", "items": { "$ref": "#/components/schemas/DeviceReleaseOperation" }, "type": "array" }, "remaining": { "description": "Remaining self-service releases in the last 30 days, calculated by Licentivo.", "type": "integer" } }, "required": [], "type": "object" }, "request_id": { "description": "HTTP request correlation identifier.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Accepted result" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication or identity assertion rejected" }, "403": { "description": "Entitlement, credential, environment or login revoked" }, "409": { "description": "Idempotency, policy, review or binding version conflict" }, "503": { "description": "Temporary failure; retry the original operation" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Read account devices, authoritative release allowance and operations", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-scope": "read" } }, "/api/v1/launch/connections/{id}/events": { "post": { "description": "Persist before acknowledgement. Duplicate IDs with different bodies conflict. Workers apply absolute validity and monotonic aggregate versions transactionally, ignore older versions, and retry failures up to 12 attempts before manual review. For an existing entitlement, refunds, suspension and expiry revoke access independently of plan mappings, policy versions, validity modes and device occupancy, while retaining ownership and version checks. Plan downgrades apply the new features, meter rules and effective device limit together, retain the oldest bindings and revoke excess-device sessions and credentials without consuming self-release allowance. Renewals, plan changes and policy saves preserve independent manual feature and device caps. Explicit entitlement.downgraded snapshots retain active commercial status but durably block old rights if application fails. Existing active snapshots with provable reductions receive the same protection. Only an applied snapshot at or above the pending restriction version clears that barrier. Idempotent runtime retries preserve operation deduplication while refreshing changed authorization and purchase deadlines. Poll the event before declaring authorization ready.", "operationId": "launch_post__api_v1_launch_connections_id_events", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_ref": "account_ref_example", "entitlement_ref": "entitlement_ref_example", "environment": "live", "event_id": "11111111-1111-4111-8111-111111111111", "launch_product_id": "11111111-1111-4111-8111-111111111111", "plan_ref": "plan_ref_example", "type": "entitlement.created", "valid_from": "2026-10-24T00:00:00Z", "version": 1 }, "schema": { "$ref": "#/components/schemas/LaunchCommerceEvent" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "data": { "attempts": 1, "available_at": "2026-10-24T00:00:00Z", "connection_id": "11111111-1111-4111-8111-111111111111", "event_id": "11111111-1111-4111-8111-111111111111", "status": "pending" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchEvent", "description": "Result of this operation." }, "request_id": { "description": "HTTP request correlation identifier.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Accepted result" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication or identity assertion rejected" }, "403": { "description": "Entitlement, credential, environment or login revoked" }, "409": { "description": "Idempotency, policy, review or binding version conflict" }, "503": { "description": "Temporary failure; retry the original operation" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Receive a full Launch commerce snapshot", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/events/{event}": { "get": { "description": "Read a Launch commerce event result. Decisions, retries and scope checks are performed by Licentivo.", "operationId": "launch_get__api_v1_launch_connections_id_events_event_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" } }, { "in": "path", "name": "event", "required": true, "schema": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "attempts": 1, "available_at": "2026-10-24T00:00:00Z", "connection_id": "11111111-1111-4111-8111-111111111111", "event_id": "11111111-1111-4111-8111-111111111111", "status": "pending" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchEvent", "description": "Result of this operation." }, "request_id": { "description": "HTTP request correlation identifier.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Accepted result" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication or identity assertion rejected" }, "403": { "description": "Entitlement, credential, environment or login revoked" }, "409": { "description": "Idempotency, policy, review or binding version conflict" }, "503": { "description": "Temporary failure; retry the original operation" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Read a Launch commerce event result", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-scope": "read" } }, "/api/v1/launch/connections/{id}/events/{event}/retry": { "post": { "description": "Retry an unapplied Launch event. Decisions, retries and scope checks are performed by Licentivo.", "operationId": "launch_post__api_v1_launch_connections_id_events_event_retry", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" } }, { "in": "path", "name": "event", "required": true, "schema": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": {}, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "description": "Result of this operation.", "properties": { "queued": { "description": "Whether this trust connection may authorize new runtime use.", "type": "boolean" } }, "required": [], "type": "object" }, "request_id": { "description": "HTTP request correlation identifier.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Accepted result" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication or identity assertion rejected" }, "403": { "description": "Entitlement, credential, environment or login revoked" }, "409": { "description": "Idempotency, policy, review or binding version conflict" }, "503": { "description": "Temporary failure; retry the original operation" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Retry an unapplied Launch event", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/plans/{plan}": { "put": { "description": "Map a Launch plan version to a licensing policy. Decisions, retries and scope checks are performed by Licentivo.", "operationId": "launch_put__api_v1_launch_connections_id_plans_plan_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" } }, { "in": "path", "name": "plan", "required": true, "schema": { "description": "Case-sensitive immutable purchase entitlement reference.", "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "launch_product_id": "11111111-1111-4111-8111-111111111111", "policy_id": "11111111-1111-4111-8111-111111111111", "policy_version": 1, "product_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/LaunchPlanMappingInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": {}, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "description": "Result of this operation.", "properties": { "saved": { "description": "Whether this trust connection may authorize new runtime use.", "type": "boolean" } }, "required": [], "type": "object" }, "request_id": { "description": "HTTP request correlation identifier.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Accepted result" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication or identity assertion rejected" }, "403": { "description": "Entitlement, credential, environment or login revoked" }, "409": { "description": "Idempotency, policy, review or binding version conflict" }, "503": { "description": "Temporary failure; retry the original operation" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Map a Launch plan version to a licensing policy", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/session-revocations": { "post": { "description": "Synchronous atomic revocation: HTTP 200 means sessions, credentials, matching device bindings and the durable receipt committed. The connection determines the environment; an optional nonempty environment must match. Omission and a matching explicit value are equivalent for idempotency. Reuse event_id and the same normalized body for retries, including concurrent retries; different bodies conflict. Successful replays return the original counts and do not revoke newer logins. Unknown accounts/sid succeed with zero affected rows and retain a login rejection marker. Account scope records a server acceptance-time authentication cutoff. Purchased entitlement validity and license terms are preserved. Disabled connections accept revocations.", "operationId": "launch_post__api_v1_launch_connections_id_session_revocations", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_ref": "account_456", "event_id": "11111111-1111-4111-8111-111111111111", "reason": "forced_logout", "scope": "session", "sid": "login_123" }, "schema": { "$ref": "#/components/schemas/LaunchSessionRevocationInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "account_ref": "account_456", "completed_at": "2026-10-24T05:00:00.145678Z", "connection_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-10-24T05:00:00.123456Z", "environment": "live", "event_id": "11111111-1111-4111-8111-111111111111", "reason": "forced_logout", "released_devices": 2, "revoked_credentials": 2, "revoked_sessions": 2, "scope": "session", "sid": "login_123", "status": "succeeded" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchSessionRevocation", "description": "Result of this operation." }, "request_id": { "description": "HTTP request correlation identifier.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Accepted result" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication or identity assertion rejected" }, "403": { "description": "Entitlement, credential, environment or login revoked" }, "404": { "description": "Connection does not exist in this tenant" }, "409": { "description": "Idempotency, policy, review or binding version conflict" }, "415": { "description": "Use Content-Type: application/json" }, "500": { "description": "Database failure or unknown outcome; query or retry the original event without changing its ID or body" }, "503": { "description": "Temporary failure; retry the original operation" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Revoke a Launch login or all account authorization sessions", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/connections/{id}/session-revocations/{event}": { "get": { "description": "Returns the original durable receipt for this tenant and connection. HTTP 404 means no committed result is currently visible; retry the original POST with the same event_id and body. No asynchronous worker is required.", "operationId": "launch_get__api_v1_launch_connections_id_session_revocations_event_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" } }, { "in": "path", "name": "event", "required": true, "schema": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "account_ref": "account_456", "completed_at": "2026-10-24T05:00:00.145678Z", "connection_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-10-24T05:00:00.123456Z", "environment": "live", "event_id": "11111111-1111-4111-8111-111111111111", "reason": "forced_logout", "released_devices": 2, "revoked_credentials": 2, "revoked_sessions": 2, "scope": "session", "sid": "login_123", "status": "succeeded" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LaunchSessionRevocation", "description": "Result of this operation." }, "request_id": { "description": "HTTP request correlation identifier.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Accepted result" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication or identity assertion rejected" }, "403": { "description": "Entitlement, credential, environment or login revoked" }, "404": { "description": "No committed result exists in this tenant and connection" }, "409": { "description": "Idempotency, policy, review or binding version conflict" }, "500": { "description": "Database failure or unknown outcome; query or retry the original event without changing its ID or body" }, "503": { "description": "Temporary failure; retry the original operation" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Query a committed Launch session revocation result", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-scope": "read" } }, "/api/v1/launch/device-operations/{operation}": { "get": { "description": "Read remote release progress. Decisions, retries and scope checks are performed by Licentivo.", "operationId": "launch_get__api_v1_launch_device_operations_operation_", "parameters": [ { "in": "path", "name": "operation", "required": true, "schema": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "activation_id": "11111111-1111-4111-8111-111111111111", "expected_generation": 1, "license_id": "11111111-1111-4111-8111-111111111111", "operation_id": "11111111-1111-4111-8111-111111111111", "source": "logout", "status": "pending" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeviceReleaseOperation", "description": "Result of this operation." }, "request_id": { "description": "HTTP request correlation identifier.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Accepted result" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication or identity assertion rejected" }, "403": { "description": "Entitlement, credential, environment or login revoked" }, "409": { "description": "Idempotency, policy, review or binding version conflict" }, "503": { "description": "Temporary failure; retry the original operation" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Read remote release progress", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-scope": "read" } }, "/api/v1/launch/device-operations/{operation}/retry": { "post": { "description": "A manual_review operation needs approve=true from the owner. Approval never bypasses the original binding version.", "operationId": "launch_post__api_v1_launch_device_operations_operation_retry", "parameters": [ { "in": "path", "name": "operation", "required": true, "schema": { "description": "Licentivo resource UUID.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "additionalProperties": false, "properties": { "approve": { "description": "Whether this trust connection may authorize new runtime use.", "type": "boolean" } }, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": {}, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "description": "Result of this operation.", "properties": { "queued": { "description": "Whether this trust connection may authorize new runtime use.", "type": "boolean" } }, "required": [], "type": "object" }, "request_id": { "description": "HTTP request correlation identifier.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Accepted result" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication or identity assertion rejected" }, "403": { "description": "Entitlement, credential, environment or login revoked" }, "409": { "description": "Idempotency, policy, review or binding version conflict" }, "503": { "description": "Temporary failure; retry the original operation" } }, "security": [ { "managementKey": [] }, { "session": [] } ], "summary": "Retry or explicitly approve a reviewed release", "tags": [ "Launch account licensing" ], "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/launch/exchange": { "post": { "description": "Idempotency-Key is mandatory. JWT header alg=Ed25519, typ=licentivo-launch-identity+jwt and pinned kid; exact iss/aud/environment, sub, sid, jti, iat, nbf, exp, auth_time, session_exp, launch_product_id, product_id and entitlement_ref are required. Assertion lifetime is at most 120 seconds. Replays only recover the same active device session with the same request and idempotency key. Purchases are read exclusively from Licentivo.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "description": "Idempotency-Key for this Launch authorization operation.", "maxLength": 80, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "environment": "live", "identity_token": "identity_token_example", "launch_connection_id": "11111111-1111-4111-8111-111111111111", "product_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/LaunchExchangeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "activation_id": "11111111-1111-4111-8111-111111111111" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeResult", "description": "Result of this operation." }, "request_id": { "description": "HTTP request correlation identifier.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Accepted result" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication or identity assertion rejected" }, "403": { "description": "Entitlement, credential, environment or login revoked" }, "409": { "description": "Idempotency, policy, review or binding version conflict" }, "503": { "description": "Temporary failure; retry the original operation" } }, "security": [], "summary": "Exchange Launch account identity for device authorization", "tags": [ "Launch account licensing" ] } }, "/api/v1/legal/policy": { "get": { "description": "Returns frozen service, refund and privacy documents in all 13 supported languages. Unconfirmed optional profile details are omitted. A published version requires explicit acceptance; existing flows continue until first publication.", "operationId": "get__api_v1_legal_policy", "parameters": [ { "in": "query", "name": "version", "schema": { "type": "string" } }, { "in": "query", "name": "locale", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommercePolicy" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [], "summary": "Read an immutable legal policy" } }, "/api/v1/licenses": { "get": { "operationId": "get_api_v1_licenses", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Page size, default 25, range 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "product_id", "schema": { "description": "Product UUID in the current workspace.", "format": "uuid", "type": "string" } }, { "in": "query", "name": "q", "schema": { "description": "Search text; target fields and maximum length depend on the operation.", "maxLength": 254, "type": "string" } }, { "in": "query", "name": "status", "schema": { "description": "Current resource state; see the enum and operation notes.", "enum": [ "active", "expired", "suspended", "revoked" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "created_at": "2026-10-18T00:00:00Z", "customer": "Order #1001", "duration_days": 30, "expires_at": null, "features": [ "export" ], "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key_prefix": "lv_lic_AAAAAAA", "max_devices": 1, "mode": "timed", "policy_id": "22222222-2222-4222-8222-222222222222", "policy_version": 1, "product_id": "11111111-1111-4111-8111-111111111111", "status": "active", "updated_at": "2026-10-18T00:00:00Z" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicenseList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List licenses", "x-management-reference": { "group": "licenses" }, "x-required-scope": "read" }, "post": { "description": "Requires Owner session or write key from an active Owner. No automatic Idempotency-Key retries.", "operationId": "post_api_v1_licenses", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": 30, "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/LicenseCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "key_prefix": "lv_lic_AAAAAAA" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicenseSecret", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Issue license", "x-management-reference": { "group": "licenses" }, "x-request-variants": [ { "name": "timed", "request": { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": 30, "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111" }, "response": { "data": { "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "key_prefix": "lv_lic_AAAAAAA" }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "perpetual", "request": { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": null, "policy_id": "22222222-2222-4222-8222-222222222223", "product_id": "11111111-1111-4111-8111-111111111111" }, "response": { "data": { "duration_days": null, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "key_prefix": "lv_lic_AAAAAAA" }, "request_id": "55555555-5555-4555-8555-555555555555" } } ], "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/batch": { "post": { "description": "Policy application never changes license mode or lifetime. Creation requires an explicit duration for each timed/trial license, from its entry or the common batch field. Launch-managed licenses reject independent single or batch renewal with HTTP 409 LAUNCH_VALIDITY_MANAGED; renew the purchase in Launch and synchronize absolute validity. A mixed renewal batch rolls back entirely.", "operationId": "post_api_v1_licenses_batch", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "duration_days": 30, "entries": [ { "customer": "Order #1001", "customer_email": "buyer@example.com" } ], "operation": "create", "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111", "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/BatchInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "count": 1, "items": [ { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } ], "operation": "create", "request_id": "55555555-5555-4555-8555-555555555555" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BatchResult", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Batch licenses", "x-management-reference": { "group": "licenses" }, "x-request-variants": [ { "name": "create", "request": { "duration_days": 30, "entries": [ { "customer": "Order #1001", "customer_email": "buyer@example.com" } ], "operation": "create", "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111", "request_id": "55555555-5555-4555-8555-555555555555" }, "response": { "data": { "count": 1, "items": [ { "customer": "Order #1001", "customer_email": "buyer@example.com", "duration_days": 30, "expires_at": null, "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } ], "operation": "create", "request_id": "55555555-5555-4555-8555-555555555555" }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "renew", "request": { "days": 30, "ids": [ "33333333-3333-4333-8333-333333333333" ], "operation": "renew", "request_id": "55555555-5555-4555-8555-555555555555" }, "response": { "data": { "count": 1, "items": [ { "id": "33333333-3333-4333-8333-333333333333", "operation": "renew" } ], "operation": "renew", "request_id": "55555555-5555-4555-8555-555555555555" }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "revoke", "request": { "ids": [ "33333333-3333-4333-8333-333333333333" ], "operation": "revoke", "request_id": "55555555-5555-4555-8555-555555555555" }, "response": { "data": { "count": 1, "items": [ { "id": "33333333-3333-4333-8333-333333333333", "operation": "revoke" } ], "operation": "revoke", "request_id": "55555555-5555-4555-8555-555555555555" }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "apply_policy", "request": { "ids": [ "33333333-3333-4333-8333-333333333333" ], "operation": "apply_policy", "policy_id": "22222222-2222-4222-8222-222222222222", "preview_token": "REPLACE_WITH_THE_UNEXPIRED_PREVIEW_TOKEN", "request_id": "55555555-5555-4555-8555-555555555555" }, "response": { "data": { "count": 1, "items": [ { "id": "33333333-3333-4333-8333-333333333333", "operation": "apply_policy" } ], "operation": "apply_policy", "request_id": "55555555-5555-4555-8555-555555555555" }, "request_id": "55555555-5555-4555-8555-555555555555" } } ], "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/export.csv": { "get": { "operationId": "get_api_v1_licenses_export_csv", "parameters": [ { "in": "query", "name": "product_id", "schema": { "description": "Product UUID in the current workspace.", "format": "uuid", "type": "string" } }, { "in": "query", "name": "q", "schema": { "description": "Search text; target fields and maximum length depend on the operation.", "maxLength": 254, "type": "string" } }, { "in": "query", "name": "status", "schema": { "description": "Current resource state; see the enum and operation notes.", "enum": [ "active", "expired", "suspended", "revoked" ], "type": "string" } } ], "responses": { "200": { "content": { "text/csv": { "example": "id,product_id,key_prefix,customer,mode,status,max_devices,expires_at\n", "schema": { "type": "string" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "413": { "content": { "application/json": { "example": { "error": { "code": "EXPORT_TOO_LARGE", "message": "Filter the export to at most 5000 records" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Filter to at most 5000 records" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Export licenses", "x-csv-columns": [ "id", "product_id", "key_prefix", "customer", "mode", "status", "max_devices", "expires_at" ], "x-management-reference": { "group": "licenses" }, "x-required-scope": "read" } }, "/api/v1/licenses/policy-preview": { "post": { "description": "Policy application never changes license mode or lifetime. Creation requires an explicit duration for each timed/trial license, from its entry or the common batch field.", "operationId": "post_api_v1_licenses_policy-preview", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "ids": [ "33333333-3333-4333-8333-333333333333" ], "policy_id": "22222222-2222-4222-8222-222222222222" }, "schema": { "$ref": "#/components/schemas/PreviewInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "changes": [], "expires_in": 600, "note": "", "policy_version": 1, "preview_token": "" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PolicyPreview", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Preview policy application", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/{id}": { "delete": { "operationId": "delete_api_v1_licenses_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Archive license", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" }, "get": { "operationId": "get_api_v1_licenses_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "created_at": "2026-10-18T00:00:00Z", "customer": "Order #1001", "duration_days": 30, "expires_at": null, "features": [ "export" ], "first_activated_at": null, "id": "33333333-3333-4333-8333-333333333333", "key_prefix": "lv_lic_AAAAAAA", "max_devices": 1, "mode": "timed", "policy_id": "22222222-2222-4222-8222-222222222222", "policy_version": 1, "product_id": "11111111-1111-4111-8111-111111111111", "status": "active", "updated_at": "2026-10-18T00:00:00Z" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/License", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Read license", "x-management-reference": { "group": "licenses" }, "x-required-scope": "read" }, "patch": { "operationId": "patch_api_v1_licenses_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "status": "suspended" }, "schema": { "$ref": "#/components/schemas/LicenseUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Update license", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/{id}/capabilities": { "get": { "operationId": "get_api_v1_licenses_by_id_capabilities", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "customer_email": "buyer@example.com", "license": { "license_id": "33333333-3333-4333-8333-333333333333", "license_model": "node_locked", "maintenance_days": 0, "maintenance_until": null, "max_version": "", "min_version": "", "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z" }, "meter_rules": [], "usage": null }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicenseCapabilityResult", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Read license capabilities", "x-management-reference": { "group": "licenses" }, "x-required-scope": "read" } }, "/api/v1/licenses/{id}/customer": { "patch": { "operationId": "patch_api_v1_licenses_by_id_customer", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "email": "buyer@example.com", "name": "Sample customer" }, "schema": { "$ref": "#/components/schemas/CustomerAssignment" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Assign customer", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/{id}/maintenance/renew": { "post": { "operationId": "post_api_v1_licenses_by_id_maintenance_renew", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "days": 30 }, "schema": { "$ref": "#/components/schemas/Renew" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "license_id": "33333333-3333-4333-8333-333333333333", "license_model": "node_locked", "maintenance_days": 0, "maintenance_until": null, "max_version": "", "min_version": "", "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicenseCapabilities", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Renew maintenance", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/{id}/renew": { "post": { "description": "Before first activation, renewal increases duration_days. After activation, the extension starts from the later of the current time and expires_at; expired licenses do not lose purchased extension time. Launch-managed licenses reject independent single or batch renewal with HTTP 409 LAUNCH_VALIDITY_MANAGED; renew the purchase in Launch and synchronize absolute validity. A mixed renewal batch rolls back entirely.", "operationId": "post_api_v1_licenses_by_id_renew", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "days": 30 }, "schema": { "$ref": "#/components/schemas/Renew" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "duration_days": 60, "expires_at": null, "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Renewed", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Renew license", "x-management-reference": { "group": "licenses" }, "x-request-variants": [ { "name": "before_activation", "request": { "days": 30 }, "response": { "data": { "duration_days": 60, "expires_at": null, "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "after_activation", "request": { "days": 30 }, "response": { "data": { "duration_days": 30, "expires_at": "2026-12-17T00:00:00Z", "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" } } ], "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/licenses/{id}/reveal-key": { "post": { "description": "Requires an active Owner browser session and CSRF token. Management API keys and read-only members are forbidden. Keys are encrypted at rest and each view is audited without recording the secret. Ordinary lists, details and CSV exports contain only the prefix. Older encrypted batch/onboarding receipts are recovered during migration. Older hash-only issuances return LICENSE_KEY_UNAVAILABLE (409); Launch account licenses return LICENSE_KEY_NOT_APPLICABLE (409). Viewing does not rotate the key or change validity, devices or usage.", "operationId": "post_api_v1_licenses_by_id_reveal-key", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicenseKeyReveal" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "View the original license key", "x-required-role": "owner" } }, "/api/v1/licenses/{id}/revoke": { "post": { "operationId": "post_api_v1_licenses_by_id_revoke", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Revoke license", "x-management-reference": { "group": "licenses" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/members": { "get": { "operationId": "get_api_v1_members", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MemberList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "get /members", "x-required-role": "owner" }, "post": { "operationId": "post_api_v1_members", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Invited" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "post /members", "x-required-role": "owner" } }, "/api/v1/members/{id}": { "patch": { "operationId": "patch_api_v1_members_by_id", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "patch /members/{id}", "x-required-role": "owner" } }, "/api/v1/offline/respond": { "post": { "operationId": "post_api_v1_offline_respond", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "activation_id": "44444444-4444-4444-8444-444444444444", "app_version": "1.0.0", "created_at": 1792281600, "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "device_name": "Office PC", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "operation": "deactivate", "product_id": "11111111-1111-4111-8111-111111111111", "request_id": "55555555-5555-4555-8555-555555555555", "version": 1 }, "schema": { "$ref": "#/components/schemas/OfflineRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "operation": "deactivate", "request_id": "55555555-5555-4555-8555-555555555555", "result": { "activation_id": "44444444-4444-4444-8444-444444444444", "deactivated": true }, "version": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OfflineResponse", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Issue offline response", "x-management-reference": { "group": "integration" }, "x-request-variants": [ { "name": "activate", "request": { "app_version": "1.0.0", "created_at": 1792281600, "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "device_name": "Office PC", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "operation": "activate", "product_id": "11111111-1111-4111-8111-111111111111", "request_id": "55555555-5555-4555-8555-555555555555", "version": 1 }, "response": { "data": { "operation": "activate", "request_id": "55555555-5555-4555-8555-555555555555", "result": { "activation_id": "44444444-4444-4444-8444-444444444444", "device_key": "lv_dev_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "heartbeat_seconds": 600, "lease": { "key_id": "66666666-6666-4666-8666-666666666666", "payload": "BASE64URL_ENCODED_SIGNED_CLAIMS", "signature": "BASE64URL_ED25519_SIGNATURE", "version": 1 } }, "version": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" } }, { "name": "deactivate", "request": { "activation_id": "44444444-4444-4444-8444-444444444444", "app_version": "1.0.0", "created_at": 1792281600, "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "device_name": "Office PC", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "operation": "deactivate", "product_id": "11111111-1111-4111-8111-111111111111", "request_id": "55555555-5555-4555-8555-555555555555", "version": 1 }, "response": { "data": { "operation": "deactivate", "request_id": "55555555-5555-4555-8555-555555555555", "result": { "activation_id": "44444444-4444-4444-8444-444444444444", "deactivated": true }, "version": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" } } ], "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/onboarding": { "post": { "operationId": "post_api_v1_onboarding", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "duration_days": 7, "mode": "trial", "name": "Report app", "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/OnboardingInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "config": { "allow_http": false, "app_version": "1.0.0", "base_url": "https://license.example.com", "cache_path": "", "device_name": "My application", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "product_id": "11111111-1111-4111-8111-111111111111", "trusted_keys": { "66666666-6666-4666-8666-666666666666": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "license_id": "33333333-3333-4333-8333-333333333333", "license_key": "lv_lic_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "next": "Choose a language and download the configured SDK bundle.", "policy_id": "22222222-2222-4222-8222-222222222222", "product_id": "11111111-1111-4111-8111-111111111111" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OnboardingResult", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Create integration resources", "x-management-reference": { "group": "integration" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/payments/paddle/webhook": { "post": { "operationId": "post__api_v1_payments_paddle_webhook", "parameters": [ { "in": "header", "name": "Paddle-Signature", "required": true, "schema": { "description": "Display name of the payment service.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaddleWebhookEvent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WebhookReceived" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [], "summary": "Verify Paddle signature and reconcile completed payments or adjustments", "x-licentivo-access": "public" } }, "/api/v1/payments/paypal/webhook": { "post": { "operationId": "post_api_v1_payments_paypal_webhook", "parameters": [ { "in": "header", "name": "Paypal-Auth-Algo", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Paypal-Cert-Url", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Paypal-Transmission-Id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Paypal-Transmission-Sig", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Paypal-Transmission-Time", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WebhookReceived" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "Verified capture/refund/reversal notification" } }, "/api/v1/payments/waffo/webhook": { "post": { "operationId": "post__api_v1_payments_waffo_webhook", "parameters": [ { "in": "header", "name": "X-Waffo-Signature", "required": true, "schema": { "description": "Merchant identifier beginning MER_.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaffoWebhookEvent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WebhookReceived" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [], "summary": "Verify Waffo signature and reconcile payment or refund", "x-licentivo-access": "public" } }, "/api/v1/policies": { "get": { "operationId": "get_api_v1_policies", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Page size, default 25, range 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "product_id", "schema": { "description": "Product UUID in the current workspace.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "created_at": "2026-10-18T00:00:00Z", "features": [ "export" ], "heartbeat_seconds": 600, "id": "22222222-2222-4222-8222-222222222222", "max_devices": 1, "mode": "timed", "name": "One device", "offline_mode": "limited", "offline_seconds": 86400, "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z", "version": 1 } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PolicyList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List policies", "x-management-reference": { "group": "policies" }, "x-required-scope": "read" }, "post": { "description": "Requires Owner session or write key from an active Owner. No automatic Idempotency-Key retries.", "operationId": "post_api_v1_policies", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "features": [ "export" ], "heartbeat_seconds": 600, "max_devices": 1, "mode": "timed", "name": "One device", "offline_mode": "limited", "offline_seconds": 86400, "product_id": "11111111-1111-4111-8111-111111111111" }, "schema": { "$ref": "#/components/schemas/PolicyCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Create policy", "x-management-reference": { "group": "policies" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/policies/{id}": { "delete": { "operationId": "delete_api_v1_policies_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Archive policy", "x-management-reference": { "group": "policies" }, "x-required-role": "owner", "x-required-scope": "write" }, "get": { "operationId": "get_api_v1_policies_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "created_at": "2026-10-18T00:00:00Z", "features": [ "export" ], "heartbeat_seconds": 600, "id": "22222222-2222-4222-8222-222222222222", "max_devices": 1, "mode": "timed", "name": "One device", "offline_mode": "limited", "offline_seconds": 86400, "product_id": "11111111-1111-4111-8111-111111111111", "updated_at": "2026-10-18T00:00:00Z", "version": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Policy", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Read policy", "x-management-reference": { "group": "policies" }, "x-required-scope": "read" }, "patch": { "description": "Atomically update the policy and every linked, non-revoked license snapshot. Existing license terms, committed usage and separate maintenance extensions are preserved. Returns synced_licenses. ACTIVE_DEVICES_CONFLICT rolls back the whole save.", "operationId": "patch_api_v1_policies_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "max_devices": 2 }, "schema": { "$ref": "#/components/schemas/PolicyUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "synced_licenses": 0 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PolicySyncResult", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Update basic policy", "x-management-reference": { "group": "policies" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/policies/{id}/capabilities": { "get": { "operationId": "get_api_v1_policies_by_id_capabilities", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "allow_vm": true, "device_match": "system", "license_model": "node_locked", "maintenance_days": 0, "max_version": "", "meter_rules": [], "min_version": "", "policy_id": "22222222-2222-4222-8222-222222222222", "policy_version": 1, "product_id": "11111111-1111-4111-8111-111111111111", "require_hardware": false, "self_release_limit": 3, "session_seconds": 7200, "updated_at": "2026-10-18T00:00:00Z" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PolicyCapabilities", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Read policy capabilities", "x-management-reference": { "group": "policies" }, "x-required-scope": "read" }, "patch": { "description": "Use the current policy_version. Atomically update the policy and every linked, non-revoked license snapshot while preserving issued terms, committed usage and separate maintenance extensions. Returns synced_licenses. POLICY_CHANGED or ACTIVE_DEVICES_CONFLICT rolls back the whole save.", "operationId": "patch_api_v1_policies_by_id_capabilities", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "license_model": "node_locked", "meter_rules": [ { "allow_overage": false, "feature": "export", "limit": 500, "max_overage": 0, "period": "month" } ], "policy_version": 1 }, "schema": { "$ref": "#/components/schemas/PolicyCapabilitiesInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "synced_licenses": 0 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PolicySyncResult", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Update policy capabilities", "x-management-reference": { "group": "policies" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/products": { "get": { "operationId": "get_api_v1_products", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Page size, default 25, range 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "q", "schema": { "description": "Search text; target fields and maximum length depend on the operation.", "maxLength": 120, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "created_at": "2026-10-18T00:00:00Z", "description": "Desktop reporting software", "id": "11111111-1111-4111-8111-111111111111", "name": "Report app", "status": "active", "updated_at": "2026-10-18T00:00:00Z" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProductList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List products", "x-management-reference": { "group": "products" }, "x-required-scope": "read" }, "post": { "description": "Requires Owner session or write key from an active Owner. No automatic Idempotency-Key retries.", "operationId": "post_api_v1_products", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "description": "Desktop reporting software", "name": "Report app" }, "schema": { "$ref": "#/components/schemas/ProductCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Create product", "x-management-reference": { "group": "products" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/products/{id}": { "delete": { "operationId": "delete_api_v1_products_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Archive product", "x-management-reference": { "group": "products" }, "x-required-role": "owner", "x-required-scope": "write" }, "get": { "operationId": "get_api_v1_products_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "created_at": "2026-10-18T00:00:00Z", "description": "Desktop reporting software", "id": "11111111-1111-4111-8111-111111111111", "name": "Report app", "status": "active", "updated_at": "2026-10-18T00:00:00Z" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Product", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Read product", "x-management-reference": { "group": "products" }, "x-required-scope": "read" }, "patch": { "operationId": "patch_api_v1_products_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Report app Pro", "status": "active" }, "schema": { "$ref": "#/components/schemas/ProductUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Update product", "x-management-reference": { "group": "products" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/products/{id}/public-keys": { "get": { "operationId": "get_api_v1_products_by_id_public-keys", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/KeyBundle" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "Product pinned key bundle" } }, "/api/v1/products/{id}/releases": { "get": { "operationId": "get_api_v1_products_by_id_releases", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Page size, default 25, range 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "channel": "stable", "created_at": "2026-10-18T00:00:00Z", "download_url": "", "id": "33333333-3333-4333-8333-333333333333", "notes": "Initial release", "product_id": "11111111-1111-4111-8111-111111111111", "published_at": "2026-10-18T00:00:00Z", "sha256": "", "version": "1.0.0" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ReleaseList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List releases", "x-management-reference": { "group": "releases" }, "x-required-scope": "read" }, "post": { "operationId": "post_api_v1_products_by_id_releases", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "channel": "stable", "notes": "Initial release", "version": "1.0.0" }, "schema": { "$ref": "#/components/schemas/ReleaseInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "channel": "stable", "created_at": "2026-10-18T00:00:00Z", "download_url": "", "id": "33333333-3333-4333-8333-333333333333", "notes": "Initial release", "product_id": "11111111-1111-4111-8111-111111111111", "published_at": "2026-10-18T00:00:00Z", "sha256": "", "version": "1.0.0" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Release", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Publish release", "x-management-reference": { "group": "releases" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/products/{id}/sdk-bundle": { "post": { "operationId": "post_api_v1_products_by_id_sdk-bundle", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "language": "go" }, "schema": { "$ref": "#/components/schemas/BundleInput" } } }, "required": true }, "responses": { "200": { "content": { "application/zip": { "schema": { "format": "binary", "type": "string" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Download product example source", "x-management-reference": { "group": "products" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/products/{id}/sdk-initializer": { "get": { "operationId": "get_api_v1_products_by_id_sdk-initializer", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } }, { "in": "query", "name": "language", "schema": { "default": "go", "description": "SDK language identifier for the download bundle.", "enum": [ "go", "java", "c", "cpp", "csharp", "python", "javascript", "rust", "ruby" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "language": "go", "product_id": "11111111-1111-4111-8111-111111111111", "source": "const productID = \"11111111-1111-4111-8111-111111111111\"\nvar trustedKeys = map[string]string{\"66666666-6666-4666-8666-666666666666\": \"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\"}\n", "trusted_keys": { "66666666-6666-4666-8666-666666666666": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SDKInitializer", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Copy product initialization code", "x-management-reference": { "group": "products" }, "x-required-scope": "read" } }, "/api/v1/products/{id}/signing-keys": { "get": { "operationId": "get_api_v1_products_by_id_signing-keys", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "keys": [], "product_id": "11111111-1111-4111-8111-111111111111" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ManagementKeyBundle", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List signing keys", "x-management-reference": { "group": "products" }, "x-required-scope": "read" } }, "/api/v1/products/{id}/signing-keys/rotate": { "post": { "operationId": "post_api_v1_products_by_id_signing-keys_rotate", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "active": true, "algorithm": "Ed25519", "created_at": "2026-10-18T00:00:00Z", "key_id": "66666666-6666-4666-8666-666666666666", "public_key": "", "retired_at": null }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SigningKey", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Rotate signing key", "x-management-reference": { "group": "products" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/releases/eligible": { "post": { "description": "License-authenticated runtime operation; no vendor cookie or API Key. Feature consumption requires a stable Idempotency-Key; no platform API debit for consume.", "operationId": "post_api_v1_releases_eligible", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/EligibleReleases" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "/releases/eligible" } }, "/api/v1/service/status": { "get": { "description": "Only global notices are public; targeted workspace IDs are not exposed.", "operationId": "get__api_v1_service_status", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ServiceIncidentList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [], "summary": "Read public maintenance and incidents" } }, "/api/v1/sessions/logout": { "post": { "description": "No browser cookies or CSRF token. A duplicate operation replays without releasing newer bindings. Status stale is successful completion of an obsolete revocation. SDKs deny local use and clear runtime credentials before submitting this request.", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "activation_id": "11111111-1111-4111-8111-111111111111", "expected_generation": 1, "operation_id": "11111111-1111-4111-8111-111111111111", "product_id": "11111111-1111-4111-8111-111111111111", "release_token": "lv_out_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" }, "schema": { "$ref": "#/components/schemas/LogoutTicket" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "activation_id": "11111111-1111-4111-8111-111111111111", "expected_generation": 1, "license_id": "11111111-1111-4111-8111-111111111111", "operation_id": "11111111-1111-4111-8111-111111111111", "source": "logout", "status": "pending" }, "request_id": "request_id_example" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeviceReleaseOperation", "description": "Result of this operation." }, "request_id": { "description": "HTTP request correlation identifier.", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Accepted result" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication or identity assertion rejected" }, "403": { "description": "Entitlement, credential, environment or login revoked" }, "409": { "description": "Idempotency, policy, review or binding version conflict" }, "503": { "description": "Temporary failure; retry the original operation" } }, "security": [], "summary": "Revoke one versioned device binding using an unlink-only ticket", "tags": [ "Launch account licensing" ] } }, "/api/v1/summary": { "get": { "operationId": "get_api_v1_summary", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "active_licenses": 0, "licenses": 0, "policies": 0, "products": 0 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Summary", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Workspace counts", "x-management-reference": { "group": "usage" }, "x-required-scope": "read" } }, "/api/v1/support/contact": { "get": { "description": "Returns only the configured contact email; empty means hidden. No mail is sent.", "operationId": "get__api_v1_support_contact", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportContact" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [], "summary": "Read the public support email" } }, "/api/v1/system/billing-notifications": { "get": { "description": "Reuses the authentication email transport, sender, encrypted persistent queue and retries. Both platform permission and recipient consent must allow a type. Delivery rechecks current consent and event state. Email choices do not grant or revoke consent to debit a wallet. Sandbox messages are labelled. No notifications are created for unpaid pending purchases or gifts.", "operationId": "get__api_v1_system_billing_notifications", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingNotificationSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Read platform billing email rules", "x-platform-admin": true, "x-required-role": "owner" }, "patch": { "description": "Partial update; explicitly false values persist. Reuses the authentication email transport, sender, encrypted persistent queue and retries. Both platform permission and recipient consent must allow a type. Delivery rechecks current consent and event state. Email choices do not grant or revoke consent to debit a wallet. Sandbox messages are labelled. No notifications are created for unpaid pending purchases or gifts.", "operationId": "patch__api_v1_system_billing_notifications", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingNotificationSettingsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingNotificationSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Configure billing email rules and public support contact", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/billing-notifications/preview": { "get": { "description": "Uses saved platform settings and sample sandbox data. No purchase or mail job is created.", "operationId": "get__api_v1_system_billing_notifications_preview", "parameters": [ { "in": "query", "name": "kind", "required": true, "schema": { "enum": [ "purchase_success", "expiry_reminder", "auto_renewal_success", "auto_renewal_problem" ], "type": "string" } }, { "in": "query", "name": "locale", "schema": { "default": "zh", "enum": [ "zh", "zh-hant", "en", "es", "hi", "ar", "fr", "bn", "pt", "id", "ur" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BillingEmailPreview" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Preview a billing email without sending", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/billing-notifications/test": { "post": { "description": "Explicit test uses sample sandbox data, adds [TEST] and follows the existing mail configuration. It can test a template even if that customer notification type is disabled. No payment or renewal is performed.", "operationId": "post__api_v1_system_billing_notifications_test", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEmailTestInput" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailQueued" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Queue a requested billing email test", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/check-mail": { "post": { "description": "Check the saved service only. API-provider checks use read-only requests and never send email. A sending-only key may produce check_status=limited and ok=false; this does not confirm valid credentials or successful delivery. An explicit test-mail request is needed to test sending.", "operationId": "post_api_v1_system_check-mail", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailConnection" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "MAIL_PROVIDER_AUTH_FAILED, MAIL_PROVIDER_RATE_LIMITED or MAIL_PROVIDER_UNAVAILABLE. Test-mail delivery is asynchronous; delivery errors appear in the job outcome rather than the original HTTP 202 response." } }, "security": [ { "session": [] } ], "summary": "post /system/check-mail", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases": { "get": { "description": "", "operationId": "get__api_v1_system_customer_cases", "parameters": [ { "description": "Exclude one request kind before counting and pagination. Use refund to keep refund cases out of the support list; access remains scoped to the current session.", "in": "query", "name": "exclude_kind", "schema": { "maxLength": 24, "type": "string" } }, { "description": "Limit refund cases to wallet top-ups or service cancellation.", "in": "query", "name": "refund_scope", "required": false, "schema": { "enum": [ "wallet", "service" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "List customer requests", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/unread": { "get": { "description": "Refund chats are excluded. Customers see only authorized workspace tickets; members see their own. Each administrator has an independent read watermark.", "operationId": "get__api_v1_system_customer_cases_unread", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportUnread" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Read personal ticket and notice unread counts", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}": { "get": { "description": "", "operationId": "get__api_v1_system_customer_cases__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Read request and replies", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/deletion-review": { "post": { "description": "Requires financial-liability acknowledgement. Revokes normal access immediately; closes customer export at exactly 30 days and retains all business records for authorised administrator export.", "operationId": "post__api_v1_system_customer_cases__id__deletion_review", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountClosureReview" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Confirm or reject logical account closure", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/manual-refund": { "post": { "description": "Requires customer agreement and completed-payment evidence. This records settlement; it never sends a bank transfer. Repeated confirmation cannot debit twice. Original Waffo/Paddle payments, including services, reject this declaration-only route with ORIGINAL_REFUND_REQUIRED.", "operationId": "post__api_v1_system_customer_cases__id__manual_refund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualRefundInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Record an actually completed alternative refund", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/messages": { "post": { "description": "Refund cases reject replies with REFUND_REVIEW_WORKFLOW; administrators approve or decline directly. Ordinary support tickets retain replies. Reviewed closures keep their privacy workflow status.", "operationId": "post__api_v1_system_customer_cases__id__messages", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportReply" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Reply to a support ticket", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/read": { "post": { "description": "Only messages through the last displayed message are marked read. Newer arrivals remain unread and delayed acknowledgements cannot move the watermark backward.", "operationId": "post__api_v1_system_customer_cases__id__read", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportReadInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Acknowledge displayed ticket messages", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/recover-original-refund": { "post": { "description": "Requires explicit administrator confirmation that no alternative transfer was actually made. Preserves the original evidence and uses compensating ledger entries. Only the remaining amount is requested from original payments.", "operationId": "post__api_v1_system_customer_cases__id__recover_original_refund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoverOriginalRefund" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" } }, "security": [ { "session": [] } ], "summary": "Correct an unpaid manual declaration and request original refund", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/refund-quote": { "post": { "description": "Fresh scope, amount and schedule preview. A changed service scope requires a new customer application; the administrator can directly decline the old one.", "operationId": "post__api_v1_system_customer_cases__id__refund_quote", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRefundPreviewInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ScopedRefundPreview" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Preview a pending scoped application before approval", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/customer/cases/{id}/refund-review": { "post": { "description": "Serialises on the target workspace. Approval reserves available wallet funds, allocates original-route refunds using stable provider request IDs, and retains any balance requiring an agreed alternative. Waffo/Paddle approvals create durable original-provider refund intents and issue merchant refund API requests. No manual declaration can complete these refunds. A processing/pending approval state is not settled funds.", "operationId": "post__api_v1_system_customer_cases__id__refund_review", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundReview" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SupportCaseDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Approve or reject customer refund", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/legal/policy": { "get": { "description": "", "operationId": "get__api_v1_system_legal_policy", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommercePolicy" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Read operator profile and pending policy versions", "x-platform-admin": true, "x-required-role": "owner" }, "patch": { "description": "Publication requires a confirmed operator legal name and valid contact email. Other profile details are optional and unconfirmed items are omitted from public documents. Published replacements preserve the previous version during at least 30 days of console and successfully dispatched email notice.", "operationId": "patch__api_v1_system_legal_policy", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommercePolicyInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommercePolicy" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Publish or schedule service policies", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/mail-jobs": { "get": { "description": "Platform-admin session only. Latest 50 messages with type, environment, recipient, attempts, status and cancellation reason. Delivered/cancelled payloads are erased. SMTP acceptance is not inbox delivery or reading.", "operationId": "get_api_v1_system_mail-jobs", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailJobList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "get /system/mail-jobs", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/mail-jobs/{id}/retry": { "post": { "description": "Resets the attempt count and queues the same failed message. Delivered, cancelled, running and pending jobs return MAIL_JOB_NOT_RETRYABLE. Billing jobs recheck current consent and event state before the new delivery attempt. SMTP errors never reverse a committed payment.", "operationId": "post__api_v1_system_mail_jobs__id__retry", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailQueued" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Retry a failed email with retained encrypted payload", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/operations": { "get": { "description": "Platform-admin session only. Append-only application log with actor, subject, reason and explicit changes.", "operationId": "get__api_v1_system_operations", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "user_id", "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "action", "schema": { "maxLength": 80, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformOperationList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "List administrative customer operations" } }, "/api/v1/system/overview": { "get": { "description": "Platform-admin session only. Package metrics use the current configured payment environment. New users covers the last 30 days; expiry covers the next 7 days.", "operationId": "get__api_v1_system_overview", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformOverview" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Read platform customer and package totals" } }, "/api/v1/system/paddle": { "get": { "operationId": "get__api_v1_system_paddle", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleSettings" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Read Paddle configuration without private keys", "x-licentivo-access": "platform" }, "patch": { "operationId": "patch__api_v1_system_paddle", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaddleSettingsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleSettings" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Save encrypted Paddle Billing credentials", "x-licentivo-access": "platform" } }, "/api/v1/system/paddle/check": { "post": { "operationId": "post__api_v1_system_paddle_check", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleCheck" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Verify Paddle credentials and active product", "x-licentivo-access": "platform" } }, "/api/v1/system/paddle/orders": { "get": { "operationId": "get__api_v1_system_paddle_orders", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderList" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "List Paddle service payments and wallet top-ups", "x-licentivo-access": "platform" } }, "/api/v1/system/paddle/orders/{id}/reconcile": { "post": { "operationId": "post__api_v1_system_paddle_orders__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaddleReconcileInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaddleOrderResult" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Reconcile or recover an original transaction without creating a charge", "x-licentivo-access": "platform" } }, "/api/v1/system/payment-channels": { "get": { "operationId": "get__api_v1_system_payment_channels", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaymentChannels" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "List independently configurable payment channels", "x-licentivo-access": "platform" }, "patch": { "operationId": "patch__api_v1_system_payment_channels", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentChannelInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaymentChannels" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Atomically enable or disable channels with optimistic concurrency", "x-licentivo-access": "platform" } }, "/api/v1/system/paypal": { "get": { "operationId": "get_api_v1_system_paypal", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "paypal", "x-platform-admin": true, "x-required-role": "owner" }, "patch": { "operationId": "patch_api_v1_system_paypal", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayPalInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "paypal", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/paypal/check": { "post": { "operationId": "post_api_v1_system_paypal_check", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalCheck" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "paypal/check", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/paypal/orders/{id}/refund": { "post": { "description": "Platform-admin session only. Reserves available unspent wallet credit before contacting PayPal. Pending means the result is not confirmed; reconcile the same request. Does not automatically cancel a package.", "operationId": "post__api_v1_system_paypal_orders__id__refund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalRefund" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." } }, "security": [ { "session": [] } ], "summary": "Refund unused wallet funds to the original PayPal payment method" } }, "/api/v1/system/paypal/refund-requests": { "get": { "description": "Cookie sessions only; management API keys are not accepted. Customer reads are scoped to their workspace. Customer writes require a verified workspace Owner, without platform administrator permission. Applications do not move or reserve funds. Administrator approval re-checks the current wallet and unrefunded captured value, then uses the existing idempotent original-route refund and reservation flow. Approval does not cancel plans.", "operationId": "get__api_v1_system_paypal_refund_requests", "parameters": [ { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletRefundRequestList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" } }, "security": [ { "session": [] } ], "summary": "List customer refund applications for review", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/paypal/refund-requests/{id}/review": { "post": { "description": "Cookie sessions only; management API keys are not accepted. Customer reads are scoped to their workspace. Customer writes require a verified workspace Owner, without platform administrator permission. Applications do not move or reserve funds. Administrator approval re-checks the current wallet and unrefunded captured value, then uses the existing idempotent original-route refund and reservation flow. Approval does not cancel plans.", "operationId": "post__api_v1_system_paypal_refund_requests__id__review", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletRefundReview" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletRefundRequest" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, authentication, ownership, review conflict or balance error" } }, "security": [ { "session": [] } ], "summary": "Approve or decline a customer refund application", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/paypal/refunds": { "get": { "description": "Platform-admin session only.", "operationId": "get__api_v1_system_paypal_refunds", "parameters": [ { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RefundList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." } }, "security": [ { "session": [] } ], "summary": "List refund requests for the selected payment environment" } }, "/api/v1/system/paypal/refunds/{id}/reconcile": { "post": { "description": "Platform-admin session only. Retries the same PayPal-Request-Id if the refund ID was not received, or fetches the existing provider refund.", "operationId": "post__api_v1_system_paypal_refunds__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PayPalRefund" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." } }, "security": [ { "session": [] } ], "summary": "Reconcile the same refund without a new charge identity" } }, "/api/v1/system/plan-gifts": { "get": { "description": "Platform-admin session only. The given recipient represents the deduplicated workspace. Search matches recipient email, workspace or package name.", "operationId": "get__api_v1_system_plan_gifts", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "maximum": 100000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "q", "schema": { "type": "string" } }, { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "user_id", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanGiftList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "List gift history" }, "post": { "description": "Platform-admin session only. Atomic batch. Supply fingerprint from preview and a stable request_id; matching replay returns the same batch. Changes to the tier or schedule require a fresh preview. Gifts retain zero actual payment and cannot become a cash refund. Their captured benefit value is credited normally when upgrading. Only new unstarted current-tier gifts follow a later upgrade with no extra payment, retaining their dates. Historical gifts are never realigned; monthly quotas and overage rules apply normally. Mixed batches use current/--- metadata; inspect individual purchase-backed gift records for each actual tier and currency.", "operationId": "post__api_v1_system_plan_gifts", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanGiftInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanGiftResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Confirm a reviewed current-tier gift" } }, "/api/v1/system/plan-gifts/preview": { "post": { "description": "Platform-admin session only. 1–100 distinct active customer user IDs. Users in the same workspace receive one contract. Each item inherits that customer’s current effective package, or last expired package in the selected environment. Mixed-tier batches return the actual plan and benefit value per item. Omit plan/currency/price_version; optional explicit values must match every customer’s existing package. Customers without a package cannot receive a different tier through this endpoint. after_current appends after all paid/gifted coverage; immediate rejects overlapping rights. No writes or charges.", "operationId": "post__api_v1_system_plan_gifts_preview", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanGiftPreviewInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanGiftPreview" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Preview a current-tier package gift" } }, "/api/v1/system/plan-gifts/{id}/cancel": { "post": { "description": "Platform-admin session only. Repeated cancellation is safe. Stops this contract without deleting history, refunding overage or moving other scheduled contracts.", "operationId": "post__api_v1_system_plan_gifts__id__cancel", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformReason" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlanGiftCancellation" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Cancel an active or scheduled gift" } }, "/api/v1/system/plans": { "get": { "operationId": "get_api_v1_system_plans", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AdminPlanList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "plans", "x-platform-admin": true, "x-required-role": "owner" }, "post": { "operationId": "post_api_v1_system_plans", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Price" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "plans", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/plans/customer-controls": { "patch": { "description": "Platform-admin session only. Both switches default false. Supply device_enabled, api_enabled, or both. Omitted switches retain their current state. Each disabled switch hides its customer controls and ignores only its own saved preference until re-enabled. API allowances marked unlimited remain unlimited.", "operationId": "patch__api_v1_system_plans_customer_controls", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerControlsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CustomerControlsResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Independently allow customer device or API overage settings" } }, "/api/v1/system/plans/default": { "patch": { "operationId": "patch_api_v1_system_plans_default", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefaultPlan" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DefaultPlan" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "plans/default", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/privacy/retention": { "get": { "description": "", "operationId": "get__api_v1_system_privacy_retention", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Read archival and retention runs", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/privacy/retention/run": { "post": { "description": "Logical archival only; customer/business rows are preserved. Rotates authenticated managed .lvb backup files after 90 days and app-owned security logs after six calendar months. Runs serialize with a database lock.", "operationId": "post__api_v1_system_privacy_retention_run", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Confirmation" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CommerceResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Process already-due archival and retention", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/provider-refunds/{id}/reconcile": { "post": { "description": "Queries the existing request by its provider/business reference. Only a previously unsubmitted durable intent may issue its first request; duplicate or unknown submissions are never posted again. Completion requires independently verified original provider receipts.", "operationId": "post__api_v1_system_provider_refunds__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProviderRefund" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" } }, "security": [ { "session": [] } ], "summary": "Reconcile the existing original-channel refund", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/refund-requests": { "get": { "description": "Read-only platform administrator session. Combines wallet refund applications and provider wallet/service cancellation cases. Environment-scoped pending counts are independent of pagination and scope filters. Reading never approves, freezes or refunds funds; use each source’s existing review endpoint.", "operationId": "get_system_refund_requests", "parameters": [ { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "review", "schema": { "enum": [ "pending", "all" ], "type": "string" } }, { "in": "query", "name": "scope", "schema": { "enum": [ "wallet", "service" ], "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RefundInboxList" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "Environment-scoped requests and pending review counts" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, session or permission error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, session or permission error" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, session or permission error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, session or permission error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, session or permission error" } }, "security": [ { "session": [] } ], "summary": "Unified customer refund review queue", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/refunds": { "get": { "operationId": "get__api_v1_system_refunds", "parameters": [ { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RefundHistory" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" } }, "security": [ { "session": [] } ], "summary": "List refunds across PayPal, Waffo and Paddle", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/revenue": { "get": { "operationId": "get_api_v1_system_revenue", "parameters": [ { "in": "query", "name": "mode", "schema": { "enum": [ "sandbox", "live" ], "type": "string" } }, { "in": "query", "name": "month", "schema": { "description": "all or UTC YYYY-MM", "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Revenue" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "revenue", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/sdk-example": { "post": { "description": "Platform administrator Owner session only, with CSRF. API keys are rejected. Reuses the dedicated product and policy; does not renew existing trials.", "operationId": "post_api_v1_system_sdk-example", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SDKExampleSetup" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SDKExampleSetting" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "Prepare/enable the administrator’s dedicated public SDK example product", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/service/incidents": { "get": { "description": "", "operationId": "get__api_v1_system_service_incidents", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ServiceIncidentList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Read all service notices", "x-platform-admin": true, "x-required-role": "owner" }, "post": { "description": "Non-emergency maintenance needs at least 24 hours notice. A continuous verified incident exceeding 24 hours credits actual affected paid time; overlapping intervals are not compensated twice. More than seven days can qualify for unused-service refund.", "operationId": "post__api_v1_system_service_incidents", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceIncidentInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ServiceIncident" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Publish maintenance or resolve an incident", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/settings": { "get": { "operationId": "get_api_v1_system_settings", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SystemSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "get /system/settings", "x-platform-admin": true, "x-required-role": "owner" }, "patch": { "operationId": "patch_api_v1_system_settings", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "patch /system/settings", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/test-mail": { "post": { "description": "Explicitly enqueue one real test message to the supplied recipient using the saved delivery service. HTTP 202 confirms queue acceptance, not inbox arrival. Follow the job status and inspect the provider dashboard/inbox for delivery issues.", "operationId": "post_api_v1_system_test-mail", "parameters": [ { "description": "Required for cookie/public-auth writes; exempt only for supported Bearer resource writes", "in": "header", "name": "X-CSRF-Token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestMail" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MailQueued" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] } ], "summary": "post /system/test-mail", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/tls": { "get": { "description": "Platform-administrator browser session only. Management API keys and tenant owners are rejected. Reflects the certificate used by this process. No certificate PEM or private key is exposed.", "operationId": "get__api_v1_system_tls", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TLSStatus" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success; only public certificate metadata is returned." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED and TLS_SETTINGS_CONFLICT leave the previous certificate in place." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED and TLS_SETTINGS_CONFLICT leave the previous certificate in place." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED and TLS_SETTINGS_CONFLICT leave the previous certificate in place." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED and TLS_SETTINGS_CONFLICT leave the previous certificate in place." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED and TLS_SETTINGS_CONFLICT leave the previous certificate in place." } }, "security": [ { "session": [] } ], "summary": "Read the active HTTPS certificate" }, "patch": { "description": "Platform-administrator browser session only. Management API keys and tenant owners are rejected. Validates and encrypts the certificate/key in MySQL, records an audit event, then swaps the active certificate. New TLS handshakes use it immediately; existing connections continue normally. A restart uses the database certificate in preference to bootstrap files.", "operationId": "patch__api_v1_system_tls", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TLSCertificateUpdateInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TLSCertificateResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success; only public certificate metadata is returned." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED and TLS_SETTINGS_CONFLICT leave the previous certificate in place." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED and TLS_SETTINGS_CONFLICT leave the previous certificate in place." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED and TLS_SETTINGS_CONFLICT leave the previous certificate in place." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED and TLS_SETTINGS_CONFLICT leave the previous certificate in place." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED and TLS_SETTINGS_CONFLICT leave the previous certificate in place." } }, "security": [ { "session": [] } ], "summary": "Replace the HTTPS certificate immediately" } }, "/api/v1/system/tls/check": { "post": { "description": "Platform-administrator browser session only. Management API keys and tenant owners are rejected. Checks format, key strength, key match, hostname, validity and trust chain. Direct HTTPS must be enabled. The active certificate is unchanged.", "operationId": "post__api_v1_system_tls_check", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TLSCertificateInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TLSCertificateInfo" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success; only public certificate metadata is returned." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED and TLS_SETTINGS_CONFLICT leave the previous certificate in place." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED and TLS_SETTINGS_CONFLICT leave the previous certificate in place." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED and TLS_SETTINGS_CONFLICT leave the previous certificate in place." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED and TLS_SETTINGS_CONFLICT leave the previous certificate in place." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code. TLS_KEY_MISMATCH, TLS_DOMAIN_MISMATCH, TLS_EXPIRED, TLS_CHAIN_UNTRUSTED and TLS_SETTINGS_CONFLICT leave the previous certificate in place." } }, "security": [ { "session": [] } ], "summary": "Validate a certificate and private key without saving" } }, "/api/v1/system/translation": { "get": { "description": "Platform-admin session only.", "operationId": "get__api_v1_system_translation", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TranslationSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." } }, "security": [ { "session": [] } ], "summary": "Read DeepL settings without exposing the API key" }, "patch": { "description": "Platform-admin session only. Use expected_version from the most recent GET. The key is never returned.", "operationId": "patch__api_v1_system_translation", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationSettingsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TranslationSettings" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." } }, "security": [ { "session": [] } ], "summary": "Save encrypted DeepL settings" } }, "/api/v1/system/translation/check": { "post": { "description": "Calls only DeepL language and usage endpoints; no forum content is sent.", "operationId": "post__api_v1_system_translation_check", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TranslationCheck" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See error.code and error.message; request_id identifies the request." } }, "security": [ { "session": [] } ], "summary": "Verify the saved API key and retrieve supported languages and usage" } }, "/api/v1/system/users": { "get": { "description": "Platform-admin session only. Includes unverified accounts and team members; never returns hashes or authentication tokens.", "operationId": "get__api_v1_system_users", "parameters": [ { "description": "Case-insensitive partial email, name or workspace match; wildcard characters are escaped.", "in": "query", "name": "q", "schema": { "maxLength": 254, "type": "string" } }, { "in": "query", "name": "status", "schema": { "enum": [ "active", "disabled" ], "type": "string" } }, { "in": "query", "name": "role", "schema": { "enum": [ "owner", "read_only" ], "type": "string" } }, { "in": "query", "name": "verified", "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformUserList" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "List all registered users" } }, "/api/v1/system/users/export.csv": { "get": { "description": "Platform-admin session only. Maximum 10000 matching records, UTF-8 BOM and spreadsheet formula escaping. No credentials.", "operationId": "get__api_v1_system_users_export_csv", "parameters": [ { "description": "Case-insensitive partial email, name or workspace match; wildcard characters are escaped.", "in": "query", "name": "q", "schema": { "maxLength": 254, "type": "string" } }, { "in": "query", "name": "status", "schema": { "enum": [ "active", "disabled" ], "type": "string" } }, { "in": "query", "name": "role", "schema": { "enum": [ "owner", "read_only" ], "type": "string" } }, { "in": "query", "name": "verified", "schema": { "enum": [ "true", "false" ], "type": "string" } } ], "responses": { "200": { "content": { "text/csv": { "schema": { "type": "string" } } }, "description": "CSV attachment" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Export filtered registered users as CSV" } }, "/api/v1/system/users/{id}": { "get": { "description": "Platform-admin session only. Workspace balances, the latest 20 contracts, and cumulative PayPal paid/refunded totals are separated by currency and environment.", "operationId": "get__api_v1_system_users__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformUserDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Read customer and workspace details" }, "patch": { "description": "Platform-admin session only. Requires an operation reason and optimistic version. Disabling revokes existing sessions, keys and login links. Restoring does not restore keys. Platform administrator accounts are protected.", "operationId": "patch__api_v1_system_users__id_", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformUserUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformUserDetail" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Update customer status or private admin note" } }, "/api/v1/system/users/{id}/data-export": { "post": { "description": "Available after account closure and after the customer deadline. Requires administrator password, scope and an audited operational reason. No business records are erased.", "operationId": "post__api_v1_system_users__id__data_export", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDataExportInput" } } }, "required": true }, "responses": { "200": { "content": { "application/zip": { "schema": { "format": "binary", "type": "string" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Export retained customer records", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/system/users/{id}/revoke-credentials": { "post": { "description": "Platform-admin session only. Does not disable the account; the customer can sign in again. Administrator credentials cannot be revoked here.", "operationId": "post__api_v1_system_users__id__revoke_credentials", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformReason" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformRevocation" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Revoke existing customer sessions and API keys" } }, "/api/v1/system/waffo": { "get": { "operationId": "get__api_v1_system_waffo", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoSettings" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Read Waffo settings without the signing key", "x-licentivo-access": "platform" }, "patch": { "operationId": "patch__api_v1_system_waffo", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaffoSettingsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoSettings" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Save encrypted Waffo credentials", "x-licentivo-access": "platform" } }, "/api/v1/system/waffo/check": { "post": { "operationId": "post__api_v1_system_waffo_check", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoCheck" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Verify Waffo credentials and active one-time product", "x-licentivo-access": "platform" } }, "/api/v1/system/waffo/orders": { "get": { "operationId": "get__api_v1_system_waffo_orders", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderList" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "List Waffo service payments and wallet top-ups", "x-licentivo-access": "platform" } }, "/api/v1/system/waffo/orders/{id}/reconcile": { "post": { "operationId": "post__api_v1_system_waffo_orders__id__reconcile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WaffoOrderResult" }, "request_id": { "description": "Local service-payment identifier.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Recover and reconcile the original Waffo payment", "x-licentivo-access": "platform" } }, "/api/v1/system/workspaces/{id}/status": { "patch": { "description": "Platform-admin session only. Suspension blocks login, management API and online licensing, and revokes credentials. Contract expiry keeps running. Platform workspaces are protected; signed offline caches remain governed by their existing expiry.", "operationId": "patch__api_v1_system_workspaces__id__status", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformWorkspaceUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PlatformWorkspaceStatus" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Inspect error.code and error.message." } }, "security": [ { "session": [] } ], "summary": "Suspend or restore an entire customer workspace" } }, "/api/v1/system/{provider}/orders/{id}/refund": { "post": { "description": "Platform administrator session. Paid service requires cancellation instead. An unapplied payment is refunded without wallet movements. Stable request_id persists intent before the gateway call; unknown outcomes are queried and never blindly re-posted.", "operationId": "post__api_v1_system__provider__orders__id__refund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "provider", "required": true, "schema": { "enum": [ "waffo", "paddle" ], "type": "string" } }, { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OriginalRefundInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OriginalRefundResult" }, "request_id": { "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Validation, ownership, environment, refund-state or provider error" } }, "security": [ { "session": [] } ], "summary": "Initiate an original-channel refund for unspent credit or unapplied payment", "x-platform-admin": true, "x-required-role": "owner" } }, "/api/v1/usage": { "get": { "description": "The current month reports active device registrations; past months report recorded device-use history. Purchased package API quotas follow their own quota months. Device history is retained after release. Current occupancy and billing peaks are separate measurements.", "operationId": "get_api_v1_usage", "parameters": [ { "description": "UTC natural month; defaults to current", "in": "query", "name": "month", "schema": { "description": "UTC month YYYY-MM; omitted query values use the current month. Billing jobs require a closed month.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "active_devices": 0, "api_calls": 0, "api_period": null, "billable_devices": 0, "estimated_total_cents": 0, "estimated_total_micros": 0, "month": "2026-09", "operations": [], "overage_devices": 0, "period": null, "products": [], "purchased": null, "purchased_active_devices": 0, "sandbox": false, "timezone": "UTC", "warning": "normal" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Usage", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "503": { "content": { "application/json": { "example": { "error": { "code": "DEFAULT_PLAN_DISABLED", "message": "The default allowance plan has not been enabled by the administrator" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Default allowance is disabled (DEFAULT_PLAN_DISABLED)" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Current device occupancy, historical device use and metered API usage", "x-management-reference": { "group": "usage" }, "x-required-scope": "read" } }, "/api/v1/usage/devices": { "get": { "description": "Device-use records for the selected UTC month, retained after device release. This is activity history, not a current online-device list. Use GET /api/v1/usage for current occupancy.", "operationId": "get_api_v1_usage_devices", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Page size, default 25, range 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "maximum": 100000, "minimum": 0, "type": "integer" } }, { "description": "UTC natural month; defaults to current", "in": "query", "name": "month", "schema": { "description": "UTC month YYYY-MM; omitted query values use the current month. Billing jobs require a closed month.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } }, { "in": "query", "name": "product_id", "schema": { "description": "Product UUID in the current workspace.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": [ { "device_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "first_seen_at": "2026-09-01T00:00:00Z", "last_seen_at": "2026-09-30T00:00:00Z", "month": "2026-09", "product_id": "11111111-1111-4111-8111-111111111111" } ], "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/UsageDeviceList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List usage devices", "x-management-reference": { "group": "usage" }, "x-required-scope": "read" } }, "/api/v1/usage/export.csv": { "get": { "description": "Device-use records for the selected UTC month, retained after device release. This is activity history, not a current online-device list. Use GET /api/v1/usage for current occupancy.", "operationId": "get_api_v1_usage_export_csv", "parameters": [ { "description": "UTC natural month; defaults to current", "in": "query", "name": "month", "schema": { "description": "UTC month YYYY-MM; omitted query values use the current month. Billing jobs require a closed month.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } } ], "responses": { "200": { "content": { "text/csv": { "example": "month,product_id,device_id,first_seen_utc,last_seen_utc\n", "schema": { "type": "string" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Export usage", "x-csv-columns": [ "month", "product_id", "device_id", "first_seen_utc", "last_seen_utc" ], "x-management-reference": { "group": "usage" }, "x-required-scope": "read" } }, "/api/v1/validate": { "post": { "description": "Authenticated by product_id + license_key + device_id. No cookie/CSRF/vendor key. activation_id required except activate. Each successful request consumes one API call; idempotent replay and failures do not. Overages debit wallet atomically or return API_QUOTA_EXCEEDED/API_BALANCE_INSUFFICIENT. Validation and heartbeat retry receipts expire after 3600 seconds. While the original authorization remains valid, matching requests within this window replay without another debit. After the window use a new key; a previously used key may be processed as a new request. Activation, deactivation and feature-usage receipts remain durable. Workspace device quota follows current activations. Release returns capacity; floating lease expiry also returns capacity, while an offline ordinary registration remains counted. Device overage is charged only when the quota-month billing peak increases beyond already paid capacity; release does not refund incurred fees. API usage is separate.", "operationId": "post_api_v1_validate", "parameters": [ { "description": "Generate a new key for each operation; retries keep the same key and body. Maximum 80 characters, no whitespace. Optional for validation and heartbeat.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 80, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeResult" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "Runtime validate" } }, "/api/v1/webhook-deliveries/{id}/attempts": { "get": { "operationId": "get_api_v1_webhook-deliveries_by_id_attempts", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": null }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AttemptList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List delivery attempts", "x-management-reference": { "group": "webhooks" }, "x-required-scope": "read" } }, "/api/v1/webhook-deliveries/{id}/retry": { "post": { "operationId": "post_api_v1_webhook-deliveries_by_id_retry", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "$ref": "#/components/schemas/Empty" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ID", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Retry webhook delivery", "x-management-reference": { "group": "webhooks" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/webhooks": { "get": { "operationId": "get_api_v1_webhooks", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": { "event_types": [], "items": [ { "created_at": "2026-10-18T00:00:00Z", "enabled": true, "events": [], "id": "33333333-3333-4333-8333-333333333333", "name": "Report app", "updated_at": "2026-10-18T00:00:00Z", "url": "https://merchant.example.com/license-events" } ] }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicensingWebhookList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List webhooks", "x-management-reference": { "group": "webhooks" }, "x-required-scope": "read" }, "post": { "operationId": "post_api_v1_webhooks", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "enabled": true, "events": [ "license.created", "license.renewed" ], "name": "Order system", "url": "https://merchant.example.com/license-events" }, "schema": { "$ref": "#/components/schemas/LicensingWebhookInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "id": "33333333-3333-4333-8333-333333333333", "secret": "whsec_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicensingWebhookSecret", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "Save webhook", "x-management-reference": { "group": "webhooks" }, "x-required-role": "owner", "x-required-scope": "write" } }, "/api/v1/webhooks/{id}/deliveries": { "get": { "operationId": "get_api_v1_webhooks_by_id_deliveries", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "Unique ID of this resource; use the matching resource ID in the path.", "format": "uuid", "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Page size, default 25, range 1–100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "default": 0, "description": "Records to skip, default 0, range 0–100000; add limit for the next page.", "maximum": 100000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "items": null, "limit": 25, "offset": 0, "total": 1 }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DeliveryList", "description": "Business result on success; failures use error instead." }, "request_id": { "description": "Top-level HTTP trace UUID. In batch/onboarding input it is a caller-generated idempotency UUID; these serve different purposes.", "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "example": { "error": { "code": "INVALID_INPUT", "message": "Invalid request fields" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHENTICATED", "message": "Please sign in again" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "message": "This operation requires an owner account" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "example": { "error": { "code": "CONFLICT", "message": "This value already exists" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "example": { "error": { "code": "JSON_REQUIRED", "message": "Use Content-Type: application/json" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "example": { "error": { "code": "RATE_LIMITED", "message": "Too many attempts; try again later" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "request_id": "55555555-5555-4555-8555-555555555555" }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [ { "session": [] }, { "managementKey": [] } ], "summary": "List webhook deliveries", "x-management-reference": { "group": "webhooks" }, "x-required-scope": "read" } }, "/healthz": { "get": { "operationId": "get_healthz", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Health" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" } }, "security": [], "summary": "Process liveness" } }, "/readyz": { "get": { "operationId": "get_readyz", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Health" }, "request_id": { "format": "uuid", "type": "string" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "See docs/error-codes.md; endpoint-specific applicability" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Database unavailable" } }, "security": [], "summary": "Database readiness" } } }, "servers": [ { "url": "https://www.licentivo.com" } ] }