--- openapi: 3.1.0 info: title: GPUaaS Public API version: 1.0.0-draft description: | Contract-first public API draft. Project context rule: - Operations that include `ProjectIdHeader` require `X-Project-ID`. - Operations that include `ProjectIdPath` derive project context from path. - If an operation carries both path and header project context in future revisions, values must match. contact: name: GPUaaS Platform Team email: platform@gpuaas.local servers: - url: http://localhost:8090 description: Local development tags: - name: Health - name: Auth - name: Users - name: Projects - name: SshKeys - name: Billing - name: Payments - name: Catalog - name: Nodes - name: Allocations - name: AllocationGroups - name: Storage - name: Apps - name: AppArtifacts - name: V3ReadModels - name: PlatformReleases - name: ServiceAccounts - name: ProjectAccessCredentials - name: AdminUsers - name: AdminRoles - name: AdminAccessCredentials - name: AdminMaasSites - name: AdminMaasLifecycle - name: AdminNodes - name: AdminSkus - name: AdminOSImages - name: AdminApps - name: AdminAllocations - name: AdminAudit - name: AdminPayments - name: AdminOps - name: InternalNodes - name: InternalAppProxy security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT nodeBearerAuth: type: http scheme: bearer bearerFormat: opaque-node-internal-token parameters: XRequestId: name: X-Request-Id in: header required: false schema: type: string maxLength: 128 IdempotencyKey: name: Idempotency-Key in: header required: false schema: type: string maxLength: 128 ProjectIdHeader: name: X-Project-ID in: header required: true description: Required project context for operations that include this parameter. Requests without this header are rejected. schema: type: string format: uuid Cursor: name: cursor in: query required: false schema: type: string PageSize: name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 200 default: 50 BillingFrom: name: from in: query required: false schema: type: string format: date-time BillingTo: name: to in: query required: false schema: type: string format: date-time BillingUsageSort: name: sort in: query required: false schema: type: string enum: - start_time_desc - start_time_asc - cost_desc - cost_asc default: start_time_desc AuditLogSort: name: sort in: query required: false description: Server-side audit evidence sort. Cursors are bound to the sort value used when the cursor was issued. schema: type: string enum: - occurred_at_desc - occurred_at_asc - action_asc - action_desc - result_asc - result_desc - target_asc - target_desc default: occurred_at_desc AllocationIdPath: name: allocation_id in: path required: true schema: type: string format: uuid AllocationGroupIdPath: name: allocation_group_id in: path required: true schema: type: string format: uuid UserIdPath: name: user_id in: path required: true schema: type: string format: uuid TenantIdPath: name: tenant_id in: path required: true schema: type: string format: uuid PlatformRolePath: name: role in: path required: true schema: type: string enum: - platform_superadmin - platform_ops - platform_user NodeIdPath: name: node_id in: path required: true schema: type: string format: uuid MaasSiteIdPath: name: id in: path required: true schema: type: string format: uuid MaasSiteProfileIdPath: name: profile_id in: path required: true schema: type: string format: uuid AccessCredentialIdPath: name: credential_id in: path required: true schema: type: string format: uuid OnboardingIdPath: name: onboarding_id in: path required: true schema: type: string format: uuid DecommissionIdPath: name: decommission_id in: path required: true schema: type: string format: uuid SkuPath: name: sku in: path required: true schema: type: string minLength: 1 OSImageIdPath: name: image_id in: path required: true schema: type: string format: uuid ProjectIdPath: name: project_id in: path required: true description: Project context derived from path for project-scoped operations. schema: type: string format: uuid OrgIdPath: name: org_id in: path required: true description: Tenant context derived from path for tenant-scoped operations. schema: type: string format: uuid ServiceAccountIdPath: name: service_account_id in: path required: true schema: type: string format: uuid AppSlugPath: name: app_slug in: path required: true schema: type: string pattern: "^[a-z0-9][a-z0-9-]{1,62}$" AppVersionPath: name: version in: path required: true schema: type: string minLength: 1 maxLength: 64 AppInstanceIdPath: name: app_instance_id in: path required: true schema: type: string format: uuid WorkloadIdPath: name: workload_id in: path required: true schema: type: string minLength: 1 maxLength: 128 V3TaskIdPath: name: task_id in: path required: true schema: type: string format: uuid V3StorageBucketIdPath: name: bucket_id in: path required: true schema: type: string minLength: 1 maxLength: 128 pattern: "^[A-Za-z0-9][A-Za-z0-9:_./-]{0,127}$" AppInstanceMemberIdPath: name: member_id in: path required: true schema: type: string format: uuid AppInstanceMemberOperationIdPath: name: operation_id in: path required: true schema: type: string format: uuid AppInstanceRepairOperationIdPath: name: repair_operation_id in: path required: true schema: type: string format: uuid SharedRuntimeIdPath: name: shared_runtime_id in: path required: true schema: type: string format: uuid SharedRuntimeAttachmentIdPath: name: attachment_id in: path required: true schema: type: string format: uuid SharedRuntimeWorkerIdPath: name: worker_id in: path required: true schema: type: string format: uuid SharedRuntimeWorkerOperationIdPath: name: operation_id in: path required: true schema: type: string format: uuid AppArtifactIdPath: name: artifact_id in: path required: true schema: type: string format: uuid SshKeyIdPath: name: key_id in: path required: true schema: type: string format: uuid InternalNodeIdPath: name: node_id in: path required: true schema: type: string minLength: 1 InternalTaskIdPath: name: task_id in: path required: true schema: type: string format: uuid V3StorageGrantIdPath: name: grant_id in: path required: true schema: type: string format: uuid V3StorageAttachmentIdPath: name: attachment_id in: path required: true schema: type: string format: uuid V3PlatformSignalKeyPath: name: signal_key in: path required: true schema: type: string minLength: 1 maxLength: 160 pattern: "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,159}$" V3ProvisioningAttentionKeyPath: name: attention_key in: path required: true schema: type: string minLength: 1 maxLength: 180 pattern: "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,179}$" V3StorageObjectPathQuery: name: path in: query required: true schema: type: string minLength: 1 maxLength: 1024 schemas: ErrorResponse: type: object additionalProperties: false properties: code: type: string description: 'Machine-readable error code. Stable across versions. See doc/architecture/Error_Code_Catalog.md for the full catalog. ' enum: - token_missing - token_invalid - token_expired - token_scope_invalid - auth_personal_disabled - auth_enterprise_required - auth_personal_required - insufficient_permissions - admin_required - ownership_required - step_up_required - validation_error - invalid_request - allocation_not_found - allocation_not_active - allocation_already_releasing - allocation_concurrency_limit - insufficient_balance - sku_unavailable - node_not_found - node_offline - node_in_use - node_already_exists - user_not_found - user_already_exists - stripe_signature_invalid - refund_window_exceeded - storage_object_not_found - storage_path_traversal - storage_already_exists - storage_quota_exceeded - sku_not_found - app_not_found - app_version_not_found - app_not_entitled - app_instance_not_found - app_instance_state_invalid - app_instance_quota_exceeded - rate_limit_exceeded - internal_error - upstream_error - service_unavailable message: type: string details: type: object additionalProperties: true correlation_id: type: string required: - code - message - correlation_id Pagination: type: object additionalProperties: false properties: next_cursor: type: string nullable: true page_size: type: integer required: - next_cursor - page_size Money: type: object additionalProperties: false properties: amount_minor: type: integer description: Amount in minor units (e.g. cents) currency: type: string pattern: "^[A-Z]{3}$" example: USD required: - amount_minor - currency BillingFXSnapshot: type: object additionalProperties: false description: | Immutable FX evidence shape used when billing presentation converts source-currency usage into a target customer currency. This is evidence only; historical ledger entries are never revalued. properties: source_currency: type: string pattern: "^[A-Z]{3}$" target_currency: type: string pattern: "^[A-Z]{3}$" rate: type: string description: Decimal rate encoded as a string to avoid floating point money math. example: '3.672500000000000000' provider: type: string example: manual provider_rate_id: type: string nullable: true captured_at: type: string format: date-time required: - source_currency - target_currency - rate - provider - provider_rate_id - captured_at BillingCurrencySettingsResponse: type: object additionalProperties: false description: Tenant billing currency settings. Live FX conversion is not performed by this endpoint. properties: tenant_id: type: string format: uuid default_currency: type: string pattern: "^[A-Z]{3}$" supported_currencies: type: array items: type: string pattern: "^[A-Z]{3}$" minItems: 1 fx_snapshot: "$ref": "#/components/schemas/BillingFXSnapshot" nullable: true required: - tenant_id - default_currency - supported_currencies - fx_snapshot BillingAccountResponse: type: object additionalProperties: false description: | Billing-owned account/channel shape. Reseller billing is modeled as a payer/rating layer above raw end-customer tenant usage, never as tenant impersonation. properties: billing_account_id: type: string format: uuid nullable: true tenant_id: type: string format: uuid account_type: type: string enum: - tenant - reseller - end_customer name: type: string parent_billing_account_id: type: string format: uuid nullable: true reseller_tenant_id: type: string format: uuid nullable: true invoice_recipient_tenant_id: type: string format: uuid nullable: true default_currency: type: string pattern: "^[A-Z]{3}$" wholesale_pricing_plan_id: type: string format: uuid nullable: true customer_pricing_plan_id: type: string format: uuid nullable: true tax_responsibility: type: string enum: - platform - reseller - end_customer credit_risk_owner: type: string enum: - platform - reseller status: type: string enum: - active - disabled - deleted required: - billing_account_id - tenant_id - account_type - display_name - parent_billing_account_id - reseller_tenant_id - invoice_recipient_tenant_id - default_currency - wholesale_pricing_plan_id - customer_pricing_plan_id - tax_responsibility - credit_risk_owner - status BillingBalanceResponse: type: object additionalProperties: false description: | Ledger-derived balance response. `balance` is kept for backward compatibility and represents the primary display currency. `balances` is the canonical per-currency list; clients must not sum currencies. properties: balance: "$ref": "#/components/schemas/Money" balances: type: array items: "$ref": "#/components/schemas/Money" minItems: 1 required: - balance - balances BillingInvoiceSummary: type: object additionalProperties: false properties: id: type: string format: uuid org_id: type: string format: uuid period_start: type: string format: date-time period_end: type: string format: date-time status: type: string enum: - draft - issued - due - paid - partially_paid - void - write_off total: "$ref": "#/components/schemas/Money" tax_total: "$ref": "#/components/schemas/Money" tax_jurisdiction: type: string nullable: true tax_treatment: type: string enum: - not_configured - standard - tax_exempt - reverse_charge seller_tax_registration: type: string nullable: true customer_tax_registration: type: string nullable: true tax_snapshot: type: object additionalProperties: true issued_at: type: string format: date-time nullable: true due_at: type: string format: date-time nullable: true finalized_at: type: string format: date-time nullable: true voided_at: type: string format: date-time nullable: true created_at: type: string format: date-time required: - id - org_id - period_start - period_end - status - total - tax_total - tax_jurisdiction - tax_treatment - seller_tax_registration - customer_tax_registration - tax_snapshot - created_at BillingInvoiceLine: type: object additionalProperties: false properties: id: type: string format: uuid line_type: type: string enum: - rated_usage - credit - adjustment - tax - fee - payment description: type: string amount: "$ref": "#/components/schemas/Money" rated_usage_line_id: type: string format: uuid nullable: true ledger_entry_id: type: string format: uuid nullable: true payment_session_id: type: string format: uuid nullable: true tax_category: type: string nullable: true tax_rate_bps: type: integer nullable: true minimum: 0 maximum: 10000 tax_jurisdiction: type: string nullable: true tax_subject_line_id: type: string format: uuid nullable: true tax_exempt_reason: type: string nullable: true reverse_charge_reason: type: string nullable: true tax_evidence: type: object additionalProperties: true created_at: type: string format: date-time required: - id - line_type - description - amount - tax_category - tax_rate_bps - tax_jurisdiction - tax_subject_line_id - tax_exempt_reason - reverse_charge_reason - tax_evidence - created_at BillingInvoiceDetail: allOf: - "$ref": "#/components/schemas/BillingInvoiceSummary" - type: object additionalProperties: false properties: lines: type: array items: "$ref": "#/components/schemas/BillingInvoiceLine" required: - lines BillingInvoiceListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/BillingInvoiceSummary" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination BillingBudgetEvent: type: object additionalProperties: false properties: id: type: string format: uuid threshold_key: type: string period_start: type: string format: date-time period_end: type: string format: date-time spent: "$ref": "#/components/schemas/Money" budget: "$ref": "#/components/schemas/Money" percent_used: type: integer format: int64 status: type: string enum: - open - acknowledged - resolved first_seen_at: type: string format: date-time last_seen_at: type: string format: date-time seen_count: type: integer correlation_id: type: string nullable: true required: - id - threshold_key - period_start - period_end - spent - budget - percent_used - status - first_seen_at - last_seen_at - seen_count BillingBudgetPosture: type: object additionalProperties: false properties: id: type: string format: uuid org_id: type: string format: uuid department_id: type: string format: uuid project_id: type: string format: uuid nullable: true scope_type: type: string enum: - tenant - project name: type: string period: type: string enum: - monthly - quarterly - annual - custom amount: "$ref": "#/components/schemas/Money" threshold_percent: type: integer enforcement_mode: type: string enum: - notify_only - block_launch - suspend active: type: boolean starts_at: type: string format: date-time ends_at: type: string format: date-time nullable: true latest_event: allOf: - "$ref": "#/components/schemas/BillingBudgetEvent" nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - org_id - department_id - project_id - scope_type - display_name - period - amount - threshold_percent - enforcement_mode - active - starts_at - latest_event - created_at - updated_at BillingBudgetPostureResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/BillingBudgetPosture" required: - items BillingBudgetDecisionRequest: type: object additionalProperties: false properties: project_id: type: string format: uuid proposed_amount: "$ref": "#/components/schemas/Money" required: - proposed_amount BillingBudgetDecisionItem: type: object additionalProperties: false properties: budget_policy_id: type: string format: uuid scope_type: type: string enum: - tenant - project project_id: type: string format: uuid nullable: true display_name: type: string enforcement_mode: type: string enum: - notify_only - block_launch - suspend decision: type: string enum: - allow - warn - would_block reason: type: string enum: - within_budget - threshold_crossed - budget_exceeded period_start: type: string format: date-time period_end: type: string format: date-time spent: "$ref": "#/components/schemas/Money" proposed_amount: "$ref": "#/components/schemas/Money" projected_spend: "$ref": "#/components/schemas/Money" budget: "$ref": "#/components/schemas/Money" threshold_percent: type: integer percent_used_before: type: integer format: int64 percent_used_after: type: integer format: int64 required: - budget_policy_id - scope_type - project_id - display_name - enforcement_mode - decision - reason - period_start - period_end - spent - proposed_amount - projected_spend - budget - threshold_percent - percent_used_before - percent_used_after BillingBudgetDecisionResponse: type: object additionalProperties: false properties: decision: type: string enum: - allow - warn - would_block items: type: array items: "$ref": "#/components/schemas/BillingBudgetDecisionItem" required: - decision - items BillingRatedUsageLine: type: object additionalProperties: false properties: id: type: string format: uuid usage_record_id: type: string format: uuid org_id: type: string format: uuid nullable: true project_id: type: string format: uuid nullable: true requested_by_user_id: type: string format: uuid usage_source: type: string enum: - allocation - app_runtime usage_unit: type: string bill_from: type: string format: date-time bill_to: type: string format: date-time unit_quantity_millis: type: integer format: int64 unit_price: "$ref": "#/components/schemas/Money" units: type: integer format: int64 amount: "$ref": "#/components/schemas/Money" pricing_source: type: string pricing_plan_id: type: string format: uuid nullable: true pricing_plan_version: type: string nullable: true pricing_snapshot: type: object additionalProperties: true fx_snapshot: "$ref": "#/components/schemas/BillingFXSnapshot" nullable: true rating_key: type: string ledger_entry_id: type: string format: uuid nullable: true invoice_line_id: type: string format: uuid nullable: true invoice_id: type: string format: uuid nullable: true created_at: type: string format: date-time required: - id - usage_record_id - org_id - project_id - requested_by_user_id - usage_source - usage_unit - bill_from - bill_to - unit_quantity_millis - unit_price - units - amount - pricing_source - pricing_plan_id - pricing_plan_version - pricing_snapshot - fx_snapshot - rating_key - ledger_entry_id - invoice_line_id - invoice_id - created_at BillingRatedUsageListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/BillingRatedUsageLine" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination BillingShadowRatingRequest: type: object additionalProperties: false properties: org_id: type: string format: uuid usage_record_ids: type: array minItems: 1 maxItems: 100 items: type: string format: uuid candidate_unit_price: "$ref": "#/components/schemas/Money" pricing_source: type: string default: shadow_rating pricing_plan_id: type: string format: uuid nullable: true pricing_plan_version: type: string nullable: true pricing_snapshot: type: object additionalProperties: true required: - org_id - usage_record_ids - candidate_unit_price BillingShadowRatingLine: type: object additionalProperties: false properties: usage_record_id: type: string format: uuid existing_rated_amount: "$ref": "#/components/schemas/Money" candidate_rated_amount: "$ref": "#/components/schemas/Money" delta_amount: "$ref": "#/components/schemas/Money" candidate_rating_key: type: string usage_source: type: string usage_unit: type: string bill_from: type: string format: date-time bill_to: type: string format: date-time unit_quantity_millis: type: integer format: int64 unit_price: "$ref": "#/components/schemas/Money" units: type: integer format: int64 pricing_source: type: string pricing_plan_id: type: string format: uuid nullable: true pricing_plan_version: type: string nullable: true pricing_snapshot: type: object additionalProperties: true required: - usage_record_id - existing_rated_amount - candidate_rated_amount - delta_amount - candidate_rating_key - usage_source - usage_unit - bill_from - bill_to - unit_quantity_millis - unit_price - units - pricing_source - pricing_plan_id - pricing_plan_version - pricing_snapshot BillingShadowRatingResponse: type: object additionalProperties: false properties: lines: type: array items: "$ref": "#/components/schemas/BillingShadowRatingLine" totals: type: object additionalProperties: false properties: existing_rated_amount: "$ref": "#/components/schemas/Money" candidate_rated_amount: "$ref": "#/components/schemas/Money" delta_amount: "$ref": "#/components/schemas/Money" required: - existing_rated_amount - candidate_rated_amount - delta_amount ledger_writes: type: boolean description: Always false for dry-run shadow rating. rated_usage_writes: type: boolean description: Always false for dry-run shadow rating. required: - lines - totals - ledger_writes - rated_usage_writes HealthResponse: type: object additionalProperties: false properties: ok: type: boolean required: - ok User: type: object additionalProperties: false properties: id: type: string format: uuid username: type: string role: type: string enum: - user - admin required: - id - username - role PlatformRole: type: string enum: - platform_superadmin - platform_ops - platform_user PlatformCapability: type: string enum: - platform.admin - platform.ops.read - platform.ops.write - platform.ops.runbook.read - platform.node.read - platform.audit.read UserWithBalance: allOf: - "$ref": "#/components/schemas/User" - type: object additionalProperties: false properties: org_id: type: string format: uuid nullable: true project_id: type: string format: uuid nullable: true org_name: type: string nullable: true project_name: type: string nullable: true platform_roles: type: array items: "$ref": "#/components/schemas/PlatformRole" platform_role_source: type: string enum: - users_role - bindings platform_capabilities: type: array items: "$ref": "#/components/schemas/PlatformCapability" balance: "$ref": "#/components/schemas/Money" required: - balance Project: type: object additionalProperties: false properties: id: type: string format: uuid org_id: type: string format: uuid org_name: type: string department_id: type: string format: uuid description: Non-null department/cost-center attribution for the project. department_name: type: string department_slug: type: string name: type: string slug: type: string role: type: string enum: - owner - admin - member - viewer is_default: type: boolean created_at: type: string format: date-time required: - id - org_id - org_name - department_id - department_name - department_slug - name - slug - role - is_default - created_at Department: type: object additionalProperties: false description: Organization-scoped cost-center and reporting anchor. Department attribution is mandatory for projects, but department-level administration, budgets, policy inheritance, approval workflows, and always-visible UX controls are capability-gated. properties: id: type: string format: uuid org_id: type: string format: uuid display_name: type: string slug: type: string is_default: type: boolean lifecycle_state: type: string enum: - active - disabled created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - org_id - display_name - slug - is_default - lifecycle_state - created_at - updated_at ProjectListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/Project" required: - items CreateProjectRequest: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 120 slug: type: string pattern: "^[a-z0-9][a-z0-9-]{1,62}$" department_id: type: string format: uuid description: Optional enterprise department selection. When omitted, the API assigns the organization's default department. required: - name CreateProjectResponse: type: object additionalProperties: false properties: project: "$ref": "#/components/schemas/Project" required: - project UpdateProjectRequest: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 120 slug: type: string pattern: "^[a-z0-9][a-z0-9-]{1,62}$" DeleteProjectResponse: type: object additionalProperties: false properties: ok: type: boolean project_id: type: string format: uuid required: - ok - project_id V3ReadModelMeta: type: object additionalProperties: false properties: generated_at: type: string format: date-time cache: type: string enum: - hit - miss - bypass - stale description: Safe read-model cache state for debugging and tests. required: - generated_at - cache V3ShellMode: type: string enum: - user - tenant_admin - project_admin - platform_admin - ops V3ShellModeOption: type: object additionalProperties: false description: Backend-owned persona mode and default landing route for the v3 shell. properties: id: "$ref": "#/components/schemas/V3ShellMode" label: type: string default_landing: type: string description: Absolute frontend route for this mode's default v3 production landing page. is_active: type: boolean required: - id - label - default_landing - is_active V3Region: type: object additionalProperties: false properties: code: type: string api_region_code: type: string label: type: string is_default: type: boolean is_available: type: boolean availability_state: type: string enum: - available - planned - maintenance - disabled capacity_scope_hint: type: string nullable: true required: - code - api_region_code - label - is_default - is_available - availability_state - capacity_scope_hint V3RegionListResponse: type: object additionalProperties: false properties: current_region_code: type: string nullable: true items: type: array items: "$ref": "#/components/schemas/V3Region" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - current_region_code - items - meta V3ShellContext: type: object additionalProperties: false properties: mode: "$ref": "#/components/schemas/V3ShellMode" available_modes: type: array items: "$ref": "#/components/schemas/V3ShellMode" mode_options: type: array items: "$ref": "#/components/schemas/V3ShellModeOption" user: type: object additionalProperties: false properties: id: type: string format: uuid username: type: string display_name: type: string required: - id - username - display_name tenant: type: object additionalProperties: false nullable: true properties: id: type: string format: uuid name: type: string required: - id - name project: type: object additionalProperties: false nullable: true properties: id: type: string format: uuid name: type: string slug: type: string required: - id - name - slug regions: type: array items: "$ref": "#/components/schemas/V3Region" balance: "$ref": "#/components/schemas/Money" nullable: true attention: type: object additionalProperties: false properties: active_workloads: type: integer minimum: 0 needs_action: type: integer minimum: 0 active_tasks: type: integer minimum: 0 unread_notifications: type: integer minimum: 0 required: - active_workloads - needs_action - active_tasks - unread_notifications meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - mode - available_modes - mode_options - user - tenant - project - regions - balance - attention - meta V3ShellContextResponse: type: object additionalProperties: false properties: context: "$ref": "#/components/schemas/V3ShellContext" required: - context V3WorkloadKind: type: string enum: - compute - jupyter - vllm - training - scheduler - kubernetes - app V3WorkloadStatus: type: string enum: - requested - provisioning - active - idle - stopped - completed - restarting - restart_failed - releasing - released - failed - release_failed V3WorkloadSummary: type: object additionalProperties: false properties: id: type: string minLength: 1 maxLength: 128 allocation_id: type: string format: uuid nullable: true app_instance_id: type: string format: uuid nullable: true name: type: string kind: "$ref": "#/components/schemas/V3WorkloadKind" status: "$ref": "#/components/schemas/V3WorkloadStatus" project_id: type: string format: uuid project_name: type: string region_code: type: string nullable: true sku: type: string nullable: true node_id: type: string format: uuid nullable: true node_name: type: string nullable: true owner_user_id: type: string format: uuid owner_username: type: string app_slug: type: string nullable: true app_name: type: string nullable: true created_at: type: string format: date-time active_at: type: string format: date-time nullable: true hourly_rate: "$ref": "#/components/schemas/Money" nullable: true accrued_cost: "$ref": "#/components/schemas/Money" nullable: true cost_projection: "$ref": "#/components/schemas/V3WorkloadCostProjection" description: Backend-owned billing/runway projection. Clients render these fields and basis labels; they must not recompute runway from partial workload data. needs_action: type: boolean description: Backward-compatible alias for is_actionable. New v3 clients should prefer is_actionable. action_required: type: boolean description: True when the workload state represents a recovery condition, even if the item has aged into history. is_actionable: type: boolean description: Server-derived actionability flag using control-plane time; clients must not recompute actionable_until locally. actionable_until: type: string format: date-time nullable: true description: Time until which a recovery condition should be shown in live attention surfaces. Null means the workload has no time-boxed recovery action. archived_at: type: string format: date-time nullable: true description: Non-null when the row belongs to workload history and is hidden from default runtime lists unless include_history=true or an explicit status filter is used. action_reason: type: string nullable: true runtime_readiness: "$ref": "#/components/schemas/V3RuntimeReadiness" description: Backend-derived app/workload readiness impact from bound node inventory. Decommissioned node, node-agent unreachable, MAAS reconciliation failure, and no schedulable GPU capacity conditions must be surfaced here instead of UI-only labels. blocking_app_use: "$ref": "#/components/schemas/V3WorkloadBlockingAppUse" nullable: true description: Active app workload currently using this allocation as placement, if any. Launch clients use this server-derived fact to disable targets instead of inferring from app_slug alone. primary_action: type: string enum: - open - connect - open_notebook - try_endpoint - open_training_ui - retry_release - review - none connection_facts: "$ref": "#/components/schemas/V3WorkloadConnectionFacts" lifecycle_actions: type: array description: Backend-owned lifecycle affordances for this workload row. Clients render these actions and disabled reasons; they must not infer lifecycle eligibility from status alone. items: "$ref": "#/components/schemas/V3WorkloadLifecycleAction" operator_state: "$ref": "#/components/schemas/V3WorkloadOperatorState" required: - id - allocation_id - app_instance_id - name - kind - status - project_id - project_name - region_code - sku - node_id - node_name - owner_user_id - owner_username - app_slug - app_name - created_at - active_at - hourly_rate - accrued_cost - cost_projection - needs_action - action_required - is_actionable - actionable_until - archived_at - action_reason - runtime_readiness - blocking_app_use - primary_action - connection_facts - lifecycle_actions - operator_state V3WorkloadBlockingAppUse: type: object additionalProperties: false properties: kind: type: string enum: - app_instance - app_instance_member app_instance_id: type: string format: uuid display_name: type: string app_slug: type: string status: type: string component_key: type: string nullable: true required: - kind - app_instance_id - display_name - app_slug - status - component_key V3WorkloadCostProjection: type: object additionalProperties: false description: Backend-owned cost and runway interpretation for a workload row. Null money fields mean the owning service could not provide that input; basis explains whether runway is actionable or unavailable. properties: balance: "$ref": "#/components/schemas/Money" nullable: true hourly_rate: "$ref": "#/components/schemas/Money" nullable: true accrued_cost: "$ref": "#/components/schemas/Money" nullable: true runway_seconds: type: integer format: int64 nullable: true description: Seconds until projected balance depletion at the current hourly rate. Null when the projection basis is not an active positive rate. projected_depletion_at: type: string format: date-time nullable: true basis: type: string enum: - active_rate - zero_rate - rate_unavailable - balance_unavailable - owner_unavailable - currency_mismatch description: Why runway fields are populated or intentionally unavailable. required: - balance - hourly_rate - accrued_cost - runway_seconds - projected_depletion_at - basis V3RuntimeReadiness: type: object additionalProperties: false properties: ready: type: boolean severity: type: string enum: - ok - info - warn - error - blocker reason_code: type: string enum: - ready - decommissioned_node - node_agent_unreachable - maas_reconciliation_failed - no_schedulable_gpu_capacity - node_unavailable - node_not_schedulable - app_runtime_failed - app_runtime_unhealthy - allocation_not_active - runtime_readiness_unknown reason_codes: type: array items: type: string summary: type: string required: - ready - severity - reason_code - reason_codes - summary V3WorkloadConnectionFacts: type: object additionalProperties: false description: Copyable connection fields promoted to the workload row so users do not need to open a detail page just to find host/IP/SSH/terminal access. properties: hostname: type: string nullable: true ip_address: type: string nullable: true ssh_command: type: string nullable: true terminal_href: type: string nullable: true app_url: type: string nullable: true terminal_startup_failure: "$ref": "#/components/schemas/V3TerminalStartupFailure" nullable: true required: - hostname - ip_address - ssh_command - terminal_href - app_url V3TerminalStartupFailure: type: object additionalProperties: false description: Latest structured node-agent terminal startup failure for this workload, if one has been reported. properties: occurred_at: type: string format: date-time session_id: type: string nullable: true allocation_id: type: string nullable: true node_id: type: string nullable: true close_reason: type: string enum: - open_failed - node_stream_timeout error_code: type: string nullable: true error_message: type: string nullable: true runtime_username: type: string nullable: true correlation_id: type: string nullable: true required: - occurred_at - session_id - allocation_id - node_id - close_reason - error_code - error_message - runtime_username - correlation_id V3WorkloadLifecycleAction: type: object additionalProperties: false properties: action: type: string enum: - release - restart - stop - start - open label: type: string enabled: type: boolean disabled_reason: type: string nullable: true method: type: string enum: - POST - GET - none href: type: string nullable: true idempotency_required: type: boolean result: "$ref": "#/components/schemas/V3WorkloadLifecycleResultHint" required: - action - label - enabled - disabled_reason - method - href - idempotency_required - result V3WorkloadLifecycleResultHint: type: object additionalProperties: false properties: task_href: type: string nullable: true description: Stable task pivot if one is already known. Null before a lifecycle submission is accepted. evidence_href: type: string nullable: true description: Stable evidence pivot if one is already known. Null before a lifecycle submission receives its correlation id. correlation_id: type: string nullable: true required: - task_href - evidence_href - correlation_id V3AppInstanceOperationResponse: type: object additionalProperties: false description: Evidence-bearing response for accepted V3 app runtime lifecycle operations. properties: app_instance: "$ref": "#/components/schemas/AppInstance" operation: type: string enum: - stop - start - restart - decommission correlation_id: type: string evidence_href: type: string task_href: type: string nullable: true audit_action: type: string required: - app_instance - operation - correlation_id - evidence_href - task_href - audit_action V3WorkloadOperatorState: type: object additionalProperties: false description: Backend-owned operator attention and ack/suppression state for a workload. properties: active: type: boolean attention_key: type: string nullable: true description: Backend-owned attention key. Clients must pass it opaquely and never derive it. signal_key: type: string nullable: true description: Backend-owned mutation handle for ack/suppression. Clients must pass it opaquely and never derive it. target_type: type: string target_id: type: string nullable: true action_family: type: string nullable: true attention_reason: type: string nullable: true review_required: type: boolean review_state: "$ref": "#/components/schemas/V3ProvisioningReviewState" ack_fingerprint: type: string nullable: true description: Backend-owned fingerprint for resurface detection. Clients must never derive it. ack_state: "$ref": "#/components/schemas/V3PlatformAckState" ack_reason: type: string nullable: true ack_expires_at: type: string format: date-time nullable: true ack_actor: type: string nullable: true ack_updated_at: type: string format: date-time nullable: true required: - active - attention_key - signal_key - target_type - target_id - action_family - attention_reason - review_required - review_state - ack_fingerprint - ack_state - ack_reason - ack_expires_at - ack_actor - ack_updated_at V3WorkloadActionBandItem: type: object additionalProperties: false properties: severity: type: string enum: - info - warn - error code: type: string title: type: string summary: type: string workload_id: type: string minLength: 1 maxLength: 128 action_label: type: string action_href: type: string required: - severity - code - title - summary - workload_id - action_label - action_href V3WorkloadListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3WorkloadSummary" action_band: type: array items: "$ref": "#/components/schemas/V3WorkloadActionBandItem" counts: type: object additionalProperties: false properties: active: type: integer minimum: 0 provisioning: type: integer minimum: 0 needs_action: type: integer minimum: 0 released: type: integer minimum: 0 required: - active - provisioning - needs_action - released pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - items - action_band - counts - pagination - meta V3WorkloadDetailResponse: type: object additionalProperties: false properties: workload: "$ref": "#/components/schemas/V3WorkloadSummary" context: type: object additionalProperties: false properties: project: type: string region: type: string nullable: true node: type: string nullable: true owner: type: string age_seconds: type: integer minimum: 0 required: - project - region - node - owner - age_seconds tabs: type: object additionalProperties: false properties: overview: type: object additionalProperties: true connect: type: object additionalProperties: true metrics: type: object additionalProperties: true events: type: object additionalProperties: true storage: type: object additionalProperties: true config: type: object additionalProperties: true required: - overview - connect - metrics - events - storage - config "$ref": "#/components/schemas/V3WorkloadDetailTabs" runtime_presentation: allOf: - "$ref": "#/components/schemas/V3AppRuntimePresentation" nullable: true meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - workload - context - tabs - runtime_presentation - meta V3TaskStatus: type: string enum: - queued - running - succeeded - failed - canceled - unknown V3TaskResourceKind: type: string enum: - workload - allocation - app_instance - node - storage - unknown V3TaskAction: type: object additionalProperties: false nullable: true properties: label: type: string href: type: string kind: type: string enum: - open_resource - retry - view_logs - none required: - label - href - kind V3TaskSummary: type: object additionalProperties: false properties: id: type: string format: uuid kind: type: string enum: - launch - release - restart - lifecycle - app_operation - unknown status: "$ref": "#/components/schemas/V3TaskStatus" title: type: string summary: type: string nullable: true resource_kind: "$ref": "#/components/schemas/V3TaskResourceKind" resource_id: type: string nullable: true resource_name: type: string nullable: true project_id: type: string format: uuid project_name: type: string correlation_id: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time completed_at: type: string format: date-time nullable: true primary_action: "$ref": "#/components/schemas/V3TaskAction" required: - id - kind - status - title - summary - resource_kind - resource_id - resource_name - project_id - project_name - correlation_id - created_at - updated_at - completed_at - primary_action V3TaskTimelineItem: type: object additionalProperties: false properties: kind: type: string enum: - accepted - workflow - placement - node_task - completion - failure - unknown name: type: string status: "$ref": "#/components/schemas/V3TaskStatus" started_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true duration_seconds: type: integer minimum: 0 nullable: true summary: type: string nullable: true source: type: string enum: - allocation - node_task - app_instance - synthetic required: - kind - name - status - started_at - completed_at - duration_seconds - summary - source V3TaskListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3TaskSummary" counts: type: object additionalProperties: false properties: queued: type: integer minimum: 0 running: type: integer minimum: 0 succeeded: type: integer minimum: 0 failed: type: integer minimum: 0 required: - queued - running - succeeded - failed pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - items - counts - pagination - meta V3TaskDetailResponse: type: object additionalProperties: false properties: task: "$ref": "#/components/schemas/V3TaskSummary" context: type: object additionalProperties: false properties: project: type: string resource_href: type: string nullable: true timeline_source: type: string enum: - allocation_timeline - synthetic required: - project - resource_href - timeline_source timeline: type: array items: "$ref": "#/components/schemas/V3TaskTimelineItem" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - task - context - timeline - meta V3ComputeAvailabilityState: type: string enum: - available - limited - unavailable V3ComputeResourceClass: type: string description: 'User-facing SKU resource class. This is broader than capacity_shape: it lets the catalog describe future CPU-only and infrastructure classes while the active SKU contract uses explicit resource and billing-unit fields instead of GPU-shaped defaults. ' enum: - gpu_baremetal - gpu_slice - cpu_vm - cpu_baremetal - control_plane V3ComputeBillingUnit: type: string enum: - gpu_hour - node_hour - vcpu_hour V3ComputeSchedulingUnit: type: string enum: - node - slice - vm V3ComputeAcceleratorResource: type: object additionalProperties: false properties: vendor: type: string model: type: string nullable: true count: type: integer minimum: 0 memory_mib: type: integer minimum: 0 nullable: true partition_profile: type: string nullable: true required: - vendor - count V3ComputeCPUResource: type: object additionalProperties: false properties: vcpu_count: type: integer minimum: 1 architecture: type: string nullable: true required: - vcpu_count V3ComputeMemoryResource: type: object additionalProperties: false properties: memory_mib: type: integer minimum: 1 required: - memory_mib V3ComputeStorageResource: type: object additionalProperties: false properties: local_storage_mib: type: integer minimum: 0 storage_class: type: string nullable: true required: - local_storage_mib V3ComputeSkuResources: type: object additionalProperties: false properties: resource_class: "$ref": "#/components/schemas/V3ComputeResourceClass" billing_unit: "$ref": "#/components/schemas/V3ComputeBillingUnit" scheduling_unit: "$ref": "#/components/schemas/V3ComputeSchedulingUnit" accelerator: "$ref": "#/components/schemas/V3ComputeAcceleratorResource" nullable: true cpu: "$ref": "#/components/schemas/V3ComputeCPUResource" nullable: true memory: "$ref": "#/components/schemas/V3ComputeMemoryResource" nullable: true local_storage: "$ref": "#/components/schemas/V3ComputeStorageResource" nullable: true required: - resource_class - billing_unit - scheduling_unit V3ComputeSkuSummary: type: object additionalProperties: false properties: sku: type: string display_name: type: string vendor: type: string family_id: type: string family_version: type: string family_display_name: type: string resource_class: "$ref": "#/components/schemas/V3ComputeResourceClass" billing_unit: "$ref": "#/components/schemas/V3ComputeBillingUnit" scheduling_unit: "$ref": "#/components/schemas/V3ComputeSchedulingUnit" resources: "$ref": "#/components/schemas/V3ComputeSkuResources" unit_price: "$ref": "#/components/schemas/Money" availability_state: "$ref": "#/components/schemas/V3ComputeAvailabilityState" available_units: type: integer minimum: 0 description: Product-safe current launch estimate. For VM SKUs this can include ready workers plus on-demand capacity from a shared provider pool. ready_units: type: integer minimum: 0 description: Idle schedulable workers that can bind immediately without provider VM creation. on_demand_units: type: integer minimum: 0 description: Estimated VM units that can be prepared from provider capacity. This is not reserved and can change when other VM SKUs consume the same pool. capacity_basis: type: string enum: - none - ready_worker - provider_capacity - mixed description: Explains whether catalog availability comes from ready workers, shared provider capacity, both, or neither. shared_capacity: type: boolean description: True when the SKU availability includes a provider capacity pool shared with other VM SKUs. capacity_note: type: string description: Product-safe explanation of the capacity posture. capacity_alternatives: type: array description: Alternative VM SKU units that could fit in the same shared provider pool if reserved now. These alternatives are not additive; creating one VM changes the remaining capacity for the others. items: type: object additionalProperties: false properties: sku: type: string display_name: type: string units_if_reserved_now: type: integer minimum: 0 required: - sku - display_name - units_if_reserved_now image_count: type: integer minimum: 0 launch_href: type: string required: - sku - display_name - vendor - family_id - family_version - family_display_name - resource_class - billing_unit - scheduling_unit - resources - unit_price - availability_state - available_units - ready_units - on_demand_units - capacity_basis - shared_capacity - capacity_note - image_count - launch_href V3ComputeImageSummary: type: object additionalProperties: false properties: id: type: string format: uuid slug: type: string display_name: type: string target: type: string enum: - baremetal - vm_slice - compute_vm driver_strategy: type: string enum: - preinstalled - cloud_init - none compatible_skus: type: array items: type: string status: type: string enum: - active - disabled required: - id - slug - display_name - target - driver_strategy - compatible_skus - status V3ComputeCatalogResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3ComputeSkuSummary" images: type: array items: "$ref": "#/components/schemas/V3ComputeImageSummary" counts: type: object additionalProperties: false properties: total: type: integer minimum: 0 gpu_baremetal: type: integer minimum: 0 gpu_slice: type: integer minimum: 0 cpu_vm: type: integer minimum: 0 cpu_baremetal: type: integer minimum: 0 control_plane: type: integer minimum: 0 available: type: integer minimum: 0 required: - total - gpu_baremetal - gpu_slice - cpu_vm - cpu_baremetal - control_plane - available pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - items - images - counts - pagination - meta V3LaunchPrecheckSeverity: type: string enum: - ok - warn - blocker V3LaunchPrecheckStatus: type: string enum: - ok - warn - blocker - unknown V3LaunchInlineActionKind: type: string enum: - none - create_ssh_key - create_bucket - create_network_policy - create_service_account - add_funds - request_quota - select_sku - select_image V3LaunchPrecheckCheck: type: object additionalProperties: false properties: id: type: string pattern: "^[a-z0-9][a-z0-9_-]{1,62}$" label: type: string status: "$ref": "#/components/schemas/V3LaunchPrecheckStatus" severity: "$ref": "#/components/schemas/V3LaunchPrecheckSeverity" message: type: string action_label: type: string nullable: true action_href: type: string nullable: true inline_action_kind: "$ref": "#/components/schemas/V3LaunchInlineActionKind" required: - id - label - status - severity - message - action_label - action_href - inline_action_kind V3LaunchPrecheckEstimate: type: object additionalProperties: false properties: hourly_rate: "$ref": "#/components/schemas/Money" nullable: true monthly_estimate: "$ref": "#/components/schemas/Money" nullable: true billing_mode: type: string enum: - on_demand - spot - reserved nullable: true required: - hourly_rate - monthly_estimate - billing_mode V3ComputeLaunchPrecheckRequest: type: object additionalProperties: false properties: sku: type: string minLength: 1 resource_class: "$ref": "#/components/schemas/V3ComputeResourceClass" unit_count: type: integer minimum: 1 nullable: true os_image_slug: type: string nullable: true region_code: type: string nullable: true scheduler_type: type: string enum: - bare_metal - slurm - k8s - ray nullable: true ssh_key_ids: type: array items: type: string format: uuid storage_bucket_ids: type: array items: type: string network_policy_id: type: string nullable: true scheduler_request: type: object additionalProperties: true required: - sku V3AppLaunchPrecheckRequest: type: object additionalProperties: false properties: app_version: type: string nullable: true display_name: type: string nullable: true placement_intent: "$ref": "#/components/schemas/AppInstancePlacementIntent" nullable: true operator_service_account_id: type: string format: uuid nullable: true dependencies: type: object additionalProperties: true config: type: object additionalProperties: true V3LaunchPrecheckResponse: type: object additionalProperties: false properties: ready: type: boolean severity: "$ref": "#/components/schemas/V3LaunchPrecheckSeverity" checks: type: array items: "$ref": "#/components/schemas/V3LaunchPrecheckCheck" estimate: "$ref": "#/components/schemas/V3LaunchPrecheckEstimate" resolved: type: object additionalProperties: true meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - ready - severity - checks - estimate - resolved - meta V3AppDependency: type: string enum: - ssh - storage - network - service_account - api_key V3AppKind: type: string enum: - jupyter - vllm - training - vector_db - labeling - tgi - scheduler - kubernetes - app V3AppPublisher: type: object additionalProperties: false properties: name: type: string tone: type: string enum: - core42 - project - community required: - name - tone V3AppEntitlementSummary: type: object additionalProperties: false properties: enabled: type: boolean reason: type: string nullable: true required: - enabled - reason V3AppRuntimeConfigField: type: object additionalProperties: false properties: name: type: string type: type: string description: type: string nullable: true default: nullable: true enum: type: array items: type: string required: - name - type - description - default - enum V3AppRuntimeConfigGroup: type: object additionalProperties: false properties: id: type: string title: type: string fields: type: array items: type: string required: - id - title - fields V3AppRuntimeEndpoint: type: object additionalProperties: false properties: name: type: string label: type: string port: type: integer nullable: true protocol: type: string default_open_path: type: string nullable: true readiness_path: type: string nullable: true required: - name - label - port - protocol - default_open_path - readiness_path V3AppRuntimePresentation: type: object additionalProperties: false properties: family: type: string runtime_label: type: string primary_surface: type: string target_label: type: string member_label: type: string nullable: true member_plural_label: type: string nullable: true add_member_label: type: string nullable: true controller_label: type: string nullable: true worker_label: type: string nullable: true config_defaults: type: object additionalProperties: true config_fields: type: array items: "$ref": "#/components/schemas/V3AppRuntimeConfigField" config_groups: type: array items: "$ref": "#/components/schemas/V3AppRuntimeConfigGroup" endpoints: type: array items: "$ref": "#/components/schemas/V3AppRuntimeEndpoint" target_requirements: "$ref": "#/components/schemas/V3AppRuntimeTargetRequirements" required: - family - runtime_label - primary_surface - target_label - member_label - member_plural_label - add_member_label - controller_label - worker_label - config_defaults - config_fields - config_groups - endpoints - target_requirements V3AppRuntimeTargetRequirements: type: object additionalProperties: false properties: min_root_disk_mib: type: integer minimum: 0 description: Minimum target root disk capacity required for app bootstrap and managed routes. reason: type: string nullable: true required: - min_root_disk_mib - reason V3AppCatalogItem: type: object additionalProperties: false properties: slug: type: string pattern: "^[a-z0-9][a-z0-9-]{1,62}$" name: type: string category: type: string kind: "$ref": "#/components/schemas/V3AppKind" publisher: "$ref": "#/components/schemas/V3AppPublisher" short_description: type: string long_description: type: string status: type: string enum: - active - deprecated - disabled version: type: string versions_available: type: array items: type: string primary_surface: type: string runtime_presentation: "$ref": "#/components/schemas/V3AppRuntimePresentation" dependencies: type: array items: "$ref": "#/components/schemas/V3AppDependency" pricing_hint: type: string support_tier: "$ref": "#/components/schemas/V3AppSupportTier" featured: type: boolean entitlement: "$ref": "#/components/schemas/V3AppEntitlementSummary" launch_href: type: string detail_href: type: string required: - slug - name - category - kind - publisher - short_description - long_description - status - version - versions_available - primary_surface - runtime_presentation - dependencies - pricing_hint - support_tier - featured - entitlement - launch_href - detail_href V3AppVersionSummary: type: object additionalProperties: false properties: version: type: string runtime_backend: type: string enum: - k8s - rke2 - slurm - ray - bare_metal status: type: string enum: - active - deprecated - disabled latest: type: boolean entitled: type: boolean required: - version - runtime_backend - status - latest - entitled V3AppSupportTier: type: object additionalProperties: false properties: level: type: string enum: - demo_ready - preview label: type: string summary: type: string required: - level - label - summary V3AppCatalogResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3AppCatalogItem" featured: type: array items: "$ref": "#/components/schemas/V3AppCatalogItem" categories: type: array items: type: string pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - items - featured - categories - pagination - meta V3AppDetailResponse: type: object additionalProperties: false properties: app: "$ref": "#/components/schemas/V3AppCatalogItem" versions: type: array items: "$ref": "#/components/schemas/V3AppVersionSummary" permissions: type: object additionalProperties: false properties: project_enabled: type: boolean allowed_versions: type: array items: type: string launch_roles: type: array items: type: string required: - project_enabled - allowed_versions - launch_roles examples: type: object additionalProperties: false properties: language: type: string nullable: true code: type: string nullable: true required: - language - code running_workloads: type: array items: "$ref": "#/components/schemas/V3WorkloadSummary" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - app - versions - permissions - examples - running_workloads - meta V3StorageBucketPurpose: type: string enum: - workspace - dataset - checkpoint - artifact - generic V3StorageFlagSeverity: type: string enum: - info - warn - error V3StorageBackendType: type: string enum: - local_dev - weka - vast - ddn - nvme_pool - s3_compatible - unknown V3StorageAccessProtocol: type: string enum: - wekafs - posix - s3 - nfs - smb - csi V3StoragePerformanceTier: type: string enum: - standard - performance - capacity - archive - unknown V3StorageProviderCapability: type: object additionalProperties: false description: 'User-safe storage provider capability hints. This object never exposes provider credentials, backend endpoints, mount secrets, cluster IDs, or raw volume identifiers. ' properties: backend_type: "$ref": "#/components/schemas/V3StorageBackendType" display_name: type: string performance_tier: "$ref": "#/components/schemas/V3StoragePerformanceTier" access_protocols: type: array items: type: string enum: - posix - nfs - s3 - smb - csi - wekafs mount_modes: type: array items: type: string enum: - read_only - read_write - multi_writer multi_attach: type: boolean encryption: type: boolean kms_managed: type: boolean snapshots: type: boolean versioning: type: boolean retention: type: boolean quotas: type: boolean region_constraints: type: array items: type: string fabric_constraints: type: array items: type: string required: - backend_type - display_name - performance_tier - access_protocols - mount_modes - multi_attach - encryption - kms_managed - snapshots - versioning - retention - quotas - region_constraints - fabric_constraints V3StorageBucketFlag: type: object additionalProperties: false properties: code: type: string enum: - quota_near_limit - unattached - failed_mount - retention_pending - permission_drift - lifecycle_drift severity: "$ref": "#/components/schemas/V3StorageFlagSeverity" title: type: string summary: type: string action_label: type: string nullable: true action_href: type: string nullable: true required: - code - severity - title - summary - action_label - action_href V3StorageBucketUsage: type: object additionalProperties: false properties: used_bytes: type: integer format: int64 minimum: 0 quota_bytes: type: integer format: int64 minimum: 0 nullable: true percent: type: number format: double minimum: 0 nullable: true required: - used_bytes - quota_bytes - percent V3StorageBucketMount: type: object additionalProperties: false properties: workload_id: type: string minLength: 1 maxLength: 128 workload_name: type: string workload_kind: "$ref": "#/components/schemas/V3WorkloadKind" mount_path: type: string access_mode: type: string enum: - read_only - read_write state: type: string enum: - mounted - pending - failed - detached mounted_at: type: string format: date-time nullable: true required: - workload_id - workload_name - workload_kind - mount_path - access_mode - state - mounted_at V3StorageAttachmentState: type: string enum: - requested - prechecking - grant_applying - grant_applied - mounting - mounted - failed - detaching - detached - detach_failed V3StorageAttachmentAccessMode: type: string enum: - read_only - read_write V3StorageAttachmentWritePolicy: type: string enum: - single_writer - multi_writer V3StorageAttachment: type: object additionalProperties: false description: Runtime binding between one project storage namespace and one allocation or workload mount. Provider secrets, raw backend mount commands, and cluster identifiers are never returned. properties: id: type: string format: uuid bucket_id: type: string minLength: 1 maxLength: 128 project_id: type: string format: uuid allocation_id: type: string format: uuid nullable: true workload_instance_id: type: string format: uuid nullable: true node_id: type: string format: uuid nullable: true mount_path: type: string minLength: 1 maxLength: 256 access_mode: "$ref": "#/components/schemas/V3StorageAttachmentAccessMode" write_policy: "$ref": "#/components/schemas/V3StorageAttachmentWritePolicy" provider_backend: "$ref": "#/components/schemas/V3StorageBackendType" state: "$ref": "#/components/schemas/V3StorageAttachmentState" workflow_id: type: string nullable: true failure_code: type: string nullable: true failure_message: type: string nullable: true requested_by_user_id: type: string format: uuid nullable: true requested_at: type: string format: date-time mounted_at: type: string format: date-time nullable: true detached_at: type: string format: date-time nullable: true updated_at: type: string format: date-time required: - id - bucket_id - project_id - allocation_id - workload_instance_id - node_id - mount_path - access_mode - write_policy - provider_backend - state - workflow_id - failure_code - failure_message - requested_by_user_id - requested_at - mounted_at - detached_at - updated_at V3StorageAttachmentCreateRequest: type: object additionalProperties: false description: Request attachment of one storage namespace to one allocation or workload. Exactly one of allocation_id or workload_instance_id must be provided. properties: allocation_id: type: string format: uuid nullable: true workload_instance_id: type: string format: uuid nullable: true mount_path: type: string minLength: 1 maxLength: 256 access_mode: "$ref": "#/components/schemas/V3StorageAttachmentAccessMode" write_policy: "$ref": "#/components/schemas/V3StorageAttachmentWritePolicy" nullable: true required: - allocation_id - workload_instance_id - mount_path - access_mode - write_policy V3StorageAttachmentResponse: type: object additionalProperties: false properties: attachment: "$ref": "#/components/schemas/V3StorageAttachment" evidence: "$ref": "#/components/schemas/V3MutationEvidence" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - attachment - meta V3StorageAttachmentListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3StorageAttachment" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - items - pagination - meta V3StorageAccessAudience: type: object additionalProperties: false properties: kind: type: string enum: - project_members - service_accounts - workload_bound label: type: string count: type: integer minimum: 0 drift_count: type: integer minimum: 0 summary: type: string required: - kind - label - count - drift_count - summary V3StorageLifecycleSummary: type: object additionalProperties: false properties: retention_policy: type: string enum: - keep_forever - delete_after_30d - delete_after_90d - scheduled_delete versioning_enabled: type: boolean auto_snapshot_enabled: type: boolean scheduled_delete_at: type: string format: date-time nullable: true required: - retention_policy - versioning_enabled - auto_snapshot_enabled - scheduled_delete_at V3StorageObjectPreview: type: object additionalProperties: false properties: key: type: string kind: type: string enum: - prefix - object size_bytes: type: integer format: int64 minimum: 0 nullable: true updated_at: type: string format: date-time nullable: true required: - key - kind - size_bytes - updated_at V3StorageBucketSummary: type: object additionalProperties: false properties: id: type: string minLength: 1 maxLength: 128 name: type: string status: type: string enum: - creating - active - failed - deleting - deleted purpose: "$ref": "#/components/schemas/V3StorageBucketPurpose" project_id: type: string format: uuid project_name: type: string owner_user_id: type: string format: uuid nullable: true owner_username: type: string nullable: true region_code: type: string nullable: true provider: "$ref": "#/components/schemas/V3StorageProviderCapability" access_protocol: "$ref": "#/components/schemas/V3StorageAccessProtocol" encryption: type: string enum: - project_default - kms_managed - unknown usage: "$ref": "#/components/schemas/V3StorageBucketUsage" mounted_workloads: type: array items: "$ref": "#/components/schemas/V3StorageBucketMount" flags: type: array items: "$ref": "#/components/schemas/V3StorageBucketFlag" created_at: type: string format: date-time nullable: true updated_at: type: string format: date-time nullable: true required: - id - name - status - purpose - project_id - project_name - owner_user_id - owner_username - region_code - provider - access_protocol - encryption - usage - mounted_workloads - flags - created_at - updated_at V3StorageBucketCreateRequest: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 128 pattern: "^[A-Za-z0-9][A-Za-z0-9:_-]{0,127}$" purpose: "$ref": "#/components/schemas/V3StorageBucketPurpose" access_protocol: "$ref": "#/components/schemas/V3StorageAccessProtocol" description: Primary access protocol requested for this storage object. Omitted requests default to WEKAFS/POSIX for the first production WEKA path. quota_gb: type: integer minimum: 1 maximum: 1048576 nullable: true encryption: type: string enum: - project_default - kms_managed retention: type: string enum: - keep_forever - keep_30d - keep_90d - scheduled_delete access_audience: type: string enum: - project_members - service_accounts - workload_bound service_account_id: type: string nullable: true mount_intent: type: string maxLength: 256 nullable: true required: - name - purpose - quota_gb - encryption - retention - access_audience - service_account_id - mount_intent V3StorageBucketCreateResponse: type: object additionalProperties: false properties: bucket: "$ref": "#/components/schemas/V3StorageBucketSummary" open_href: type: string meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - bucket - open_href - meta V3StorageBucketUpdateRequest: type: object additionalProperties: false properties: purpose: "$ref": "#/components/schemas/V3StorageBucketPurpose" access_protocol: "$ref": "#/components/schemas/V3StorageAccessProtocol" quota_gb: type: integer minimum: 1 maximum: 1048576 nullable: true encryption: type: string enum: - project_default - kms_managed retention: type: string enum: - keep_forever - keep_30d - keep_90d - scheduled_delete access_audience: type: string enum: - project_members - service_accounts - workload_bound service_account_id: type: string nullable: true mount_intent: type: string maxLength: 256 nullable: true V3StorageBucketArchiveRequest: type: object additionalProperties: false properties: reason: type: string maxLength: 256 nullable: true V3StorageBucketMutationEvidence: type: object additionalProperties: false properties: correlation_id: type: string audit_action: type: string enum: - storage.bucket.update - storage.bucket.archive - storage.bucket.delete project_id: type: string format: uuid bucket_id: type: string required: - correlation_id - audit_action - project_id - bucket_id V3MutationEvidence: type: object additionalProperties: false description: Durable user/operator pivot for a completed V3 mutation. It is safe to show in the UI and link to evidence/audit surfaces; it must never contain raw provider payloads or secrets. properties: correlation_id: type: string audit_action: type: string evidence_href: type: string nullable: true task_href: type: string nullable: true operation_id: type: string nullable: true target_type: type: string target_id: type: string required: - correlation_id - audit_action - evidence_href - task_href - operation_id - target_type - target_id V3StorageBucketMutationResponse: type: object additionalProperties: false properties: bucket: "$ref": "#/components/schemas/V3StorageBucketSummary" evidence: "$ref": "#/components/schemas/V3StorageBucketMutationEvidence" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - bucket - evidence - meta V3StorageActionBandItem: type: object additionalProperties: false properties: severity: "$ref": "#/components/schemas/V3StorageFlagSeverity" code: type: string title: type: string summary: type: string bucket_id: type: string minLength: 1 maxLength: 128 action_label: type: string action_href: type: string required: - severity - code - title - summary - bucket_id - action_label - action_href V3StorageBucketListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3StorageBucketSummary" action_band: type: array items: "$ref": "#/components/schemas/V3StorageActionBandItem" counts: type: object additionalProperties: false properties: total: type: integer minimum: 0 attached: type: integer minimum: 0 unattached: type: integer minimum: 0 flagged: type: integer minimum: 0 total_used_bytes: type: integer format: int64 minimum: 0 total_quota_bytes: type: integer format: int64 minimum: 0 nullable: true required: - total - attached - unattached - flagged - total_used_bytes - total_quota_bytes pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - items - action_band - counts - pagination - meta V3StorageBucketDetailResponse: type: object additionalProperties: false properties: bucket: "$ref": "#/components/schemas/V3StorageBucketSummary" context: type: object additionalProperties: false properties: purpose: "$ref": "#/components/schemas/V3StorageBucketPurpose" project: type: string owner: type: string nullable: true encryption: type: string enum: - project_default - kms_managed - unknown usage_percent: type: number format: double minimum: 0 nullable: true created_at: type: string format: date-time nullable: true required: - purpose - project - owner - encryption - usage_percent - created_at tabs: type: object additionalProperties: false properties: overview: type: object additionalProperties: false properties: flags: type: array items: "$ref": "#/components/schemas/V3StorageBucketFlag" access: type: array items: "$ref": "#/components/schemas/V3StorageAccessAudience" lifecycle: "$ref": "#/components/schemas/V3StorageLifecycleSummary" required: - flags - access - lifecycle objects: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3StorageObjectPreview" required: - items mounts: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3StorageBucketMount" required: - items access: type: object additionalProperties: false properties: audiences: type: array items: "$ref": "#/components/schemas/V3StorageAccessAudience" required: - audiences lifecycle: "$ref": "#/components/schemas/V3StorageLifecycleSummary" events: type: object additionalProperties: false properties: items: type: array items: type: object additionalProperties: false properties: occurred_at: type: string format: date-time actor: type: string nullable: true action: type: string summary: type: string required: - occurred_at - actor - action - summary required: - items required: - overview - objects - mounts - access - lifecycle - events meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - bucket - context - tabs - meta V3AccessSeverity: type: string enum: - info - warn - error V3AccessSubjectKind: type: string enum: - user - service_account - workload - platform_role - identity_provider V3AccessDriftItem: type: object additionalProperties: false properties: severity: "$ref": "#/components/schemas/V3AccessSeverity" code: type: string enum: - expiring_credential - stale_member - policy_mismatch - entitlement_drift - missing_owner - provider_link_required title: type: string summary: type: string subject_kind: "$ref": "#/components/schemas/V3AccessSubjectKind" subject_id: type: string action_label: type: string nullable: true action_href: type: string nullable: true required: - severity - code - title - summary - subject_kind - subject_id - action_label - action_href V3AccessMembershipRow: type: object additionalProperties: false properties: user_id: type: string format: uuid username: type: string display_name: type: string tenant_role: type: string enum: - owner - admin - member - billing_viewer nullable: true project_role: type: string enum: - owner - admin - member - viewer nullable: true access_source: type: string enum: - project_role - tenant_role - explicit - platform_role x-enum-varnames: - V3AccessMembershipRowAccessSourceProjectRole - V3AccessMembershipRowAccessSourceTenantRole - V3AccessMembershipRowAccessSourceExplicit - V3AccessMembershipRowAccessSourcePlatformRole last_seen_at: type: string format: date-time nullable: true drift: type: array items: "$ref": "#/components/schemas/V3AccessDriftItem" required: - user_id - username - display_name - tenant_role - project_role - access_source - last_seen_at - drift V3AccessServiceAccountRow: type: object additionalProperties: false properties: id: type: string format: uuid name: type: string project_id: type: string format: uuid project_name: type: string status: type: string enum: - active - disabled scopes: type: array items: type: string used_by_workloads: type: array items: type: object additionalProperties: false properties: workload_id: type: string workload_name: type: string required: - workload_id - workload_name key_age_days: type: integer minimum: 0 nullable: true rotation_due_at: type: string format: date-time nullable: true drift: type: array items: "$ref": "#/components/schemas/V3AccessDriftItem" required: - id - name - project_id - project_name - status - scopes - used_by_workloads - key_age_days - rotation_due_at - drift V3AccessCredentialRow: type: object additionalProperties: false properties: id: type: string kind: type: string enum: - ssh_key - personal_api_key - service_account_key - workload_api_key subject_kind: "$ref": "#/components/schemas/V3AccessSubjectKind" subject_id: type: string label: type: string fingerprint: type: string nullable: true last_used_at: type: string format: date-time nullable: true expires_at: type: string format: date-time nullable: true status: type: string enum: - active - expiring - expired - disabled - revoked managed_in: type: string enum: - account - access - platform required: - id - kind - subject_kind - subject_id - label - fingerprint - last_used_at - expires_at - status - managed_in V3AccessEntitlementRow: type: object additionalProperties: false properties: id: type: string kind: type: string enum: - app - sku - region - product - tenant - project name: type: string project_id: type: string format: uuid project_name: type: string enabled: type: boolean allowed_versions: type: array items: type: string limits: type: object additionalProperties: true drift: type: array items: "$ref": "#/components/schemas/V3AccessDriftItem" required: - id - kind - name - project_id - project_name - enabled - allowed_versions - limits - drift V3AccessAuditEvent: type: object additionalProperties: false description: Access-family lifecycle/audit event scoped to the active tenant/project context. properties: id: type: string occurred_at: type: string format: date-time source: type: string enum: - membership - service_account - credential - entitlement - identity - connectivity - audit action: type: string status: type: string enum: - success - failure severity: "$ref": "#/components/schemas/V3AccessSeverity" actor: type: string subject: type: string target_type: type: string target_id: type: string nullable: true summary: type: string correlation_id: type: string href: type: string nullable: true required: - id - occurred_at - source - action - status - severity - actor - subject - target_type - target_id - summary - correlation_id - href V3AccessOperation: type: object additionalProperties: false description: Server-owned operation affordance for V3 access lifecycle actions. Row-scoped operations use templated hrefs and are disabled until the UI supplies the selected target. properties: key: type: string source: type: string enum: - membership - service_account - credential - entitlement - identity - connectivity label: type: string method: type: string enum: - GET - POST - PUT - PATCH - DELETE href: type: string target_type: type: string target_id: type: string nullable: true enabled: type: boolean disabled_reason: type: string nullable: true danger: type: string enum: - safe - low - medium - high - destructive audit_action: type: string result: type: string latest_actor: type: string nullable: true latest_at: type: string format: date-time nullable: true evidence_href: type: string nullable: true required: - key - source - label - method - href - target_type - target_id - enabled - disabled_reason - danger - audit_action - result - latest_actor - latest_at - evidence_href V3AccessOverviewResponse: type: object additionalProperties: false properties: counts: type: object additionalProperties: false properties: members: type: integer minimum: 0 service_accounts: type: integer minimum: 0 credentials: type: integer minimum: 0 entitlements: type: integer minimum: 0 drift: type: integer minimum: 0 required: - members - service_accounts - credentials - entitlements - drift drift: type: array items: "$ref": "#/components/schemas/V3AccessDriftItem" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - counts - drift - meta V3AccessMembershipListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3AccessMembershipRow" pagination: "$ref": "#/components/schemas/Pagination" operations: type: array items: "$ref": "#/components/schemas/V3AccessOperation" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - items - pagination - operations - meta V3AccessServiceAccountListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3AccessServiceAccountRow" pagination: "$ref": "#/components/schemas/Pagination" operations: type: array items: "$ref": "#/components/schemas/V3AccessOperation" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - items - pagination - operations - meta V3AccessCredentialListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3AccessCredentialRow" pagination: "$ref": "#/components/schemas/Pagination" operations: type: array items: "$ref": "#/components/schemas/V3AccessOperation" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - items - pagination - operations - meta V3AccessEntitlementListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3AccessEntitlementRow" pagination: "$ref": "#/components/schemas/Pagination" operations: type: array items: "$ref": "#/components/schemas/V3AccessOperation" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - items - pagination - operations - meta V3AccessAuditEventListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3AccessAuditEvent" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - items - pagination - meta V3AccessAuditEventExportResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3AccessAuditEvent" export: type: object additionalProperties: false properties: format: type: string enum: - json count: type: integer minimum: 0 sort: type: string required: - format - count - sort required: - items - export V3AccountAttentionItem: type: object additionalProperties: false properties: severity: type: string enum: - info - warn - error code: type: string enum: - missing_mfa - stale_ssh_key - expiring_api_key - duplicate_identity_candidate - unfamiliar_session title: type: string summary: type: string action_label: type: string nullable: true action_href: type: string nullable: true required: - severity - code - title - summary - action_label - action_href V3AccountLinkedIdentity: type: object additionalProperties: false properties: provider: type: string enum: - password - keycloak - github - huggingface - google - microsoft - saml - oidc subject: type: string display_label: type: string email: type: string nullable: true linked_at: type: string format: date-time nullable: true is_primary: type: boolean status: type: string enum: - linked - pending - duplicate_candidate - disabled required: - provider - subject - display_label - email - linked_at - is_primary - status V3AccountProfile: type: object additionalProperties: false properties: user_id: type: string format: uuid username: type: string display_name: type: string email: type: string nullable: true tenant_id: type: string format: uuid nullable: true tenant_name: type: string nullable: true default_project_id: type: string format: uuid nullable: true default_project_name: type: string nullable: true joined_at: type: string format: date-time nullable: true theme_preference: type: string description: User profile preference for the v3 shell appearance. System follows the browser or operating system color scheme. enum: - system - light - dark linked_identities: type: array items: "$ref": "#/components/schemas/V3AccountLinkedIdentity" required: - user_id - username - display_name - email - tenant_id - tenant_name - default_project_id - default_project_name - joined_at - theme_preference - linked_identities V3AccountProfileUpdateRequest: type: object additionalProperties: false properties: theme_preference: type: string description: Persisted v3 shell appearance preference. enum: - system - light - dark required: - theme_preference V3AccountCredentialSummary: type: object additionalProperties: false properties: id: type: string kind: type: string enum: - ssh_key - personal_api_key label: type: string fingerprint: type: string nullable: true status: type: string enum: - active - expiring - expired - revoked created_at: type: string format: date-time nullable: true last_used_at: type: string format: date-time nullable: true expires_at: type: string format: date-time nullable: true attached_workloads: type: array items: type: object additionalProperties: false properties: workload_id: type: string workload_name: type: string required: - workload_id - workload_name required: - id - kind - label - fingerprint - status - created_at - last_used_at - expires_at - attached_workloads V3AccountSession: type: object additionalProperties: false properties: id: type: string device_label: type: string browser: type: string nullable: true os: type: string nullable: true ip_address: type: string nullable: true location_label: type: string nullable: true auth_provider: type: string enum: - oidc - personal_token - service_account - password - unknown signed_in_at: type: string format: date-time nullable: true last_seen_at: type: string format: date-time nullable: true is_current: type: boolean risk: type: string enum: - normal - attention - high status: type: string enum: - active - expired - revoked expires_at: type: string format: date-time nullable: true revoked_at: type: string format: date-time nullable: true required: - id - device_label - browser - os - ip_address - location_label - auth_provider - signed_in_at - last_seen_at - is_current - risk - status - expires_at - revoked_at V3AccountOperation: type: object additionalProperties: false description: Server-owned operation affordance for V3 account security lifecycle actions. Row-scoped operations use templated hrefs and are disabled until the UI supplies the selected target. properties: key: type: string source: type: string enum: - credential - session - mfa - identity label: type: string method: type: string enum: - GET - POST - PUT - PATCH - DELETE href: type: string target_type: type: string target_id: type: string nullable: true enabled: type: boolean disabled_reason: type: string nullable: true danger: type: string enum: - safe - low - medium - high - destructive audit_action: type: string result: type: string latest_actor: type: string nullable: true latest_at: type: string format: date-time nullable: true evidence_href: type: string nullable: true required: - key - source - label - method - href - target_type - target_id - enabled - disabled_reason - danger - audit_action - result - latest_actor - latest_at - evidence_href V3AccountSessionRevokeRequest: type: object additionalProperties: false properties: reason: type: string nullable: true maxLength: 512 V3AccountSessionRevokeResponse: type: object additionalProperties: false properties: revoked_count: type: integer minimum: 0 session_id: type: string nullable: true evidence: "$ref": "#/components/schemas/V3MutationEvidence" required: - revoked_count - session_id - evidence V3AccountOverviewResponse: type: object additionalProperties: false properties: profile: "$ref": "#/components/schemas/V3AccountProfile" counts: type: object additionalProperties: false properties: ssh_keys: type: integer minimum: 0 personal_api_keys: type: integer minimum: 0 active_sessions: type: integer minimum: 0 linked_identities: type: integer minimum: 0 required: - ssh_keys - personal_api_keys - active_sessions - linked_identities attention: type: array items: "$ref": "#/components/schemas/V3AccountAttentionItem" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - profile - counts - attention - meta V3AccountProfileResponse: type: object additionalProperties: false properties: profile: "$ref": "#/components/schemas/V3AccountProfile" duplicate_identity_candidates: type: array items: "$ref": "#/components/schemas/V3AccountLinkedIdentity" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - profile - duplicate_identity_candidates - meta V3AccountSecurityResponse: type: object additionalProperties: false properties: credentials: type: array items: "$ref": "#/components/schemas/V3AccountCredentialSummary" mfa: type: object additionalProperties: false properties: totp_enabled: type: boolean description: Backward-compatible summary flag. True only when token/provider evidence identifies an OTP/TOTP MFA method. False is not proof that the provider has no TOTP factor unless totp_evidence_state is not_observed_in_provider. webauthn_enabled: type: boolean description: Backward-compatible summary flag. True only when token/provider evidence identifies a WebAuthn/FIDO MFA method. False is not proof that the provider has no WebAuthn factor unless webauthn_evidence_state is not_observed_in_provider. factor_evidence_source: type: string enum: - provider - token_claim - manual_policy - provider_unavailable - provider_pending - provider_unqueried - unavailable description: Source of factor-method evidence. Provider-unqueried, pending, and unavailable values must not be treated as proof that the provider has no factor. totp_evidence_state: type: string enum: - observed - not_observed_in_provider - not_observed_in_token - provider_unavailable - provider_pending - provider_unqueried - unavailable description: Evidence state for OTP/TOTP. Provider-unqueried, pending, unavailable, and not_observed_in_token are partial states, not provider proof of no TOTP factor. webauthn_evidence_state: type: string enum: - observed - not_observed_in_provider - not_observed_in_token - provider_unavailable - provider_pending - provider_unqueried - unavailable description: Evidence state for WebAuthn/FIDO/passkey. Provider-unqueried, pending, unavailable, and not_observed_in_token are partial states, not provider proof of no WebAuthn factor. posture_source: type: string enum: - provider - token_claim - manual_policy - provider_unavailable - provider_pending - provider_unqueried - unavailable description: Source of the MFA posture decision. Pending/unavailable values must not be treated as proof of enforcement. effective_requirement: type: string enum: - optional - required - grace - exempt - provider_pending - unavailable - not_configured description: Effective requirement known to GPUaaS without making a live provider mutation or lookup. enforcement_state: type: string enum: - enforced - not_enforced - enforcement_unavailable - provider_pending description: Whether MFA enforcement is proven for the current session or remains unavailable/pending. session_assurance: type: string enum: - mfa_verified - mfa_not_present - unknown - not_applicable description: Current-session assurance derived from validated token claims when present. action_state: type: string enum: - enabled - disabled - external - unavailable description: Whether the account surface may show a local MFA action, an external identity-provider action, or no action. action_label: type: string action_href: type: string disabled_reason: type: string acr: type: string description: Optional OIDC ACR claim value when present in the validated token. factors: type: array description: Sanitized MFA factors observed from the provider. Empty is not proof of no factor unless provider evidence state is observed or not_observed_in_provider. items: "$ref": "#/components/schemas/V3AccountMFAFactor" recovery: "$ref": "#/components/schemas/V3AccountMFARecoveryState" required: - totp_enabled - webauthn_enabled - factor_evidence_source - totp_evidence_state - webauthn_evidence_state - posture_source - effective_requirement - enforcement_state - session_assurance - action_state - action_label - action_href - disabled_reason - factors - recovery attention: type: array items: "$ref": "#/components/schemas/V3AccountAttentionItem" operations: type: array items: "$ref": "#/components/schemas/V3AccountOperation" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - credentials - mfa - attention - operations - meta V3AccountMFAFactor: type: object additionalProperties: false properties: id: type: string description: Provider credential identifier. This is not secret material. type: type: string enum: - totp - webauthn - unknown label: type: string provider: type: string enum: - keycloak - unknown created_at: type: string format: date-time nullable: true remove_state: type: string enum: - self_service_available - recovery_required - unavailable remove_reason: type: string required: - id - type - label - provider - created_at - remove_state - remove_reason V3AccountMFARecoveryState: type: object additionalProperties: false properties: state: type: string enum: - available - submitted - unavailable href: type: string support_required: type: boolean approval_required: type: boolean self_service: type: boolean request_id: type: string nullable: true submitted_at: type: string format: date-time nullable: true required: - state - href - support_required - approval_required - self_service V3AccountMFARecoveryRequest: type: object additionalProperties: false properties: reason: type: string maxLength: 200 description: User-facing reason such as lost phone, upgraded device, or remove last factor. V3AccountMFARecoveryRequestResponse: type: object additionalProperties: false properties: request_id: type: string status: type: string enum: - submitted support_required: type: boolean approval_required: type: boolean message: type: string required: - request_id - status - support_required - approval_required - message V3AccountSessionListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3AccountSession" operations: type: array items: "$ref": "#/components/schemas/V3AccountOperation" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - items - pagination - operations - meta AdminBindUserPlatformRoleRequest: type: object additionalProperties: false properties: role: type: string enum: - platform_superadmin - platform_ops - platform_user required: - role AdminUserPlatformRoleListResponse: type: object additionalProperties: false properties: user_id: type: string format: uuid items: type: array items: type: string enum: - platform_superadmin - platform_ops - platform_user required: - user_id - items AdminUserPlatformRoleMutationResponse: type: object additionalProperties: false properties: ok: type: boolean user_id: type: string format: uuid role: type: string enum: - platform_superadmin - platform_ops - platform_user required: - ok - user_id - role AdminBindUserMembershipRequest: type: object additionalProperties: false properties: user_id: type: string format: uuid project_id: type: string format: uuid tenant_role: type: string enum: - owner - admin - member - billing_viewer project_role: type: string enum: - owner - admin - member - viewer mode: type: string enum: - strict - rehome default: strict description: | strict rejects when user already has an active tenant membership on a different tenant. rehome soft-deletes active tenant/project memberships first, then assigns the requested bindings. reason: type: string maxLength: 256 nullable: true required: - user_id - project_id - tenant_role - project_role MembershipBindingSummary: type: object additionalProperties: false properties: tenant_id: type: string format: uuid project_id: type: string format: uuid user_id: type: string format: uuid tenant_role: type: string enum: - owner - admin - member - billing_viewer project_role: type: string enum: - owner - admin - member - viewer required: - tenant_id - project_id - user_id - tenant_role - project_role AdminBindUserMembershipResponse: type: object additionalProperties: false properties: ok: type: boolean mode: type: string enum: - strict - rehome rehomed: type: boolean binding: "$ref": "#/components/schemas/MembershipBindingSummary" required: - ok - mode - rehomed - binding V3RemoveAccessMembershipRequest: type: object additionalProperties: false properties: project_id: type: string format: uuid description: Project membership to remove, or an anchor project in the tenant when scope is tenant. scope: type: string enum: - project - tenant default: project description: project removes only the selected project membership; tenant removes tenant membership plus all project memberships in the tenant. reason: type: string maxLength: 256 nullable: true required: - project_id V3AccessMembershipRemovalEvidence: type: object additionalProperties: false properties: correlation_id: type: string audit_action: type: string enum: - tenant.user.membership.remove target_user_id: type: string format: uuid tenant_id: type: string format: uuid project_id: type: string format: uuid required: - correlation_id - audit_action - target_user_id - tenant_id - project_id V3RemoveAccessMembershipResponse: type: object additionalProperties: false properties: ok: type: boolean scope: type: string enum: - project - tenant removed: type: boolean description: False when the request was already satisfied by a prior removal. removed_project_memberships: type: integer format: int64 minimum: 0 removed_tenant_membership: type: integer format: int64 minimum: 0 evidence: "$ref": "#/components/schemas/V3AccessMembershipRemovalEvidence" required: - ok - scope - removed - removed_project_memberships - removed_tenant_membership - evidence AdminTenantSummary: type: object additionalProperties: false properties: id: type: string format: uuid type: type: string enum: - personal - enterprise name: type: string slug: type: string created_at: type: string format: date-time required: - id - type - name - slug - created_at AdminTenantListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AdminTenantSummary" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination AdminTenantProjectSummary: type: object additionalProperties: false properties: id: type: string format: uuid org_id: type: string format: uuid department_id: type: string format: uuid department_name: type: string department_slug: type: string name: type: string slug: type: string created_at: type: string format: date-time required: - id - org_id - department_id - department_name - department_slug - name - slug - created_at AdminTenantProjectListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AdminTenantProjectSummary" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination TenantMemberSummary: type: object additionalProperties: false properties: user_id: type: string format: uuid username: type: string tenant_id: type: string format: uuid tenant_role: type: string enum: - owner - admin - member - billing_viewer project_id: type: string format: uuid nullable: true project_name: type: string nullable: true project_role: type: string enum: - owner - admin - member - viewer nullable: true required: - user_id - username - tenant_id - tenant_role TenantMemberListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/TenantMemberSummary" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination TenantBindUserMembershipRequest: type: object additionalProperties: false properties: project_id: type: string format: uuid tenant_role: type: string enum: - owner - admin - member - billing_viewer default: member project_role: type: string enum: - owner - admin - member - viewer default: member required: - project_id TenantCreateUserRequest: type: object additionalProperties: false properties: username: type: string minLength: 1 password: type: string minLength: 8 description: Dev/local credential for tenant-managed account creation. project_id: type: string format: uuid tenant_role: type: string enum: - owner - admin - member - billing_viewer default: member project_role: type: string enum: - owner - admin - member - viewer default: member required: - username - password - project_id SshPublicKey: type: object additionalProperties: false properties: id: type: string format: uuid owner_scope: type: string enum: - user - project description: Ownership scope for the registered SSH public key. user_id: type: string format: uuid nullable: true project_id: type: string format: uuid nullable: true created_by_service_account_id: type: string format: uuid nullable: true name: type: string public_key: type: string fingerprint: type: string is_default: type: boolean description: If true, this key is used by default for new allocations when no per-allocation override is provided. Only valid for user-scoped keys. last_used_at: type: string format: date-time nullable: true created_at: type: string format: date-time revoked_at: type: string format: date-time nullable: true required: - id - owner_scope - name - public_key - fingerprint - is_default - created_at SshPublicKeyRef: type: object additionalProperties: false properties: id: type: string format: uuid name: type: string fingerprint: type: string required: - id - name - fingerprint SshPublicKeyListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/SshPublicKey" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination CreateSshPublicKeyRequest: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 64 public_key: type: string minLength: 32 set_as_default: type: boolean default: false description: If true, promotes this key to default for future allocations. Only supported for user-scoped keys. required: - name - public_key CreateSshPublicKeyResponse: type: object additionalProperties: false properties: key: "$ref": "#/components/schemas/SshPublicKey" required: - key OidcAuthorizeResponse: type: object additionalProperties: false properties: authorization_url: type: string format: uri state: type: string pkce_required: type: boolean default: true org_id: type: string format: uuid nullable: true description: 'Resolved tenant context for federation-aware authorize flows when deterministically known. ' required: - authorization_url - state - pkce_required OidcExchangeRequest: type: object additionalProperties: false properties: code: type: string minLength: 8 code_verifier: type: string minLength: 32 redirect_uri: type: string format: uri state: type: string minLength: 8 description: Opaque callback state returned from authorize flow. required: - code - code_verifier - redirect_uri - state AuthSessionResponse: type: object additionalProperties: false properties: access_token: type: string expires_in_seconds: type: integer minimum: 1 refresh_token: type: string nullable: true account_type: "$ref": "#/components/schemas/AccountType" org_id: type: string format: uuid description: Resolved tenant context included in issued token/session. user: "$ref": "#/components/schemas/UserWithBalance" required: - access_token - expires_in_seconds - account_type - org_id - user OidcExchangeResponse: allOf: - "$ref": "#/components/schemas/AuthSessionResponse" description: Compatibility alias for auth session response (retained for codegen/protocol naming continuity). IdentityProviderType: type: string enum: - oidc - saml - social IdentityLinkState: type: string enum: - active - pending_conflict - revoked IdentityLinkProof: type: string enum: - current_session - admin_approval - invite UserIdentityLink: type: object additionalProperties: false properties: id: type: string format: uuid user_id: type: string format: uuid provider_type: "$ref": "#/components/schemas/IdentityProviderType" provider_name: type: string minLength: 1 issuer: type: string minLength: 1 subject_hint: type: string description: Redacted provider subject hint for user display; never a raw token. external_username: type: string nullable: true email: type: string format: email nullable: true email_verified: type: boolean state: "$ref": "#/components/schemas/IdentityLinkState" is_primary: type: boolean created_at: type: string format: date-time required: - id - user_id - provider_type - provider_name - issuer - subject_hint - email_verified - state - is_primary - created_at UserIdentityLinkListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/UserIdentityLink" required: - items CreateIdentityLinkRequest: type: object additionalProperties: false properties: provider_type: "$ref": "#/components/schemas/IdentityProviderType" provider_name: type: string minLength: 1 issuer: type: string minLength: 1 subject: type: string minLength: 1 description: Provider subject from a verified callback or approved recovery flow. external_username: type: string nullable: true email: type: string format: email nullable: true email_verified: type: boolean default: false proof: "$ref": "#/components/schemas/IdentityLinkProof" required: - provider_type - provider_name - issuer - subject - proof CreateIdentityLinkResponse: type: object additionalProperties: false properties: link: "$ref": "#/components/schemas/UserIdentityLink" required: - link SamlAuthorizeResponse: type: object additionalProperties: false properties: redirect_url: type: string format: uri state: type: string description: Opaque state token that must be forwarded as `RelayState` in SAML flow and echoed back to callback. protocol: type: string enum: - saml org_id: type: string format: uuid nullable: true description: Resolved tenant context when deterministically known. required: - redirect_url - state - protocol SamlCallbackRequest: type: object additionalProperties: false properties: SAMLResponse: type: string minLength: 16 description: Base64-encoded SAML assertion payload (HTTP POST binding field name). RelayState: type: string minLength: 8 description: Opaque state token issued by `/api/v1/auth/saml/authorize` (`state` field) and returned via SAML POST binding. required: - SAMLResponse - RelayState TenantFederationProvider: type: object additionalProperties: false description: | Planned tenant federation provider configuration contract for enterprise SSO (OIDC/SAML). Note: schema is defined now for contract-first readiness; tenant-admin CRUD endpoints are pending. properties: id: type: string format: uuid org_id: type: string format: uuid provider_type: type: string enum: - oidc - saml provider_name: type: string minLength: 1 maxLength: 128 enabled: type: boolean issuer: type: string nullable: true description: OIDC issuer; required for oidc providers. saml_entity_id: type: string nullable: true description: SAML entity id; required for saml providers. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - org_id - provider_type - provider_name - enabled - created_at - updated_at TenantFederationDomainBinding: type: object additionalProperties: false description: | Optional domain binding used for server-side tenant federation resolution. Note: schema is defined now for contract-first readiness; tenant-admin CRUD endpoints are pending. properties: id: type: string format: uuid org_id: type: string format: uuid domain: type: string minLength: 3 idp_id: type: string format: uuid verification_state: type: string enum: - pending - verified - failed created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - org_id - domain - idp_id - verification_state - created_at - updated_at CreateTenantFederationProviderRequest: type: object additionalProperties: false description: Planned write contract for tenant-admin federation provider creation. properties: provider_type: type: string enum: - oidc - saml provider_name: type: string minLength: 1 maxLength: 128 enabled: type: boolean default: true issuer: type: string nullable: true client_id: type: string nullable: true client_secret: type: string nullable: true description: Accepted in plaintext on write; server encrypts before storage into `client_secret_enc`. authorization_endpoint: type: string format: uri nullable: true token_endpoint: type: string format: uri nullable: true jwks_uri: type: string format: uri nullable: true saml_entity_id: type: string nullable: true saml_sso_url: type: string format: uri nullable: true saml_x509_cert_pem: type: string nullable: true description: Accepted in plaintext PEM on write; server encrypts before storage into `saml_x509_cert_enc`. required: - provider_type - provider_name UpdateTenantFederationProviderRequest: type: object additionalProperties: false description: | Planned write contract for tenant-admin federation provider updates. PATCH semantics: only provided fields are updated. properties: provider_name: type: string minLength: 1 maxLength: 128 enabled: type: boolean issuer: type: string nullable: true client_id: type: string nullable: true client_secret: type: string nullable: true description: Accepted in plaintext on write; server encrypts before storage into `client_secret_enc`. authorization_endpoint: type: string format: uri nullable: true token_endpoint: type: string format: uri nullable: true jwks_uri: type: string format: uri nullable: true saml_entity_id: type: string nullable: true saml_sso_url: type: string format: uri nullable: true saml_x509_cert_pem: type: string nullable: true description: Accepted in plaintext PEM on write; server encrypts before storage into `saml_x509_cert_enc`. UsageRecord: type: object additionalProperties: false properties: id: type: string format: uuid usage_source: type: string enum: - allocation - app_runtime usage_unit: type: string allocation_id: type: string format: uuid nullable: true app_instance_id: type: string format: uuid nullable: true requested_by_user_id: type: string format: uuid sku: type: string nullable: true control_plane_component: type: boolean operating_mode: type: string enum: - tenant_dedicated - platform_managed nullable: true control_plane_scope: type: string enum: - project - tenant - platform nullable: true runtime_backend: type: string enum: - k8s - rke2 - slurm - ray - bare_metal nullable: true start_time: type: string format: date-time end_time: type: string format: date-time nullable: true last_billed_at: type: string format: date-time nullable: true cost: "$ref": "#/components/schemas/Money" required: - id - usage_source - usage_unit - requested_by_user_id - control_plane_component - start_time - cost UsageListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/UsageRecord" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination Sku: type: object additionalProperties: false properties: sku: type: string vendor: type: string name: type: string resource_class: "$ref": "#/components/schemas/SkuResourceClass" billing_unit: "$ref": "#/components/schemas/SkuBillingUnit" scheduling_unit: "$ref": "#/components/schemas/SkuSchedulingUnit" resources: "$ref": "#/components/schemas/SkuResources" unit_price: "$ref": "#/components/schemas/Money" required: - sku - vendor - name - resource_class - billing_unit - scheduling_unit - resources - unit_price SkuResourceClass: type: string enum: - gpu_baremetal - gpu_slice - cpu_vm - cpu_baremetal - control_plane SkuBillingUnit: type: string enum: - gpu_hour - node_hour - vcpu_hour SkuSchedulingUnit: type: string enum: - node - slice - vm SkuResources: type: object additionalProperties: false properties: vcpu_count: type: integer minimum: 0 nullable: true memory_mib: type: integer minimum: 0 nullable: true accelerator_vendor: type: string nullable: true accelerator_model: type: string nullable: true accelerator_count: type: integer minimum: 0 nullable: true accelerator_memory_mib: type: integer minimum: 0 nullable: true allowed_accelerator_counts: type: array items: type: integer minimum: 1 required: - allowed_accelerator_counts SkuListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/Sku" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination NodeSummary: type: object additionalProperties: false properties: id: type: string format: uuid resource_name: type: string description: Canonical resource identifier in core42:aicloud format. sku: type: string gpus_total: type: integer status: type: string enum: - registered - bootstrap_issued - enrolling - active - cordoned - offline - quarantined - draining - retired - removing occupancy_status: type: string enum: - available - assigned - reserved - restarting - restart_failed - releasing - cleanup - unavailable in_use: type: boolean slot_summary: "$ref": "#/components/schemas/NodeSlotSummary" nullable: true readiness: "$ref": "#/components/schemas/NodeInventoryReadiness" description: Node inventory readiness derived by the backend from lifecycle status, node-agent heartbeat, MAAS reconciliation state, and schedulable GPU capacity. region_code: type: string onboarding_mode: type: string enum: - manual - maas required: - id - sku - gpus_total - status - occupancy_status - in_use - readiness - region_code - onboarding_mode NodeInventoryReadiness: type: object additionalProperties: false properties: state: type: string enum: - ready - decommissioned - unavailable - active - cordoned - draining - registered - bootstrap_issued - enrolling - reconciliation_failed - agent_unreachable - capacity_exhausted - unknown schedulable: type: boolean severity: type: string enum: - ok - info - warn - error - blocker reason_code: type: string enum: - ready - decommissioned_node - node_agent_unreachable - maas_reconciliation_failed - no_schedulable_gpu_capacity - node_unavailable - node_not_schedulable - runtime_readiness_unknown summary: type: string required: - state - schedulable - severity - reason_code - summary CapacityShape: type: string enum: - baremetal - gpu_slice AllocationPlacementStatus: type: string enum: - unplaced - pending_capacity - reserved - provisioning - active - releasing - released - failed NodeSlotSummary: type: object additionalProperties: false properties: total: type: integer minimum: 0 available: type: integer minimum: 0 schedulable_available: type: integer minimum: 0 description: Available slots that satisfy current scheduler topology and exclusivity filters. Marketplace clients use this value; raw `available` remains an operator inventory count. reserved: type: integer minimum: 0 provisioning: type: integer minimum: 0 active: type: integer minimum: 0 releasing: type: integer minimum: 0 cleanup: type: integer minimum: 0 cleanup_blocked: type: integer minimum: 0 failed: type: integer minimum: 0 disabled: type: integer minimum: 0 by_sku: type: array description: Slot capacity grouped by the schedulable SKU carried by slot metadata. Used to keep slice slots separate from the physical bare-metal node SKU. items: "$ref": "#/components/schemas/NodeSlotSkuSummary" required: - total - available - reserved - provisioning - active - releasing - cleanup - cleanup_blocked - failed - disabled NodeSlotSkuSummary: type: object additionalProperties: false properties: sku: type: string total: type: integer minimum: 0 available: type: integer minimum: 0 schedulable_available: type: integer minimum: 0 description: Available slots for this SKU that satisfy current scheduler topology and exclusivity filters. Marketplace clients use this value; raw `available` remains an operator inventory count. reserved: type: integer minimum: 0 provisioning: type: integer minimum: 0 active: type: integer minimum: 0 releasing: type: integer minimum: 0 cleanup: type: integer minimum: 0 cleanup_blocked: type: integer minimum: 0 failed: type: integer minimum: 0 disabled: type: integer minimum: 0 required: - sku - total - available - reserved - provisioning - active - releasing - cleanup - cleanup_blocked - failed - disabled NodeResourceSlotStatus: type: string enum: - available - reserved - provisioning - active - releasing - cleanup - cleanup_blocked - failed - disabled AdminUpsertNodeResourceSlotStatus: type: string description: Operator-settable slot states. Runtime lifecycle states are system-owned and returned only through NodeResourceSlotStatus. enum: - available - reserved - active - cleanup - cleanup_blocked - disabled NodeResourceSlot: type: object additionalProperties: false properties: id: type: string format: uuid node_id: type: string format: uuid parent_slot_id: type: string format: uuid nullable: true slot_index: type: integer minimum: 0 status: "$ref": "#/components/schemas/NodeResourceSlotStatus" capacity_shape: "$ref": "#/components/schemas/CapacityShape" sharing_model: type: string nullable: true enum: - exclusive_device description: Current implemented slots are whole-GPU exclusive devices. Fractional, MIG, vGPU, MPS, and time-sliced products remain design-only and are not accepted by the v1 admin slot API. profile_name: type: string nullable: true description: Reserved vendor/runtime profile name for future partition, vGPU, or share profiles. accelerator_vendor: type: string nullable: true accelerator_model: type: string nullable: true gpu_index: type: integer nullable: true gpu_uuid: type: string nullable: true pci_address: type: string nullable: true numa_node: type: integer nullable: true nvme_device: type: string nullable: true nvme_wwn: type: string nullable: true fabric_kind: type: string nullable: true enum: - ib - roce - ethernet fabric_device: type: string nullable: true vcpu_count: type: integer nullable: true minimum: 1 memory_mib: type: integer nullable: true minimum: 1 gpu_memory_mib: type: integer nullable: true minimum: 1 description: Reserved accelerator memory quantity for future fractional/shared GPU inventory. compute_milli: type: integer nullable: true minimum: 1 description: Reserved compute-share quantity where 1000 represents one nominal whole accelerator unit for future products. max_claims: type: integer nullable: true minimum: 1 description: Reserved maximum colocated claims for future shared GPU inventory. Current slots remain single-claim. mac_address: type: string nullable: true private_ip: type: string nullable: true health_state: type: string nullable: true health_detail: type: object additionalProperties: true capacity_metadata: type: object description: Slot approval metadata. For schedulable whole-GPU slice slots, `storage_ownership` must be `slice` and `destructive_wipe_policy` must name the approved cleanup method, for example `blkdiscard`, `nvme_format`, or a site-specific secure erase profile. Schedulable slice slots also require `fabric_claim_mode=per_slot_vf` plus a non-empty `fabric_vf_pci_address` that identifies the isolated fabric attachment assigned to that slot. `fabric_device` may still carry the parent BF/IB device for operator context, but it is not sufficient for concurrent slice placement. additionalProperties: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - node_id - slot_index - status - capacity_shape - created_at - updated_at NodeResourceSlotListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/NodeResourceSlot" required: - items AdminUpsertNodeResourceSlot: type: object additionalProperties: false properties: parent_slot_id: type: string format: uuid nullable: true slot_index: type: integer minimum: 0 status: "$ref": "#/components/schemas/AdminUpsertNodeResourceSlotStatus" capacity_shape: "$ref": "#/components/schemas/CapacityShape" sharing_model: type: string nullable: true enum: - exclusive_device description: Current implemented slots are whole-GPU exclusive devices. Fractional, MIG, vGPU, MPS, and time-sliced products remain design-only and are not accepted by the v1 admin slot API. profile_name: type: string nullable: true description: Reserved vendor/runtime profile name for future partition, vGPU, or share profiles. accelerator_vendor: type: string nullable: true accelerator_model: type: string nullable: true gpu_index: type: integer nullable: true gpu_uuid: type: string nullable: true pci_address: type: string nullable: true numa_node: type: integer nullable: true nvme_device: type: string nullable: true nvme_wwn: type: string nullable: true fabric_kind: type: string nullable: true enum: - ib - roce - ethernet fabric_device: type: string nullable: true vcpu_count: type: integer nullable: true minimum: 1 memory_mib: type: integer nullable: true minimum: 1 gpu_memory_mib: type: integer nullable: true minimum: 1 description: Reserved accelerator memory quantity for future fractional/shared GPU inventory. compute_milli: type: integer nullable: true minimum: 1 description: Reserved compute-share quantity where 1000 represents one nominal whole accelerator unit for future products. max_claims: type: integer nullable: true minimum: 1 description: Reserved maximum colocated claims for future shared GPU inventory. Current slots remain single-claim. mac_address: type: string nullable: true private_ip: type: string nullable: true health_state: type: string nullable: true health_detail: type: object additionalProperties: true capacity_metadata: type: object description: Slot approval metadata. Setting an exclusive whole-GPU slot to `available` requires `storage_ownership` to be `slice` and a non-empty `destructive_wipe_policy`; mounted baremetal/share devices must remain disabled or cleanup_blocked until infra completes the mode transition. Whole-GPU slice slots also require `fabric_claim_mode=per_slot_vf` and a non-empty `fabric_vf_pci_address` before they can be saved as `available`. Missing values, `exclusive_device`, and `shared_host` are not schedulable for the VM-slice product. additionalProperties: true required: - slot_index - status - capacity_shape AdminUpsertNodeResourceSlotsRequest: type: object additionalProperties: false properties: slots: type: array minItems: 1 maxItems: 64 items: "$ref": "#/components/schemas/AdminUpsertNodeResourceSlot" required: - slots NodeSliceTopologyDiscovery: type: object additionalProperties: false properties: task_id: type: string format: uuid node_id: type: string format: uuid task_type: type: string enum: - slice.topology_discover status: type: string enum: - queued - dispatched - completed - failed - rejected - expired correlation_id: type: string issued_at: type: string format: date-time expires_at: type: string format: date-time dispatched_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true error: type: string nullable: true output: type: object nullable: true additionalProperties: true description: Raw advisory candidate map from `slice.topology_discover`; must be admin-approved into `gpuaas_node_resource_slots` before scheduling. required: - task_id - node_id - task_type - status - correlation_id - issued_at - expires_at NodeSliceTopologyDiscoveryResponse: type: object additionalProperties: false properties: item: nullable: true allOf: - "$ref": "#/components/schemas/NodeSliceTopologyDiscovery" required: - item OSImageTarget: type: string enum: - baremetal - vm_slice - compute_vm x-enum-varnames: - OSImageTargetBaremetal - OSImageTargetVmSlice - OSImageTargetComputeVm OSImageFormat: type: string enum: - raw - qcow2 - iso - maas OSImageStatus: type: string enum: - active - disabled - deprecated OSImageDriverStrategy: type: string enum: - preinstalled - cloud-init - none OSImage: type: object additionalProperties: false properties: id: type: string format: uuid slug: type: string minLength: 2 display_name: type: string minLength: 1 target: "$ref": "#/components/schemas/OSImageTarget" image_format: "$ref": "#/components/schemas/OSImageFormat" source_uri: type: string minLength: 1 digest_sha256: type: string pattern: "^[a-f0-9]{64}$" default_username: type: string minLength: 1 accelerator_vendor: type: string nullable: true driver_strategy: "$ref": "#/components/schemas/OSImageDriverStrategy" compatible_skus: type: array items: type: string minLength: 1 status: "$ref": "#/components/schemas/OSImageStatus" metadata: type: object additionalProperties: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - slug - display_name - target - image_format - source_uri - digest_sha256 - default_username - driver_strategy - compatible_skus - status - created_at - updated_at OSImageListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/OSImage" next_cursor: type: string nullable: true required: - items AdminCreateOSImageRequest: type: object additionalProperties: false properties: slug: type: string minLength: 2 display_name: type: string minLength: 1 target: "$ref": "#/components/schemas/OSImageTarget" image_format: "$ref": "#/components/schemas/OSImageFormat" source_uri: type: string minLength: 1 digest_sha256: type: string pattern: "^[a-f0-9]{64}$" default_username: type: string minLength: 1 accelerator_vendor: type: string nullable: true driver_strategy: "$ref": "#/components/schemas/OSImageDriverStrategy" compatible_skus: type: array items: type: string minLength: 1 status: "$ref": "#/components/schemas/OSImageStatus" metadata: type: object additionalProperties: true required: - slug - display_name - target - image_format - source_uri - digest_sha256 - default_username AdminUpdateOSImageRequest: type: object additionalProperties: false properties: slug: type: string minLength: 2 display_name: type: string minLength: 1 target: "$ref": "#/components/schemas/OSImageTarget" image_format: "$ref": "#/components/schemas/OSImageFormat" source_uri: type: string minLength: 1 digest_sha256: type: string pattern: "^[a-f0-9]{64}$" default_username: type: string minLength: 1 accelerator_vendor: type: string nullable: true driver_strategy: "$ref": "#/components/schemas/OSImageDriverStrategy" compatible_skus: type: array items: type: string minLength: 1 status: "$ref": "#/components/schemas/OSImageStatus" metadata: type: object additionalProperties: true NodeAdmin: type: object additionalProperties: false properties: id: type: string format: uuid resource_name: type: string description: Canonical resource identifier in core42:aicloud format. sku: type: string gpus_total: type: integer status: type: string enum: - registered - bootstrap_issued - enrolling - active - cordoned - offline - quarantined - draining - retired - removing occupancy_status: type: string enum: - available - assigned - reserved - restarting - restart_failed - releasing - cleanup - unavailable in_use: type: boolean slot_summary: "$ref": "#/components/schemas/NodeSlotSummary" nullable: true region_code: type: string onboarding_mode: type: string enum: - manual - maas host: type: string hostname: type: string nullable: true port: type: integer ssh_username: type: string agent_version: type: string nullable: true description: Latest node-agent build version reported by the enrolled node. agent_commit: type: string nullable: true description: Latest node-agent git commit reported by the enrolled node. agent_built_at: type: string nullable: true description: Latest node-agent build timestamp reported by the enrolled node. agent_reported_at: type: string format: date-time nullable: true description: Time the control plane last observed node-agent build metadata. agent_lifecycle: "$ref": "#/components/schemas/NodeAgentLifecycleState" nullable: true current_allocation: "$ref": "#/components/schemas/NodeOccupancy" nullable: true required: - id - sku - gpus_total - status - occupancy_status - in_use - region_code - onboarding_mode - host - port - ssh_username AdminNodeLifecycleRecoveryAction: type: string enum: - task_already_queued - task_in_progress - task_requeued - task_recreated AdminResumeNodeLifecycleResponse: type: object additionalProperties: false properties: ok: type: boolean node_id: type: string format: uuid status: type: string enum: - draining - removing task_type: type: string enum: - node.drain - node.uninstall recovery_action: "$ref": "#/components/schemas/AdminNodeLifecycleRecoveryAction" required: - ok - node_id - status - task_type - recovery_action NodeOccupancy: type: object additionalProperties: false properties: allocation_id: type: string format: uuid user_id: type: string format: uuid username_on_node: type: string description: Stable per-user node username sourced from user POSIX identity mapping. status: type: string enum: - active - releasing - release_failed required: - allocation_id - user_id - username_on_node - status NodeSummaryListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/NodeSummary" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination NodeAdminListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/NodeAdmin" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination NodeAgentDeliveryMode: type: string enum: - reimage - manual_install - rebootstrap NodeAgentLifecycleScenario: type: string enum: - bootstrap_install - in_place_upgrade - repair_reinstall - certificate_repair - drift_reconcile NodeAgentLifecycleStatus: type: string enum: - pending - running - completed - failed_retryable - failed_manual_intervention - cancelled NodeAgentUpgradeSafetyPolicy: type: string enum: - idle_only - drain_then_upgrade - force NodeAgentDriftState: type: string enum: - in_sync - version_drift - config_drift - certificate_only_repair_needed - unknown NodeAgentLifecycleState: type: object additionalProperties: false properties: desired_agent_version: type: string nullable: true reported_agent_version: type: string nullable: true desired_delivery_mode: "$ref": "#/components/schemas/NodeAgentDeliveryMode" nullable: true drift_state: "$ref": "#/components/schemas/NodeAgentDriftState" last_delivery_attempt_at: type: string format: date-time nullable: true last_delivery_result: type: string nullable: true last_delivery_correlation_id: type: string nullable: true required: - drift_state AdminStartNodeAgentLifecycleRequest: type: object additionalProperties: false properties: mode: "$ref": "#/components/schemas/NodeAgentDeliveryMode" scenario: "$ref": "#/components/schemas/NodeAgentLifecycleScenario" target_version: type: string nullable: true description: Required for `bootstrap_install` and `in_place_upgrade`; optional for repair-only scenarios. safety_policy: "$ref": "#/components/schemas/NodeAgentUpgradeSafetyPolicy" reason: type: string nullable: true required: - mode - scenario - safety_policy AdminRecoverStaleNodeAgentLifecycleRequest: type: object additionalProperties: false properties: reason: type: string minLength: 1 description: Operator reason for reconciling a stale pending or running node-agent lifecycle run. min_stale_seconds: type: integer minimum: 30 maximum: 86400 nullable: true description: Minimum age since lifecycle updated_at before recovery may mutate the run. Defaults to 120 seconds. required: - reason NodeAgentLifecycleRun: type: object additionalProperties: false properties: lifecycle_id: type: string format: uuid node_id: type: string format: uuid mode: "$ref": "#/components/schemas/NodeAgentDeliveryMode" scenario: "$ref": "#/components/schemas/NodeAgentLifecycleScenario" status: "$ref": "#/components/schemas/NodeAgentLifecycleStatus" desired_agent_version: type: string nullable: true reported_agent_version: type: string nullable: true safety_policy: "$ref": "#/components/schemas/NodeAgentUpgradeSafetyPolicy" error_code: type: string nullable: true error_message: type: string nullable: true error_details: type: object additionalProperties: true correlation_id: type: string requested_at: type: string format: date-time started_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true updated_at: type: string format: date-time required: - lifecycle_id - node_id - mode - scenario - status - safety_policy - error_details - correlation_id - requested_at - updated_at AdminStartNodeAgentLifecycleResponse: type: object additionalProperties: false properties: lifecycle: "$ref": "#/components/schemas/NodeAgentLifecycleRun" required: - lifecycle MaasSiteStatus: type: string enum: - active - disabled MaasSiteProfileStatus: type: string enum: - active - disabled MaasSitePolicy: type: object additionalProperties: false properties: fabric_mode: type: string enum: - ethernet - roce - ib strict_pxe_preflight: type: boolean enable_phase2_roce: type: boolean require_hw_sync: type: boolean hardware_sync_interval: type: string minLength: 1 maxLength: 32 release_fallback_no_erase: type: boolean enable_deploy_retry_on_datasource_failure: type: boolean max_deploy_retry_attempts: type: integer minimum: 0 maximum: 10 auto_claim_single_new_machine: type: boolean batch_max_parallel: type: integer minimum: 1 maximum: 100 site_bootstrap_bundle_ref: type: string nullable: true maxLength: 512 description: Canonical infra-owned first-boot site bootstrap bundle reference. commissioning_bundle_ref: type: string nullable: true maxLength: 512 description: Optional infra-owned commissioning or MAAS script bundle reference reserved for future site automation. post_deploy_validation_bundle_ref: type: string nullable: true maxLength: 512 description: Optional post-deploy validation bundle reference reserved for future hardware or fabric checks. fabric_controller_bundle_ref: type: string nullable: true maxLength: 512 description: Optional future fabric-controller integration bundle reference, for example UFM or PKEY orchestration hooks. extra_cloud_init_bundle_path: type: string nullable: true maxLength: 512 deprecated: true description: Deprecated legacy alias for `site_bootstrap_bundle_ref`. Accepted only for backward compatibility. enrollment_token_ttl_seconds: type: integer minimum: 60 maximum: 86400 required: - fabric_mode - strict_pxe_preflight - enable_phase2_roce - require_hw_sync - hardware_sync_interval - release_fallback_no_erase - enable_deploy_retry_on_datasource_failure - max_deploy_retry_attempts - auto_claim_single_new_machine - batch_max_parallel - enrollment_token_ttl_seconds MaasSiteCredentialStatus: type: object additionalProperties: false properties: api_token_configured: type: boolean default_power_credentials_configured: type: boolean deploy_password_configured: type: boolean api_token_vault_path: type: string default_power_creds_vault_path: type: string deploy_password_vault_path: type: string configured_at: type: string format: date-time nullable: true required: - api_token_configured - default_power_credentials_configured - deploy_password_configured - api_token_vault_path - default_power_creds_vault_path - deploy_password_vault_path MaasSiteProbeResult: type: object additionalProperties: false properties: ok: type: boolean version: type: string nullable: true subversion: type: string nullable: true capabilities: type: array items: type: string probed_at: type: string format: date-time error: type: string nullable: true required: - ok - capabilities - probed_at MaasSite: type: object additionalProperties: false properties: id: type: string format: uuid name: type: string region_code: type: string api_base_url: type: string format: uri pxe_iface: type: string pxe_vlan_vid: type: integer minimum: 1 maximum: 4094 node_pxe_iface: type: string distro_series: type: string architecture: type: string deploy_user: type: string minLength: 1 maxLength: 64 deploy_ssh_iface: type: string minLength: 1 maxLength: 64 upstream_dns_servers: type: array items: type: string minLength: 1 maxLength: 255 status: "$ref": "#/components/schemas/MaasSiteStatus" default_profile_id: type: string format: uuid nullable: true profile_count: type: integer minimum: 0 credentials: "$ref": "#/components/schemas/MaasSiteCredentialStatus" policy: "$ref": "#/components/schemas/MaasSitePolicy" last_probe: allOf: - "$ref": "#/components/schemas/MaasSiteProbeResult" nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time disabled_at: type: string format: date-time nullable: true required: - id - name - region_code - api_base_url - pxe_iface - pxe_vlan_vid - node_pxe_iface - distro_series - architecture - deploy_user - deploy_ssh_iface - upstream_dns_servers - status - profile_count - credentials - policy - created_at - updated_at MaasSiteProfile: type: object additionalProperties: false properties: id: type: string format: uuid site_id: type: string format: uuid name: type: string status: "$ref": "#/components/schemas/MaasSiteProfileStatus" is_default: type: boolean pxe_iface: type: string minLength: 1 maxLength: 64 nullable: true pxe_vlan_vid: type: integer minimum: 1 maximum: 4094 nullable: true node_pxe_iface: type: string minLength: 1 maxLength: 64 nullable: true distro_series: type: string minLength: 1 maxLength: 64 architecture: type: string minLength: 1 maxLength: 64 policy: allOf: - "$ref": "#/components/schemas/MaasSitePolicy" description: Profile-scoped MAAS lifecycle policy bundle. created_at: type: string format: date-time updated_at: type: string format: date-time disabled_at: type: string format: date-time nullable: true required: - id - site_id - name - status - is_default - distro_series - architecture - policy - created_at - updated_at MaasSiteProfileListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/MaasSiteProfile" required: - items MaasSiteListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/MaasSite" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination MaasDiscoveryCandidateState: type: string enum: - candidate - known_node - existing_onboarding MaasDiscoveryCandidateReviewState: type: string enum: - active - ignored - suppressed MaasDiscoveryCandidateSKUHint: type: object additionalProperties: false properties: sku: type: string nullable: true confidence: type: string reason: type: string required: - confidence - reason MaasDiscoveryCandidateGPUDevice: type: object additionalProperties: false properties: vendor_name: type: string product_name: type: string pci_address: type: string nullable: true required: - vendor_name - product_name MaasGPUaaSProfileIntent: type: string enum: - slice_vm - baremetal - unprofiled - conflict MaasDiscoveryCandidateEnrichment: type: object additionalProperties: false properties: maas_system_id: type: string hostname: type: string tag_names: type: array items: type: string gpuaas_profile_intent: "$ref": "#/components/schemas/MaasGPUaaSProfileIntent" power_address: type: string nullable: true power_driver: type: string nullable: true power_user: type: string nullable: true sku_hint: "$ref": "#/components/schemas/MaasDiscoveryCandidateSKUHint" gpu_devices: type: array items: "$ref": "#/components/schemas/MaasDiscoveryCandidateGPUDevice" required: - maas_system_id - hostname - tag_names - gpuaas_profile_intent - sku_hint - gpu_devices MaasDiscoveryCandidate: type: object additionalProperties: false properties: maas_system_id: type: string hostname: type: string architecture: type: string maas_status: type: string power_state: type: string nullable: true power_address: type: string nullable: true tag_names: type: array items: type: string gpuaas_profile_intent: "$ref": "#/components/schemas/MaasGPUaaSProfileIntent" interface_count: type: integer minimum: 0 blockdevice_count: type: integer minimum: 0 state: "$ref": "#/components/schemas/MaasDiscoveryCandidateState" node_id: type: string format: uuid nullable: true node_status: type: string nullable: true onboarding_id: type: string format: uuid nullable: true onboarding_status: "$ref": "#/components/schemas/MaasWorkflowStatus" nullable: true review_state: "$ref": "#/components/schemas/MaasDiscoveryCandidateReviewState" review_reason: type: string nullable: true reviewed_at: type: string format: date-time nullable: true matched_profile_ids: type: array items: type: string format: uuid matched_profile_names: type: array items: type: string sku_hint: "$ref": "#/components/schemas/MaasDiscoveryCandidateSKUHint" already_managed_by_gpuaas: type: boolean required: - maas_system_id - hostname - architecture - maas_status - tag_names - gpuaas_profile_intent - interface_count - blockdevice_count - state - review_state - review_reason - reviewed_at - matched_profile_ids - matched_profile_names - sku_hint - already_managed_by_gpuaas MaasDiscoveryCandidateListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/MaasDiscoveryCandidate" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination AdminUpdateMaasDiscoveryCandidateDecisionRequest: type: object additionalProperties: false properties: review_state: "$ref": "#/components/schemas/MaasDiscoveryCandidateReviewState" reason: type: string nullable: true maxLength: 500 required: - review_state MaasDiscoveryCandidateDecision: type: object additionalProperties: false properties: site_id: type: string format: uuid maas_system_id: type: string review_state: "$ref": "#/components/schemas/MaasDiscoveryCandidateReviewState" review_reason: type: string nullable: true reviewed_at: type: string format: date-time required: - site_id - maas_system_id - review_state - reviewed_at AdminCreateMaasSiteRequest: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 120 region_code: type: string minLength: 1 maxLength: 64 api_base_url: type: string format: uri pxe_iface: type: string minLength: 1 maxLength: 64 pxe_vlan_vid: type: integer minimum: 1 maximum: 4094 node_pxe_iface: type: string minLength: 1 maxLength: 64 distro_series: type: string minLength: 1 maxLength: 64 default: ubuntu/noble architecture: type: string minLength: 1 maxLength: 64 default: amd64/generic deploy_user: type: string minLength: 1 maxLength: 64 default: hpcadmin deploy_ssh_iface: type: string minLength: 1 maxLength: 64 default: eno8303 upstream_dns_servers: type: array items: type: string minLength: 1 maxLength: 255 policy: "$ref": "#/components/schemas/MaasSitePolicy" required: - name - region_code - api_base_url - pxe_iface - pxe_vlan_vid - node_pxe_iface AdminUpdateMaasSiteRequest: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 120 region_code: type: string minLength: 1 maxLength: 64 api_base_url: type: string format: uri pxe_iface: type: string minLength: 1 maxLength: 64 pxe_vlan_vid: type: integer minimum: 1 maximum: 4094 node_pxe_iface: type: string minLength: 1 maxLength: 64 distro_series: type: string minLength: 1 maxLength: 64 architecture: type: string minLength: 1 maxLength: 64 deploy_user: type: string minLength: 1 maxLength: 64 deploy_ssh_iface: type: string minLength: 1 maxLength: 64 upstream_dns_servers: type: array items: type: string minLength: 1 maxLength: 255 status: "$ref": "#/components/schemas/MaasSiteStatus" policy: "$ref": "#/components/schemas/MaasSitePolicy" AdminWriteMaasSiteCredentialsRequest: type: object additionalProperties: false properties: api_token: type: string minLength: 1 default_power_username: type: string minLength: 1 maxLength: 128 default_power_password: type: string minLength: 1 maxLength: 4096 deploy_password: type: string minLength: 1 maxLength: 4096 required: - api_token - default_power_username - default_power_password - deploy_password AdminWriteMaasSiteCredentialsResponse: type: object additionalProperties: false properties: site: "$ref": "#/components/schemas/MaasSite" probe: "$ref": "#/components/schemas/MaasSiteProbeResult" required: - site - probe AdminBulkUpsertMaasRoceAssignmentsRequest: type: object additionalProperties: false properties: items: type: array minItems: 1 items: "$ref": "#/components/schemas/AdminUpsertMaasRoceAssignmentItem" required: - items AdminUpsertMaasRoceAssignmentItem: type: object additionalProperties: false properties: hostname: type: string minLength: 1 maxLength: 255 interface: type: string minLength: 1 maxLength: 64 ipv4_cidr: type: string minLength: 1 maxLength: 64 required: - hostname - interface - ipv4_cidr AdminSetMaasRoceAssignmentStatusRequest: type: object additionalProperties: false properties: reason: type: string minLength: 1 maxLength: 500 nullable: true AdminCreateMaasSiteProfileRequest: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 120 pxe_iface: type: string minLength: 1 maxLength: 64 nullable: true pxe_vlan_vid: type: integer minimum: 1 maximum: 4094 nullable: true node_pxe_iface: type: string minLength: 1 maxLength: 64 nullable: true distro_series: type: string minLength: 1 maxLength: 64 architecture: type: string minLength: 1 maxLength: 64 policy: "$ref": "#/components/schemas/MaasSitePolicy" required: - name AdminUpdateMaasSiteProfileRequest: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 120 status: "$ref": "#/components/schemas/MaasSiteProfileStatus" pxe_iface: type: string minLength: 1 maxLength: 64 nullable: true pxe_vlan_vid: type: integer minimum: 1 maximum: 4094 nullable: true node_pxe_iface: type: string minLength: 1 maxLength: 64 nullable: true distro_series: type: string minLength: 1 maxLength: 64 architecture: type: string minLength: 1 maxLength: 64 policy: "$ref": "#/components/schemas/MaasSitePolicy" MaasOnboardingNodeInput: type: object additionalProperties: false description: Batch onboarding accepts selected discovery rows directly. Provide hostname and ipmi_ip, or provide maas_system_id and let the backend resolve missing hostname/ipmi_ip from MAAS. properties: hostname: type: string minLength: 1 maxLength: 255 ipmi_ip: type: string minLength: 1 maxLength: 64 maas_system_id: type: string minLength: 1 maxLength: 128 AdminStartMaasOnboardingRequest: type: object additionalProperties: false properties: site_id: type: string format: uuid profile_id: type: string format: uuid sku_id: type: string minLength: 1 maxLength: 128 hostname: type: string minLength: 1 maxLength: 255 ipmi_ip: type: string minLength: 1 maxLength: 64 required: - site_id - profile_id - sku_id - hostname - ipmi_ip AdminStartMaasOnboardingResponse: type: object additionalProperties: false properties: onboarding_id: type: string format: uuid status: "$ref": "#/components/schemas/MaasWorkflowStatus" required: - onboarding_id - status AdminStartMaasBatchOnboardingRequest: type: object additionalProperties: false properties: site_id: type: string format: uuid profile_id: type: string format: uuid sku_id: type: string minLength: 1 maxLength: 128 nodes: type: array minItems: 1 items: "$ref": "#/components/schemas/MaasOnboardingNodeInput" required: - site_id - profile_id - sku_id - nodes AdminStartMaasBatchOnboardingItem: type: object additionalProperties: false properties: hostname: type: string minLength: 1 maxLength: 255 ipmi_ip: type: string minLength: 1 maxLength: 64 maas_system_id: type: string nullable: true minLength: 1 maxLength: 128 onboarding_id: type: string format: uuid status: "$ref": "#/components/schemas/MaasWorkflowStatus" required: - hostname - ipmi_ip - maas_system_id - onboarding_id - status AdminStartMaasBatchOnboardingResponse: type: object additionalProperties: false properties: batch_id: type: string format: uuid onboardings: type: array items: "$ref": "#/components/schemas/AdminStartMaasBatchOnboardingItem" required: - batch_id - onboardings MaasWorkflowStatus: type: string enum: - pending - running - completed - failed_retryable - failed_manual_intervention - cancelled - compensating - reconciled MaasWorkflowEventStatus: type: string enum: - started - succeeded - failed - compensated - skipped MaasOnboardingEvent: type: object additionalProperties: false properties: id: type: string format: uuid stage: type: string attempt: type: integer minimum: 0 status: "$ref": "#/components/schemas/MaasWorkflowEventStatus" message: type: string nullable: true details: type: object additionalProperties: true occurred_at: type: string format: date-time required: - id - stage - attempt - status - details - occurred_at MaasOnboarding: type: object additionalProperties: false properties: onboarding_id: type: string format: uuid batch_id: type: string format: uuid nullable: true node_id: type: string format: uuid nullable: true site_id: type: string format: uuid profile_id: type: string format: uuid nullable: true sku_id: type: string minLength: 1 maxLength: 128 hostname: type: string ipmi_ip: type: string pxe_mac: type: string nullable: true maas_system_id: type: string nullable: true management_interface: type: string nullable: true management_ip: type: string nullable: true management_subnet_cidr: type: string nullable: true requested_by_user_id: type: string format: uuid nullable: true current_stage: type: string current_attempt: type: integer minimum: 0 status: "$ref": "#/components/schemas/MaasWorkflowStatus" error_code: type: string nullable: true error_message: type: string nullable: true error_details: type: object additionalProperties: true workflow_id: type: string workflow_run_id: type: string nullable: true requested_at: type: string format: date-time started_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true updated_at: type: string format: date-time attention_key: type: string description: Backend-owned operator attention key used by provisioning review mutations. review_required: type: boolean description: True when this workflow represents an open operator attention item. review_state: "$ref": "#/components/schemas/V3ProvisioningReviewState" reviewed_at: type: string format: date-time nullable: true reviewed_by: type: string nullable: true review_note: type: string nullable: true attention_reason: type: string nullable: true next_action: type: string nullable: true superseded_by_workflow_id: type: string nullable: true required: - onboarding_id - site_id - sku_id - hostname - ipmi_ip - current_stage - current_attempt - status - error_details - workflow_id - requested_at - updated_at - attention_key - review_required - review_state - reviewed_at - reviewed_by - review_note - attention_reason - next_action - superseded_by_workflow_id MaasOnboardingDetail: allOf: - "$ref": "#/components/schemas/MaasOnboarding" - type: object additionalProperties: false properties: attention_key: type: string description: Backend-owned operator attention key used by provisioning review mutations. review_required: type: boolean description: True when this workflow detail represents an open operator attention item. review_state: "$ref": "#/components/schemas/V3ProvisioningReviewState" reviewed_at: type: string format: date-time nullable: true reviewed_by: type: string nullable: true review_note: type: string nullable: true attention_reason: type: string nullable: true next_action: type: string nullable: true superseded_by_workflow_id: type: string nullable: true events: type: array items: "$ref": "#/components/schemas/MaasOnboardingEvent" required: - attention_key - review_required - review_state - reviewed_at - reviewed_by - review_note - attention_reason - next_action - superseded_by_workflow_id - events MaasOnboardingInstallOutput: type: object additionalProperties: false properties: onboarding_id: type: string format: uuid maas_system_id: type: string source: type: string enum: - current_installation content_type: type: string output: type: string fetched_at: type: string format: date-time required: - onboarding_id - maas_system_id - source - content_type - output - fetched_at MaasDecommissionInstallOutput: type: object additionalProperties: false properties: decommission_id: type: string format: uuid maas_system_id: type: string source: type: string enum: - current_installation content_type: type: string output: type: string fetched_at: type: string format: date-time required: - decommission_id - maas_system_id - source - content_type - output - fetched_at MaasEvent: type: object additionalProperties: false properties: id: type: integer level: type: string type: type: string description: type: string created_at: type: string format: date-time required: - id - level - type - description - created_at MaasOnboardingEvents: type: object additionalProperties: false properties: onboarding_id: type: string format: uuid maas_system_id: type: string level: type: string nullable: true limit: type: integer events: type: array items: "$ref": "#/components/schemas/MaasEvent" fetched_at: type: string format: date-time required: - onboarding_id - maas_system_id - limit - events - fetched_at MaasOnboardingListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/MaasOnboarding" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination MaasDecommissionEvent: type: object additionalProperties: false properties: id: type: string format: uuid stage: type: string attempt: type: integer minimum: 0 status: "$ref": "#/components/schemas/MaasWorkflowEventStatus" message: type: string nullable: true details: type: object additionalProperties: true occurred_at: type: string format: date-time required: - id - stage - attempt - status - details - occurred_at MaasDecommission: type: object additionalProperties: false properties: decommission_id: type: string format: uuid node_id: type: string format: uuid site_id: type: string format: uuid nullable: true maas_system_id: type: string nullable: true management_interface: type: string nullable: true management_ip: type: string nullable: true management_subnet_cidr: type: string nullable: true mode: type: string enum: - soft_reset - reimage - full_decommission - storage_cleanup status: "$ref": "#/components/schemas/MaasWorkflowStatus" current_stage: type: string current_attempt: type: integer minimum: 0 requested_by_user_id: type: string format: uuid nullable: true error_code: type: string nullable: true error_message: type: string nullable: true error_details: type: object additionalProperties: true workflow_id: type: string workflow_run_id: type: string nullable: true requested_at: type: string format: date-time started_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true updated_at: type: string format: date-time attention_key: type: string description: Backend-owned operator attention key used by provisioning review mutations. review_required: type: boolean description: True when this workflow represents an open operator attention item. review_state: "$ref": "#/components/schemas/V3ProvisioningReviewState" reviewed_at: type: string format: date-time nullable: true reviewed_by: type: string nullable: true review_note: type: string nullable: true attention_reason: type: string nullable: true next_action: type: string nullable: true superseded_by_workflow_id: type: string nullable: true required: - decommission_id - node_id - mode - status - current_stage - current_attempt - error_details - workflow_id - requested_at - updated_at - attention_key - review_required - review_state - reviewed_at - reviewed_by - review_note - attention_reason - next_action - superseded_by_workflow_id MaasDecommissionDetail: allOf: - "$ref": "#/components/schemas/MaasDecommission" - type: object additionalProperties: false properties: attention_key: type: string description: Backend-owned operator attention key used by provisioning review mutations. review_required: type: boolean description: True when this workflow detail represents an open operator attention item. review_state: "$ref": "#/components/schemas/V3ProvisioningReviewState" reviewed_at: type: string format: date-time nullable: true reviewed_by: type: string nullable: true review_note: type: string nullable: true attention_reason: type: string nullable: true next_action: type: string nullable: true superseded_by_workflow_id: type: string nullable: true events: type: array items: "$ref": "#/components/schemas/MaasDecommissionEvent" required: - attention_key - review_required - review_state - reviewed_at - reviewed_by - review_note - attention_reason - next_action - superseded_by_workflow_id - events MaasDecommissionEvents: type: object additionalProperties: false properties: decommission_id: type: string format: uuid maas_system_id: type: string level: type: string nullable: true limit: type: integer events: type: array items: "$ref": "#/components/schemas/MaasEvent" fetched_at: type: string format: date-time required: - decommission_id - maas_system_id - limit - events - fetched_at MaasDecommissionListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/MaasDecommission" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination AdminStartMaasDecommissionRequest: type: object additionalProperties: false properties: mode: type: string enum: - soft_reset - reimage - full_decommission - storage_cleanup required: - mode AdminStartMaasDecommissionResponse: type: object additionalProperties: false properties: decommission_id: type: string format: uuid status: "$ref": "#/components/schemas/MaasWorkflowStatus" required: - decommission_id - status MaasRoceAssignment: type: object additionalProperties: false properties: id: type: string format: uuid site_id: type: string format: uuid hostname: type: string interface: type: string ipv4_cidr: type: string status: "$ref": "#/components/schemas/MaasRoceAssignmentStatus" disabled_at: type: string format: date-time nullable: true disabled_by_user_id: type: string format: uuid nullable: true disable_reason: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - site_id - hostname - interface - ipv4_cidr - status - created_at - updated_at MaasRoceAssignmentStatus: type: string enum: - enabled - disabled MaasRoceAssignmentListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/MaasRoceAssignment" required: - items MaasReconciliationStatus: type: object additionalProperties: false properties: total_nodes: type: integer minimum: 0 drifted_nodes: type: integer minimum: 0 unresolved_drift_nodes: type: integer minimum: 0 reconciled_nodes: type: integer minimum: 0 workflow_engine: "$ref": "#/components/schemas/MaasReconciliationWorkflowEngineStatus" generated_at: type: string format: date-time required: - total_nodes - drifted_nodes - unresolved_drift_nodes - reconciled_nodes - generated_at MaasReconciliationWorkflowEngineStatus: type: object additionalProperties: false properties: engine: type: string connected: type: boolean schedule_id: type: string schedule_present: type: boolean paused: type: boolean note: type: string nullable: true num_actions: type: integer minimum: 0 num_actions_missed_catchup: type: integer minimum: 0 num_actions_skipped_overlap: type: integer minimum: 0 running_workflow_ids: type: array items: type: string recent_workflow_ids: type: array items: type: string last_action_scheduled_at: type: string format: date-time nullable: true last_action_started_at: type: string format: date-time nullable: true next_action_at: type: string format: date-time nullable: true error_message: type: string nullable: true checked_at: type: string format: date-time required: - engine - connected - schedule_id - schedule_present - paused - num_actions - num_actions_missed_catchup - num_actions_skipped_overlap - running_workflow_ids - recent_workflow_ids - checked_at MaasDriftRecord: type: object additionalProperties: false properties: node_id: type: string format: uuid site_id: type: string format: uuid maas_system_id: type: string host: type: string hostname: type: string nullable: true last_maas_status: type: string nullable: true last_maas_power_state: type: string nullable: true last_maas_ips: type: array items: type: string last_reconciled_at: type: string format: date-time nullable: true drift_detected: type: boolean drift_details: type: object additionalProperties: true drift_resolved_at: type: string format: date-time nullable: true required: - node_id - site_id - maas_system_id - host - last_maas_ips - drift_detected - drift_details MaasDriftListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/MaasDriftRecord" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination AdminNodeEnrollmentTokenResponse: type: object additionalProperties: false properties: node_id: type: string format: uuid enrollment_token: type: string minLength: 1 expires_in_seconds: type: integer minimum: 1 expires_at: type: string format: date-time bootstrap_bundle: "$ref": "#/components/schemas/NodeBootstrapBundle" required: - node_id - enrollment_token - expires_in_seconds - expires_at - bootstrap_bundle AdminNodeReenrollmentResponse: type: object additionalProperties: false properties: node_id: type: string format: uuid enrollment_token: type: string minLength: 1 expires_in_seconds: type: integer minimum: 1 expires_at: type: string format: date-time recovery_bundle: "$ref": "#/components/schemas/NodeReenrollmentBundle" required: - node_id - enrollment_token - expires_in_seconds - expires_at - recovery_bundle NodeReenrollmentBundle: type: object additionalProperties: false properties: api_url: type: string format: uri terminal_api_url: type: string format: uri nullable: true trust_bundle_version: type: string env_file_path: type: string cert_path: type: string key_path: type: string node_cert_ca_bundle_path: type: string restart_command: type: string required: - api_url - trust_bundle_version - env_file_path - cert_path - key_path - node_cert_ca_bundle_path - restart_command NodeBootstrapBundle: type: object additionalProperties: false properties: api_url: type: string format: uri task_signing_pubkeys: type: string nullable: true ca_bundle_pem: type: string nullable: true ca_fingerprint_sha256: type: string nullable: true trust_bundle_version: type: string ca_bundle_path: type: string node_cert_ca_bundle_path: type: string cert_path: type: string key_path: type: string package: "$ref": "#/components/schemas/NodeBootstrapPackage" required: - api_url - trust_bundle_version - ca_bundle_path - node_cert_ca_bundle_path - cert_path - key_path - package NodeBootstrapPackage: type: object additionalProperties: false properties: architecture: type: string enum: - amd64 - arm64 available_architectures: type: array items: type: string enum: - amd64 - arm64 minItems: 1 oci_ref: type: string digest: type: string tag: type: string nullable: true registry_api_base_url: type: string format: uri nullable: true pull_delivery_mode: type: string enum: - manual - vault_wrapped_token pull_wrapped_token: type: string nullable: true pull_unwrap_url: type: string format: uri nullable: true pull_expires_at: type: string format: date-time nullable: true install_root: type: string env_file_path: type: string systemd_unit_name: type: string install_entrypoint: type: string env_template_path: type: string service_unit_path: type: string binary_path: type: string install_container_runtime: type: boolean container_runtime_package: type: string required: - architecture - available_architectures - oci_ref - digest - pull_delivery_mode - install_root - env_file_path - systemd_unit_name - install_entrypoint - env_template_path - service_unit_path - binary_path - install_container_runtime - container_runtime_package NodeBootstrapRegistryCredential: type: object additionalProperties: false properties: registry_host: type: string minLength: 1 registry_api_base_url: type: string format: uri username: type: string minLength: 1 password: type: string minLength: 1 required: - registry_host - registry_api_base_url - username - password AdminNodeBootstrapScriptResponse: type: object additionalProperties: false properties: node_id: type: string format: uuid bootstrap_token: type: string minLength: 1 expires_in_seconds: type: integer minimum: 1 expires_at: type: string format: date-time mode: type: string enum: - manual - cloud_init script: type: string minLength: 1 script_sha256: type: string minLength: 1 metadata: "$ref": "#/components/schemas/NodeBootstrapScriptMetadata" required: - node_id - bootstrap_token - expires_in_seconds - expires_at - mode - script - script_sha256 - metadata NodeBootstrapScriptMetadata: type: object additionalProperties: false properties: trust_bundle_version: type: string package_ref: type: string package_digest: type: string package_download_url: type: string format: uri runtime_api_url: type: string format: uri required: - trust_bundle_version - package_ref - package_digest - package_download_url - runtime_api_url NodeBootstrapProgressRequest: type: object additionalProperties: false properties: phase: type: string enum: - site_bootstrap - node_bootstrap - node_enrollment state: type: string enum: - started - running - in_progress - succeeded - completed - done - failed - error - skipped message: type: string details: type: object additionalProperties: true required: - phase - state NodeBootstrapProgressResponse: type: object additionalProperties: false properties: recorded: type: boolean onboarding_id: type: string format: uuid nullable: true attempt: type: integer minimum: 0 required: - recorded AllocationRuntimeHealth: type: object additionalProperties: false description: Runtime health reported by the allocation runtime. For gpu_slice allocations this is the libvirt guest state and guest SSH probe result, not the physical host health. properties: allocation_id: type: string format: uuid vm_name: type: string private_ip: type: string nullable: true checked_at: type: string format: date-time domstate: type: string description: Libvirt domain state such as running, shut off, paused, or unknown. autostart: type: boolean nullable: true description: Whether libvirt autostart is enabled for the guest domain. ssh_reachable: type: boolean nullable: true description: Guest SSH reachability probe result when a private IP is known. ssh_port: type: integer nullable: true ssh_probe_ms: type: integer format: int64 nullable: true last_probe_error: type: string nullable: true required: - allocation_id - vm_name - checked_at - domstate Allocation: type: object additionalProperties: false properties: id: type: string format: uuid resource_name: type: string description: Canonical resource identifier in core42:aicloud format. requested_by_user_id: type: string format: uuid requested_by_username: type: string nullable: true description: Operator-facing username for the requesting user. Canonical identity remains requested_by_user_id. requested_by_display_name: type: string nullable: true description: Optional human display name for the requesting user when the identity source provides one. org_id: type: string format: uuid project_id: type: string format: uuid project_name: type: string nullable: true description: Human project label for operator read models. Canonical scope remains project_id. node_id: type: string format: uuid nullable: true node_hostname: type: string nullable: true description: Human node label for operator read models. Canonical node identity remains node_id. scheduler_type: type: string enum: - bare_metal - slurm - k8s - ray capacity_shape: "$ref": "#/components/schemas/CapacityShape" placement_status: "$ref": "#/components/schemas/AllocationPlacementStatus" placement_metadata: type: object additionalProperties: true description: Opaque placement read-model metadata. It must not be used as the source of scheduling correctness. runtime_health: "$ref": "#/components/schemas/AllocationRuntimeHealth" placement_claims: type: array items: "$ref": "#/components/schemas/AllocationPlacementClaim" description: Admin read model of durable placement claims. Claims are the source of placement correctness for baremetal and slice allocations. sku: type: string gpus_total: type: integer status: type: string enum: - requested - provisioning - active - restarting - restart_failed - releasing - released - failed - release_failed failure_reason: type: string nullable: true provisioning_started_at: type: string format: date-time nullable: true active_at: type: string format: date-time nullable: true restart_failed_at: type: string format: date-time nullable: true restart_failed_reason: type: string nullable: true released_at: type: string format: date-time nullable: true release_failed_at: type: string format: date-time nullable: true release_failed_reason: type: string nullable: true connection: "$ref": "#/components/schemas/AllocationConnection" nullable: true ssh_keys: type: array items: "$ref": "#/components/schemas/SshPublicKeyRef" description: SSH public keys installed for this allocation user account. created_at: type: string format: date-time required: - id - requested_by_user_id - org_id - project_id - scheduler_type - sku - gpus_total - status - ssh_keys - created_at AllocationPlacementClaim: type: object additionalProperties: false properties: id: type: string format: uuid allocation_id: type: string format: uuid node_id: type: string format: uuid slot_id: type: string format: uuid nullable: true claim_kind: type: string enum: - node_exclusive - slot status: type: string enum: - reserved - provisioning - active - releasing - released - failed resource_snapshot: type: object additionalProperties: true created_at: type: string format: date-time released_at: type: string format: date-time nullable: true required: - id - allocation_id - node_id - claim_kind - status - resource_snapshot - created_at AllocationConnection: type: object additionalProperties: false properties: host: type: string hostname: type: string nullable: true port: type: integer minimum: 1 maximum: 65535 username_on_node: type: string description: Stable per-user node username sourced from user POSIX identity mapping. required: - host - port - username_on_node AllocationListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/Allocation" limits: "$ref": "#/components/schemas/AllocationLimits" pagination: "$ref": "#/components/schemas/Pagination" required: - items - limits - pagination AllocationGroupKind: type: string enum: - batch - cluster - app_runtime - shared_runtime description: Coarse product intent for a parent group of normal allocations. Runtime-specific topology stays in app/runtime-owned contracts. AllocationGroupStatus: type: string enum: - requested - provisioning - active - degraded - releasing - released - failed - release_failed description: Aggregate group status derived from member allocation states and group-level release intent. It does not replace member allocation status. AllocationGroupOwnerKind: type: string enum: - user_request - app_instance - shared_app_runtime AllocationGroupOwner: type: object additionalProperties: false properties: owner_kind: "$ref": "#/components/schemas/AllocationGroupOwnerKind" owner_id: type: string format: uuid nullable: true description: Owning app/runtime id when owner_kind is not user_request. required: - owner_kind - owner_id AllocationGroupMemberSummary: type: object additionalProperties: false properties: id: type: string format: uuid allocation_group_id: type: string format: uuid allocation_id: type: string format: uuid member_role: type: string nullable: true description: Runtime or product role label such as controller, worker, server, or agent. The role meaning is adapter/product-owned. ordinal: type: integer minimum: 0 required: type: boolean description: Whether this member is required for the group to be fully active. status: type: string enum: - requested - provisioning - active - restarting - restart_failed - releasing - released - failed - release_failed description: Current status of the bound allocation. capacity_shape: "$ref": "#/components/schemas/CapacityShape" sku: type: string gpus_total: type: integer node_id: type: string format: uuid nullable: true connection: "$ref": "#/components/schemas/AllocationConnection" nullable: true created_at: type: string format: date-time active_at: type: string format: date-time nullable: true released_at: type: string format: date-time nullable: true required: - id - allocation_group_id - allocation_id - ordinal - required - status - sku - gpus_total - created_at AllocationGroup: type: object additionalProperties: false description: Project-scoped parent resource for a set of normal single-node allocations. Member allocations remain the source of billing, placement, connection, and release truth. properties: id: type: string format: uuid resource_name: type: string description: Canonical resource identifier in core42:aicloud format. org_id: type: string format: uuid project_id: type: string format: uuid requested_by_user_id: type: string format: uuid group_kind: "$ref": "#/components/schemas/AllocationGroupKind" display_name: type: string minLength: 1 status: "$ref": "#/components/schemas/AllocationGroupStatus" owner: "$ref": "#/components/schemas/AllocationGroupOwner" desired_member_count: type: integer minimum: 1 required_member_count: type: integer minimum: 0 active_member_count: type: integer minimum: 0 failed_member_count: type: integer minimum: 0 releasing_member_count: type: integer minimum: 0 released_member_count: type: integer minimum: 0 members: type: array items: "$ref": "#/components/schemas/AllocationGroupMemberSummary" created_at: type: string format: date-time updated_at: type: string format: date-time released_at: type: string format: date-time nullable: true required: - id - resource_name - org_id - project_id - requested_by_user_id - group_kind - display_name - status - owner - desired_member_count - required_member_count - active_member_count - failed_member_count - releasing_member_count - released_member_count - members - created_at - updated_at AllocationGroupListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AllocationGroup" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination CreateAllocationGroupMemberIntent: type: object additionalProperties: false properties: member_role: type: string nullable: true description: Optional role label for the member allocation. requested_count: type: integer minimum: 1 default: 1 required: type: boolean default: true required: - requested_count CreateAllocationGroupRequest: type: object additionalProperties: false description: Request a parent group and one or more normal member allocations. The implementation may create members synchronously or continue provisioning asynchronously, but each member remains a standard allocation. properties: display_name: type: string minLength: 1 group_kind: "$ref": "#/components/schemas/AllocationGroupKind" owner: "$ref": "#/components/schemas/AllocationGroupOwner" sku: type: string minLength: 1 scheduler_type: type: string enum: - bare_metal - slurm - k8s - ray default: bare_metal capacity_shape: "$ref": "#/components/schemas/CapacityShape" member_intents: type: array minItems: 1 maxItems: 20 items: "$ref": "#/components/schemas/CreateAllocationGroupMemberIntent" ssh_key_ids: type: array description: Optional SSH key set applied to each created member allocation. minItems: 1 maxItems: 20 uniqueItems: true items: type: string format: uuid nullable: true scheduler_request: type: object additionalProperties: true required: - display_name - group_kind - sku - scheduler_type - member_intents CreateAllocationGroupResponse: type: object additionalProperties: false properties: allocation_group: "$ref": "#/components/schemas/AllocationGroup" requested_member_count: type: integer minimum: 1 created_member_count: type: integer minimum: 0 required: - allocation_group - requested_member_count - created_member_count ReleaseAllocationGroupRequest: type: object additionalProperties: false properties: release_strategy: type: string enum: - all_members - active_or_failed_members default: all_members description: Controls which member allocations receive release requests. reason: type: string nullable: true maxLength: 500 required: - release_strategy ReleaseAllocationGroupResponse: type: object additionalProperties: false properties: allocation_group: "$ref": "#/components/schemas/AllocationGroup" release_requested_member_count: type: integer minimum: 0 required: - allocation_group - release_requested_member_count AllocationTimelineItem: type: object additionalProperties: false properties: kind: type: string enum: - allocation_state - placement_claim - node_task name: type: string status: type: string enum: - pending - running - succeeded - failed - skipped - unknown task_id: type: string format: uuid nullable: true node_id: type: string format: uuid nullable: true started_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true duration_seconds: type: integer minimum: 0 nullable: true summary: type: string nullable: true required: - kind - name - status - task_id - node_id - started_at - completed_at - duration_seconds - summary AllocationTimelineResponse: type: object additionalProperties: false properties: allocation_id: type: string format: uuid status: type: string enum: - requested - provisioning - active - restarting - restart_failed - releasing - released - failed - release_failed generated_at: type: string format: date-time next_cursor: type: string nullable: true description: Opaque cursor for the next page of older timeline items. items: type: array items: "$ref": "#/components/schemas/AllocationTimelineItem" required: - allocation_id - status - generated_at - next_cursor - items AllocationLimits: type: object additionalProperties: false properties: max_concurrent_allocations: type: integer minimum: 1 current_concurrent_allocations: type: integer minimum: 0 available_allocation_slots: type: integer minimum: 0 required: - max_concurrent_allocations - current_concurrent_allocations - available_allocation_slots AdminIntegerPolicyBounds: type: object additionalProperties: false properties: min_value: type: integer nullable: true max_value: type: integer nullable: true required: - min_value - max_value AdminAllocationConcurrencyPolicy: type: object additionalProperties: false properties: policy_key: type: string enum: - allocation.max_concurrent_per_user description: type: string value_type: type: string enum: - integer scope_type: type: string enum: - global value: type: integer minimum: 1 default_value: type: integer minimum: 1 bounds: "$ref": "#/components/schemas/AdminIntegerPolicyBounds" effective_at: type: string format: date-time created_at: type: string format: date-time created_by_user_id: type: string format: uuid nullable: true reason: type: string nullable: true correlation_id: type: string nullable: true required: - policy_key - description - value_type - scope_type - value - default_value - bounds - effective_at - created_at AdminSetAllocationConcurrencyPolicyRequest: type: object additionalProperties: false properties: value: type: integer minimum: 1 reason: type: string nullable: true maxLength: 500 required: - value AdminBackfillAllocationPlacementClaimsResponse: type: object additionalProperties: false properties: candidate_count: type: integer minimum: 0 inserted_count: type: integer minimum: 0 skipped_count: type: integer minimum: 0 required: - candidate_count - inserted_count - skipped_count CreateAllocationRequest: type: object additionalProperties: false properties: node_id: type: string format: uuid nullable: true requested_count: type: integer minimum: 1 maximum: 20 default: 1 description: Number of independent allocations to request in one API call. Each successful result creates a separate single-node allocation. ssh_key_ids: type: array description: Optional per-allocation SSH key set. If omitted, the user's active default SSH key is used. minItems: 1 maxItems: 20 uniqueItems: true items: type: string format: uuid nullable: true runtime_bundle_id: type: string format: uuid nullable: true description: Optional managed runtime bundle to associate with each created allocation. The bundle is platform-owned state layered above raw allocation provisioning and does not govern arbitrary user SSH-installed packages. runtime_bundle_slug: type: string nullable: true description: Optional managed runtime bundle slug. If both id and slug are provided, id wins. scheduler_type: type: string enum: - bare_metal - slurm - k8s - ray default: bare_metal capacity_shape: "$ref": "#/components/schemas/CapacityShape" description: Requested capacity shape. Defaults to baremetal until slice SKUs are enabled. gpu_count: type: integer minimum: 1 description: Requested GPU count for selectable slice products. For fixed baremetal products, the SKU determines the count. scheduler_request: type: object additionalProperties: true required: - scheduler_type SetAllocationSshKeysRequest: type: object additionalProperties: false properties: ssh_key_ids: type: array description: Registered SSH key IDs to attach to this allocation. For active allocations, the resolved public keys are asynchronously synchronized to the existing allocation runtime user's authorized_keys file on the node. minItems: 1 maxItems: 20 uniqueItems: true items: type: string format: uuid required: - ssh_key_ids ManagedRuntimeBundle: type: object additionalProperties: false properties: id: type: string format: uuid slug: type: string display_name: type: string version: type: string support_level: type: string enum: - supported - preview - deprecated status: type: string enum: - active - deprecated - disabled install_root: type: string activation_hint: type: string description: type: string compatible_accelerators: type: array items: type: string metadata: type: object additionalProperties: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - slug - display_name - version - support_level - status - install_root - activation_hint - description - compatible_accelerators - metadata - created_at - updated_at ManagedRuntimeBundleListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/ManagedRuntimeBundle" required: - items AllocationRuntimeBundleStatus: type: string enum: - pending - queued - active - failed - removed AllocationRuntimeBundle: type: object additionalProperties: false properties: id: type: string format: uuid allocation_id: type: string format: uuid project_id: type: string format: uuid bundle: "$ref": "#/components/schemas/ManagedRuntimeBundle" status: "$ref": "#/components/schemas/AllocationRuntimeBundleStatus" apply_task_id: type: string format: uuid nullable: true failure_reason: type: string nullable: true requested_by_user_id: type: string format: uuid nullable: true requested_at: type: string format: date-time applied_at: type: string format: date-time nullable: true removed_at: type: string format: date-time nullable: true updated_at: type: string format: date-time required: - id - allocation_id - project_id - bundle - status - requested_at - updated_at AllocationRuntimeBundleListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AllocationRuntimeBundle" required: - items ApplyAllocationRuntimeBundleRequest: type: object additionalProperties: false properties: bundle_id: type: string format: uuid nullable: true bundle_slug: type: string nullable: true minProperties: 1 ApplyAllocationRuntimeBundleResponse: type: object additionalProperties: false properties: runtime: "$ref": "#/components/schemas/AllocationRuntimeBundle" required: - runtime AllocationAccessGrantStatus: type: string enum: - active - revoked AllocationAccessGrantRuntimeSyncStatus: type: string enum: - pending - queued - not_required - failed AllocationAccessGrant: type: object additionalProperties: false properties: id: type: string format: uuid allocation_id: type: string format: uuid project_id: type: string format: uuid grantee_user_id: type: string format: uuid grantee_username: type: string ssh_key: "$ref": "#/components/schemas/SshPublicKeyRef" status: "$ref": "#/components/schemas/AllocationAccessGrantStatus" runtime_sync_status: "$ref": "#/components/schemas/AllocationAccessGrantRuntimeSyncStatus" runtime_sync_task_id: type: string format: uuid nullable: true runtime_sync_error: type: string nullable: true reason: type: string nullable: true created_by_user_id: type: string format: uuid nullable: true created_at: type: string format: date-time revoked_by_user_id: type: string format: uuid nullable: true revoked_at: type: string format: date-time nullable: true required: - id - allocation_id - project_id - grantee_user_id - grantee_username - ssh_key - status - runtime_sync_status - created_at AllocationAccessGrantListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AllocationAccessGrant" required: - items CreateAllocationAccessGrantRequest: type: object additionalProperties: false properties: grantee_user_id: type: string format: uuid description: Project member receiving access. The referenced SSH key must be this user's personal key. ssh_key_id: type: string format: uuid description: Personal SSH public key owned by the grantee. reason: type: string maxLength: 500 nullable: true required: - grantee_user_id - ssh_key_id CreateAllocationAccessGrantResponse: type: object additionalProperties: false properties: grant: "$ref": "#/components/schemas/AllocationAccessGrant" required: - grant RevokeAllocationAccessGrantResponse: type: object additionalProperties: false properties: grant: "$ref": "#/components/schemas/AllocationAccessGrant" required: - grant CreateAllocationResponse: type: object additionalProperties: false properties: allocation: "$ref": "#/components/schemas/Allocation" allocations: type: array description: Created allocations for this request. For single-create callers, `allocation` is the first item in this array. items: "$ref": "#/components/schemas/Allocation" requested_count: type: integer minimum: 1 created_count: type: integer minimum: 1 failed_count: type: integer minimum: 0 required: - allocation - allocations - requested_count - created_count - failed_count ReleaseAllocationResponse: type: object additionalProperties: false properties: allocation: "$ref": "#/components/schemas/Allocation" operation: "$ref": "#/components/schemas/V3WorkloadLifecycleMutationResult" required: - allocation RestartAllocationResponse: type: object additionalProperties: false properties: allocation: "$ref": "#/components/schemas/Allocation" operation: "$ref": "#/components/schemas/V3WorkloadLifecycleMutationResult" required: - allocation V3WorkloadLifecycleMutationResult: type: object additionalProperties: false description: Traceable lifecycle submission result returned by workload release and restart mutations. properties: ok: type: boolean operation: type: string enum: - release - restart workload_id: type: string format: uuid allocation_id: type: string format: uuid previous_status: type: string enum: - requested - provisioning - active - idle - stopped - completed - restarting - restart_failed - releasing - released - failed - release_failed nullable: true status: "$ref": "#/components/schemas/V3WorkloadStatus" correlation_id: type: string task_href: type: string evidence_href: type: string required: - ok - operation - workload_id - allocation_id - previous_status - status - correlation_id - task_href - evidence_href AllocationMetrics: type: object additionalProperties: false properties: netdata_up: type: boolean cpu_utilization_pct: type: number nullable: true memory_utilization_pct: type: number nullable: true gpu_utilization_pct: type: number nullable: true gpu_memory_utilization_pct: type: number nullable: true gpu_memory_used_mib: type: number nullable: true gpu_memory_total_mib: type: number nullable: true gpu_power_w: type: number nullable: true gpu_temperature_c: type: number nullable: true gpu_ecc_errors: type: integer nullable: true disk_read_mib_per_s: type: number nullable: true disk_write_mib_per_s: type: number nullable: true network_receive_mib_per_s: type: number nullable: true network_transmit_mib_per_s: type: number nullable: true fabric_receive_mib_per_s: type: number nullable: true fabric_transmit_mib_per_s: type: number nullable: true load1: type: number nullable: true cpu_some_pressure_pct: type: number nullable: true memory_some_pressure_pct: type: number nullable: true io_some_pressure_pct: type: number nullable: true last_error: type: string nullable: true sampled_at: type: string format: date-time required: - netdata_up - cpu_utilization_pct - memory_utilization_pct - gpu_utilization_pct - gpu_memory_utilization_pct - gpu_memory_used_mib - gpu_memory_total_mib - gpu_power_w - gpu_temperature_c - gpu_ecc_errors - disk_read_mib_per_s - disk_write_mib_per_s - network_receive_mib_per_s - network_transmit_mib_per_s - fabric_receive_mib_per_s - fabric_transmit_mib_per_s - load1 - cpu_some_pressure_pct - memory_some_pressure_pct - io_some_pressure_pct - last_error - sampled_at AllocationMetricsCapabilities: type: object additionalProperties: false properties: has_gpu_metrics: type: boolean has_gpu_device_metrics: type: boolean has_network_interface_metrics: type: boolean has_fabric_metrics: type: boolean has_pressure_metrics: type: boolean has_power_metrics: type: boolean has_temperature_metrics: type: boolean has_ecc_metrics: type: boolean required: - has_gpu_metrics - has_gpu_device_metrics - has_network_interface_metrics - has_fabric_metrics - has_pressure_metrics - has_power_metrics - has_temperature_metrics - has_ecc_metrics AllocationMetricsGPUDevice: type: object additionalProperties: false properties: device_id: type: string name: type: string nullable: true model: type: string nullable: true utilization_pct: type: number nullable: true memory_utilization_pct: type: number nullable: true memory_used_mib: type: number nullable: true memory_total_mib: type: number nullable: true power_w: type: number nullable: true temperature_c: type: number nullable: true ecc_errors: type: integer nullable: true health_status: type: string nullable: true enum: - healthy - warning - critical - unknown required: - device_id - name - model - utilization_pct - memory_utilization_pct - memory_used_mib - memory_total_mib - power_w - temperature_c - ecc_errors - health_status AllocationMetricsNetworkInterface: type: object additionalProperties: false properties: name: type: string role: type: string enum: - fabric - public - storage - unknown transport_type: type: string enum: - ethernet - roce - infiniband - unknown rx_mib_per_s: type: number nullable: true tx_mib_per_s: type: number nullable: true rx_packets_per_s: type: number nullable: true tx_packets_per_s: type: number nullable: true drops_per_s: type: number nullable: true link_speed_mbps: type: number nullable: true utilization_pct: type: number nullable: true operstate: type: string nullable: true carrier_up: type: boolean nullable: true required: - name - role - transport_type - rx_mib_per_s - tx_mib_per_s - rx_packets_per_s - tx_packets_per_s - drops_per_s - link_speed_mbps - utilization_pct - operstate - carrier_up AllocationMetricsResponse: type: object additionalProperties: false properties: allocation_id: type: string format: uuid node_id: type: string format: uuid nullable: true node_host: type: string nullable: true netdata_url: type: string nullable: true deprecated: true description: Legacy field retained for compatibility. Tenant allocation pages should use first-party GPUaaS metrics and this field should be null in current responses. status: type: string enum: - requested - provisioning - active - restarting - restart_failed - releasing - released - failed - release_failed metrics: "$ref": "#/components/schemas/AllocationMetrics" capabilities: "$ref": "#/components/schemas/AllocationMetricsCapabilities" gpu_devices: type: array items: "$ref": "#/components/schemas/AllocationMetricsGPUDevice" network_interfaces: type: array items: "$ref": "#/components/schemas/AllocationMetricsNetworkInterface" required: - allocation_id - status - metrics - capabilities - gpu_devices - network_interfaces AllocationMetricsPoint: type: object additionalProperties: false properties: ts: type: string format: date-time value: type: number nullable: true required: - ts - value AllocationMetricsTimeseriesResponse: type: object additionalProperties: false properties: allocation_id: type: string format: uuid node_id: type: string format: uuid nullable: true node_host: type: string nullable: true status: type: string enum: - requested - provisioning - active - restarting - restart_failed - releasing - released - failed - release_failed window_seconds: type: integer minimum: 60 maximum: 86400 collection_status: type: string description: Time-series collection availability for the requested window. enum: - available - unavailable unavailable_reason: type: string nullable: true description: Classified reason when collection_status is unavailable. enum: - allocation_not_active - node_host_unavailable - no_history - telemetry_unavailable points: type: object additionalProperties: false properties: cpu: type: array items: "$ref": "#/components/schemas/AllocationMetricsPoint" memory: type: array items: "$ref": "#/components/schemas/AllocationMetricsPoint" gpu: type: array items: "$ref": "#/components/schemas/AllocationMetricsPoint" gpu_memory: type: array items: "$ref": "#/components/schemas/AllocationMetricsPoint" disk_read: type: array items: "$ref": "#/components/schemas/AllocationMetricsPoint" disk_write: type: array items: "$ref": "#/components/schemas/AllocationMetricsPoint" network_in: type: array items: "$ref": "#/components/schemas/AllocationMetricsPoint" network_out: type: array items: "$ref": "#/components/schemas/AllocationMetricsPoint" fabric_in: type: array items: "$ref": "#/components/schemas/AllocationMetricsPoint" fabric_out: type: array items: "$ref": "#/components/schemas/AllocationMetricsPoint" load1: type: array items: "$ref": "#/components/schemas/AllocationMetricsPoint" cpu_pressure: type: array items: "$ref": "#/components/schemas/AllocationMetricsPoint" memory_pressure: type: array items: "$ref": "#/components/schemas/AllocationMetricsPoint" io_pressure: type: array items: "$ref": "#/components/schemas/AllocationMetricsPoint" required: - cpu - memory - gpu - gpu_memory - disk_read - disk_write - network_in - network_out - fabric_in - fabric_out - load1 - cpu_pressure - memory_pressure - io_pressure required: - allocation_id - status - window_seconds - collection_status - unavailable_reason - points CreateChargeSessionRequest: type: object additionalProperties: false properties: amount_minor: type: integer minimum: 1 description: Amount in minor units (e.g., cents). currency: type: string pattern: "^[A-Z]{3}$" default: USD required: - amount_minor - currency SessionUrlResponse: type: object additionalProperties: false properties: url: type: string format: uri payment_session_id: type: string format: uuid description: Platform payment session recorded before redirect for reconciliation and support. provider_session_id: type: string description: External payment provider checkout session identifier. required: - url StorageItem: type: object additionalProperties: false properties: name: type: string resource_name: type: string description: Canonical resource identifier in core42:aicloud format. type: type: string enum: - dir - file size_bytes: type: integer nullable: true mtime_ms: type: integer nullable: true required: - name - type StorageListResponse: type: object additionalProperties: false properties: path: type: string items: type: array items: "$ref": "#/components/schemas/StorageItem" pagination: "$ref": "#/components/schemas/Pagination" required: - path - items - pagination StorageMkdirRequest: type: object additionalProperties: false properties: path: type: string minLength: 1 required: - path StorageRenameRequest: type: object additionalProperties: false properties: from: type: string minLength: 1 to: type: string minLength: 1 required: - from - to AdminCreateUserRequest: type: object additionalProperties: false properties: username: type: string minLength: 1 oidc_issuer: type: string minLength: 3 nullable: true oidc_subject: type: string minLength: 3 nullable: true password: type: string minLength: 1 nullable: true description: Dev/bootstrap-only local credential path. OIDC anchors are primary for production. role: type: string enum: - user - admin default: user required: - username anyOf: - required: - oidc_issuer - oidc_subject - required: - password AdminCreateUserResponse: type: object additionalProperties: false properties: id: type: string format: uuid required: - id AdminAdjustBalanceRequest: type: object additionalProperties: false properties: direction: type: string enum: - credit - debit amount_minor: type: integer minimum: 1 currency: type: string pattern: "^[A-Z]{3}$" default: USD reason: type: string required: - direction - amount_minor - currency - reason AdminCreateRefundRequest: type: object additionalProperties: false properties: amount_minor: type: integer minimum: 1 currency: type: string pattern: "^[A-Z]{3}$" default: USD reason: type: string minLength: 3 payment_reference: type: string description: Provider payment/session reference for traceability. mode: type: string enum: - auto_policy - force_internal_credit default: auto_policy description: | auto_policy applies hybrid refund policy: provider refund in-window, internal credit fallback out-of-window. required: - amount_minor - currency - reason AdminCreateRefundResponse: type: object additionalProperties: false properties: refund_id: type: string format: uuid outcome: type: string nullable: true enum: - provider_refund - internal_credit status: type: string enum: - accepted - completed - failed amount: "$ref": "#/components/schemas/Money" policy_applied: type: object additionalProperties: false properties: refund_window_days: type: integer in_window: type: boolean unused_balance_rule_applied: type: boolean required: - refund_window_days - in_window - unused_balance_rule_applied required: - refund_id - status - amount - policy_applied PaymentSession: type: object additionalProperties: false description: Tracks a Stripe checkout session from initiation through credit posting. properties: id: type: string format: uuid org_id: type: string format: uuid initiated_by_user_id: type: string format: uuid stripe_checkout_session_id: type: string stripe_payment_intent_id: type: string nullable: true requested_amount: "$ref": "#/components/schemas/Money" credited_amount: allOf: - "$ref": "#/components/schemas/Money" nullable: true description: Actual credited amount from Stripe webhook; should equal requested_amount. status: type: string enum: - initiated - checkout_completed - credited - failed_reconcile - expired initiated_at: type: string format: date-time checkout_completed_at: type: string format: date-time nullable: true credited_at: type: string format: date-time nullable: true failed_at: type: string format: date-time nullable: true failure_reason: type: string nullable: true ledger_entry_id: type: string format: uuid nullable: true correlation_id: type: string created_at: type: string format: date-time required: - id - org_id - initiated_by_user_id - stripe_checkout_session_id - requested_amount - status - initiated_at - correlation_id - created_at PaymentDispute: type: object additionalProperties: false description: Provider-neutral payment dispute and chargeback lifecycle evidence. properties: id: type: string format: uuid org_id: type: string format: uuid user_id: type: string format: uuid nullable: true payment_session_id: type: string format: uuid nullable: true provider: type: string enum: - stripe provider_dispute_id: type: string provider_charge_id: type: string nullable: true provider_payment_intent_id: type: string nullable: true status: type: string enum: - opened - needs_response - evidence_due - evidence_submitted - won - lost - closed provider_status: type: string nullable: true reason: type: string nullable: true amount: "$ref": "#/components/schemas/Money" evidence_due_at: type: string format: date-time nullable: true evidence_submitted_at: type: string format: date-time nullable: true closed_at: type: string format: date-time nullable: true provider_event_id: type: string nullable: true chargeback_ledger_entry_id: type: string format: uuid nullable: true reversal_ledger_entry_id: type: string format: uuid nullable: true correlation_id: type: string nullable: true metadata: type: object additionalProperties: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - org_id - user_id - payment_session_id - provider - provider_dispute_id - provider_charge_id - provider_payment_intent_id - status - provider_status - reason - amount - evidence_due_at - evidence_submitted_at - closed_at - provider_event_id - chargeback_ledger_entry_id - reversal_ledger_entry_id - correlation_id - metadata - created_at - updated_at AdminReconcilePaymentSessionRequest: type: object additionalProperties: false properties: action: type: string enum: - post_credit - mark_expired - mark_failed amount_minor: type: integer minimum: 1 description: Optional override for post_credit; defaults to credited amount or requested amount. reason: type: string minLength: 3 failure_reason: type: string description: Operator-visible failure reason when action is mark_failed. required: - action - reason RefundRequest: type: object additionalProperties: false properties: id: type: string format: uuid org_id: type: string format: uuid user_id: type: string format: uuid requested_by_user_id: type: string format: uuid nullable: true amount: "$ref": "#/components/schemas/Money" reason: type: string payment_reference: type: string nullable: true mode: type: string enum: - auto_policy - force_internal_credit outcome: type: string nullable: true enum: - provider_refund - internal_credit status: type: string enum: - accepted - completed - failed provider_refund_id: type: string nullable: true internal_ledger_entry_id: type: string format: uuid nullable: true correlation_id: type: string created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - org_id - user_id - amount - reason - mode - status - correlation_id - created_at - updated_at RefundListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/RefundRequest" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination BillingReconciliationSummary: type: object additionalProperties: false properties: checked_at: type: string format: date-time missing_open_usage_count: type: integer minimum: 0 orphan_open_usage_count: type: integer minimum: 0 unbilled_closed_usage_count: type: integer minimum: 0 sample_allocation_id: type: string format: uuid nullable: true sample_usage_id: type: string format: uuid nullable: true severity: type: string enum: - ok - warn - error required: - checked_at - missing_open_usage_count - orphan_open_usage_count - unbilled_closed_usage_count - severity BillingReconciliationRun: type: object additionalProperties: false properties: id: type: string format: uuid requested_by_user_id: type: string format: uuid nullable: true status: type: string enum: - running - completed - failed summary: "$ref": "#/components/schemas/BillingReconciliationSummary" failure_reason: type: string nullable: true correlation_id: type: string created_at: type: string format: date-time completed_at: type: string format: date-time nullable: true required: - id - status - summary - correlation_id - created_at BillingReconciliationListResponse: type: object additionalProperties: false properties: current: "$ref": "#/components/schemas/BillingReconciliationSummary" runs: type: array items: "$ref": "#/components/schemas/BillingReconciliationRun" pagination: "$ref": "#/components/schemas/Pagination" required: - current - runs - pagination BillingDiagnosticsResponse: type: object additionalProperties: false properties: correlation_id: type: string payment_sessions: type: array items: "$ref": "#/components/schemas/PaymentSession" refunds: type: array items: "$ref": "#/components/schemas/RefundRequest" usage_records: type: array items: "$ref": "#/components/schemas/UsageRecord" ledger_entries: type: array items: "$ref": "#/components/schemas/BillingLedgerEntry" audit_logs: type: array items: "$ref": "#/components/schemas/BillingAuditEvidence" required: - correlation_id - payment_sessions - refunds - usage_records - ledger_entries - audit_logs BillingLedgerEntry: type: object additionalProperties: false properties: id: type: string format: uuid user_id: type: string format: uuid entry_type: type: string amount: "$ref": "#/components/schemas/Money" reference_type: type: string nullable: true reference_id: type: string nullable: true created_at: type: string format: date-time required: - id - user_id - entry_type - amount - created_at BillingAuditEvidence: type: object additionalProperties: false properties: id: type: string format: uuid actor_user_id: type: string format: uuid nullable: true actor_role: type: string action: type: string target_type: type: string target_id: type: string result: type: string correlation_id: type: string occurred_at: type: string format: date-time required: - id - actor_role - action - target_type - target_id - result - correlation_id - occurred_at FinancialRestriction: type: object additionalProperties: false properties: id: type: string format: uuid scope_type: type: string enum: - tenant - project - user scope_id: type: string format: uuid state: type: string enum: - healthy - at_risk - restricted - suspended - collections_hold reason: type: string effects: type: object additionalProperties: true description: Non-destructive policy effects. Runtime suspension or forced release requires a separate reviewed policy gate. correlation_id: type: string updated_at: type: string format: date-time required: - id - scope_type - scope_id - state - reason - effects - correlation_id - updated_at BillingFinancialPostureResponse: type: object additionalProperties: false properties: state: type: string enum: - healthy - at_risk - restricted - suspended - collections_hold reason: type: string effects: type: object additionalProperties: true description: Current non-destructive financial restriction effects. restriction: "$ref": "#/components/schemas/FinancialRestriction" nullable: true affected_allocation_ids: type: array items: type: string format: uuid affected_app_instance_ids: type: array items: type: string format: uuid selected_action: type: string enum: - '' - restrict - force_release description: Policy-selected action for the latest prepaid depletion decision, when known. balance_minor: type: integer format: int64 nullable: true description: Balance snapshot from the latest financial posture transition, when known. correlation_id: type: string nullable: true updated_at: type: string format: date-time nullable: true required: - state - reason - effects - restriction - affected_allocation_ids - affected_app_instance_ids - selected_action - balance_minor - correlation_id - updated_at SetFinancialRestrictionRequest: type: object additionalProperties: false properties: state: type: string enum: - healthy - at_risk - restricted - suspended - collections_hold reason: type: string minLength: 1 metadata: type: object additionalProperties: true required: - state - reason LinkProviderCustomerRequest: type: object additionalProperties: false properties: org_id: type: string format: uuid provider: type: string enum: - stripe provider_customer_id: type: string minLength: 1 source: type: string enum: - api - backfill - webhook - admin default: admin is_default: type: boolean required: - org_id - provider - provider_customer_id - is_default ProviderCustomer: type: object additionalProperties: false properties: id: type: string format: uuid org_id: type: string format: uuid provider: type: string enum: - stripe provider_customer_id: type: string status: type: string enum: - active - disabled - deleted is_default: type: boolean source: type: string enum: - api - backfill - webhook - admin created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - org_id - provider - provider_customer_id - status - is_default - source - created_at - updated_at ServiceAccount: type: object additionalProperties: false properties: id: type: string format: uuid org_id: type: string format: uuid project_id: type: string format: uuid name: type: string slug: type: string description: type: string nullable: true purpose: type: string enum: - operator - controller - automation description: 'User-facing intent for the service account. `controller` identities are platform/app-controller credentials and must not be offered as app operator runtime identities. ' default: operator state: type: string enum: - active - disabled - deleted created_by_user_id: type: string format: uuid created_at: type: string format: date-time disabled_at: type: string format: date-time nullable: true deleted_at: type: string format: date-time nullable: true required: - id - org_id - project_id - name - slug - state - created_by_user_id - created_at ServiceAccountListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/ServiceAccount" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination CreateServiceAccountRequest: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 128 slug: type: string minLength: 1 maxLength: 128 description: type: string nullable: true maxLength: 512 purpose: type: string enum: - operator - controller - automation required: - name - slug CreateServiceAccountResponse: type: object additionalProperties: false properties: service_account: "$ref": "#/components/schemas/ServiceAccount" initial_credential: "$ref": "#/components/schemas/ServiceAccountCredentialSecret" required: - service_account - initial_credential RotateServiceAccountCredentialResponse: type: object additionalProperties: false properties: service_account: "$ref": "#/components/schemas/ServiceAccount" credential: "$ref": "#/components/schemas/ServiceAccountCredentialSecret" required: - service_account - credential ServiceAccountCredentialSecret: type: object additionalProperties: false description: One-time credential material. client_secret is returned only on create/rotate. properties: key_id: type: string client_secret: type: string algorithm: type: string created_at: type: string format: date-time required: - key_id - client_secret - algorithm - created_at ServiceAccountTokenRequest: type: object additionalProperties: false properties: service_account_id: type: string format: uuid key_id: type: string minLength: 1 maxLength: 128 client_secret: type: string minLength: 16 maxLength: 512 description: Plaintext credential secret; server verifies against encrypted credential record. audience: type: string minLength: 1 maxLength: 256 scope: type: array items: type: string minLength: 1 maxLength: 128 required: - service_account_id - key_id - client_secret ServiceAccountTokenResponse: type: object additionalProperties: false properties: access_token: type: string expires_in_seconds: type: integer minimum: 1 token_type: type: string enum: - Bearer required: - access_token - expires_in_seconds - token_type SharedRuntimeOperatorTokenRequest: type: object additionalProperties: false description: 'Token request for a delegated tenant-shared runtime operator identity. ' properties: shared_runtime_id: type: string format: uuid key_id: type: string minLength: 1 maxLength: 128 client_secret: type: string minLength: 16 maxLength: 512 description: Plaintext delegated operator secret; server verifies against encrypted credential record. audience: type: string minLength: 1 maxLength: 256 scope: type: array items: type: string minLength: 1 maxLength: 128 required: - shared_runtime_id - key_id - client_secret SharedRuntimeOperatorTokenResponse: type: object additionalProperties: false properties: access_token: type: string expires_in_seconds: type: integer minimum: 1 token_type: type: string enum: - Bearer required: - access_token - expires_in_seconds - token_type SharedRuntimeOperatorTokenClaims: type: object additionalProperties: false description: 'Claim shape for delegated shared-runtime operator tokens. ' properties: sub: type: string minLength: 1 actor_type: type: string enum: - shared_runtime_operator org_id: type: string format: uuid shared_runtime_id: type: string format: uuid scope: type: array items: type: string minLength: 1 maxLength: 128 iss: type: string minLength: 1 aud: type: string minLength: 1 iat: type: integer minimum: 0 exp: type: integer minimum: 0 jti: type: string minLength: 1 required: - sub - actor_type - org_id - shared_runtime_id - iss - aud - iat - exp - jti AccessCredentialScopeType: type: string enum: - platform - tenant - project AccessCredentialOperationalDomain: type: string enum: - platform-control - platform-ops - tenant-runtime AccessCredentialKind: type: string enum: - ssh_key - password - token - certificate_bundle AccessCredentialCustodyBackend: type: string enum: - vault AccessCredentialDeliveryMode: type: string enum: - vault_ref - vault_wrapped_token AccessCredentialStatus: type: string enum: - active - disabled - rotation_pending - expired - deleted AccessCredentialData: type: object additionalProperties: type: string minProperties: 1 description: Generic secret payload stored under the credential custody backend. Keys are app- and kind-specific. AccessCredentialBinding: type: object additionalProperties: false properties: id: type: string format: uuid credential_id: type: string format: uuid resource_type: type: string maxLength: 128 resource_id: type: string maxLength: 255 purpose: type: string maxLength: 128 description: Binding purpose such as app_bootstrap_ssh. usage_tags: type: array items: type: string minLength: 1 maxLength: 64 created_at: type: string format: date-time required: - id - credential_id - resource_type - resource_id - purpose - usage_tags - created_at AdminAccessCredential: type: object additionalProperties: false properties: id: type: string format: uuid display_name: type: string description: type: string nullable: true scope_type: "$ref": "#/components/schemas/AccessCredentialScopeType" scope_id: type: string format: uuid nullable: true resource_type: type: string nullable: true maxLength: 128 resource_id: type: string nullable: true maxLength: 255 bindings: type: array items: "$ref": "#/components/schemas/AccessCredentialBinding" operational_domain: "$ref": "#/components/schemas/AccessCredentialOperationalDomain" credential_kind: "$ref": "#/components/schemas/AccessCredentialKind" usage_tags: type: array items: type: string minLength: 1 maxLength: 64 principal_username: type: string nullable: true maxLength: 255 description: Optional username paired with the credential for registry/basic-auth style use cases. custody_backend: "$ref": "#/components/schemas/AccessCredentialCustodyBackend" custody_instance: type: string minLength: 1 maxLength: 128 delivery_mode: "$ref": "#/components/schemas/AccessCredentialDeliveryMode" vault_path: type: string nullable: true description: Backend reference for Vault-backed custody. Metadata only; not a secret reveal surface. status: "$ref": "#/components/schemas/AccessCredentialStatus" last_validated_at: type: string format: date-time nullable: true last_used_at: type: string format: date-time nullable: true rotation_due_at: type: string format: date-time nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - display_name - scope_type - operational_domain - credential_kind - usage_tags - custody_backend - custody_instance - delivery_mode - status - created_at - updated_at ProjectAccessCredential: type: object additionalProperties: false properties: id: type: string format: uuid display_name: type: string description: type: string nullable: true scope_type: "$ref": "#/components/schemas/AccessCredentialScopeType" scope_id: type: string format: uuid nullable: true resource_type: type: string nullable: true maxLength: 128 resource_id: type: string nullable: true maxLength: 255 bindings: type: array items: "$ref": "#/components/schemas/AccessCredentialBinding" operational_domain: "$ref": "#/components/schemas/AccessCredentialOperationalDomain" credential_kind: "$ref": "#/components/schemas/AccessCredentialKind" usage_tags: type: array items: type: string minLength: 1 maxLength: 64 principal_username: type: string nullable: true maxLength: 255 description: Optional username paired with the credential for SSH or basic-auth style use cases. custody_backend: "$ref": "#/components/schemas/AccessCredentialCustodyBackend" custody_instance: type: string minLength: 1 maxLength: 128 delivery_mode: "$ref": "#/components/schemas/AccessCredentialDeliveryMode" vault_path: type: string nullable: true description: Backend reference for Vault-backed custody. Metadata only; not a secret reveal surface. status: "$ref": "#/components/schemas/AccessCredentialStatus" last_validated_at: type: string format: date-time nullable: true last_used_at: type: string format: date-time nullable: true rotation_due_at: type: string format: date-time nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - display_name - scope_type - operational_domain - credential_kind - usage_tags - custody_backend - custody_instance - delivery_mode - status - created_at - updated_at ProjectAccessCredentialListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/ProjectAccessCredential" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination AdminAccessCredentialListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AdminAccessCredential" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination AdminCreateAccessCredentialRequest: type: object additionalProperties: false properties: display_name: type: string minLength: 1 maxLength: 128 description: type: string nullable: true maxLength: 512 scope_type: "$ref": "#/components/schemas/AccessCredentialScopeType" scope_id: type: string format: uuid nullable: true resource_type: type: string nullable: true maxLength: 128 resource_id: type: string nullable: true maxLength: 255 operational_domain: "$ref": "#/components/schemas/AccessCredentialOperationalDomain" credential_kind: "$ref": "#/components/schemas/AccessCredentialKind" usage_tags: type: array minItems: 1 items: type: string minLength: 1 maxLength: 64 principal_username: type: string nullable: true maxLength: 255 custody_backend: "$ref": "#/components/schemas/AccessCredentialCustodyBackend" custody_instance: type: string minLength: 1 maxLength: 128 delivery_mode: "$ref": "#/components/schemas/AccessCredentialDeliveryMode" credential_data: "$ref": "#/components/schemas/AccessCredentialData" required: - display_name - scope_type - operational_domain - credential_kind - usage_tags - custody_backend - custody_instance - delivery_mode - credential_data AdminCreateAccessCredentialResponse: type: object additionalProperties: false properties: credential: "$ref": "#/components/schemas/AdminAccessCredential" required: - credential AdminUpdateAccessCredentialRequest: type: object additionalProperties: false properties: display_name: type: string minLength: 1 maxLength: 128 description: type: string nullable: true maxLength: 512 resource_type: type: string nullable: true maxLength: 128 resource_id: type: string nullable: true maxLength: 255 usage_tags: type: array items: type: string minLength: 1 maxLength: 64 principal_username: type: string nullable: true maxLength: 255 status: description: Metadata-level enable/disable control. Secret material changes must use rotate. allOf: - "$ref": "#/components/schemas/AccessCredentialStatus" AdminRotateAccessCredentialRequest: type: object additionalProperties: false properties: principal_username: type: string nullable: true maxLength: 255 rotation_reason: type: string nullable: true maxLength: 512 credential_data: "$ref": "#/components/schemas/AccessCredentialData" required: - credential_data ProjectCreateAccessCredentialRequest: type: object additionalProperties: false properties: display_name: type: string minLength: 1 maxLength: 128 description: type: string nullable: true maxLength: 512 resource_type: type: string nullable: true maxLength: 128 resource_id: type: string nullable: true maxLength: 255 operational_domain: "$ref": "#/components/schemas/AccessCredentialOperationalDomain" credential_kind: "$ref": "#/components/schemas/AccessCredentialKind" usage_tags: type: array minItems: 1 items: type: string minLength: 1 maxLength: 64 principal_username: type: string nullable: true maxLength: 255 custody_backend: "$ref": "#/components/schemas/AccessCredentialCustodyBackend" custody_instance: type: string minLength: 1 maxLength: 128 delivery_mode: "$ref": "#/components/schemas/AccessCredentialDeliveryMode" credential_data: "$ref": "#/components/schemas/AccessCredentialData" required: - display_name - operational_domain - credential_kind - usage_tags - custody_backend - custody_instance - delivery_mode - credential_data ProjectCreateAccessCredentialResponse: type: object additionalProperties: false properties: credential: "$ref": "#/components/schemas/ProjectAccessCredential" required: - credential ProjectUpdateAccessCredentialRequest: type: object additionalProperties: false properties: display_name: type: string minLength: 1 maxLength: 128 nullable: true description: type: string nullable: true maxLength: 512 resource_type: type: string nullable: true maxLength: 128 resource_id: type: string nullable: true maxLength: 255 usage_tags: type: array items: type: string minLength: 1 maxLength: 64 principal_username: type: string nullable: true maxLength: 255 status: type: string enum: - active - disabled - rotation_pending - expired - deleted nullable: true ProjectRotateAccessCredentialRequest: type: object additionalProperties: false properties: principal_username: type: string nullable: true maxLength: 255 rotation_reason: type: string nullable: true maxLength: 512 credential_data: "$ref": "#/components/schemas/AccessCredentialData" required: - credential_data ProjectDeliverAccessCredentialRequest: type: object additionalProperties: false properties: wrap_ttl_seconds: type: integer minimum: 1 maximum: 3600 description: Optional wrapped delivery TTL. Only used for `vault_wrapped_token`. AccessCredentialDelivery: type: object additionalProperties: false properties: mode: "$ref": "#/components/schemas/AccessCredentialDeliveryMode" vault_path: type: string nullable: true wrapped_token: type: string nullable: true unwrap_url: type: string nullable: true description: Vault unwrap endpoint for wrapped delivery flows. expires_at: type: string format: date-time nullable: true required: - mode ProjectDeliverAccessCredentialResponse: type: object additionalProperties: false properties: credential: "$ref": "#/components/schemas/ProjectAccessCredential" delivery: "$ref": "#/components/schemas/AccessCredentialDelivery" required: - credential - delivery AdminCreateNodeRequest: type: object additionalProperties: false properties: host: type: string minLength: 3 hostname: type: string minLength: 3 nullable: true port: type: integer minimum: 1 maximum: 65535 default: 22 sku: type: string minLength: 1 gpus_total: type: integer minimum: 0 description: Accelerator count on the worker. CPU VM workers report 0. region_code: type: string default: region-maas-1 onboarding_mode: type: string enum: - manual - maas default: manual description: Registration mode. manual = operator installs bootstrap bundle. maas = legacy/bootstrap MAAS path; prefer dedicated `/api/v1/admin/onboardings` endpoints for new MAAS onboarding flows. probe: type: boolean default: true required: - host - sku - gpus_total AdminSku: type: object additionalProperties: false properties: sku: type: string minLength: 1 vendor: type: string minLength: 1 display_name: type: string minLength: 1 family_id: type: string minLength: 1 family_version: type: string minLength: 1 family_display_name: type: string minLength: 1 runtime_provider: type: string minLength: 1 resource_class: "$ref": "#/components/schemas/SkuResourceClass" billing_unit: "$ref": "#/components/schemas/SkuBillingUnit" scheduling_unit: "$ref": "#/components/schemas/SkuSchedulingUnit" resources: "$ref": "#/components/schemas/SkuResources" resource_profile: type: object additionalProperties: true description: SKU-level capacity and topology hints such as default vCPU, memory, fabric, and allowed topology groups. active: type: boolean unit_price: "$ref": "#/components/schemas/Money" required: - sku - vendor - display_name - family_id - family_version - family_display_name - resource_class - billing_unit - scheduling_unit - resources - active - unit_price AdminCreateSkuRequest: type: object additionalProperties: false properties: sku: type: string minLength: 1 vendor: type: string minLength: 1 display_name: type: string minLength: 1 family_id: type: string minLength: 1 family_version: type: string minLength: 1 resource_class: "$ref": "#/components/schemas/SkuResourceClass" billing_unit: "$ref": "#/components/schemas/SkuBillingUnit" scheduling_unit: "$ref": "#/components/schemas/SkuSchedulingUnit" resources: "$ref": "#/components/schemas/SkuResources" resource_profile: type: object additionalProperties: true unit_price: "$ref": "#/components/schemas/Money" required: - sku - vendor - display_name - resource_class - billing_unit - scheduling_unit - resources - unit_price AdminUpdateSkuRequest: type: object additionalProperties: false properties: vendor: type: string minLength: 1 display_name: type: string minLength: 1 family_id: type: string minLength: 1 family_version: type: string minLength: 1 resource_class: "$ref": "#/components/schemas/SkuResourceClass" billing_unit: "$ref": "#/components/schemas/SkuBillingUnit" scheduling_unit: "$ref": "#/components/schemas/SkuSchedulingUnit" resources: "$ref": "#/components/schemas/SkuResources" resource_profile: type: object additionalProperties: true unit_price: "$ref": "#/components/schemas/Money" required: - vendor - display_name - resource_class - billing_unit - scheduling_unit - resources - unit_price AdminSkuListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AdminSku" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination ProviderCapacityInventoryHealth: type: object additionalProperties: false properties: status: type: string enum: - healthy - degraded - unhealthy - unknown messages: type: array items: type: string required: - status ProviderCapacityRefreshPolicy: type: object additionalProperties: false description: Operator-owned policy for automatic provider capacity refresh, capacity freshness, maintenance holds, and launch eligibility. Omitted values preserve current platform defaults. properties: auto_refresh_enabled: type: boolean default: true description: Enables periodic provider inventory refresh by the provider reconciler or inventory collector. refresh_interval_seconds: type: integer minimum: 0 default: 0 description: Minimum seconds between automatic refresh attempts for this provider. Zero means use the reconciler deployment interval. inventory_freshness_ttl_seconds: type: integer minimum: 1 default: 600 description: Maximum age before placement and catalog treat provider capacity as stale. refresh_hold_until: type: string format: date-time nullable: true description: Optional operator hold; automatic refresh is skipped until this time. refresh_hold_reason: type: string nullable: true manual_refresh_allowed: type: boolean default: true description: Whether privileged operators may trigger an explicit refresh. degraded_capacity_mode: type: string enum: - exclude - include_for_ops_only - include_for_launch default: exclude stale_inventory_launch_policy: type: string enum: - hide_capacity - block - trigger_refresh_then_retry - allow_ready_workers_only default: hide_capacity max_refresh_failure_streak: type: integer minimum: 0 default: 0 refresh_timeout_seconds: type: integer minimum: 0 default: 0 description: Provider refresh timeout override. Zero means use the provider adapter default. maintenance_mode: type: boolean default: false maintenance_starts_at: type: string format: date-time nullable: true maintenance_ends_at: type: string format: date-time nullable: true capacity_reservation_buffer_percent: type: integer minimum: 0 maximum: 95 default: 0 description: Percentage of reported raw CPU, memory, and storage capacity held back from placement. max_on_demand_workers_per_refresh: type: integer minimum: 0 default: 0 description: Maximum on-demand worker compose/clone requests a single refresh cycle may authorize. Zero means no policy cap. allowed_skus: type: array items: type: string disabled_skus: type: array items: type: string ProviderCapacityInventory: type: object additionalProperties: false properties: provider_id: type: string minLength: 1 contract_version: type: string minLength: 1 default: v1 runtime_provider: type: string enum: - manual - maas_baremetal - proxmox_vm - maas_lxd_vm - gpu_slice_vm environment_profile: type: string minLength: 1 observed_at: type: string format: date-time health: "$ref": "#/components/schemas/ProviderCapacityInventoryHealth" capacity_pools: type: array items: "$ref": "#/components/schemas/ProviderCapacityPool" refresh_policy: "$ref": "#/components/schemas/ProviderCapacityRefreshPolicy" last_refresh_failure: "$ref": "#/components/schemas/ProviderCapacityRefreshFailure" nullable: true evidence_refs: type: object additionalProperties: true raw_evidence: type: object additionalProperties: true updated_at: type: string format: date-time required: - provider_id - contract_version - runtime_provider - environment_profile - observed_at - health - capacity_pools - refresh_policy - evidence_refs - raw_evidence - updated_at ProviderCapacityRefreshFailure: type: object additionalProperties: false description: Sanitized last failed provider capacity refresh evidence projected from raw provider-reconciler evidence for operator triage. properties: code: type: string minLength: 1 description: Canonical provider capacity refresh failure code. message: type: string minLength: 1 description: Sanitized provider-facing failure message. Must not contain credential material. failed_at: type: string format: date-time provider: type: string minLength: 1 provider_id: type: string minLength: 1 correlation_id: type: string minLength: 1 classification: type: string enum: - auth - network - provider_api - capacity - bootstrap_handoff required: - code - message - failed_at - provider - provider_id - correlation_id - classification ProviderCapacityInventoryUpsertRequest: type: object additionalProperties: false description: Normalized provider capacity inventory report accepted from trusted operator ingestion paths. The server may default observed_at when omitted. properties: provider_id: type: string minLength: 1 contract_version: type: string minLength: 1 default: v1 runtime_provider: type: string enum: - manual - maas_baremetal - proxmox_vm - maas_lxd_vm - gpu_slice_vm environment_profile: type: string minLength: 1 observed_at: type: string format: date-time health: "$ref": "#/components/schemas/ProviderCapacityInventoryHealth" capacity_pools: type: array items: "$ref": "#/components/schemas/ProviderCapacityPool" refresh_policy: "$ref": "#/components/schemas/ProviderCapacityRefreshPolicy" evidence_refs: type: object additionalProperties: true raw_evidence: type: object additionalProperties: true required: - provider_id - runtime_provider - environment_profile - health - capacity_pools ProviderCapacityInventoryListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/ProviderCapacityInventory" required: - items ProviderCapacityPool: type: object additionalProperties: true description: Normalized provider-neutral capacity pool reported by Proxmox, MAAS-LXD, MAAS bare metal, or future providers. Provider-specific details remain under raw_evidence. properties: id: type: string minLength: 1 eligible_families: type: array items: "$ref": "#/components/schemas/ProviderCapacityPoolFamily" resources: "$ref": "#/components/schemas/ProviderCapacityPoolResources" failure_domain: type: object additionalProperties: true network_profiles: type: array items: type: object additionalProperties: true warm_pools: type: array items: type: object additionalProperties: true source_observed_at: type: string format: date-time nullable: true cleanup_safety: "$ref": "#/components/schemas/ProviderCapacityPoolCleanupSafety" evidence: type: object additionalProperties: true raw_evidence: type: object additionalProperties: true required: - id - eligible_families - resources - failure_domain - network_profiles - warm_pools - cleanup_safety - evidence - raw_evidence ProviderCapacityPoolFamily: type: object additionalProperties: false properties: family_id: type: string minLength: 1 family_version: type: string minLength: 1 required: - family_id - family_version ProviderCapacityPoolResources: type: object additionalProperties: true properties: vcpu_total: type: integer format: int64 vcpu_used: type: integer format: int64 vcpu_reserved: type: integer format: int64 vcpu_free: type: integer format: int64 vcpu_available: type: integer format: int64 description: Legacy alias for vcpu_free retained during provider adapter migration. vcpu_maintenance: type: integer format: int64 vcpu_stale: type: integer format: int64 memory_mib_total: type: integer format: int64 memory_mib_used: type: integer format: int64 memory_mib_reserved: type: integer format: int64 memory_mib_free: type: integer format: int64 memory_mib_available: type: integer format: int64 description: Legacy alias for memory_mib_free retained during provider adapter migration. memory_mib_maintenance: type: integer format: int64 memory_mib_stale: type: integer format: int64 storage_mib_total: type: integer format: int64 storage_mib_used: type: integer format: int64 storage_mib_reserved: type: integer format: int64 storage_mib_free: type: integer format: int64 storage_mib_available: type: integer format: int64 description: Legacy alias for storage_mib_free retained during provider adapter migration. storage_mib_maintenance: type: integer format: int64 storage_mib_stale: type: integer format: int64 accelerators: type: array items: type: object additionalProperties: true ProviderCapacityPoolCleanupSafety: type: object additionalProperties: false properties: safe_to_reuse: type: boolean safe_to_delete: type: boolean blocking_reasons: type: array items: type: string required: - safe_to_reuse - safe_to_delete - blocking_reasons ProviderCapacityRefreshRequest: type: object additionalProperties: false description: Privileged operator request for the provider reconciler to refresh one provider capacity inventory report on its next cycle. properties: reason: type: string nullable: true maxLength: 512 correlation_id: type: string nullable: true maxLength: 128 ProviderResourceLifecycleState: type: string enum: - requested - creating - bootstrapping - ready - bound - draining - deleting - quarantined - orphaned - deleted ProviderResourceLifecycleActionKey: type: string enum: - retry_cleanup - request_delete - quarantine - mark_external ProviderResourceLifecycleAction: type: object additionalProperties: false properties: key: "$ref": "#/components/schemas/ProviderResourceLifecycleActionKey" label: type: string minLength: 1 method: type: string enum: - POST path: type: string minLength: 1 requires_idempotency: type: boolean required: - key - label - method - path - requires_idempotency ProviderResourceOwnerType: type: string enum: - allocation - warm_pool - operator - unknown ProviderResourceLifecycle: type: object additionalProperties: false properties: id: type: string format: uuid provider_id: type: string minLength: 1 provider_object_type: type: string minLength: 1 provider_object_id: type: string minLength: 1 gpuaas_resource_type: type: string minLength: 1 gpuaas_resource_id: type: string format: uuid nullable: true allocation_id: type: string format: uuid nullable: true owner_type: "$ref": "#/components/schemas/ProviderResourceOwnerType" owner_id: type: string nullable: true family_id: type: string nullable: true family_version: type: string nullable: true sku: type: string nullable: true network_profile: type: string nullable: true storage_profile: type: string nullable: true correlation_id: type: string minLength: 1 lifecycle_state: "$ref": "#/components/schemas/ProviderResourceLifecycleState" observed_state: type: string minLength: 1 desired_state: type: object additionalProperties: true retry_count: type: integer minimum: 0 next_retry_at: type: string format: date-time nullable: true last_error_code: type: string nullable: true last_error_message: type: string nullable: true evidence_refs: type: object additionalProperties: true raw_evidence: type: object additionalProperties: true actions: type: array description: Operator actions currently available for this provider resource lifecycle record. Actions are generated from server-side lifecycle state so UX does not branch on provider names. items: "$ref": "#/components/schemas/ProviderResourceLifecycleAction" created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - provider_id - provider_object_type - provider_object_id - gpuaas_resource_type - gpuaas_resource_id - allocation_id - owner_type - owner_id - family_id - family_version - sku - network_profile - storage_profile - correlation_id - lifecycle_state - observed_state - desired_state - retry_count - next_retry_at - last_error_code - last_error_message - evidence_refs - raw_evidence - actions - created_at - updated_at ProviderResourceLifecycleActionRequest: type: object additionalProperties: false properties: reason: type: string maxLength: 512 correlation_id: type: string maxLength: 128 ProviderResourceLifecycleUpsertRequest: type: object additionalProperties: false description: Desired-state and observed-state lifecycle record for a provider-owned object. This endpoint persists provider resource state only; it does not call provider APIs. properties: provider_id: type: string minLength: 1 provider_object_type: type: string minLength: 1 provider_object_id: type: string minLength: 1 gpuaas_resource_type: type: string minLength: 1 gpuaas_resource_id: type: string format: uuid nullable: true allocation_id: type: string format: uuid nullable: true owner_type: "$ref": "#/components/schemas/ProviderResourceOwnerType" owner_id: type: string nullable: true family_id: type: string nullable: true family_version: type: string nullable: true sku: type: string nullable: true network_profile: type: string nullable: true storage_profile: type: string nullable: true correlation_id: type: string minLength: 1 lifecycle_state: "$ref": "#/components/schemas/ProviderResourceLifecycleState" observed_state: type: string desired_state: type: object additionalProperties: true retry_count: type: integer minimum: 0 next_retry_at: type: string format: date-time nullable: true last_error_code: type: string nullable: true last_error_message: type: string nullable: true evidence_refs: type: object additionalProperties: true raw_evidence: type: object additionalProperties: true required: - provider_id - provider_object_type - provider_object_id - gpuaas_resource_type - owner_type - correlation_id - lifecycle_state ProviderResourceLifecycleListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/ProviderResourceLifecycle" required: - items AuditLogEntry: type: object additionalProperties: false properties: id: type: string format: uuid actor_user_id: type: string format: uuid nullable: true actor_service_account_id: type: string format: uuid nullable: true actor_role: type: string enum: - user - admin - service_account - system action: type: string target_type: type: string target_id: type: string nullable: true result: type: string enum: - success - failure correlation_id: type: string occurred_at: type: string format: date-time metadata: type: object additionalProperties: true presentation: "$ref": "#/components/schemas/AuditLogPresentation" required: - id - actor_role - action - target_type - result - correlation_id - occurred_at AuditLogPresentation: type: object additionalProperties: false description: Backend-owned display model for audit/evidence surfaces. Raw audit fields remain authoritative. properties: actor_label: type: string target_label: type: string target_type_label: type: string action_label: type: string action_category: type: string action_family: type: string summary: type: string result_label: type: string severity: type: string enum: - info - success - warning - error - critical safe_details: type: object additionalProperties: true description: Allowlisted metadata suitable for operator display. Raw metadata remains available for authorized debugging. debug_refs: type: object additionalProperties: false properties: correlation_id: type: string trace_id: type: string nullable: true request_id: type: string nullable: true actor_ref: type: string nullable: true target_ref: type: string nullable: true required: - correlation_id required: - actor_label - target_label - target_type_label - action_label - action_category - action_family - summary - result_label - severity - debug_refs AuditLogListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AuditLogEntry" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination AdminOverviewResponse: type: object additionalProperties: false properties: total_nodes: type: integer minimum: 0 online_nodes: type: integer minimum: 0 active_allocations: type: integer minimum: 0 total_users: type: integer minimum: 0 generated_at: type: string format: date-time required: - total_nodes - online_nodes - active_allocations - total_users - generated_at AdminOpsOverviewResponse: type: object additionalProperties: false description: Aggregated operational telemetry snapshot for the admin ops dashboard. properties: generated_at: type: string format: date-time stale_seconds: type: integer minimum: 0 service_health: type: object additionalProperties: false properties: api_ok: type: boolean billing_worker_ok: type: boolean provisioning_worker_ok: type: boolean outbox_relay_ok: type: boolean outbox_relay_runbook_id: type: string nullable: true required: - api_ok - billing_worker_ok - provisioning_worker_ok - outbox_relay_ok - outbox_relay_runbook_id queue_depth: type: object additionalProperties: false properties: outbox_pending: type: integer minimum: 0 dlq_pending: type: integer minimum: 0 dlq_runbook_id: type: string nullable: true required: - outbox_pending - dlq_pending - dlq_runbook_id throughput_5m: type: object additionalProperties: false properties: allocations_activated: type: integer minimum: 0 allocations_released: type: integer minimum: 0 payments_credited: type: integer minimum: 0 required: - allocations_activated - allocations_released - payments_credited error_rate_5m: type: object additionalProperties: false properties: api_5xx_per_min: type: number minimum: 0 worker_failures_per_min: type: number minimum: 0 api_5xx_runbook_id: type: string nullable: true worker_failures_runbook_id: type: string nullable: true required: - api_5xx_per_min - worker_failures_per_min - api_5xx_runbook_id - worker_failures_runbook_id control_plane: type: object additionalProperties: false properties: nats_connected: type: boolean api_ratelimit_fail_open_total: type: integer minimum: 0 api_idempotency_replays_served_total: type: integer minimum: 0 terminal_token_consumed_ok_total: type: integer minimum: 0 terminal_token_replay_rejected_total: type: integer minimum: 0 ws_notifications_active_connections: type: integer minimum: 0 ws_notifications_write_errors_total: type: integer minimum: 0 platform_role_list_requests_total: type: integer minimum: 0 platform_role_bind_requests_total: type: integer minimum: 0 platform_role_revoke_requests_total: type: integer minimum: 0 platform_role_mutation_success_total: type: integer minimum: 0 platform_role_mutation_failure_total: type: integer minimum: 0 platform_role_admin_denied_total: type: integer minimum: 0 platform_role_service_unavailable_total: type: integer minimum: 0 required: - nats_connected - api_ratelimit_fail_open_total - api_idempotency_replays_served_total - terminal_token_consumed_ok_total - terminal_token_replay_rejected_total - ws_notifications_active_connections - ws_notifications_write_errors_total - platform_role_list_requests_total - platform_role_bind_requests_total - platform_role_revoke_requests_total - platform_role_mutation_success_total - platform_role_mutation_failure_total - platform_role_admin_denied_total - platform_role_service_unavailable_total node_metrics: type: object additionalProperties: false properties: summary: type: object additionalProperties: false properties: total_nodes: type: integer minimum: 0 active_nodes: type: integer minimum: 0 sampled_nodes: type: integer minimum: 0 netdata_reachable_nodes: type: integer minimum: 0 gpu_reporting_nodes: type: integer minimum: 0 required: - total_nodes - active_nodes - sampled_nodes - netdata_reachable_nodes - gpu_reporting_nodes sample: type: array maxItems: 20 items: type: object additionalProperties: false properties: node_id: type: string format: uuid host: type: string status: type: string netdata_up: type: boolean cpu_utilization_pct: type: number nullable: true gpu_utilization_pct: type: number nullable: true gpu_memory_utilization_pct: type: number nullable: true last_error: type: string nullable: true sampled_at: type: string format: date-time required: - node_id - host - status - netdata_up - cpu_utilization_pct - gpu_utilization_pct - gpu_memory_utilization_pct - last_error - sampled_at required: - summary - sample required: - generated_at - stale_seconds - service_health - queue_depth - throughput_5m - error_rate_5m - control_plane - node_metrics AdminRuntimeMetadataResponse: type: object additionalProperties: false description: Live runtime metadata for platform-control services visible to platform operators. properties: generated_at: type: string format: date-time items: type: array items: "$ref": "#/components/schemas/AdminRuntimeMetadataItem" required: - generated_at - items AdminRuntimeMetadataItem: type: object additionalProperties: false properties: service_name: type: string description: Kubernetes deployment or logical runtime service name. component: type: string description: Runtime component within the service, for example api. runtime_kind: type: string enum: - go_service - web - worker - controller - unknown version: type: string description: Build version linked into the running binary when available. commit: type: string description: Git commit linked into the running binary or supplied by deployment metadata. built_at: type: string description: Build timestamp linked into the running binary when available. image_ref: type: string nullable: true description: Deployed image reference from runtime metadata when available. image_digest: type: string nullable: true description: Deployed image digest, or digest parsed from image_ref when available. pipeline_id: type: string nullable: true description: CI pipeline id that deployed the runtime when available. deployed_at: type: string nullable: true description: Deployment timestamp from platform-control rollout metadata when available. source: type: string description: Source of the metadata. The first slice reports the API service itself. required: - service_name - component - runtime_kind - version - commit - built_at - image_ref - image_digest - pipeline_id - deployed_at - source AdminFleetTelemetryWindow: type: object additionalProperties: false properties: range: type: string enum: - 15m - 1h - 6h - 24h window_seconds: type: integer minimum: 1 points: type: integer minimum: 1 required: - range - window_seconds - points AdminFleetTelemetryOverview: type: object additionalProperties: false properties: total_nodes: type: integer minimum: 0 active_nodes: type: integer minimum: 0 total_allocations: type: integer minimum: 0 active_allocations: type: integer minimum: 0 storage_bytes: type: integer minimum: 0 sampled_nodes: type: integer minimum: 0 reporting_nodes: type: integer minimum: 0 required: - total_nodes - active_nodes - total_allocations - active_allocations - storage_bytes - sampled_nodes - reporting_nodes AdminFleetTelemetryRollups: type: object additionalProperties: false properties: cpu_utilization_pct: type: number nullable: true gpu_utilization_pct: type: number nullable: true memory_utilization_pct: type: number nullable: true storage_bytes: type: number minimum: 0 required: - cpu_utilization_pct - gpu_utilization_pct - memory_utilization_pct - storage_bytes AdminFleetTelemetryPoint: type: object additionalProperties: false properties: ts: type: string format: date-time value: type: number nullable: true required: - ts - value AdminFleetTelemetryTimeseries: type: object additionalProperties: false properties: cpu: type: array items: "$ref": "#/components/schemas/AdminFleetTelemetryPoint" gpu: type: array items: "$ref": "#/components/schemas/AdminFleetTelemetryPoint" memory: type: array items: "$ref": "#/components/schemas/AdminFleetTelemetryPoint" storage: type: array items: "$ref": "#/components/schemas/AdminFleetTelemetryPoint" required: - cpu - gpu - memory - storage AdminFleetTelemetryTenantDimension: type: object additionalProperties: false properties: org_id: type: string format: uuid org_name: type: string active_allocations: type: integer minimum: 0 storage_bytes: type: integer minimum: 0 required: - org_id - org_name - active_allocations - storage_bytes AdminFleetTelemetryProjectDimension: type: object additionalProperties: false properties: project_id: type: string format: uuid project_name: type: string org_id: type: string format: uuid org_name: type: string active_allocations: type: integer minimum: 0 storage_bytes: type: integer minimum: 0 required: - project_id - project_name - org_id - org_name - active_allocations - storage_bytes AdminFleetTelemetryDimensions: type: object additionalProperties: false properties: tenants: type: array items: "$ref": "#/components/schemas/AdminFleetTelemetryTenantDimension" projects: type: array items: "$ref": "#/components/schemas/AdminFleetTelemetryProjectDimension" required: - tenants - projects AdminFleetTelemetryResponse: type: object additionalProperties: false description: Fleet telemetry rollups over a bounded window for admin incident and capacity triage. properties: generated_at: type: string format: date-time window: "$ref": "#/components/schemas/AdminFleetTelemetryWindow" overview: "$ref": "#/components/schemas/AdminFleetTelemetryOverview" rollups: "$ref": "#/components/schemas/AdminFleetTelemetryRollups" timeseries: "$ref": "#/components/schemas/AdminFleetTelemetryTimeseries" dimensions: "$ref": "#/components/schemas/AdminFleetTelemetryDimensions" required: - generated_at - window - overview - rollups - timeseries - dimensions AdminOutboxFailedEvent: type: object additionalProperties: false properties: id: type: string format: uuid aggregate_type: type: string aggregate_id: type: string event_type: type: string payload: type: object additionalProperties: true correlation_id: type: string retry_count: type: integer minimum: 0 last_attempted_at: type: string format: date-time nullable: true occurred_at: type: string format: date-time required: - id - aggregate_type - aggregate_id - event_type - payload - correlation_id - retry_count - last_attempted_at - occurred_at AdminOutboxFailedListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AdminOutboxFailedEvent" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination AdminOutboxMutationResponse: type: object additionalProperties: false properties: ok: type: boolean outbox_event_id: type: string format: uuid status: type: string enum: - pending - discarded required: - ok - outbox_event_id - status AdminDLQMessage: type: object additionalProperties: false properties: stream_seq: type: integer format: int64 minimum: 1 subject: type: string original_topic: type: string nullable: true event_type: type: string nullable: true correlation_id: type: string nullable: true occurred_at: type: string format: date-time nullable: true payload: type: object additionalProperties: true requeue_enabled: type: boolean required: - stream_seq - subject - original_topic - event_type - correlation_id - occurred_at - payload - requeue_enabled AdminDLQMessageListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AdminDLQMessage" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination AdminDLQMutationResponse: type: object additionalProperties: false properties: ok: type: boolean stream_seq: type: integer format: int64 minimum: 1 status: type: string enum: - requeued - discarded target_subject: type: string nullable: true required: - ok - stream_seq - status - target_subject AdminRunbook: type: object additionalProperties: false properties: id: type: string minLength: 1 title: type: string minLength: 1 severity_hint: type: string enum: - sev1 - sev2 - sev3 owner_team: type: string minLength: 1 last_reviewed_at: type: string format: date url: type: string minLength: 1 signals: type: array minItems: 1 items: type: string minLength: 1 required: - id - title - severity_hint - owner_team - last_reviewed_at - url - signals AdminRunbookListResponse: type: object additionalProperties: false properties: generated_at: type: string format: date-time items: type: array items: "$ref": "#/components/schemas/AdminRunbook" required: - generated_at - items OkResponse: type: object additionalProperties: false properties: ok: type: boolean required: - ok AccountType: type: string enum: - enterprise - personal description: User account model resolved by the active authentication flow. LoginRequest: type: object additionalProperties: false properties: username: type: string minLength: 1 password: type: string minLength: 1 required: - username - password LoginResponse: type: object additionalProperties: false properties: access_token: type: string expires_in_seconds: type: integer minimum: 1 refresh_token: type: string nullable: true account_type: "$ref": "#/components/schemas/AccountType" org_id: type: string format: uuid nullable: true user: "$ref": "#/components/schemas/UserWithBalance" required: - access_token - expires_in_seconds - account_type - user SignupRequest: type: object additionalProperties: false properties: username: type: string minLength: 1 password: type: string minLength: 8 required: - username - password SignupResponse: allOf: - "$ref": "#/components/schemas/AuthSessionResponse" description: Internal/dev bootstrap signup response. RefreshTokenRequest: type: object additionalProperties: false properties: refresh_token: type: string minLength: 1 required: - refresh_token RefreshTokenResponse: type: object additionalProperties: false properties: access_token: type: string expires_in_seconds: type: integer minimum: 1 refresh_token: type: string nullable: true org_id: type: string format: uuid nullable: true user: "$ref": "#/components/schemas/UserWithBalance" required: - access_token - expires_in_seconds - user LogoutRequest: type: object additionalProperties: false description: Optional refresh token for full session revocation at OIDC provider. properties: refresh_token: type: string minLength: 1 TerminalTokenResponse: type: object additionalProperties: false description: | Short-lived, single-use terminal session token scoped to a specific allocation. Clients must obtain this token via the REST API immediately before opening the ws/terminal WebSocket connection. Browser clients pass this token via `Sec-WebSocket-Protocol`. Non-browser clients may pass it via `Authorization: Bearer `. properties: token: type: string expires_in_seconds: type: integer minimum: 1 maximum: 300 allocation_id: type: string format: uuid required: - token - expires_in_seconds - allocation_id InternalNodeEnrollmentRequest: type: object additionalProperties: false properties: node_id: type: string minLength: 1 csr: type: string minLength: 1 description: PEM-encoded CSR required: - node_id - csr InternalNodeEnrollmentResponse: type: object additionalProperties: false properties: certificate: type: string minLength: 1 description: PEM-encoded certificate chain ca_bundle: type: string minLength: 1 description: PEM-encoded CA bundle required: - certificate - ca_bundle InternalNodeCertRenewRequest: type: object additionalProperties: false properties: csr: type: string minLength: 1 description: PEM-encoded CSR required: - csr InternalNodeCertRenewResponse: type: object additionalProperties: false properties: certificate: type: string minLength: 1 description: PEM-encoded certificate chain required: - certificate InternalNodeTask: type: object additionalProperties: false properties: task_id: type: string format: uuid task_type: type: string minLength: 1 node_id: type: string minLength: 1 correlation_id: type: string issued_at: type: string format: date-time expires_at: type: string format: date-time params: type: object additionalProperties: true signature: type: string minLength: 1 required: - task_id - task_type - node_id - correlation_id - issued_at - expires_at - params - signature InternalNodeTaskResultRequest: type: object additionalProperties: false properties: status: type: string enum: - success - failed - rejected error: type: string nullable: true completed_at: type: string format: date-time output: type: object additionalProperties: true required: - status - completed_at - output InternalNodeTaskResultResponse: type: object additionalProperties: false properties: ok: type: boolean required: - ok InternalAppProxyRouteReportRequest: type: object additionalProperties: false properties: status: type: string enum: - pending - active - failed route_url: type: string nullable: true description: Browser-facing URL published by the gateway/controller when active. target_host: type: string nullable: true description: Gateway-resolved private host, node-local endpoint, or controller-owned upstream reference. target_port: type: integer minimum: 1 maximum: 65535 nullable: true failure_reason: type: string nullable: true target_metadata: type: object additionalProperties: true nullable: true required: - status InternalAppProxyRouteReportResponse: type: object additionalProperties: false properties: route: "$ref": "#/components/schemas/AppInstanceProxyRoute" required: - route InternalTerminalStreamFrame: type: object additionalProperties: false properties: session_id: type: string format: uuid type: type: string enum: - data - resize - close direction: type: string enum: - upstream - downstream payload: type: string format: byte nullable: true close_reason: type: string enum: - normal_close - allocation_released - session_timeout - node_stream_dropped - open_failed - admin_terminate nullable: true error_code: type: string description: Stable node-agent terminal startup failure code for close frames, when available. nullable: true error_message: type: string description: Human-safe node-agent terminal startup failure message for close frames, when available. nullable: true runtime_username: type: string description: Allocation runtime username that node-agent attempted to open for terminal startup failures. nullable: true cols: type: integer minimum: 1 maximum: 512 nullable: true rows: type: integer minimum: 1 maximum: 512 nullable: true required: - session_id - type - direction AppCatalogItem: type: object additionalProperties: false properties: slug: type: string pattern: "^[a-z0-9][a-z0-9-]{1,62}$" display_name: type: string category: type: string enum: - model_serving - inference - training - orchestration - observability - other publisher: type: string latest_version: type: string status: type: string enum: - active - deprecated - disabled description: type: string nullable: true logo_url: type: string format: uri nullable: true tags: type: array items: type: string nullable: true required: - slug - display_name - category - publisher - latest_version - status AppCatalogListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AppCatalogItem" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination AppCatalogVersion: type: object additionalProperties: false properties: app_slug: type: string pattern: "^[a-z0-9][a-z0-9-]{1,62}$" version: type: string minLength: 1 runtime_backend: type: string enum: - k8s - rke2 - slurm - ray - bare_metal manifest: type: object additionalProperties: true status: type: string enum: - active - deprecated - disabled required: - app_slug - version - runtime_backend - manifest - status AppEntitlement: type: object additionalProperties: false properties: app_slug: type: string pattern: "^[a-z0-9][a-z0-9-]{1,62}$" project_id: type: string format: uuid enabled: type: boolean policy_overrides: type: object additionalProperties: true required: - app_slug - project_id - enabled - policy_overrides AppEntitlementListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AppEntitlement" required: - items UpsertAppEntitlementRequest: type: object additionalProperties: false properties: enabled: type: boolean policy_overrides: type: object additionalProperties: true required: - enabled CreateAppInstanceRequest: type: object additionalProperties: false properties: app_slug: type: string pattern: "^[a-z0-9][a-z0-9-]{1,62}$" app_version: type: string minLength: 1 display_name: type: string minLength: 1 app_artifact_id: type: string format: uuid nullable: true operating_mode: type: string enum: - tenant_dedicated - platform_managed nullable: true description: | Optional request hint for the desired app runtime operating mode. Server policy and app backend determine the effective mode; clients must not assume the requested mode is always granted. control_plane_scope: type: string enum: - project - tenant - platform nullable: true description: | Optional request hint for the desired runtime control-plane scope. Current baseline allows `project` or `tenant` only when the effective operating mode is `tenant_dedicated`; `platform` requires `platform_managed`. Server policy and app backend remain authoritative. operator_service_account_id: type: string format: uuid nullable: true placement_intent: "$ref": "#/components/schemas/AppInstancePlacementIntent" config: type: object additionalProperties: true resource_overrides: type: object additionalProperties: true required: - app_slug - app_version - display_name AppInstance: type: object additionalProperties: false properties: id: type: string format: uuid resource_name: type: string project_id: type: string format: uuid app_slug: type: string pattern: "^[a-z0-9][a-z0-9-]{1,62}$" app_version: type: string display_name: type: string app_artifact_id: type: string format: uuid nullable: true operating_mode: type: string enum: - tenant_dedicated - platform_managed description: Effective runtime operating mode for the instance. control_plane_scope: type: string enum: - project - tenant - platform description: Effective scope of the runtime control plane serving this instance. runtime_backend: type: string enum: - k8s - rke2 - slurm - ray - bare_metal description: Effective runtime backend serving this instance. tenant_boundary_mode: type: string enum: - tenant_isolated - shared_service description: Whether the instance runs on tenant-bounded infrastructure or a shared managed substrate. status: type: string enum: - requested - deploying - running - stopping - stopped - starting - restarting - upgrading - rolling_back - failed - decommissioning - decommissioned - deleting - deleted failure_reason: type: string nullable: true requested_by_user_id: type: string format: uuid nullable: true requested_by_service_account_id: type: string format: uuid nullable: true operator_service_account_id: type: string format: uuid nullable: true placement_intent: "$ref": "#/components/schemas/AppInstancePlacementIntent" runtime_state: type: object additionalProperties: true phase: type: string nullable: true progress: type: object additionalProperties: true health_status: type: string nullable: true health_detail: type: object additionalProperties: true proxy_routes: type: array items: "$ref": "#/components/schemas/AppInstanceProxyRoute" description: Platform-proxy route intents and observed route state for app endpoints that requested `platform_proxy` exposure. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - resource_name - project_id - app_slug - app_version - display_name - operating_mode - control_plane_scope - runtime_backend - tenant_boundary_mode - status - created_at - updated_at AppInstanceProxyRoute: type: object additionalProperties: false properties: id: type: string format: uuid app_instance_id: type: string format: uuid project_id: type: string format: uuid endpoint_name: type: string minLength: 1 protocol: type: string enum: - http - https - ws - wss exposure_mode: type: string enum: - platform_proxy route_path: type: string description: Stable platform path reserved for the proxy route. It may be active only after the proxy controller reconciles the route. route_url: type: string nullable: true description: Browser-facing URL once a gateway/controller has published the route. target_kind: type: string enum: - app_instance_endpoint target_host: type: string nullable: true description: Gateway-resolved private host or node-local target. Null until the proxy controller has enough runtime state to resolve it. target_port: type: integer minimum: 1 maximum: 65535 target_metadata: type: object additionalProperties: true status: type: string enum: - pending - active - failed - deleting - deleted failure_reason: type: string nullable: true last_reconciled_at: type: string format: date-time nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - app_instance_id - project_id - endpoint_name - protocol - exposure_mode - route_path - target_kind - target_port - target_metadata - status - created_at - updated_at ManagedIngressRouteResolveResponse: type: object additionalProperties: false description: Correlation-safe ops read model for resolving a managed-ingress public URL or host to its owning route and backend target. It never includes workload tokens, cookies, authorization headers, OIDC state, or query-string auth material. properties: route_id: type: string format: uuid owner_type: type: string enum: - app_instance app_instance_id: type: string format: uuid app_instance_name: type: string app_instance_status: type: string endpoint_name: type: string public_url: type: string backend_route_path: type: string target_host: type: string target_port: type: integer minimum: 1 maximum: 65535 allocation_id: type: string format: uuid nullable: true node_id: type: string format: uuid nullable: true node_host: type: string nullable: true project_id: type: string format: uuid org_id: type: string format: uuid proxy_pool_id: type: string client_auth_mode: type: string enum: - browser_oidc - api_bearer route_family: type: string enum: - platform_admin - browser_app - api_app - terminal_ws last_reconcile_status: type: string last_reconciled_at: type: string format: date-time nullable: true pomerium_ingress_name: type: string nullable: true failure_reason: type: string nullable: true evidence_href: type: string runbook_hrefs: type: array items: type: string resolved_public_host: type: string resolved_public_path: type: string route_version: type: string runtime_correlation_id: type: string required: - route_id - owner_type - app_instance_id - app_instance_name - app_instance_status - endpoint_name - public_url - backend_route_path - target_host - target_port - project_id - org_id - proxy_pool_id - client_auth_mode - route_family - last_reconcile_status - evidence_href - runbook_hrefs - resolved_public_host - resolved_public_path - route_version - runtime_correlation_id AppInstancePlacementIntent: type: object additionalProperties: false properties: target_allocation_id: type: string format: uuid nullable: true description: Requested allocation that should host an allocation-local workload, such as a launchable OCI workload image. controller_allocation_id: type: string format: uuid nullable: true description: Requested allocation that should host the app control-plane member when the app runtime needs one. worker_allocation_ids: type: array items: type: string format: uuid description: Explicit worker allocation targets selected at deploy time. server_allocation_id: type: string format: uuid nullable: true description: Requested allocation that should host the self-managed Kubernetes server member. agent_allocation_ids: type: array items: type: string format: uuid description: Explicit agent allocation targets selected at deploy time for self-managed Kubernetes. Reserved for multi-node RKE2 launch support; the current launchable RKE2 path accepts a server allocation only. allow_shared_allocation: type: boolean description: Whether the controller and one or more workers may reuse the same active allocation. SharedAppRuntimePlacementIntent: type: object additionalProperties: false description: | Reserved contract for tenant-owned shared runtime placement. This schema is additive contract direction only; tenant-shared runtime endpoints are not implemented yet. properties: controller_allocation_ids: type: array items: type: string format: uuid description: Explicit controller/control-plane allocation targets for the tenant-owned shared runtime. allow_project_contributed_workers: type: boolean description: Whether attached consumer projects may contribute worker allocations to the shared runtime. CreateSharedAppRuntimeRequest: type: object additionalProperties: false description: Request contract for creating a tenant-owned shared app runtime. properties: app_slug: type: string pattern: "^[a-z0-9][a-z0-9-]{1,62}$" app_version: type: string minLength: 1 display_name: type: string minLength: 1 operating_mode: type: string enum: - tenant_dedicated description: Tenant-owned shared mode is only defined for tenant-dedicated runtimes in this baseline. control_plane_scope: type: string enum: - tenant description: Shared runtime control plane is tenant-scoped in this baseline. operator_identity_ref: type: string nullable: true description: Reserved reference to the tenant-bounded machine identity that will operate the shared runtime. placement_intent: "$ref": "#/components/schemas/SharedAppRuntimePlacementIntent" config: type: object additionalProperties: true initial_attached_project_ids: type: array items: type: string format: uuid required: - app_slug - app_version - display_name SharedAppRuntime: type: object additionalProperties: false description: Tenant-owned shared runtime control-plane object. properties: id: type: string format: uuid resource_name: type: string org_id: type: string format: uuid app_slug: type: string pattern: "^[a-z0-9][a-z0-9-]{1,62}$" app_version: type: string display_name: type: string operating_mode: type: string enum: - tenant_dedicated control_plane_scope: type: string enum: - tenant runtime_backend: type: string enum: - k8s - rke2 - slurm - ray - bare_metal status: type: string enum: - requested - deploying - running - upgrading - rolling_back - failed - deleting - deleted operator_identity_ref: type: string nullable: true placement_intent: "$ref": "#/components/schemas/SharedAppRuntimePlacementIntent" runtime_state: type: object additionalProperties: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - resource_name - org_id - app_slug - app_version - display_name - operating_mode - control_plane_scope - runtime_backend - status - created_at - updated_at CreateSharedAppRuntimeAttachmentRequest: type: object additionalProperties: false description: Request contract for attaching a consumer project to a tenant-owned shared runtime. properties: project_id: type: string format: uuid allow_worker_contribution: type: boolean allow_job_submission: type: boolean policy: type: object additionalProperties: true required: - project_id SharedAppRuntimeAttachment: type: object additionalProperties: false description: Attachment resource between a tenant-owned shared runtime and a consumer project. properties: id: type: string format: uuid shared_runtime_id: type: string format: uuid org_id: type: string format: uuid project_id: type: string format: uuid status: type: string enum: - requested - attached - detaching - detached - failed allow_worker_contribution: type: boolean allow_job_submission: type: boolean policy: type: object additionalProperties: true runtime_state: type: object additionalProperties: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - shared_runtime_id - org_id - project_id - status - created_at - updated_at SharedAppRuntimeListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/SharedAppRuntime" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination SharedAppRuntimeAttachmentListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/SharedAppRuntimeAttachment" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination SharedAppRuntimeWorker: type: object additionalProperties: false description: | Additive contract direction for one concrete worker contribution inside a tenant-owned shared runtime. Reserved for tenant-shared worker topology; not fully implemented yet. properties: id: type: string format: uuid shared_runtime_id: type: string format: uuid org_id: type: string format: uuid source_project_id: type: string format: uuid nullable: true attachment_id: type: string format: uuid nullable: true component_key: type: string contribution_mode: type: string enum: - tenant_owned - project_contributed allocation_id: type: string format: uuid bound_node_id: type: string format: uuid nullable: true status: type: string enum: - requested - provisioning - ready - draining - removed - failed runtime_state: type: object additionalProperties: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - shared_runtime_id - org_id - contribution_mode - allocation_id - status - created_at - updated_at ReportSharedAppRuntimeWorkerRequest: type: object additionalProperties: false properties: status: type: string enum: - requested - provisioning - ready - draining - removed - failed bound_node_id: type: string format: uuid nullable: true runtime_state: type: object additionalProperties: true required: - status SharedAppRuntimeWorkerListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/SharedAppRuntimeWorker" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination CreateSharedAppRuntimeWorkerOperationRequest: type: object additionalProperties: false description: | Additive contract direction for requesting tenant-shared worker changes. Reserved for shared-runtime worker contribution flow; not fully implemented yet. properties: action: type: string enum: - add - drain - remove attachment_id: type: string format: uuid nullable: true source_project_id: type: string format: uuid nullable: true requested_allocation_ids: type: array items: type: string format: uuid required: - action SharedAppRuntimeWorkerOperation: type: object additionalProperties: false description: | One worker lifecycle request against a tenant-owned shared runtime. External app workers consume these operations through the polling-compatible runtime contract and report progress through the operation report endpoint. properties: id: type: string format: uuid shared_runtime_id: type: string format: uuid org_id: type: string format: uuid action: type: string enum: - add - drain - remove attachment_id: type: string format: uuid nullable: true source_project_id: type: string format: uuid nullable: true requested_allocation_ids: type: array items: type: string format: uuid status: type: string enum: - accepted - in_progress - succeeded - failed - cancelled correlation_id: type: string requested_by_user_id: type: string format: uuid nullable: true last_error_code: type: string nullable: true last_error_message: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time started_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true required: - id - shared_runtime_id - org_id - action - status - correlation_id - created_at - updated_at SharedAppRuntimeWorkerResult: type: object additionalProperties: false properties: allocation_id: type: string format: uuid bound_node_id: type: string format: uuid nullable: true status: type: string enum: - requested - provisioning - ready - draining - removed - failed runtime_state: type: object additionalProperties: true required: - allocation_id - status ReportSharedAppRuntimeWorkerOperationRequest: type: object additionalProperties: false properties: status: type: string enum: - in_progress - succeeded - failed - cancelled last_error_code: type: string nullable: true last_error_message: type: string nullable: true workers: type: array items: "$ref": "#/components/schemas/SharedAppRuntimeWorkerResult" required: - status SharedAppRuntimeWorkerOperationListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperation" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination ReportAppInstanceRequest: type: object additionalProperties: false properties: status: type: string enum: - deploying - running - failed - decommissioning - decommissioned - deleting - deleted failure_reason: type: string nullable: true runtime_state: type: object additionalProperties: true phase: type: string nullable: true progress: type: object additionalProperties: true health_status: type: string nullable: true health_detail: type: object additionalProperties: true required: - status ReconcileAppInstanceBootstrapSshTrustRequest: type: object additionalProperties: false properties: access_credential_id: type: string format: uuid nullable: true allocation_id: type: string format: uuid username_on_node: type: string public_key: type: string nullable: true desired_state: type: string enum: - present - absent required: - allocation_id - username_on_node - desired_state AppInstanceBootstrapSshTrustState: type: object additionalProperties: false properties: app_instance_id: type: string format: uuid allocation_id: type: string format: uuid username_on_node: type: string access_credential_id: type: string format: uuid nullable: true managed_key_id: type: string description: Stable node-side GPUaaS managed-key marker. App bootstrap SSH reconcile uses the bound access credential ID when present, so repeat deploys with the same credential update one authorized_keys block; app-instance scoped markers are retained only as a legacy fallback. desired_state: type: string enum: - present - absent status: type: string enum: - sync_requested public_key_fingerprint: type: string nullable: true node_task_type: type: string correlation_id: type: string last_reconciled_at: type: string format: date-time required: - app_instance_id - allocation_id - username_on_node - managed_key_id - desired_state - status - node_task_type - correlation_id - last_reconciled_at ReportSharedAppRuntimeRequest: type: object additionalProperties: false properties: status: type: string enum: - deploying - running - failed - deleting - deleted failure_reason: type: string nullable: true runtime_state: type: object additionalProperties: true required: - status ReportSharedAppRuntimeAttachmentRequest: type: object additionalProperties: false properties: status: type: string enum: - attached - failed - detaching - detached runtime_state: type: object additionalProperties: true required: - status IssueAppInstanceRuntimeSecretRequest: type: object additionalProperties: false properties: purpose: type: string enum: - artifact_pull required: - purpose AppInstanceRuntimeSecretBundle: type: object additionalProperties: false properties: app_instance_id: type: string format: uuid project_id: type: string format: uuid app_artifact_id: type: string format: uuid app_slug: type: string pattern: "^[a-z0-9][a-z0-9-]{1,62}$" app_version: type: string artifact_kind: type: string enum: - oci - blob source_type: type: string enum: - oci_registry - s3 - gcs - azure_blob - https - huggingface - artifact_store repository: type: string source_uri: type: string nullable: true digest: type: string pattern: "^sha256:[a-f0-9]{64}$" digest_algorithm: type: string enum: - sha256 runtime_backend: type: string purpose: type: string enum: - artifact_pull delivery_mode: type: string enum: - vault_wrapped_token wrapped_token: type: string minLength: 1 unwrap_url: type: string nullable: true expires_at: type: string format: date-time nullable: true required: - app_instance_id - project_id - app_artifact_id - app_slug - app_version - artifact_kind - source_type - repository - digest - digest_algorithm - runtime_backend - purpose - delivery_mode - wrapped_token AppInstanceAccessBundle: type: object additionalProperties: false properties: app_instance_id: type: string format: uuid project_id: type: string format: uuid runtime_backend: type: string access_kind: type: string enum: - kubeconfig - openai_compatible_http status: type: string enum: - available - pending - unavailable cluster_name: type: string nullable: true server_endpoint: type: string nullable: true kubeconfig: type: string nullable: true headlamp_token: type: string nullable: true description: Kubernetes bearer token accepted by the managed Headlamp console. detail: type: string nullable: true generated_at: type: string format: date-time nullable: true expires_at: type: string format: date-time nullable: true required: - app_instance_id - project_id - runtime_backend - access_kind - status UpgradeAppInstanceRequest: type: object additionalProperties: false properties: app_version: type: string minLength: 1 required: - app_version RollbackAppInstanceRequest: type: object additionalProperties: false properties: app_version: type: string minLength: 1 required: - app_version AppInstanceListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AppInstance" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination AppInstanceMember: type: object additionalProperties: false properties: id: type: string format: uuid app_instance_id: type: string format: uuid component_key: type: string minLength: 1 description: Stable adapter-supplied component identifier. Runtime meaning remains adapter-owned. member_role: type: string nullable: true description: Normalized runtime role when the adapter exposes one, for example controller or worker. status: type: string enum: - requested - reconciling - ready - draining - deleting - failed - deleted description: Generic platform member status. Runtime-specific interpretation remains adapter-owned. bound_node_id: type: string format: uuid nullable: true bound_node_resource_name: type: string nullable: true bound_allocation_id: type: string format: uuid nullable: true runtime_state: type: object additionalProperties: true nullable: true description: Normalized member runtime state. Legacy adapter detail is lifted into this field when possible. health_status: type: string nullable: true health_detail: type: object additionalProperties: true nullable: true endpoint: type: object additionalProperties: true nullable: true description: Adapter-reported or derived endpoint details for workload member connectivity. last_operation_id: type: string format: uuid nullable: true last_correlation_id: type: string nullable: true adapter_detail: type: object additionalProperties: true nullable: true description: Adapter-owned runtime detail surfaced through a generic envelope. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - app_instance_id - component_key - status - created_at - updated_at AppInstanceMemberListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AppInstanceMember" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination AppInstanceMemberOperationListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AppInstanceMemberOperation" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination CreateAppInstanceMemberOperationRequest: type: object additionalProperties: false properties: action: type: string enum: - add - drain - remove - replace component_key: type: string minLength: 1 nullable: true description: Generic adapter-supplied component identifier. Required for `add`. target_member_id: type: string format: uuid nullable: true description: Target member for `drain`, `remove`, or `replace`. requested_count: type: integer minimum: 1 nullable: true description: Requested member count delta for `add`. allocation_intent: type: object additionalProperties: true nullable: true description: Opaque app-level capacity intent. This is not a raw node-placement contract. required: - action AppInstanceMemberOperation: type: object additionalProperties: false properties: id: type: string format: uuid app_instance_id: type: string format: uuid action: type: string enum: - add - drain - remove - replace component_key: type: string nullable: true target_member_id: type: string format: uuid nullable: true requested_count: type: integer minimum: 1 nullable: true allocation_intent: type: object additionalProperties: true nullable: true description: Opaque app-level capacity intent echoed back through the operation read model. status: type: string enum: - accepted - in_progress - succeeded - failed - cancelled correlation_id: type: string requested_by_user_id: type: string format: uuid nullable: true requested_by_service_account_id: type: string format: uuid nullable: true last_error_code: type: string nullable: true last_error_message: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time started_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true required: - id - app_instance_id - action - status - correlation_id - created_at - updated_at ReportAppInstanceMemberOperationRequest: type: object additionalProperties: false properties: status: type: string enum: - in_progress - succeeded - failed - cancelled target_member_id: type: string format: uuid nullable: true description: Optional target member binding when the operation was accepted without a concrete target id. For `add` and `replace`, adapters may report a new member id here and the platform will materialize the generic member row through this report flow. member_status: type: string enum: - requested - reconciling - ready - draining - deleting - failed - deleted nullable: true bound_node_id: type: string format: uuid nullable: true bound_allocation_id: type: string format: uuid nullable: true member_role: type: string nullable: true runtime_state: type: object additionalProperties: true nullable: true health_status: type: string nullable: true health_detail: type: object additionalProperties: true nullable: true endpoint: type: object additionalProperties: true nullable: true adapter_detail: type: object additionalProperties: true nullable: true description: Adapter-owned runtime detail surfaced through the generic platform envelope. last_error_code: type: string nullable: true last_error_message: type: string nullable: true required: - status AppInstanceRepairAction: type: string enum: - reconcile - repair description: Reconcile is drift correction without destructive restart when possible. Repair may restart/reinstall runtime services for the targeted scope when the runtime contract declares it safe. AppInstanceRepairScope: type: string enum: - whole_runtime - control_plane - member description: Target scope for app-runtime repair. RKE2 maps control_plane to the server member and member to one server or agent member. AppInstanceRepairOperationStatus: type: string enum: - accepted - in_progress - succeeded - failed - cancelled AppInstanceRepairStep: type: object additionalProperties: false properties: name: type: string minLength: 1 status: type: string enum: - pending - running - succeeded - failed - skipped started_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true summary: type: string nullable: true required: - name - status - started_at - completed_at - summary CreateAppInstanceRepairRequest: type: object additionalProperties: false properties: action: "$ref": "#/components/schemas/AppInstanceRepairAction" scope: "$ref": "#/components/schemas/AppInstanceRepairScope" target_member_id: type: string format: uuid nullable: true description: Required when scope is member. component_key: type: string nullable: true description: Optional adapter component key such as server or agent, useful for scoped repair requests before a target member is selected. reason: type: string nullable: true maxLength: 500 dry_run: type: boolean default: false description: When true, validates and returns the planned operation without mutating runtime state. required: - action - scope AppInstanceRepairOperation: type: object additionalProperties: false properties: id: type: string format: uuid app_instance_id: type: string format: uuid action: "$ref": "#/components/schemas/AppInstanceRepairAction" scope: "$ref": "#/components/schemas/AppInstanceRepairScope" target_member_id: type: string format: uuid nullable: true component_key: type: string nullable: true status: "$ref": "#/components/schemas/AppInstanceRepairOperationStatus" phase: type: string nullable: true description: Adapter-owned phase label for progress display. progress: type: object additionalProperties: true nullable: true steps: type: array items: "$ref": "#/components/schemas/AppInstanceRepairStep" correlation_id: type: string requested_by_user_id: type: string format: uuid nullable: true requested_by_service_account_id: type: string format: uuid nullable: true last_error_code: type: string nullable: true last_error_message: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time started_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true required: - id - app_instance_id - action - scope - status - steps - correlation_id - created_at - updated_at AppInstanceRepairOperationListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AppInstanceRepairOperation" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination ReportAppInstanceRepairOperationRequest: type: object additionalProperties: false properties: status: "$ref": "#/components/schemas/AppInstanceRepairOperationStatus" phase: type: string nullable: true progress: type: object additionalProperties: true nullable: true steps: type: array items: "$ref": "#/components/schemas/AppInstanceRepairStep" runtime_state: type: object additionalProperties: true nullable: true health_status: type: string nullable: true health_detail: type: object additionalProperties: true nullable: true last_error_code: type: string nullable: true last_error_message: type: string nullable: true required: - status ReportAppInstanceMemberRequest: type: object additionalProperties: false properties: status: type: string enum: - requested - reconciling - ready - draining - deleting - failed - deleted bound_node_id: type: string format: uuid nullable: true bound_allocation_id: type: string format: uuid nullable: true member_role: type: string nullable: true runtime_state: type: object additionalProperties: true nullable: true health_status: type: string nullable: true health_detail: type: object additionalProperties: true nullable: true endpoint: type: object additionalProperties: true nullable: true adapter_detail: type: object additionalProperties: true nullable: true description: Adapter-owned runtime detail surfaced through the generic platform envelope. required: - status OciRegistryInfo: type: object additionalProperties: false properties: registry_host: type: string registry_api_base_url: type: string format: uri namespace_mode: type: string enum: - platform - tenant - project digest_required: type: boolean project_private_repositories_enabled: type: boolean publish_intent_ttl_seconds: type: integer minimum: 1 required: - registry_host - registry_api_base_url - namespace_mode - digest_required - project_private_repositories_enabled - publish_intent_ttl_seconds PlatformReleaseArtifact: type: object additionalProperties: false properties: artifact_id: type: string enum: - cli-linux-amd64 - cli-darwin-arm64 - cli-darwin-amd64 - go-sdk - python-sdk - node-agent - node-agent-bootstrap display_name: type: string minLength: 1 description: type: string minLength: 1 audience: type: string enum: - developer - operator platforms: type: array items: type: string minLength: 1 version: type: string minLength: 1 file_name: type: string minLength: 1 oci_ref: type: string nullable: true digest: type: string nullable: true tag: type: string nullable: true artifact_type: type: string nullable: true download_url: type: string minLength: 1 required: - artifact_id - display_name - description - audience - platforms - version - file_name - download_url ArtifactPullIntent: type: object additionalProperties: false description: Short-lived registry pull intent. Credential material is Vault-wrapped and must not be cached or persisted by clients. properties: artifact_scope: type: string enum: - platform_release - app_artifact artifact_id: type: string minLength: 1 project_id: type: string format: uuid nullable: true version: type: string nullable: true app_slug: type: string nullable: true app_version: type: string nullable: true artifact_kind: type: string nullable: true enum: - oci - blob source_type: type: string enum: - oci_registry registry_host: type: string minLength: 1 registry_api_base_url: type: string minLength: 1 repository: type: string minLength: 1 oci_ref: type: string minLength: 1 digest: type: string minLength: 1 tag: type: string nullable: true credential_delivery_mode: type: string enum: - vault_wrapped_token credential_wrapped_token: type: string minLength: 1 credential_unwrap_url: type: string format: uri nullable: true credential_expires_at: type: string format: date-time required: - artifact_scope - artifact_id - registry_host - registry_api_base_url - repository - oci_ref - digest - credential_delivery_mode - credential_wrapped_token - credential_expires_at PlatformRelease: type: object additionalProperties: false properties: version: type: string minLength: 1 artifacts: type: array items: "$ref": "#/components/schemas/PlatformReleaseArtifact" required: - version - artifacts PlatformReleaseListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/PlatformRelease" required: - items PlatformDevCA: type: object additionalProperties: false properties: display_name: type: string minLength: 1 description: type: string minLength: 1 file_name: type: string minLength: 1 fingerprint_sha256: type: string minLength: 1 format: type: string enum: - pem download_url: type: string minLength: 1 required: - display_name - description - file_name - fingerprint_sha256 - format - download_url AppArtifact: type: object additionalProperties: false properties: id: type: string format: uuid project_id: type: string format: uuid app_slug: type: string pattern: "^[a-z0-9][a-z0-9-]{1,62}$" app_version: type: string artifact_name: type: string minLength: 1 artifact_kind: type: string enum: - oci - blob source_type: type: string enum: - oci_registry - s3 - gcs - azure_blob - https - huggingface - artifact_store publish_intent_id: type: string format: uuid nullable: true repository: type: string minLength: 1 source_uri: type: string minLength: 1 nullable: true digest: type: string pattern: "^sha256:[a-f0-9]{64}$" digest_algorithm: type: string enum: - sha256 tag: type: string nullable: true media_type: type: string minLength: 1 platform_os: type: string enum: - linux platform_arch: type: string enum: - amd64 - arm64 platform_variant: type: string nullable: true lifecycle_state: type: string enum: - published - promoted - deprecated - retired trust_state: type: string enum: - unverified - verified - failed_verification - revoked verification_method: type: string nullable: true verification_key_id: type: string nullable: true provenance_digest: type: string pattern: "^sha256:[a-f0-9]{64}$" nullable: true size_bytes: type: integer format: int64 minimum: 0 nullable: true verified_at: type: string format: date-time nullable: true promoted_channel: type: string nullable: true target_environment: type: string nullable: true requested_by_user_id: type: string format: uuid nullable: true registered_by_service_account_id: type: string format: uuid nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - project_id - app_slug - app_version - artifact_name - artifact_kind - source_type - repository - digest - digest_algorithm - media_type - platform_os - platform_arch - lifecycle_state - trust_state - created_at - updated_at AppArtifactListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AppArtifact" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination CreateAppArtifactPublishIntentRequest: type: object additionalProperties: false properties: app_slug: type: string pattern: "^[a-z0-9][a-z0-9-]{1,62}$" app_version: type: string minLength: 1 artifact_name: type: string minLength: 1 artifact_kind: type: string enum: - oci - blob source_type: type: string enum: - oci_registry - s3 - gcs - azure_blob - https - huggingface - artifact_store channel: type: string minLength: 1 nullable: true platform_os: type: string enum: - linux platform_arch: type: string enum: - amd64 - arm64 platform_variant: type: string nullable: true required: - app_slug - app_version - artifact_name - artifact_kind - source_type - platform_os - platform_arch AppArtifactPublishIntent: type: object additionalProperties: false properties: intent_id: type: string format: uuid project_id: type: string format: uuid app_slug: type: string pattern: "^[a-z0-9][a-z0-9-]{1,62}$" app_version: type: string artifact_name: type: string artifact_kind: type: string enum: - oci - blob source_type: type: string enum: - oci_registry - s3 - gcs - azure_blob - https - huggingface - artifact_store repository: type: string source_uri: type: string nullable: true upload_path: type: string nullable: true upload_method: type: string enum: - oci_push - blob_upload - external_register tag: type: string nullable: true platform_os: type: string enum: - linux platform_arch: type: string enum: - amd64 - arm64 platform_variant: type: string nullable: true digest_required: type: boolean signature_required: type: boolean signature_scheme: type: string nullable: true signing_key_id: type: string nullable: true provenance_required: type: boolean credential_delivery_mode: type: string nullable: true enum: - vault_wrapped_token credential_wrapped_token: type: string nullable: true credential_unwrap_url: type: string format: uri nullable: true credential_expires_at: type: string format: date-time nullable: true expires_at: type: string format: date-time required: - intent_id - project_id - app_slug - app_version - artifact_name - artifact_kind - source_type - repository - upload_method - platform_os - platform_arch - digest_required - signature_required - provenance_required - expires_at RegisterAppArtifactRequest: type: object additionalProperties: false properties: app_slug: type: string pattern: "^[a-z0-9][a-z0-9-]{1,62}$" app_version: type: string minLength: 1 artifact_name: type: string minLength: 1 artifact_kind: type: string enum: - oci - blob source_type: type: string enum: - oci_registry - s3 - gcs - azure_blob - https - huggingface - artifact_store publish_intent_id: type: string format: uuid nullable: true repository: type: string minLength: 1 source_uri: type: string minLength: 1 nullable: true digest: type: string pattern: "^sha256:[a-f0-9]{64}$" digest_algorithm: type: string enum: - sha256 tag: type: string nullable: true media_type: type: string minLength: 1 platform_os: type: string enum: - linux platform_arch: type: string enum: - amd64 - arm64 platform_variant: type: string nullable: true required: - app_slug - app_version - artifact_name - artifact_kind - source_type - repository - digest - digest_algorithm - media_type - platform_os - platform_arch PromoteAppArtifactRequest: type: object additionalProperties: false properties: channel: type: string minLength: 1 target_environment: type: string minLength: 1 nullable: true required: - channel V3ComputeLaunchSubmitRequest: type: object additionalProperties: false properties: name: type: string maxLength: 120 nullable: true sku: type: string minLength: 1 resource_class: "$ref": "#/components/schemas/V3ComputeResourceClass" unit_count: type: integer minimum: 1 nullable: true os_image_slug: type: string nullable: true region_code: type: string nullable: true scheduler_type: type: string enum: - bare_metal - slurm - k8s - ray nullable: true ssh_key_ids: type: array items: type: string format: uuid storage_bucket_ids: type: array items: type: string network_policy_id: type: string nullable: true scheduler_request: type: object additionalProperties: true required: - sku V3AppLaunchSubmitRequest: type: object additionalProperties: false properties: app_version: type: string nullable: true display_name: type: string minLength: 1 nullable: true placement_intent: "$ref": "#/components/schemas/AppInstancePlacementIntent" nullable: true operator_service_account_id: type: string format: uuid nullable: true dependencies: type: object additionalProperties: true config: type: object additionalProperties: true resource_overrides: type: object additionalProperties: true V3LaunchSubmitResponse: type: object additionalProperties: false properties: task_id: type: string format: uuid task_href: type: string workload_id: type: string workload_href: type: string resource_kind: "$ref": "#/components/schemas/V3TaskResourceKind" status: "$ref": "#/components/schemas/V3TaskStatus" message: type: string required: - task_id - task_href - workload_id - workload_href - resource_kind - status - message V3PlatformSeverity: type: string enum: - ok - info - warn - error V3PlatformKPI: type: object additionalProperties: false properties: key: type: string label: type: string value: type: string summary: type: string nullable: true severity: type: string enum: - ok - info - warn - error - blocker required: - key - label - value - summary - severity V3PlatformActionItem: type: object additionalProperties: false properties: severity: "$ref": "#/components/schemas/V3PlatformSeverity" code: type: string title: type: string summary: type: string primary_action_label: type: string nullable: true primary_action_href: type: string nullable: true runbook_href: type: string nullable: true signal_key: type: string description: Backend-owned stable key for acknowledgement/suppression mutations. target_type: type: string target_id: type: string nullable: true ack_fingerprint: type: string description: Opaque backend fingerprint used to resurface changed failures. ack_state: "$ref": "#/components/schemas/V3PlatformAckState" ack_reason: type: string nullable: true ack_expires_at: type: string format: date-time nullable: true ack_actor: type: string nullable: true ack_updated_at: type: string format: date-time nullable: true required: - severity - code - title - summary - primary_action_label - primary_action_href - runbook_href - signal_key - target_type - target_id - ack_fingerprint - ack_state - ack_reason - ack_expires_at - ack_actor - ack_updated_at V3PlatformAckState: type: string enum: - none - acknowledged - suppressed - expired - resurfaced V3PlatformSignalAcknowledgeRequest: type: object additionalProperties: false properties: ack_fingerprint: type: string minLength: 1 maxLength: 512 reason: type: string nullable: true maxLength: 500 expires_at: type: string format: date-time nullable: true scope: type: string enum: - item default: item required: - ack_fingerprint V3PlatformSignalSuppressRequest: type: object additionalProperties: false properties: ack_fingerprint: type: string minLength: 1 maxLength: 512 reason: type: string minLength: 1 maxLength: 500 expires_at: type: string format: date-time scope: type: string enum: - item default: item required: - ack_fingerprint - reason - expires_at V3PlatformSignalClearRequest: type: object additionalProperties: false properties: reason: type: string nullable: true maxLength: 500 V3PlatformSignalAckResponse: type: object additionalProperties: false properties: signal_key: type: string target_type: type: string target_id: type: string nullable: true ack_fingerprint: type: string ack_state: "$ref": "#/components/schemas/V3PlatformAckState" ack_reason: type: string nullable: true ack_expires_at: type: string format: date-time nullable: true ack_actor: type: string nullable: true ack_updated_at: type: string format: date-time nullable: true meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - signal_key - target_type - target_id - ack_fingerprint - ack_state - ack_reason - ack_expires_at - ack_actor - ack_updated_at - meta V3PlatformFamilyCard: type: object additionalProperties: false properties: key: type: string enum: - ops - lifecycle - config - evidence - finance - iam title: type: string summary: type: string href: type: string severity: "$ref": "#/components/schemas/V3PlatformSeverity" metric: type: string nullable: true bullets: type: array items: type: string required: - key - title - summary - href - severity - metric - bullets V3PlatformWorkflowCard: type: object additionalProperties: false properties: key: type: string title: type: string summary: type: string href: type: string severity: "$ref": "#/components/schemas/V3PlatformSeverity" metric: type: string nullable: true bullets: type: array items: type: string primary_action_label: type: string nullable: true owner_domain: type: string nullable: true review_required: type: boolean description: True when this workflow card represents an open operator attention item. review_state: "$ref": "#/components/schemas/V3ProvisioningReviewState" reviewed_at: type: string format: date-time nullable: true reviewed_by: type: string nullable: true review_note: type: string nullable: true attention_reason: type: string nullable: true next_action: type: string nullable: true superseded_by_workflow_id: type: string nullable: true required: - key - title - summary - href - severity - metric - bullets - primary_action_label - owner_domain - review_required - review_state - reviewed_at - reviewed_by - review_note - attention_reason - next_action - superseded_by_workflow_id V3PlatformProxyAction: type: object additionalProperties: false description: Governed platform tool launch action for operator tools. The web client opens host-based tool routes directly, but must not put auth material in query strings. properties: key: type: string title: type: string purpose: type: string path: type: string verify_strategy: type: string enum: - none - html_only - html_plus_asset swagger_auth: type: boolean required_capability: "$ref": "#/components/schemas/PlatformCapability" permission_label: type: string evidence_href: type: string runbook_href: type: string configured: type: boolean disabled_reason: type: string nullable: true required: - key - title - purpose - path - verify_strategy - swagger_auth - required_capability - permission_label - evidence_href - runbook_href - configured - disabled_reason V3ProvisioningReviewState: type: string enum: - open - taken_care_of - ignored - superseded V3ProvisioningAttentionReviewDecision: type: string enum: - taken_care_of - ignored V3ProvisioningAttentionReviewRequest: type: object additionalProperties: false properties: review_state: "$ref": "#/components/schemas/V3ProvisioningAttentionReviewDecision" review_note: type: string minLength: 1 maxLength: 500 required: - review_state - review_note V3ProvisioningAttentionReviewResponse: type: object additionalProperties: false properties: attention_key: type: string target_type: type: string target_id: type: string workflow_id: type: string nullable: true review_state: "$ref": "#/components/schemas/V3ProvisioningReviewState" reviewed_at: type: string format: date-time reviewed_by: type: string review_note: type: string required: - attention_key - target_type - target_id - workflow_id - review_state - reviewed_at - reviewed_by - review_note V3PlatformHealthItem: type: object additionalProperties: false properties: key: type: string label: type: string status: "$ref": "#/components/schemas/V3PlatformSeverity" detail: type: string nullable: true required: - key - label - status - detail V3PlatformNodeRow: type: object additionalProperties: false properties: id: type: string format: uuid hostname: type: string nullable: true sku: type: string status: type: string occupancy: type: string placement: "$ref": "#/components/schemas/V3PlatformNodePlacementSummary" placement_impact: "$ref": "#/components/schemas/V3PlatformNodePlacementImpact" heartbeat: "$ref": "#/components/schemas/V3PlatformNodeHeartbeatSummary" readiness: "$ref": "#/components/schemas/V3PlatformNodeReadiness" network: "$ref": "#/components/schemas/V3PlatformNodeNetworkSummary" image: "$ref": "#/components/schemas/V3PlatformNodeImageSummary" latest_operation: "$ref": "#/components/schemas/V3PlatformNodeLatestOperation" schedulability: "$ref": "#/components/schemas/V3PlatformNodeSchedulability" agent_version: type: string nullable: true reported_at: type: string format: date-time nullable: true open_href: type: string required: - id - hostname - sku - status - occupancy - placement - placement_impact - heartbeat - readiness - network - image - latest_operation - schedulability - agent_version - reported_at - open_href V3PlatformNodePlacementSummary: type: object additionalProperties: false properties: region_code: type: string site_id: type: string format: uuid nullable: true site_name: type: string nullable: true rack: type: string nullable: true placement_domain: type: string required: - region_code - site_id - site_name - rack - placement_domain V3PlatformNodePlacementImpact: type: object additionalProperties: false properties: active_allocations: type: integer active_slices: type: integer project_count: type: integer tenant_count: type: integer primary_tenant_name: type: string nullable: true primary_project_name: type: string nullable: true primary_owner_username: type: string nullable: true maintenance_summary: type: string contact_hint: type: string required: - active_allocations - active_slices - project_count - tenant_count - primary_tenant_name - primary_project_name - primary_owner_username - maintenance_summary - contact_hint V3PlatformNodeHeartbeatSummary: type: object additionalProperties: false properties: reported_at: type: string format: date-time nullable: true age_seconds: type: integer nullable: true severity: "$ref": "#/components/schemas/V3PlatformSeverity" summary: type: string required: - reported_at - age_seconds - severity - summary V3PlatformNodeReadiness: type: object additionalProperties: false properties: state: type: string schedulable: type: boolean severity: "$ref": "#/components/schemas/V3PlatformSeverity" reason_code: type: string summary: type: string required: - state - schedulable - severity - reason_code - summary V3PlatformNodeNetworkSummary: type: object additionalProperties: false properties: host: type: string primary_ip: type: string nullable: true management_ip: type: string nullable: true maas_ip: type: string nullable: true source: type: string enum: - slot - maas_management - maas - host - unknown required: - host - primary_ip - management_ip - maas_ip - source V3PlatformNodeImageSummary: type: object additionalProperties: false properties: os_image_slug: type: string nullable: true os_image_display_name: type: string nullable: true driver_strategy: type: string nullable: true driver_version: type: string nullable: true cuda_version: type: string nullable: true kernel_version: type: string nullable: true fabric_profile: type: string nullable: true image_status: type: string nullable: true verified_at: type: string format: date-time nullable: true required: - os_image_slug - os_image_display_name - driver_strategy - driver_version - cuda_version - kernel_version - fabric_profile - image_status - verified_at V3PlatformNodeLatestOperation: type: object additionalProperties: false properties: operation: type: string nullable: true status: type: string nullable: true summary: type: string occurred_at: type: string format: date-time nullable: true correlation_id: type: string nullable: true task_href: type: string nullable: true evidence_href: type: string nullable: true required: - operation - status - summary - occurred_at - correlation_id - task_href - evidence_href V3PlatformNodeSchedulability: type: object additionalProperties: false properties: state: type: string enum: - schedulable - cordoned - draining - offline - retired - blocked can_cordon: type: boolean can_drain: type: boolean can_resume_scheduling: type: boolean next_safe_action: type: string disabled_reason: type: string nullable: true required: - state - can_cordon - can_drain - can_resume_scheduling - next_safe_action - disabled_reason V3PlatformNodeFact: type: object additionalProperties: false properties: key: type: string label: type: string value: type: string severity: "$ref": "#/components/schemas/V3PlatformSeverity" required: - key - label - value - severity V3PlatformNodeRecoveryStatus: type: object additionalProperties: false properties: reason_code: type: string enum: - healthy - agent_down - cert_expired - cert_untrusted_by_ingress - endpoint_profile_drift - task_backlog_stale - lifecycle_recovery_required - identity_revoked_or_fenced action: type: string enum: - none - repair_node_agent - repair_certs - reenroll_node - expire_or_retry_tasks - investigate_lifecycle - reactivate_or_reenroll severity: "$ref": "#/components/schemas/V3PlatformSeverity" summary: type: string stale_task_count: type: integer format: int64 required: - reason_code - action - severity - summary - stale_task_count V3PlatformNodeAgent: type: object additionalProperties: false properties: version: type: string nullable: true commit: type: string nullable: true built_at: type: string nullable: true reported_at: type: string format: date-time nullable: true lifecycle_status: type: string nullable: true desired_agent_version: type: string nullable: true reported_agent_version: type: string nullable: true error_code: type: string nullable: true error_message: type: string nullable: true recovery_status: "$ref": "#/components/schemas/V3PlatformNodeRecoveryStatus" required: - version - commit - built_at - reported_at - lifecycle_status - desired_agent_version - reported_agent_version - error_code - error_message - recovery_status V3PlatformNodeMAAS: type: object additionalProperties: false properties: site_id: type: string format: uuid nullable: true maas_system_id: type: string nullable: true last_maas_status: type: string nullable: true last_maas_power_state: type: string nullable: true last_maas_ips: type: array items: type: string drift_detected: type: boolean last_reconciled_at: type: string format: date-time nullable: true required: - site_id - maas_system_id - last_maas_status - last_maas_power_state - last_maas_ips - drift_detected - last_reconciled_at V3PlatformNodeAllocation: type: object additionalProperties: false properties: id: type: string format: uuid status: type: string capacity_shape: type: string sku: type: string requested_by_user_id: type: string format: uuid requested_by_username: type: string nullable: true tenant_name: type: string nullable: true project_name: type: string nullable: true active_at: type: string format: date-time nullable: true created_at: type: string format: date-time open_href: type: string required: - id - status - capacity_shape - sku - requested_by_user_id - requested_by_username - tenant_name - project_name - active_at - created_at - open_href V3PlatformNodeSlot: type: object additionalProperties: false properties: slot_index: type: integer status: type: string profile_name: type: string nullable: true accelerator_model: type: string nullable: true gpu_index: type: integer nullable: true gpu_uuid: type: string nullable: true private_ip: type: string nullable: true health_state: type: string required: - slot_index - status - profile_name - accelerator_model - gpu_index - gpu_uuid - private_ip - health_state V3PlatformNodeTask: type: object additionalProperties: false properties: id: type: string format: uuid task_type: type: string status: type: string issued_at: type: string format: date-time completed_at: type: string format: date-time nullable: true error: type: string nullable: true correlation_id: type: string required: - id - task_type - status - issued_at - completed_at - error - correlation_id V3PlatformNodeRuntimeCleanup: type: object additionalProperties: false description: API-first runtime cleanup/readiness read model for app workloads hosted by a platform node. Operators should use this surface before app launch UAT instead of direct docker, LXD, kubectl, or SQL inspection. properties: node_id: type: string format: uuid stale_containers: type: array items: "$ref": "#/components/schemas/V3PlatformNodeRuntimeCleanupContainer" port_bindings: type: array items: "$ref": "#/components/schemas/V3PlatformNodeRuntimePortBinding" approved_runtime_hints: type: array items: type: string registry_trust_status: type: string enum: - trusted - untrusted - unknown - not_reported cleanup_blocked: type: boolean cleanup_blockers: type: array items: "$ref": "#/components/schemas/V3PlatformNodeRuntimeCleanupBlocker" required: - node_id - stale_containers - port_bindings - approved_runtime_hints - registry_trust_status - cleanup_blocked - cleanup_blockers V3PlatformNodeRuntimeCleanupContainer: type: object additionalProperties: false properties: app_instance_id: type: string format: uuid app_slug: type: string container_name: type: string nullable: true image_ref: type: string nullable: true status: type: string adapter_phase: type: string nullable: true reason: type: string required: - app_instance_id - app_slug - container_name - image_ref - status - adapter_phase - reason V3PlatformNodeRuntimePortBinding: type: object additionalProperties: false properties: app_instance_id: type: string format: uuid app_slug: type: string endpoint_name: type: string protocol: type: string host_port: type: integer nullable: true container_port: type: integer nullable: true status: type: string required: - app_instance_id - app_slug - endpoint_name - protocol - host_port - container_port - status V3PlatformNodeRuntimeCleanupBlocker: type: object additionalProperties: false properties: app_instance_id: type: string format: uuid app_slug: type: string status: type: string adapter_phase: type: string nullable: true reason: type: string evidence_href: type: string required: - app_instance_id - app_slug - status - adapter_phase - reason - evidence_href V3PlatformNodeActivityItem: type: object additionalProperties: false description: First-class lifecycle/activity row for a platform node. The UI must prefer this over deriving activity from unrelated sections. properties: id: type: string occurred_at: type: string format: date-time nullable: true source: type: string enum: - allocation - node_task - agent_lifecycle - maas_decommission - audit - fact action: type: string status: type: string severity: "$ref": "#/components/schemas/V3PlatformSeverity" summary: type: string actor: type: string nullable: true correlation_id: type: string nullable: true href: type: string nullable: true required: - id - occurred_at - source - action - status - severity - summary - actor - correlation_id - href V3PlatformNodeCapability: type: object additionalProperties: false description: Operation capability advertised by the node lifecycle read model. properties: key: type: string label: type: string available: type: boolean severity: "$ref": "#/components/schemas/V3PlatformSeverity" summary: type: string href: type: string nullable: true required: - key - label - available - severity - summary - href V3PlatformNodeOperationIntentGroup: type: object additionalProperties: false description: Intent group for node lifecycle operations. properties: key: type: string enum: - inspect - repair - scheduling - provisioning - retirement - destructive label: type: string description: type: string required: - key - label - description V3PlatformNodeOperation: type: object additionalProperties: false description: Server-derived operation affordance for node lifecycle recovery and maintenance. properties: key: type: string group: type: string enum: - inspect - repair - scheduling - provisioning - retirement - destructive label: type: string description: type: string preconditions: type: array items: type: string result: type: string progress_location: type: string failure_path: type: string evidence_href: type: string nullable: true mutation_method: type: string enum: - POST nullable: true mutation_href: type: string nullable: true danger: type: string enum: - safe - low - medium - high - destructive enabled: type: boolean disabled_reason: type: string nullable: true required: - key - group - label - description - preconditions - result - progress_location - failure_path - evidence_href - mutation_method - mutation_href - danger - enabled - disabled_reason V3PlatformNodeLifecycleMutationResponse: type: object additionalProperties: false description: Result envelope for V3 platform node scheduling lifecycle mutations. properties: ok: type: boolean operation: type: string enum: - cordon - drain - resume_scheduling - refresh_inventory node_id: type: string format: uuid previous_status: type: string nullable: true status: type: string task_id: type: string format: uuid nullable: true task_type: type: string nullable: true recovery_action: "$ref": "#/components/schemas/AdminNodeLifecycleRecoveryAction" nullable: true correlation_id: type: string evidence_href: type: string task_href: type: string nullable: true required: - ok - operation - node_id - previous_status - status - task_id - task_type - recovery_action - correlation_id - evidence_href - task_href V3PlatformSetupChecklistStatus: type: string enum: - configured - missing - stale - unsafe V3PlatformSetupChecklistRow: type: object additionalProperties: false properties: key: type: string label: type: string area: type: string enum: - identity_pki - registry_artifacts - fleet_provisioning - runtime_inventory - telemetry - network_security - storage status: "$ref": "#/components/schemas/V3PlatformSetupChecklistStatus" detail: type: string owner: type: string next_action: type: string nullable: true evidence_href: type: string nullable: true config_href: type: string required: - key - label - area - status - detail - owner - next_action - evidence_href - config_href V3PlatformSetupChecklistResponse: type: object additionalProperties: false properties: kpis: type: array items: "$ref": "#/components/schemas/V3PlatformKPI" rows: type: array items: "$ref": "#/components/schemas/V3PlatformSetupChecklistRow" action_queue: type: array items: "$ref": "#/components/schemas/V3PlatformActionItem" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - kpis - rows - action_queue - meta V3PlatformOnboardingMode: type: object additionalProperties: false properties: key: type: string enum: - automated_maas - manual_bootstrap label: type: string description: type: string enabled: type: boolean disabled_reason: type: string nullable: true required: - key - label - description - enabled - disabled_reason V3PlatformOnboardingSite: type: object additionalProperties: false properties: id: type: string format: uuid name: type: string region_code: type: string status: type: string last_probe_ok: type: boolean nullable: true active_onboardings: type: integer format: int64 open_href: type: string required: - id - name - region_code - status - last_probe_ok - active_onboardings - open_href V3PlatformOnboardingProfile: type: object additionalProperties: false properties: id: type: string format: uuid name: type: string site_name: type: string status: type: string is_default: type: boolean distro_series: type: string architecture: type: string fabric_mode: type: string site_bootstrap_bundle_ref: type: string nullable: true commissioning_bundle_ref: type: string nullable: true post_deploy_validation_bundle_ref: type: string nullable: true batch_max_parallel: type: integer required: - id - name - site_name - status - is_default - distro_series - architecture - fabric_mode - site_bootstrap_bundle_ref - commissioning_bundle_ref - post_deploy_validation_bundle_ref - batch_max_parallel V3PlatformOnboardingStep: type: object additionalProperties: false properties: key: type: string label: type: string summary: type: string automated: type: boolean required: - key - label - summary - automated V3PlatformOnboardingAutomation: type: object additionalProperties: false properties: maas_mutation_ready: type: boolean manual_bootstrap_ready: type: boolean bootstrap_token_ttl_seconds: type: integer progress_poll_interval_seconds: type: integer disabled_reason: type: string nullable: true required: - maas_mutation_ready - manual_bootstrap_ready - bootstrap_token_ttl_seconds - progress_poll_interval_seconds - disabled_reason V3PlatformOnboardingGuidanceResponse: type: object additionalProperties: false properties: modes: type: array items: "$ref": "#/components/schemas/V3PlatformOnboardingMode" sites: type: array items: "$ref": "#/components/schemas/V3PlatformOnboardingSite" profiles: type: array items: "$ref": "#/components/schemas/V3PlatformOnboardingProfile" prerequisites: type: array items: "$ref": "#/components/schemas/V3PlatformSetupChecklistRow" steps: type: array items: "$ref": "#/components/schemas/V3PlatformOnboardingStep" automation: "$ref": "#/components/schemas/V3PlatformOnboardingAutomation" manual_command_template: type: string meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - modes - sites - profiles - prerequisites - steps - automation - manual_command_template - meta V3PlatformAuditRow: type: object additionalProperties: false properties: id: type: string occurred_at: type: string format: date-time actor: type: string action: type: string target: type: string result: type: string correlation_id: type: string nullable: true required: - id - occurred_at - actor - action - target - result - correlation_id V3PlatformPaymentSessionRow: type: object additionalProperties: false properties: id: type: string user_id: type: string nullable: true user_label: type: string nullable: true amount_minor: type: integer format: int64 credited_amount_minor: type: integer format: int64 nullable: true currency: type: string status: type: string created_at: type: string format: date-time initiated_at: type: string format: date-time checkout_completed_at: type: string format: date-time nullable: true credited_at: type: string format: date-time nullable: true failed_at: type: string format: date-time nullable: true reason_hint: type: string nullable: true ledger_entry_id: type: string nullable: true correlation_id: type: string nullable: true attention_reason: type: string nullable: true detail_href: type: string diagnostics_href: type: string nullable: true signal_key: type: string description: Backend-owned mutation handle for ack/suppression. Clients must pass it opaquely and never derive it. target_type: type: string target_id: type: string ack_fingerprint: type: string description: Backend-owned fingerprint for resurface detection. Clients must never derive it. ack_state: "$ref": "#/components/schemas/V3PlatformAckState" ack_reason: type: string nullable: true ack_expires_at: type: string format: date-time nullable: true ack_actor: type: string nullable: true ack_updated_at: type: string format: date-time nullable: true required: - id - user_id - amount_minor - currency - status - created_at - reason_hint - correlation_id - signal_key - target_type - target_id - ack_fingerprint - ack_state - ack_reason - ack_expires_at - ack_actor - ack_updated_at V3PlatformUserRoleRow: type: object additionalProperties: false properties: user_id: type: string format: uuid username: type: string org_id: type: string format: uuid nullable: true role: type: string enum: - admin - user primary_role: type: string platform_roles: type: array items: type: string tenant_ids: type: array items: type: string format: uuid project_ids: type: array items: type: string format: uuid tenant_count: type: integer format: int32 project_count: type: integer format: int32 posture: type: string enum: - privileged - missing_tenant - local_password - oidc - standard balance_minor: type: integer format: int64 nullable: true last_activity_at: type: string format: date-time nullable: true created_at: type: string format: date-time required: - user_id - username - org_id - role - primary_role - platform_roles - tenant_ids - project_ids - tenant_count - project_count - posture - balance_minor - last_activity_at - created_at V3PlatformOverviewResponse: type: object additionalProperties: false properties: kpis: type: array items: "$ref": "#/components/schemas/V3PlatformKPI" families: type: array items: "$ref": "#/components/schemas/V3PlatformFamilyCard" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - kpis - families - meta V3PlatformOpsResponse: type: object additionalProperties: false properties: signals: type: array items: "$ref": "#/components/schemas/V3PlatformActionItem" health: type: array items: "$ref": "#/components/schemas/V3PlatformHealthItem" tools: type: array items: "$ref": "#/components/schemas/V3PlatformFamilyCard" workflows: type: array items: "$ref": "#/components/schemas/V3PlatformWorkflowCard" proxy_actions: type: array items: "$ref": "#/components/schemas/V3PlatformProxyAction" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - signals - health - tools - workflows - proxy_actions - meta V3PlatformLifecycleResponse: type: object additionalProperties: false properties: kpis: type: array items: "$ref": "#/components/schemas/V3PlatformKPI" action_queue: type: array items: "$ref": "#/components/schemas/V3PlatformActionItem" nodes: type: array items: "$ref": "#/components/schemas/V3PlatformNodeRow" intervention_queues: type: array items: "$ref": "#/components/schemas/V3PlatformWorkflowCard" onboarding_workflows: type: array items: "$ref": "#/components/schemas/V3PlatformWorkflowCard" decommission_workflows: type: array items: "$ref": "#/components/schemas/V3PlatformWorkflowCard" agent_workflows: type: array items: "$ref": "#/components/schemas/V3PlatformWorkflowCard" maas_profiles: type: array items: "$ref": "#/components/schemas/V3PlatformWorkflowCard" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - kpis - action_queue - nodes - intervention_queues - onboarding_workflows - decommission_workflows - agent_workflows - maas_profiles - pagination - meta V3PlatformNodeDetailResponse: type: object additionalProperties: false properties: summary: "$ref": "#/components/schemas/V3PlatformNodeRow" facts: type: array items: "$ref": "#/components/schemas/V3PlatformNodeFact" agent: "$ref": "#/components/schemas/V3PlatformNodeAgent" maas: "$ref": "#/components/schemas/V3PlatformNodeMAAS" allocations: type: array items: "$ref": "#/components/schemas/V3PlatformNodeAllocation" slots: type: array items: "$ref": "#/components/schemas/V3PlatformNodeSlot" tasks: type: array items: "$ref": "#/components/schemas/V3PlatformNodeTask" runtime_cleanup: "$ref": "#/components/schemas/V3PlatformNodeRuntimeCleanup" activity: type: array items: "$ref": "#/components/schemas/V3PlatformNodeActivityItem" capabilities: type: array items: "$ref": "#/components/schemas/V3PlatformNodeCapability" operation_groups: type: array items: "$ref": "#/components/schemas/V3PlatformNodeOperationIntentGroup" operations: type: array items: "$ref": "#/components/schemas/V3PlatformNodeOperation" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - summary - facts - agent - maas - allocations - slots - tasks - runtime_cleanup - activity - capabilities - operation_groups - operations - meta V3PlatformConfigResponse: type: object additionalProperties: false properties: kpis: type: array items: "$ref": "#/components/schemas/V3PlatformKPI" rows: type: array items: "$ref": "#/components/schemas/V3PlatformFamilyCard" publish_workflows: type: array items: "$ref": "#/components/schemas/V3PlatformWorkflowCard" operations: type: array items: "$ref": "#/components/schemas/V3PlatformConfigOperation" activity: type: array items: "$ref": "#/components/schemas/V3PlatformConfigActivityItem" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - kpis - rows - publish_workflows - operations - activity - meta V3PlatformConfigOperation: type: object additionalProperties: false description: Server-owned operation affordance for platform configuration lifecycle actions. Row-scoped operations use templated hrefs and are disabled until the UI supplies the selected target. properties: key: type: string source: type: string enum: - sku - os_image - policy - quota - maas_profile - maas_site label: type: string method: type: string enum: - GET - POST - PUT - PATCH - DELETE href: type: string target_type: type: string target_id: type: string nullable: true enabled: type: boolean disabled_reason: type: string nullable: true danger: type: string enum: - safe - low - medium - high - destructive audit_action: type: string result: type: string latest_actor: type: string nullable: true latest_at: type: string format: date-time nullable: true evidence_href: type: string nullable: true required: - key - source - label - method - href - target_type - target_id - enabled - disabled_reason - danger - audit_action - result - latest_actor - latest_at - evidence_href V3PlatformConfigActivityItem: type: object additionalProperties: false description: First-class lifecycle/activity row for durable platform configuration changes. properties: id: type: string occurred_at: type: string format: date-time nullable: true source: type: string enum: - sku - os_image - policy - maas_profile - maas_site - quota - audit action: type: string status: type: string severity: "$ref": "#/components/schemas/V3PlatformSeverity" summary: type: string actor: type: string nullable: true correlation_id: type: string nullable: true href: type: string nullable: true required: - id - occurred_at - source - action - status - severity - summary - actor - correlation_id - href V3PlatformEvidenceResponse: type: object additionalProperties: false properties: rows: type: array items: "$ref": "#/components/schemas/V3PlatformAuditRow" pagination: "$ref": "#/components/schemas/Pagination" tools: type: array items: "$ref": "#/components/schemas/V3PlatformFamilyCard" pivots: type: array items: "$ref": "#/components/schemas/V3PlatformWorkflowCard" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - rows - pagination - tools - pivots - meta V3PlatformFinanceResponse: type: object additionalProperties: false properties: kpis: type: array items: "$ref": "#/components/schemas/V3PlatformKPI" sessions: type: array items: "$ref": "#/components/schemas/V3PlatformPaymentSessionRow" action_queue: type: array items: "$ref": "#/components/schemas/V3PlatformActionItem" interventions: type: array items: "$ref": "#/components/schemas/V3PlatformWorkflowCard" activity: type: array items: "$ref": "#/components/schemas/V3PlatformFinanceActivityItem" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - kpis - sessions - action_queue - interventions - activity - pagination - meta V3PlatformFinanceSessionsResponse: type: object additionalProperties: false properties: sessions: type: array items: "$ref": "#/components/schemas/V3PlatformPaymentSessionRow" pagination: "$ref": "#/components/schemas/Pagination" filters: "$ref": "#/components/schemas/V3PlatformFinanceSessionFilters" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - sessions - pagination - filters - meta V3PlatformFinanceSessionFilters: type: object additionalProperties: false properties: status: type: string nullable: true user_id: type: string nullable: true correlation_id: type: string nullable: true required: - status - user_id - correlation_id V3PlatformFinanceSessionDetailResponse: type: object additionalProperties: false properties: summary: "$ref": "#/components/schemas/V3PlatformPaymentSessionRow" diagnostics: "$ref": "#/components/schemas/V3PlatformFinanceSessionDiagnostics" operations: type: array items: "$ref": "#/components/schemas/V3PlatformFinanceSessionOperation" recovery_policy: "$ref": "#/components/schemas/V3PlatformFinanceSessionRecoveryPolicy" activity: type: array items: "$ref": "#/components/schemas/V3PlatformFinanceActivityItem" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - summary - diagnostics - operations - recovery_policy - activity - meta V3PlatformFinanceSessionDiagnostics: type: object additionalProperties: false properties: payment_session_id: type: string correlation_id: type: string nullable: true billing_diagnostics_href: type: string nullable: true evidence_href: type: string payment_session_count: type: integer format: int64 ledger_entry_count: type: integer format: int64 refund_count: type: integer format: int64 audit_log_count: type: integer format: int64 required: - payment_session_id - correlation_id - billing_diagnostics_href - evidence_href - payment_session_count - ledger_entry_count - refund_count - audit_log_count V3PlatformFinanceSessionOperation: type: object additionalProperties: false properties: key: type: string enum: - post_credit - mark_expired - mark_failed - create_refund label: type: string method: type: string enum: - POST href: type: string target_type: type: string target_id: type: string enabled: type: boolean disabled_reason: type: string nullable: true danger: type: string enum: - safe - low - medium - high - destructive audit_action: type: string result: type: string recovery_mode: type: string enum: - manual_internal_credit - manual_state_update - manual_refund_workflow required: - key - label - method - href - target_type - target_id - enabled - disabled_reason - danger - audit_action - result - recovery_mode V3PlatformFinanceSessionRecoveryPolicy: type: object additionalProperties: false properties: provider_replay_supported: type: boolean provider_replay_reason: type: string supported_modes: type: array items: type: string enum: - manual_internal_credit - manual_state_update - manual_refund_workflow required: - provider_replay_supported - provider_replay_reason - supported_modes V3PlatformFinanceActivityItem: type: object additionalProperties: false description: First-class lifecycle/activity row for platform finance operations. This intentionally excludes provider payment references and raw webhook payloads. properties: id: type: string occurred_at: type: string format: date-time nullable: true source: type: string enum: - payment_session - ledger - refund - audit - outbox action: type: string status: type: string severity: "$ref": "#/components/schemas/V3PlatformSeverity" summary: type: string actor: type: string nullable: true user_id: type: string nullable: true amount_minor: type: integer format: int64 nullable: true currency: type: string nullable: true correlation_id: type: string nullable: true href: type: string nullable: true required: - id - occurred_at - source - action - status - severity - summary - actor - user_id - amount_minor - currency - correlation_id - href V3PlatformIAMResponse: type: object additionalProperties: false properties: kpis: type: array items: "$ref": "#/components/schemas/V3PlatformKPI" users: type: array items: "$ref": "#/components/schemas/V3PlatformUserRoleRow" governance: type: array items: "$ref": "#/components/schemas/V3PlatformWorkflowCard" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - kpis - users - governance - pagination - meta V3WorkloadLifecycleItem: type: object additionalProperties: false properties: label: type: string status: type: string enum: - completed - current - pending - failed occurred_at: type: string format: date-time nullable: true summary: type: string required: - label - status - occurred_at - summary V3WorkloadEventItem: type: object additionalProperties: false properties: occurred_at: type: string format: date-time actor: type: string nullable: true action: type: string status: type: string source: type: string summary: type: string required: - occurred_at - actor - action - status - source - summary V3WorkloadConnectTab: type: object additionalProperties: false properties: primary_action: type: string enum: - open - connect - open_notebook - try_endpoint - open_training_ui - retry_release - review - none terminal_href: type: string nullable: true ssh_command: type: string nullable: true ssh_keys: type: array description: SSH public keys installed for the allocation owner runtime account. items: "$ref": "#/components/schemas/SshPublicKeyRef" app_url: type: string nullable: true proxy_status: "$ref": "#/components/schemas/V3WorkloadProxyStatus" kubeconfig_status: "$ref": "#/components/schemas/V3WorkloadKubeconfigStatus" nullable: true kubeconfig_last_error: type: string nullable: true description: User-safe latest RKE2 kubeconfig delivery error when kubeconfig_status is failed. kubeconfig_evidence_href: type: string nullable: true description: Stable evidence pivot for failed RKE2 kubeconfig delivery, when the runtime or audit trail reported one. terminal_startup_failure: "$ref": "#/components/schemas/V3TerminalStartupFailure" nullable: true notes: type: array items: type: string required: - primary_action - terminal_href - ssh_command - ssh_keys - app_url - proxy_status - notes V3WorkloadKubeconfigStatus: type: string description: Backend-owned RKE2 kubeconfig delivery state for the workload connect surface. Raw kubeconfig content is never returned here. enum: - pending - available - revoked - failed V3WorkloadProxyStatus: type: string description: Platform proxy readiness for the workload connect surface. enum: - pending - reachable - unreachable - proxy_disabled V3WorkloadMetricsTab: type: object additionalProperties: false properties: source: type: string enum: - allocation_metrics - guest_metrics - node_metrics - unavailable snapshot_href: type: string nullable: true timeseries_href: type: string nullable: true sampled_at: type: string format: date-time nullable: true capabilities: type: array items: type: string required: - source - snapshot_href - timeseries_href - sampled_at - capabilities V3WorkloadStorageMount: type: object additionalProperties: false properties: bucket_id: type: string nullable: true bucket_name: type: string nullable: true mount_path: type: string access_mode: type: string enum: - read_only - read_write state: type: string enum: - mounted - pending - failed - detached source: type: string required: - bucket_id - bucket_name - mount_path - access_mode - state - source V3WorkloadOverviewTab: type: object additionalProperties: false properties: lifecycle: type: array items: "$ref": "#/components/schemas/V3WorkloadLifecycleItem" recent_activity: type: array items: "$ref": "#/components/schemas/V3WorkloadEventItem" summary: type: string required: - lifecycle - recent_activity - summary V3WorkloadEventsTab: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3WorkloadEventItem" timeline_href: type: string required: - items - timeline_href V3WorkloadStorageTab: type: object additionalProperties: false properties: mounts: type: array items: "$ref": "#/components/schemas/V3WorkloadStorageMount" storage_href: type: string nullable: true required: - mounts - storage_href V3WorkloadCredentialPosture: type: object additionalProperties: false description: App-runtime credential posture metadata only. Never include private keys, tokens, passwords, wrapped tokens, or provider secrets. properties: credential_id: type: string format: uuid binding_id: type: string format: uuid label: type: string purpose: type: string kind: type: string status: type: string scope_type: type: string severity: type: string enum: - ok - info - warn - error summary: type: string last_validated_at: type: string format: date-time nullable: true last_used_at: type: string format: date-time nullable: true rotation_due_at: type: string format: date-time nullable: true capabilities: "$ref": "#/components/schemas/V3AppRuntimeCredentialOperationCapabilities" required: - credential_id - binding_id - label - purpose - kind - status - scope_type - severity - summary - last_validated_at - last_used_at - rotation_due_at - capabilities V3AppRuntimeCredentialOperationCapabilities: type: object additionalProperties: false description: UI capability flags for app runtime credential operations. These flags are metadata only and never expose raw credential material. properties: reconcile: "$ref": "#/components/schemas/V3AppRuntimeCredentialOperationCapability" rotate: "$ref": "#/components/schemas/V3AppRuntimeCredentialOperationCapability" disable: "$ref": "#/components/schemas/V3AppRuntimeCredentialOperationCapability" required: - reconcile - rotate - disable V3AppRuntimeCredentialOperationCapability: type: object additionalProperties: false properties: enabled: type: boolean disabled_reason: type: string nullable: true href: type: string required: - enabled - disabled_reason - href V3AppRuntimeCredentialOperationRequest: type: object additionalProperties: false description: Metadata-only app runtime credential operation request. Raw secrets, private keys, passwords, wrapped tokens, and provider credential material are not accepted here. properties: reason: type: string maxLength: 300 nullable: true V3AppRuntimeCredentialSweepRequest: type: object additionalProperties: false description: Metadata-only app runtime credential sweep request. Raw secrets, private keys, passwords, wrapped tokens, and provider credential material are not accepted here. properties: reason: type: string maxLength: 300 nullable: true max_age_seconds: type: integer minimum: 0 maximum: 2592000 nullable: true description: Minimum age for stale disabled credentials to be swept. Omit or set to 0 for the platform default. dry_run: type: boolean default: false V3AppRuntimeCredentialOperationResponse: type: object additionalProperties: false description: Durable metadata-only evidence for an app runtime credential operation. This response never includes raw secret material. properties: operation_id: type: string format: uuid app_instance_id: type: string format: uuid workload_id: type: string format: uuid credential_id: type: string format: uuid binding_id: type: string format: uuid operation: type: string enum: - reconcile - rotate - disable status: type: string enum: - accepted previous_status: type: string credential_status: type: string correlation_id: type: string evidence_href: type: string audit_action: type: string requested_at: type: string format: date-time required: - operation_id - app_instance_id - workload_id - credential_id - binding_id - operation - status - previous_status - credential_status - correlation_id - evidence_href - audit_action - requested_at V3AppRuntimeCredentialSweepResponse: type: object additionalProperties: false description: Durable metadata-only evidence for an app runtime credential sweep. This response never includes raw secret material. properties: operation_id: type: string format: uuid app_instance_id: type: string format: uuid workload_id: type: string format: uuid operation: type: string enum: - sweep status: type: string enum: - accepted scanned_count: type: integer minimum: 0 deleted_count: type: integer minimum: 0 retained_count: type: integer minimum: 0 error_count: type: integer minimum: 0 dry_run: type: boolean correlation_id: type: string evidence_href: type: string audit_action: type: string enum: - app.credential.sweep requested_at: type: string format: date-time required: - operation_id - app_instance_id - workload_id - operation - status - scanned_count - deleted_count - retained_count - error_count - dry_run - correlation_id - evidence_href - audit_action - requested_at V3WorkloadConfigTab: type: object additionalProperties: false properties: scheduler_type: type: string capacity_shape: type: string placement_status: type: string sku: type: string gpus_total: type: integer minimum: 0 effective_config: type: object additionalProperties: true credential_posture: type: array items: "$ref": "#/components/schemas/V3WorkloadCredentialPosture" required: - scheduler_type - capacity_shape - placement_status - sku - gpus_total - effective_config - credential_posture V3WorkloadDetailTabs: type: object additionalProperties: false description: V3Workload detail tabs are typed so production pages can match the mock without ad-hoc payloads. properties: overview: "$ref": "#/components/schemas/V3WorkloadOverviewTab" connect: "$ref": "#/components/schemas/V3WorkloadConnectTab" metrics: "$ref": "#/components/schemas/V3WorkloadMetricsTab" events: "$ref": "#/components/schemas/V3WorkloadEventsTab" storage: "$ref": "#/components/schemas/V3WorkloadStorageTab" config: "$ref": "#/components/schemas/V3WorkloadConfigTab" required: - overview - connect - metrics - events - storage - config V3StoragePrincipalKind: type: string enum: - project - user - service_account - workload - tenant_group V3StoragePermission: type: string enum: - list - read - write - delete - mount - admin V3StorageGrantSubject: type: object additionalProperties: false properties: kind: "$ref": "#/components/schemas/V3StoragePrincipalKind" id: type: string minLength: 1 maxLength: 128 project_id: type: string format: uuid nullable: true required: - kind - id - project_id V3StorageGrantScope: type: object additionalProperties: false properties: bucket_id: type: string minLength: 1 maxLength: 128 prefixes: type: array items: type: string maxLength: 1024 description: Empty means the whole bucket. Prefixes are normalized by the storage service before provider policy compilation. required: - bucket_id - prefixes V3StorageGrant: type: object additionalProperties: false description: GPUaaS-owned storage grant. Provider policy is compiled from this record; WEKA/VAST/provider raw policy is not exposed. properties: id: type: string format: uuid owner_project_id: type: string format: uuid subject: "$ref": "#/components/schemas/V3StorageGrantSubject" scope: "$ref": "#/components/schemas/V3StorageGrantScope" permissions: type: array minItems: 1 items: "$ref": "#/components/schemas/V3StoragePermission" provider_backend: "$ref": "#/components/schemas/V3StorageBackendType" provider_policy_ref: type: string nullable: true description: Opaque GPUaaS/provider binding reference; never raw policy JSON. expires_at: type: string format: date-time nullable: true reason: type: string nullable: true created_at: type: string format: date-time revoked_at: type: string format: date-time nullable: true required: - id - owner_project_id - subject - scope - permissions - provider_backend - provider_policy_ref - expires_at - reason - created_at - revoked_at V3StorageGrantCreateRequest: type: object additionalProperties: false properties: subject: "$ref": "#/components/schemas/V3StorageGrantSubject" prefixes: type: array items: type: string maxLength: 1024 permissions: type: array minItems: 1 items: "$ref": "#/components/schemas/V3StoragePermission" expires_at: type: string format: date-time nullable: true reason: type: string maxLength: 256 required: - subject - prefixes - permissions - expires_at - reason V3StorageGrantResponse: type: object additionalProperties: false properties: grant: "$ref": "#/components/schemas/V3StorageGrant" evidence: "$ref": "#/components/schemas/V3MutationEvidence" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - grant - evidence - meta V3StorageGrantRevokeResponse: type: object additionalProperties: false properties: grant_id: type: string format: uuid bucket_id: type: string revoked: type: boolean evidence: "$ref": "#/components/schemas/V3MutationEvidence" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - grant_id - bucket_id - revoked - evidence - meta V3StorageGrantListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3StorageGrant" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - items - pagination - meta V3StorageCredentialClientKind: type: string enum: - s3_cli - sdk - workload_mount V3StorageCredentialType: type: string enum: - s3_session - provider_session - vault_wrapped_secret V3StorageCredentialSessionState: type: string enum: - active - expired - revocation_pending - revoked - failed V3StorageCredentialIssueRequest: type: object additionalProperties: false properties: subject: "$ref": "#/components/schemas/V3StorageGrantSubject" prefixes: type: array items: type: string maxLength: 1024 permissions: type: array minItems: 1 items: "$ref": "#/components/schemas/V3StoragePermission" ttl_seconds: type: integer minimum: 60 maximum: 43200 client_kind: "$ref": "#/components/schemas/V3StorageCredentialClientKind" reason: type: string maxLength: 256 required: - subject - prefixes - permissions - ttl_seconds - client_kind - reason V3StorageCredentialScopeSummary: type: object additionalProperties: false properties: bucket_id: type: string prefixes: type: array items: type: string permissions: type: array items: "$ref": "#/components/schemas/V3StoragePermission" provider_backend: "$ref": "#/components/schemas/V3StorageBackendType" required: - bucket_id - prefixes - permissions - provider_backend V3StorageCredentialSessionEvidence: type: object additionalProperties: false description: User-safe durable evidence for a one-time provider credential issuance. This object may appear in read models and audit pivots; it must never contain provider access keys, secret keys, session tokens, wrapped-token bytes, or raw provider policy JSON. properties: credential_session_id: type: string format: uuid credential_type: "$ref": "#/components/schemas/V3StorageCredentialType" client_kind: "$ref": "#/components/schemas/V3StorageCredentialClientKind" subject: "$ref": "#/components/schemas/V3StorageGrantSubject" scope: "$ref": "#/components/schemas/V3StorageCredentialScopeSummary" issued_at: type: string format: date-time expires_at: type: string format: date-time revocation_state: "$ref": "#/components/schemas/V3StorageCredentialSessionState" revoke_supported: type: boolean description: Whether the selected provider supports active session revocation before expiry. source_workflow_id: type: string nullable: true audit_action: type: string enum: - auth.provider_credential.issue - storage.credential.issue required: - credential_session_id - credential_type - client_kind - subject - scope - issued_at - expires_at - revocation_state - revoke_supported - source_workflow_id - audit_action V3StorageCredentialIssueResponse: type: object additionalProperties: false description: One-time credential issuance response. Credential material is returned only here; read models may keep only the nested session evidence. properties: credential_session_id: type: string format: uuid credential_type: "$ref": "#/components/schemas/V3StorageCredentialType" provider_backend: "$ref": "#/components/schemas/V3StorageBackendType" endpoint: type: string format: uri access_key_id: type: string secret_access_key: type: string session_token: type: string nullable: true expires_at: type: string format: date-time scope: "$ref": "#/components/schemas/V3StorageCredentialScopeSummary" session: "$ref": "#/components/schemas/V3StorageCredentialSessionEvidence" required: - credential_session_id - credential_type - provider_backend - endpoint - access_key_id - secret_access_key - session_token - expires_at - scope - session V3AccessQuotaPosture: type: string enum: - ok - near_limit - blocked V3AccessQuotaSignal: type: object additionalProperties: false properties: severity: "$ref": "#/components/schemas/V3AccessSeverity" title: type: string summary: type: string action_label: type: string nullable: true action_href: type: string nullable: true required: - severity - title - summary - action_label - action_href V3AccessQuotaResponse: type: object additionalProperties: false properties: project_id: type: string format: uuid project_name: type: string user_id: type: string format: uuid limits: "$ref": "#/components/schemas/AllocationLimits" posture: "$ref": "#/components/schemas/V3AccessQuotaPosture" signals: type: array items: "$ref": "#/components/schemas/V3AccessQuotaSignal" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - project_id - project_name - user_id - limits - posture - signals - meta V3StorageObjectPathRequest: type: object additionalProperties: false properties: path: type: string minLength: 1 maxLength: 1024 required: - path V3PlatformLifecycleNodesResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3PlatformNodeRow" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - items - pagination - meta V3PlatformEvidenceResult: type: string enum: - pass - fail - partial - blocked - missing - not_applicable V3PlatformEvidenceBundleListResponse: type: object additionalProperties: false properties: bundles: type: array items: "$ref": "#/components/schemas/V3PlatformEvidenceBundleSummary" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - bundles - pagination - meta V3PlatformEvidenceBundleDetailResponse: type: object additionalProperties: false properties: bundle: "$ref": "#/components/schemas/V3PlatformEvidenceBundle" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - bundle - meta V3PlatformEvidenceBundleSummary: type: object additionalProperties: false properties: bundle_id: type: string format: uuid source_commit: type: string release_branch: type: string nullable: true environment_profile: type: string product_scope: type: string change_summary: type: string gate_state: "$ref": "#/components/schemas/V3PlatformEvidenceResult" residual_risk: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - bundle_id - source_commit - release_branch - environment_profile - product_scope - change_summary - gate_state - residual_risk - created_at - updated_at V3PlatformEvidenceBundle: allOf: - "$ref": "#/components/schemas/V3PlatformEvidenceBundleSummary" - type: object additionalProperties: false properties: artifact_digests: type: array items: "$ref": "#/components/schemas/V3PlatformArtifactDigest" migration_status: type: string nullable: true capacity_posture: type: string nullable: true rollback_plan: type: string nullable: true correlation_ids: type: array items: type: string approvals: type: array items: "$ref": "#/components/schemas/V3PlatformEvidenceApproval" invariants: type: array items: "$ref": "#/components/schemas/V3PlatformProductInvariantCoverage" items: type: array items: "$ref": "#/components/schemas/V3PlatformEvidenceItem" required: - artifact_digests - migration_status - capacity_posture - rollback_plan - correlation_ids - approvals - invariants - items V3PlatformArtifactDigest: type: object additionalProperties: false properties: name: type: string artifact_type: type: string digest: type: string source_uri: type: string nullable: true required: - name - artifact_type - digest - source_uri V3PlatformEvidenceApproval: type: object additionalProperties: false properties: owner: type: string role: type: string result: "$ref": "#/components/schemas/V3PlatformEvidenceResult" approved_at: type: string format: date-time nullable: true comment: type: string nullable: true required: - owner - role - result - approved_at - comment V3PlatformProductInvariantCoverage: type: object additionalProperties: false properties: invariant_id: type: string product_area: type: string result: "$ref": "#/components/schemas/V3PlatformEvidenceResult" evidence_item_ids: type: array items: type: string format: uuid missing_reason: type: string nullable: true required: - invariant_id - product_area - result - evidence_item_ids - missing_reason V3PlatformEvidenceItem: type: object additionalProperties: false properties: evidence_item_id: type: string format: uuid evidence_type: type: string producer: type: string source_uri: type: string nullable: true artifact_path: type: string nullable: true result: "$ref": "#/components/schemas/V3PlatformEvidenceResult" started_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true correlation_id: type: string nullable: true owner: type: string retention_class: type: string proves_invariants: type: array items: type: string details: type: object additionalProperties: true description: Sanitized structured evidence details used by read-model projections. Must not contain secrets, tokens, private keys, raw provider credentials, or tenant payloads. required: - evidence_item_id - evidence_type - producer - source_uri - artifact_path - result - started_at - completed_at - correlation_id - owner - retention_class - proves_invariants - details CreateV3PlatformEvidenceBundleRequest: type: object additionalProperties: false properties: source_commit: type: string release_branch: type: string nullable: true environment_profile: type: string product_scope: type: string change_summary: type: string artifact_digests: type: array items: "$ref": "#/components/schemas/V3PlatformArtifactDigest" migration_status: type: string nullable: true capacity_posture: type: string nullable: true residual_risk: type: string nullable: true rollback_plan: type: string nullable: true correlation_ids: type: array items: type: string required: - source_commit - release_branch - environment_profile - product_scope - change_summary - artifact_digests - migration_status - capacity_posture - residual_risk - rollback_plan - correlation_ids CreateV3PlatformEvidenceItemRequest: type: object additionalProperties: false properties: evidence_type: type: string producer: type: string source_uri: type: string nullable: true artifact_path: type: string nullable: true result: "$ref": "#/components/schemas/V3PlatformEvidenceResult" started_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true correlation_id: type: string nullable: true owner: type: string retention_class: type: string proves_invariants: type: array items: type: string details: type: object additionalProperties: true description: Sanitized structured evidence details used by read-model projections. Must not contain secrets, tokens, private keys, raw provider credentials, or tenant payloads. required: - evidence_type - producer - source_uri - artifact_path - result - started_at - completed_at - correlation_id - owner - retention_class - proves_invariants V3PlatformPublicStatusResponse: type: object additionalProperties: false properties: status: "$ref": "#/components/schemas/V3PlatformPublicStatus" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - status - meta V3PlatformPublicStatus: type: object additionalProperties: false properties: environment_profile: type: string overall_health: type: string enum: - healthy - degraded - unhealthy - unknown service_areas: type: array items: "$ref": "#/components/schemas/V3PlatformPublicServiceArea" active_incidents: type: array items: "$ref": "#/components/schemas/V3PlatformPublicIncident" checked_at: type: string format: date-time required: - environment_profile - overall_health - service_areas - active_incidents - checked_at V3PlatformPublicServiceArea: type: object additionalProperties: false properties: name: type: string status: type: string enum: - healthy - degraded - unhealthy - unknown required: - name - status V3PlatformPublicIncident: type: object additionalProperties: false properties: summary: type: string severity: type: string status: type: string href: type: string nullable: true required: - summary - severity - status - href V3PlatformStatusReadinessResponse: type: object additionalProperties: false properties: environment_profile: type: string product_scope: type: string gate_state: "$ref": "#/components/schemas/V3PlatformEvidenceResult" gates: type: array items: "$ref": "#/components/schemas/V3PlatformReleaseGateStatus" evidence_freshness: type: array items: "$ref": "#/components/schemas/V3PlatformEvidenceFreshness" incidents: type: array items: "$ref": "#/components/schemas/V3PlatformStatusIncident" capacity_posture: type: string nullable: true degradation_level: type: string enum: - normal - partial - impaired - unknown slo_evidence: type: array items: "$ref": "#/components/schemas/V3PlatformSLOEvidence" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - environment_profile - product_scope - gate_state - gates - evidence_freshness - incidents - capacity_posture - degradation_level - slo_evidence - meta V3PlatformSLOEvidence: type: object additionalProperties: false properties: dimension: type: string status: type: string enum: - healthy - degraded - unhealthy - unknown latest_value: type: number nullable: true unit: type: string checked_at: type: string format: date-time nullable: true evidence_href: type: string nullable: true required: - dimension - status - latest_value - unit - checked_at - evidence_href V3PlatformReleaseGateStatus: type: object additionalProperties: false properties: gate_id: type: string label: type: string result: "$ref": "#/components/schemas/V3PlatformEvidenceResult" owner: type: string evidence_item_ids: type: array items: type: string format: uuid missing_reason: type: string nullable: true required: - gate_id - label - result - owner - evidence_item_ids - missing_reason V3PlatformEvidenceFreshness: type: object additionalProperties: false properties: evidence_type: type: string latest_completed_at: type: string format: date-time nullable: true max_age_seconds: type: integer format: int64 state: type: string enum: - fresh - stale - missing required: - evidence_type - latest_completed_at - max_age_seconds - state V3PlatformStatusIncident: type: object additionalProperties: false properties: incident_id: type: string severity: "$ref": "#/components/schemas/V3PlatformSeverity" summary: type: string status: type: string classification: type: string nullable: true environment: type: string nullable: true affected_surfaces: type: array items: type: string started_at: type: string format: date-time nullable: true detected_at: type: string format: date-time nullable: true acknowledged_at: type: string format: date-time nullable: true mitigated_at: type: string format: date-time nullable: true resolved_at: type: string format: date-time nullable: true incident_commander: type: string nullable: true owner_domains: type: array items: type: string runbook_ids: type: array items: type: string evidence_refs: type: object additionalProperties: type: string notification_state: type: object additionalProperties: type: string post_incident_review: "$ref": "#/components/schemas/V3PlatformPostIncidentReview" href: type: string nullable: true required: - incident_id - severity - summary - status - classification - environment - affected_surfaces - started_at - detected_at - acknowledged_at - mitigated_at - resolved_at - incident_commander - owner_domains - runbook_ids - evidence_refs - notification_state - post_incident_review - href V3PlatformPostIncidentReview: type: object additionalProperties: false properties: required: type: boolean due_at: type: string format: date-time nullable: true status: type: string required: - required - due_at - status V3PlatformComponentStatusListResponse: type: object additionalProperties: false properties: components: type: array items: "$ref": "#/components/schemas/V3PlatformComponentStatus" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - components - pagination - meta V3PlatformComponentStatus: type: object additionalProperties: false properties: component_id: type: string component_type: type: string environment_profile: type: string status: type: string enum: - healthy - degraded - unhealthy - unknown freshness_seconds: type: integer format: int64 evidence_href: type: string nullable: true checked_at: type: string format: date-time nullable: true details: type: object additionalProperties: true required: - component_id - component_type - environment_profile - status - freshness_seconds - evidence_href - checked_at - details V3PlatformGuardStatusResponse: type: object additionalProperties: false properties: reports: type: array items: "$ref": "#/components/schemas/V3PlatformGuardReportSummary" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - reports - pagination - meta V3PlatformGuardReportSummary: type: object additionalProperties: false properties: guard_id: type: string mode: type: string enum: - report_only - warning - blocking - blocking_new - blocking_all source_commit: type: string generated_at: type: string format: date-time artifact_path: type: string nullable: true findings: type: array items: "$ref": "#/components/schemas/V3PlatformGuardFinding" allowed_debt: type: array items: type: string graduation_criteria: type: string required: - guard_id - mode - source_commit - generated_at - artifact_path - findings - allowed_debt - graduation_criteria V3PlatformGuardFinding: type: object additionalProperties: false properties: guard_id: type: string severity: type: string owner: type: string file: type: string line: type: string rule: type: string reason: type: string approval: type: string nullable: true allowed_debt_owner: type: string nullable: true allowed_debt_task: type: string nullable: true allowed_debt_expiry: type: string nullable: true required: - guard_id - severity - owner - file - line - rule - reason V3PlatformRegistryEnvironmentArtifactKind: type: string enum: - container_image - oci_artifact - helm_chart - manifest_bundle - sbom - provenance - unknown V3PlatformRegistryEnvironmentArtifactStatus: type: string enum: - current - previous - pending - failed - unknown V3PlatformRegistryEnvironmentArtifactEnvironment: type: object additionalProperties: false properties: environment_profile: type: string cluster_name: type: string generated_at: type: string format: date-time required: - environment_profile - cluster_name - generated_at V3PlatformRegistryEnvironmentArtifactReplicas: type: object additionalProperties: false properties: desired: type: integer available: type: integer updated: type: integer required: - desired - available - updated V3PlatformRegistryEnvironmentArtifactWorkload: type: object additionalProperties: false properties: kind: type: string name: type: string rollout_revision: type: string replicas: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactReplicas" required: - kind - name - rollout_revision - replicas V3PlatformRegistryEnvironmentArtifactRef: type: object additionalProperties: false properties: artifact_kind: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactKind" image_ref: type: string display_tag: type: string digest: type: string digest_authority: type: boolean source_sha: type: string build_id: type: string platform: type: string required: - artifact_kind - image_ref - display_tag - digest - digest_authority - source_sha - build_id - platform V3PlatformRegistryEnvironmentArtifactReleaseEvidence: type: object additionalProperties: false properties: release_id: type: string release_evidence_href: type: string nullable: true rollback_evidence_href: type: string nullable: true required: - release_id - release_evidence_href - rollback_evidence_href V3PlatformRegistryEnvironmentArtifactTrust: type: object additionalProperties: false properties: trust_status: type: string artifact_trust_href: type: string nullable: true required: - trust_status - artifact_trust_href V3PlatformRegistryEnvironmentArtifactItem: type: object additionalProperties: false properties: component: type: string component_type: type: string namespace: type: string workload: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactWorkload" artifact: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactRef" status: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactStatus" deployed_at: type: string format: date-time nullable: true deployed_by: type: string release: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactReleaseEvidence" trust: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactTrust" required: - component - component_type - namespace - workload - artifact - status - deployed_at - deployed_by - release - trust V3PlatformRegistryEnvironmentArtifactRollups: type: object additionalProperties: false properties: current_components: type: integer missing_digest: type: integer mutable_tag_without_digest: type: integer source_sha_missing: type: integer release_evidence_missing: type: integer rollout_revision_missing: type: integer required: - current_components - missing_digest - mutable_tag_without_digest - source_sha_missing - release_evidence_missing - rollout_revision_missing V3PlatformRegistryEnvironmentArtifactMeta: type: object additionalProperties: false properties: sources: type: array items: type: string mutable_tags_authoritative: type: boolean secret_material_included: type: boolean required: - sources - mutable_tags_authoritative - secret_material_included V3PlatformRegistryEnvironmentArtifactsResponse: type: object additionalProperties: false properties: environment: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactEnvironment" items: type: array items: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactItem" rollups: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactRollups" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactMeta" required: - environment - items - rollups - pagination - meta V3PlatformRegistryArtifactTrustStatus: type: string enum: - trusted - not_ready - waived - expired - unknown V3PlatformRegistryArtifactTrustEvidenceState: type: string enum: - present - missing - expired - failed - unknown V3PlatformRegistryArtifactTrustWaiverState: type: string enum: - none - valid - expired V3PlatformRegistryArtifactTrustArtifact: type: object additionalProperties: false properties: artifact_name: type: string artifact_kind: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactKind" image_ref: type: string digest: type: string source_sha: type: string platform: type: string required: - artifact_name - artifact_kind - image_ref - digest - source_sha - platform V3PlatformRegistryArtifactTrustSummary: type: object additionalProperties: false properties: trust_status: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustStatus" promotion_eligible: type: boolean blocking_reasons: type: array items: type: string expires_at: type: string format: date-time nullable: true required: - trust_status - promotion_eligible - blocking_reasons - expires_at V3PlatformRegistryArtifactTrustDocumentEvidence: type: object additionalProperties: false properties: state: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustEvidenceState" format: type: string digest: type: string signature_state: type: string signature_provider: type: string required: - state - format - digest V3PlatformRegistryArtifactTrustSignatureEvidence: type: object additionalProperties: false properties: state: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustEvidenceState" provider: type: string production_acceptable: type: boolean required: - state - provider - production_acceptable V3PlatformRegistryArtifactTrustScannerSummary: type: object additionalProperties: false properties: state: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustEvidenceState" result: type: string blocked_count: type: integer finding_count: type: integer summary_href: type: string nullable: true required: - state - result - blocked_count - finding_count - summary_href V3PlatformRegistryArtifactTrustEvidence: type: object additionalProperties: false properties: sbom: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustDocumentEvidence" provenance: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustDocumentEvidence" artifact_signature: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustSignatureEvidence" scanner_summary: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustScannerSummary" release_evidence_href: type: string nullable: true required: - sbom - provenance - artifact_signature - scanner_summary - release_evidence_href V3PlatformRegistryArtifactTrustWaiver: type: object additionalProperties: false properties: state: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustWaiverState" waiver_id: type: string nullable: true owner: type: string nullable: true approved_by: type: string nullable: true expires_on: type: string format: date-time nullable: true compensating_control: type: string nullable: true required: - state - waiver_id - owner - approved_by - expires_on - compensating_control V3PlatformRegistryArtifactTrustMeta: type: object additionalProperties: false properties: sources: type: array items: type: string raw_scanner_output_included: type: boolean secret_material_included: type: boolean required: - sources - raw_scanner_output_included - secret_material_included V3PlatformRegistryArtifactTrustItem: type: object additionalProperties: false properties: artifact: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustArtifact" trust: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustSummary" evidence: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustEvidence" waiver: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustWaiver" meta: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustMeta" required: - artifact - trust - evidence - waiver - meta V3PlatformRegistryArtifactTrustResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustItem" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination V3PlatformTemporalWorkflowFamily: type: string enum: - provisioning - maas_onboarding - maas_decommission - node_agent_lifecycle - app_runtime - reconciliation - unknown V3PlatformTemporalWorkflowStatus: type: string enum: - running - completed - failed - cancelled - terminated - timed_out - unknown V3PlatformTemporalWorkflowSearchResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowItem" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowSearchMeta" required: - items - pagination - meta V3PlatformTemporalWorkflowItem: type: object additionalProperties: false properties: workflow_id: type: string workflow_run_id: type: string nullable: true family: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowFamily" status: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowStatus" source: type: string enum: - product_record - audit_log - workflow_memo owner: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowOwner" target: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowTarget" timestamps: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowTimestamps" correlation_id: type: string nullable: true summary: type: string detail_href: type: string nullable: true evidence_href: type: string nullable: true temporal_href: type: string nullable: true required: - workflow_id - workflow_run_id - family - status - source - owner - target - timestamps - correlation_id - summary - detail_href - evidence_href - temporal_href V3PlatformTemporalWorkflowOwner: type: object additionalProperties: false properties: org_id: type: string format: uuid nullable: true project_id: type: string format: uuid nullable: true actor_user_id: type: string format: uuid nullable: true required: - org_id - project_id - actor_user_id V3PlatformTemporalWorkflowTarget: type: object additionalProperties: false properties: allocation_id: type: string format: uuid nullable: true node_id: type: string nullable: true site_id: type: string format: uuid nullable: true resource_type: type: string required: - allocation_id - node_id - site_id - resource_type V3PlatformTemporalWorkflowTimestamps: type: object additionalProperties: false properties: started_at: type: string format: date-time nullable: true updated_at: type: string format: date-time closed_at: type: string format: date-time nullable: true required: - started_at - updated_at - closed_at V3PlatformTemporalWorkflowSearchMeta: type: object additionalProperties: false properties: generated_at: type: string format: date-time sources: type: array items: type: string enum: - product_record - audit_log - workflow_memo temporal_search_attributes_enabled: type: boolean required: - generated_at - sources - temporal_search_attributes_enabled V3PlatformTemporalRetryHistoryResponse: type: object additionalProperties: false properties: workflow_id: type: string family: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowFamily" current_run_id: type: string nullable: true target: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowTarget" attempts: type: array items: "$ref": "#/components/schemas/V3PlatformTemporalRetryAttempt" pagination: "$ref": "#/components/schemas/Pagination" required: - workflow_id - family - current_run_id - target - attempts - pagination V3PlatformTemporalRetryAttempt: type: object additionalProperties: false properties: attempt: type: integer minimum: 0 workflow_run_id: type: string nullable: true workflow_id: type: string status: type: string started_at: type: string format: date-time nullable: true ended_at: type: string format: date-time nullable: true actor_user_id: type: string format: uuid nullable: true correlation_id: type: string nullable: true reason: type: string nullable: true resume_from_stage: type: string nullable: true result: type: string enum: - running - completed - failed - cancelled - unknown superseded_by_workflow_id: type: string nullable: true evidence_href: type: string nullable: true required: - attempt - workflow_run_id - workflow_id - status - started_at - ended_at - actor_user_id - correlation_id - reason - resume_from_stage - result - superseded_by_workflow_id - evidence_href V3PlatformTemporalScheduleStatus: type: string enum: - healthy - paused - missing - degraded - error - unknown V3PlatformWorkflowSchedulesResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3PlatformWorkflowScheduleItem" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination V3PlatformWorkflowScheduleItem: type: object additionalProperties: false properties: schedule_id: type: string family: type: string enum: - maas_reconciliation owner_domain: type: string engine: type: string status: "$ref": "#/components/schemas/V3PlatformTemporalScheduleStatus" connected: type: boolean schedule_present: type: boolean paused: type: boolean note: type: string nullable: true num_actions: type: integer format: int64 num_actions_missed_catchup: type: integer format: int64 num_actions_skipped_overlap: type: integer format: int64 running_workflow_ids: type: array items: type: string recent_workflow_ids: type: array items: type: string last_action_scheduled_at: type: string format: date-time nullable: true last_action_started_at: type: string format: date-time nullable: true next_action_at: type: string format: date-time nullable: true error_message: type: string nullable: true checked_at: type: string format: date-time next_operator_action: type: string nullable: true evidence_href: type: string nullable: true environment_profile_expected: type: boolean required: - schedule_id - family - owner_domain - engine - status - connected - schedule_present - paused - note - num_actions - num_actions_missed_catchup - num_actions_skipped_overlap - running_workflow_ids - recent_workflow_ids - last_action_scheduled_at - last_action_started_at - next_action_at - error_message - checked_at - next_operator_action - evidence_href - environment_profile_expected V3PlatformTemporalStuckActivityStatus: type: string enum: - stuck - retrying - waiting - failed - unknown V3PlatformTemporalStuckActivitiesResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3PlatformTemporalStuckActivityItem" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination V3PlatformTemporalStuckActivityItem: type: object additionalProperties: false properties: diagnostic_id: type: string workflow_id: type: string workflow_run_id: type: string nullable: true family: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowFamily" owner_domain: type: string target: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowTarget" activity_name: type: string activity_display_name: type: string current_attempt: type: integer minimum: 0 activity_status: "$ref": "#/components/schemas/V3PlatformTemporalStuckActivityStatus" workflow_status: type: string last_update_at: type: string format: date-time last_heartbeat_at: type: string format: date-time nullable: true age_seconds: type: integer format: int64 minimum: 0 retry_state: type: string error_code: type: string nullable: true error_summary: type: string nullable: true next_operator_action: type: string evidence_href: type: string nullable: true required: - diagnostic_id - workflow_id - workflow_run_id - family - owner_domain - target - activity_name - activity_display_name - current_attempt - activity_status - workflow_status - last_update_at - last_heartbeat_at - age_seconds - retry_state - error_code - error_summary - next_operator_action - evidence_href V3PlatformObservabilityComponentType: type: string enum: - api - web - worker - gateway - queue - database - cache - event_bus - workflow - observability - runtime - node_log_gateway V3PlatformObservabilityHealthStatus: type: string enum: - healthy - degraded - unhealthy - unknown - not_reported V3PlatformObservabilityHealthSnapshotResponse: type: object additionalProperties: false properties: overall: "$ref": "#/components/schemas/V3PlatformObservabilityHealthOverall" components: type: array items: "$ref": "#/components/schemas/V3PlatformObservabilityHealthComponent" rollups: "$ref": "#/components/schemas/V3PlatformObservabilityHealthRollups" evidence: type: array items: "$ref": "#/components/schemas/V3PlatformObservabilityHealthEvidence" direct_ui: "$ref": "#/components/schemas/V3PlatformObservabilityDirectUI" meta: "$ref": "#/components/schemas/V3PlatformObservabilityHealthMeta" required: - overall - components - rollups - evidence - direct_ui - meta V3PlatformObservabilityHealthOverall: type: object additionalProperties: false properties: status: "$ref": "#/components/schemas/V3PlatformObservabilityHealthStatus" degradation_level: type: string enum: - normal - partial - impaired - unknown summary: type: string generated_at: type: string format: date-time environment_profile: type: string required: - status - degradation_level - summary - generated_at - environment_profile V3PlatformObservabilityHealthComponent: type: object additionalProperties: false properties: component_id: type: string component_type: "$ref": "#/components/schemas/V3PlatformObservabilityComponentType" owner_domain: type: string status: "$ref": "#/components/schemas/V3PlatformObservabilityHealthStatus" freshness_seconds: type: integer format: int64 minimum: 0 checked_at: type: string format: date-time nullable: true degradation_reason: type: string nullable: true runbook_id: type: string nullable: true evidence_href: type: string nullable: true metrics: "$ref": "#/components/schemas/V3PlatformObservabilityHealthMetrics" details: type: object additionalProperties: true required: - component_id - component_type - owner_domain - status - freshness_seconds - checked_at - degradation_reason - runbook_id - evidence_href - metrics - details V3PlatformObservabilityHealthMetrics: type: object additionalProperties: false properties: scrape_state: type: string scrape_freshness_seconds: type: integer format: int64 minimum: 0 nullable: true error_rate_class: type: string latency_class: type: string saturation_class: type: string prometheus_query_id: type: string prometheus_result_class: type: string required: - scrape_state - scrape_freshness_seconds - error_rate_class - latency_class - saturation_class V3PlatformObservabilityHealthRollups: type: object additionalProperties: false properties: service: "$ref": "#/components/schemas/V3PlatformObservabilityStatusCounts" worker: "$ref": "#/components/schemas/V3PlatformObservabilityStatusCounts" queue: "$ref": "#/components/schemas/V3PlatformObservabilityQueueRollup" runtime: "$ref": "#/components/schemas/V3PlatformObservabilityRuntimeRollup" observability: "$ref": "#/components/schemas/V3PlatformObservabilityStackRollup" required: - service - worker - queue - runtime - observability V3PlatformObservabilityStatusCounts: type: object additionalProperties: false properties: healthy: type: integer degraded: type: integer unhealthy: type: integer unknown: type: integer not_reported: type: integer required: - healthy - degraded - unhealthy - unknown - not_reported V3PlatformObservabilityQueueRollup: type: object additionalProperties: false properties: max_lag_seconds: type: integer format: int64 dlq_backlog: type: integer format: int64 stale_consumers: type: integer required: - max_lag_seconds - dlq_backlog - stale_consumers V3PlatformObservabilityRuntimeRollup: type: object additionalProperties: false properties: stale_deployments: type: integer image_digest_missing: type: integer profile_mismatch: type: integer required: - stale_deployments - image_digest_missing - profile_mismatch V3PlatformObservabilityStackRollup: type: object additionalProperties: false properties: prometheus_reachable: type: boolean loki_reachable: type: boolean tempo_reachable: type: boolean grafana_escape_hatch_configured: type: boolean required: - prometheus_reachable - loki_reachable - tempo_reachable - grafana_escape_hatch_configured V3PlatformObservabilityHealthEvidence: type: object additionalProperties: false properties: source: type: string state: type: string enum: - fresh - stale - missing freshness_seconds: type: integer format: int64 href: type: string nullable: true required: - source - state - freshness_seconds - href V3PlatformObservabilityDirectUI: type: object additionalProperties: false properties: grafana: "$ref": "#/components/schemas/V3PlatformObservabilityDirectUITarget" prometheus: "$ref": "#/components/schemas/V3PlatformObservabilityDirectUITarget" required: - grafana - prometheus V3PlatformObservabilityDirectUITarget: type: object additionalProperties: false properties: configured: type: boolean path: type: string nullable: true use_when: type: string required: - configured - path - use_when V3PlatformObservabilityHealthMeta: type: object additionalProperties: false properties: cache: type: string sources: type: array items: type: string raw_telemetry_included: type: boolean required: - cache - sources - raw_telemetry_included V3PlatformObservabilityCorrelationTimelineResponse: type: object additionalProperties: false properties: query: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineQuery" summary: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineSummary" items: type: array items: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineItem" pivots: "$ref": "#/components/schemas/V3PlatformCorrelationTimelinePivots" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineMeta" required: - query - summary - items - pivots - pagination - meta V3PlatformCorrelationTimelineSource: type: string enum: - audit_log - structured_log_summary - trace_summary - task_event - domain_event - workflow_record - evidence_item V3PlatformCorrelationTimelineTargetType: type: string enum: - allocation - node - app_instance - project - org - workflow - payment - artifact - secret - unknown V3PlatformCorrelationTimelineQuery: type: object additionalProperties: false properties: correlation_id: type: string request_id: type: string trace_id: type: string workflow_id: type: string workflow_run_id: type: string task_id: type: string event_id: type: string target_type: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineTargetType" target_id: type: string time_range: type: string source: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineSource" include_log_excerpts: type: boolean required: - include_log_excerpts V3PlatformCorrelationTimelineSummary: type: object additionalProperties: false properties: status: type: string enum: - complete - partial - empty - blocked primary_correlation_id: type: string nullable: true time_window: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineWindow" owner_domains: type: array items: type: string resource_refs: type: array items: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineResourceRef" missing_sources: type: array items: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineSource" required: - status - primary_correlation_id - time_window - owner_domains - resource_refs - missing_sources V3PlatformCorrelationTimelineWindow: type: object additionalProperties: false properties: from: type: string format: date-time nullable: true to: type: string format: date-time nullable: true required: - from - to V3PlatformCorrelationTimelineResourceRef: type: object additionalProperties: false properties: type: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineTargetType" id: type: string required: - type - id V3PlatformCorrelationTimelineItem: type: object additionalProperties: false properties: id: type: string source: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineSource" occurred_at: type: string format: date-time severity: type: string owner_domain: type: string action: type: string result: type: string correlation_id: type: string nullable: true request_id: type: string nullable: true trace_id: type: string nullable: true span_id: type: string nullable: true workflow_id: type: string nullable: true workflow_run_id: type: string nullable: true task_id: type: string nullable: true event_id: type: string nullable: true target: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineResourceRef" summary: type: string detail_href: type: string nullable: true observability_href: type: string nullable: true redaction: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineRedaction" required: - id - source - occurred_at - severity - owner_domain - action - result - correlation_id - request_id - trace_id - span_id - workflow_id - workflow_run_id - task_id - event_id - target - summary - detail_href - observability_href - redaction V3PlatformCorrelationTimelineRedaction: type: object additionalProperties: false properties: payload_included: type: boolean redaction_state: type: string excluded_fields: type: array items: type: string required: - payload_included - redaction_state - excluded_fields V3PlatformCorrelationTimelinePivots: type: object additionalProperties: false properties: logs_href: type: string nullable: true trace_href: type: string nullable: true workflow_href: type: string nullable: true evidence_href: type: string nullable: true required: - logs_href - trace_href - workflow_href - evidence_href V3PlatformCorrelationTimelineMeta: type: object additionalProperties: false properties: generated_at: type: string format: date-time sources: type: array items: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineSource" raw_log_payloads_included: type: boolean raw_trace_spans_included: type: boolean raw_workflow_payloads_included: type: boolean required: - generated_at - sources - raw_log_payloads_included - raw_trace_spans_included - raw_workflow_payloads_included V3PlatformObservabilityLogSeverity: type: string enum: - debug - info - warn - error - fatal V3PlatformObservabilityLogsResponse: type: object additionalProperties: false properties: query: "$ref": "#/components/schemas/V3PlatformObservabilityLogQuery" items: type: array items: "$ref": "#/components/schemas/V3PlatformObservabilityLogItem" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3PlatformObservabilityLogMeta" required: - query - items - pagination - meta V3PlatformObservabilityLogQuery: type: object additionalProperties: false properties: correlation_id: type: string request_id: type: string trace_id: type: string workflow_id: type: string task_id: type: string event_id: type: string target_type: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineTargetType" target_id: type: string service: type: string severity: "$ref": "#/components/schemas/V3PlatformObservabilityLogSeverity" time_range: type: string V3PlatformObservabilityLogItem: type: object additionalProperties: false properties: id: type: string occurred_at: type: string format: date-time source: type: string service: type: string level: "$ref": "#/components/schemas/V3PlatformObservabilityLogSeverity" owner_domain: type: string correlation_id: type: string nullable: true request_id: type: string nullable: true trace_id: type: string nullable: true span_id: type: string nullable: true workflow_id: type: string nullable: true task_id: type: string nullable: true event_id: type: string nullable: true target: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineResourceRef" message_summary: type: string excerpt: type: string runbook_id: type: string nullable: true evidence_href: type: string nullable: true trace_href: type: string nullable: true retention: "$ref": "#/components/schemas/V3PlatformObservabilityRetention" redaction: "$ref": "#/components/schemas/V3PlatformObservabilityLogRedaction" required: - id - occurred_at - source - service - level - owner_domain - correlation_id - request_id - trace_id - span_id - workflow_id - task_id - event_id - target - message_summary - excerpt - runbook_id - evidence_href - trace_href - retention - redaction V3PlatformObservabilityRetention: type: object additionalProperties: false properties: class: type: string expires_at: type: string format: date-time nullable: true required: - class - expires_at V3PlatformObservabilityLogRedaction: type: object additionalProperties: false properties: state: type: string raw_payload_included: type: boolean excluded_fields: type: array items: type: string required: - state - raw_payload_included - excluded_fields V3PlatformObservabilityLogMeta: type: object additionalProperties: false properties: generated_at: type: string format: date-time sources: type: array items: type: string raw_log_payloads_included: type: boolean required: - generated_at - sources - raw_log_payloads_included V3PlatformObservabilityTracesResponse: type: object additionalProperties: false properties: query: "$ref": "#/components/schemas/V3PlatformObservabilityTraceQuery" items: type: array items: "$ref": "#/components/schemas/V3PlatformObservabilityTraceItem" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3PlatformObservabilityTraceMeta" required: - query - items - pagination - meta V3PlatformObservabilityTraceQuery: type: object additionalProperties: false properties: trace_id: type: string correlation_id: type: string request_id: type: string workflow_id: type: string task_id: type: string target_type: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineTargetType" target_id: type: string time_range: type: string V3PlatformObservabilityTraceItem: type: object additionalProperties: false properties: trace_id: type: string root_service: type: string root_operation: type: string status: type: string duration_ms: type: integer format: int64 started_at: type: string format: date-time nullable: true ended_at: type: string format: date-time nullable: true span_count: type: integer error_span_count: type: integer service_count: type: integer owner_domains: type: array items: type: string correlation_id: type: string nullable: true request_id: type: string nullable: true target: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineResourceRef" error_summaries: type: array items: "$ref": "#/components/schemas/V3PlatformObservabilityTraceError" logs_href: type: string nullable: true timeline_href: type: string nullable: true evidence_href: type: string nullable: true tempo_href: type: string nullable: true required: - trace_id - root_service - root_operation - status - duration_ms - started_at - ended_at - span_count - error_span_count - service_count - owner_domains - correlation_id - request_id - target - error_summaries - logs_href - timeline_href - evidence_href - tempo_href V3PlatformObservabilityTraceError: type: object additionalProperties: false properties: service: type: string operation: type: string summary: type: string span_id: type: string nullable: true required: - service - operation - summary - span_id V3PlatformObservabilityTraceMeta: type: object additionalProperties: false properties: generated_at: type: string format: date-time sources: type: array items: type: string raw_trace_spans_included: type: boolean required: - generated_at - sources - raw_trace_spans_included V3PlatformObservabilityPostureStatus: type: string enum: - healthy - degraded - blocked - unknown V3PlatformObservabilityAlertSeverity: type: string enum: - sev1 - sev2 - sev3 - warning - critical - unknown V3PlatformObservabilityAlertState: type: string enum: - firing - resolved - suppressed - unknown - not_loaded V3PlatformObservabilityAlertsResponse: type: object additionalProperties: false properties: overall: "$ref": "#/components/schemas/V3PlatformObservabilityAlertOverall" items: type: array items: "$ref": "#/components/schemas/V3PlatformObservabilityAlertItem" rollups: "$ref": "#/components/schemas/V3PlatformObservabilityAlertRollups" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3PlatformObservabilityAlertMeta" required: - overall - items - rollups - pagination - meta V3PlatformObservabilityAlertOverall: type: object additionalProperties: false properties: status: "$ref": "#/components/schemas/V3PlatformObservabilityPostureStatus" environment_profile: type: string generated_at: type: string format: date-time firing_count: type: integer missing_route_count: type: integer stale_drill_count: type: integer required: - status - environment_profile - generated_at - firing_count - missing_route_count - stale_drill_count V3PlatformObservabilityAlertItem: type: object additionalProperties: false properties: alert_name: type: string state: "$ref": "#/components/schemas/V3PlatformObservabilityAlertState" severity: "$ref": "#/components/schemas/V3PlatformObservabilityAlertSeverity" owner_team: type: string service: type: string domain: type: string signal_key: type: string runbook_id: type: string nullable: true runbook_href: type: string nullable: true summary: type: string last_fired_at: type: string format: date-time nullable: true last_resolved_at: type: string format: date-time nullable: true route: "$ref": "#/components/schemas/V3PlatformObservabilityAlertRoute" drill: "$ref": "#/components/schemas/V3PlatformObservabilityAlertDrill" evidence_href: type: string nullable: true required: - alert_name - state - severity - owner_team - service - domain - signal_key - runbook_id - runbook_href - summary - last_fired_at - last_resolved_at - route - drill - evidence_href V3PlatformObservabilityAlertRoute: type: object additionalProperties: false properties: destination: type: string configured: type: boolean last_verified_at: type: string format: date-time nullable: true required: - destination - configured - last_verified_at V3PlatformObservabilityAlertDrill: type: object additionalProperties: false properties: last_drill_at: type: string format: date-time nullable: true state: type: string required: - last_drill_at - state V3PlatformObservabilityAlertRollups: type: object additionalProperties: false properties: by_severity: type: object additionalProperties: type: integer by_owner_team: type: object additionalProperties: type: integer route_state: type: object additionalProperties: type: integer required: - by_severity - by_owner_team - route_state V3PlatformObservabilityAlertMeta: type: object additionalProperties: false properties: sources: type: array items: type: string raw_prometheus_samples_included: type: boolean notification_secrets_included: type: boolean required: - sources - raw_prometheus_samples_included - notification_secrets_included V3PlatformObservabilitySLOEvidenceResponse: type: object additionalProperties: false properties: overall: "$ref": "#/components/schemas/V3PlatformObservabilitySLOOverall" items: type: array items: "$ref": "#/components/schemas/V3PlatformObservabilitySLOItem" release_gate: "$ref": "#/components/schemas/V3PlatformObservabilitySLOReleaseGate" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3PlatformObservabilitySLOMeta" required: - overall - items - release_gate - pagination - meta V3PlatformObservabilitySLOOverall: type: object additionalProperties: false properties: status: "$ref": "#/components/schemas/V3PlatformObservabilityPostureStatus" environment_profile: type: string generated_at: type: string format: date-time release_id: type: string nullable: true summary: type: string required: - status - environment_profile - generated_at - release_id - summary V3PlatformObservabilitySLOItem: type: object additionalProperties: false properties: slo_id: type: string service: type: string owner_team: type: string objective: "$ref": "#/components/schemas/V3PlatformObservabilitySLOObjective" current: "$ref": "#/components/schemas/V3PlatformObservabilitySLOCurrent" query_outcome: "$ref": "#/components/schemas/V3PlatformObservabilitySLOQueryOutcome" nullable: true alert_coverage: "$ref": "#/components/schemas/V3PlatformObservabilitySLOAlertCoverage" evidence_href: type: string nullable: true required: - slo_id - service - owner_team - objective - current - query_outcome - alert_coverage - evidence_href V3PlatformObservabilitySLOObjective: type: object additionalProperties: false properties: target: type: string unit: type: string window: type: string required: - target - unit - window V3PlatformObservabilitySLOCurrent: type: object additionalProperties: false properties: value: type: string status: type: string error_budget_remaining_percent: type: number nullable: true required: - value - status - error_budget_remaining_percent V3PlatformObservabilitySLOQueryOutcome: type: object additionalProperties: false properties: source: type: string query_id: type: string state: type: string checked_at: type: string format: date-time nullable: true required: - source - query_id - state - checked_at V3PlatformObservabilitySLOAlertCoverage: type: object additionalProperties: false properties: required_alerts: type: array items: type: string loaded: type: boolean route_configured: type: boolean required: - required_alerts - loaded - route_configured V3PlatformObservabilitySLOReleaseGate: type: object additionalProperties: false properties: state: "$ref": "#/components/schemas/V3PlatformObservabilityPostureStatus" blocking_reasons: type: array items: type: string attachable_evidence_href: type: string nullable: true required: - state - blocking_reasons - attachable_evidence_href V3PlatformObservabilitySLOMeta: type: object additionalProperties: false properties: sources: type: array items: type: string raw_prometheus_samples_included: type: boolean grafana_screenshots_required: type: boolean required: - sources - raw_prometheus_samples_included - grafana_screenshots_required V3PlatformBreakglassEvidenceListResponse: type: object additionalProperties: false properties: events: type: array items: "$ref": "#/components/schemas/V3PlatformBreakglassEvidence" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - events - pagination - meta V3PlatformBreakglassEvidenceStage: type: string enum: - activation - approval - expiry - revocation - use_log - post_use_review - unknown V3PlatformBreakglassEvidence: type: object additionalProperties: false properties: evidence_id: type: string elevation_id: type: string nullable: true environment_profile: type: string nullable: true stage: "$ref": "#/components/schemas/V3PlatformBreakglassEvidenceStage" action: type: string result: type: string actor_user_id: type: string nullable: true actor_role: type: string scope_type: type: string nullable: true scope_id: type: string nullable: true operation_class: type: string nullable: true approval_ref: type: string nullable: true incident_ref: type: string nullable: true expires_at: type: string format: date-time nullable: true revoked_at: type: string format: date-time nullable: true reviewed_at: type: string format: date-time nullable: true occurred_at: type: string format: date-time correlation_id: type: string evidence_href: type: string nullable: true post_use_review_required: type: boolean metadata: type: object additionalProperties: true required: - evidence_id - elevation_id - environment_profile - stage - action - result - actor_user_id - actor_role - scope_type - scope_id - operation_class - approval_ref - incident_ref - expires_at - revoked_at - reviewed_at - occurred_at - correlation_id - evidence_href - post_use_review_required - metadata V3PlatformEdgeRouteListResponse: type: object additionalProperties: false properties: routes: type: array items: "$ref": "#/components/schemas/V3PlatformEdgeRouteStatus" summary: "$ref": "#/components/schemas/V3PlatformEdgeRouteSummary" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - routes - summary - pagination - meta V3PlatformEdgeRouteSummary: type: object additionalProperties: false properties: environment_profile: type: string edge_profile: "$ref": "#/components/schemas/V3PlatformEdgeProfile" total: type: integer minimum: 0 healthy: type: integer minimum: 0 degraded: type: integer minimum: 0 unhealthy: type: integer minimum: 0 unknown: type: integer minimum: 0 stale: type: integer minimum: 0 last_smoke_completed_at: type: string format: date-time nullable: true next_action: type: string nullable: true required: - environment_profile - edge_profile - total - healthy - degraded - unhealthy - unknown - stale - last_smoke_completed_at - next_action V3PlatformEdgeRouteStatus: type: object additionalProperties: false description: Provider-neutral edge route readiness row. Provider-native IDs, DNS record payloads, tunnel credentials, tokens, and mutable provider actions are intentionally excluded. properties: route_id: type: string display_name: type: string environment_profile: type: string edge_profile: "$ref": "#/components/schemas/V3PlatformEdgeProfile" route_family: "$ref": "#/components/schemas/V3PlatformEdgeRouteFamily" hostname: type: string target_host: type: string auth_mode: "$ref": "#/components/schemas/V3PlatformEdgeAuthMode" readiness_status: "$ref": "#/components/schemas/V3PlatformEdgeReadinessStatus" dns: "$ref": "#/components/schemas/V3PlatformEdgeCheckStatus" tls: "$ref": "#/components/schemas/V3PlatformEdgeCheckStatus" pomerium: "$ref": "#/components/schemas/V3PlatformEdgeCheckStatus" ingress: "$ref": "#/components/schemas/V3PlatformEdgeCheckStatus" upstream: "$ref": "#/components/schemas/V3PlatformEdgeCheckStatus" evidence_freshness: "$ref": "#/components/schemas/V3PlatformEdgeEvidenceFreshness" last_http_status: type: string nullable: true request_id: type: string nullable: true description: Pomerium or upstream request identifier when present in smoke evidence. ray_id: type: string nullable: true description: Cloudflare Ray/request identifier when present. Null for non-Cloudflare profiles or unavailable evidence. next_action: type: string evidence_href: type: string nullable: true runbook_href: type: string nullable: true checked_at: type: string format: date-time nullable: true required: - route_id - display_name - environment_profile - edge_profile - route_family - hostname - target_host - auth_mode - readiness_status - dns - tls - pomerium - ingress - upstream - evidence_freshness - last_http_status - request_id - ray_id - next_action - evidence_href - runbook_href - checked_at V3PlatformEdgeCheckStatus: type: object additionalProperties: false properties: status: "$ref": "#/components/schemas/V3PlatformEdgeReadinessStatus" summary: type: string observed_at: type: string format: date-time nullable: true evidence_href: type: string nullable: true required: - status - summary - observed_at - evidence_href V3PlatformEdgeEvidenceFreshness: type: object additionalProperties: false properties: state: type: string enum: - fresh - stale - missing latest_completed_at: type: string format: date-time nullable: true max_age_seconds: type: integer format: int64 minimum: 0 source: type: string nullable: true required: - state - latest_completed_at - max_age_seconds - source V3PlatformEdgeProfile: type: string enum: - kind_cloudflare - kind_local_dns - prod_public_ingress - prod_private_ingress - airgapped_private_ca - unknown V3PlatformEdgeRouteFamily: type: string enum: - core - platform_tool - runtime_app - api - authn - unknown V3PlatformEdgeAuthMode: type: string enum: - browser_auth - api_bearer - public - internal - unknown V3PlatformEdgeReadinessStatus: type: string enum: - healthy - degraded - unhealthy - unknown V3DevSecOpsMetricListResponse: type: object additionalProperties: false properties: metrics: type: array items: "$ref": "#/components/schemas/V3DevSecOpsMetric" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - metrics - pagination - meta V3DevSecOpsMetric: type: object additionalProperties: false properties: metric_id: type: string family: "$ref": "#/components/schemas/V3DevSecOpsMetricFamily" environment_profile: type: string product_scope: type: string release_branch: type: string nullable: true source_commit: type: string nullable: true time_window_start: type: string format: date-time nullable: true time_window_end: type: string format: date-time nullable: true value: type: object additionalProperties: true unit: "$ref": "#/components/schemas/V3DevSecOpsMetricUnit" state: "$ref": "#/components/schemas/V3DevSecOpsMetricState" owner: type: string source_uri: type: string nullable: true freshness_seconds: type: integer format: int64 nullable: true max_age_seconds: type: integer format: int64 nullable: true detected_by: type: string nullable: true expected_gate: type: string nullable: true residual_risk: type: string nullable: true next_action: type: string nullable: true required: - metric_id - family - environment_profile - product_scope - release_branch - source_commit - time_window_start - time_window_end - value - unit - state - owner - source_uri - freshness_seconds - max_age_seconds - detected_by - expected_gate - residual_risk - next_action V3DevSecOpsMetricFamily: type: string enum: - pipeline_adoption - scan_enforcement - vulnerability_sla - waiver_hygiene - supply_chain - release_evidence - risk_burn_down - agent_governance V3DevSecOpsMetricState: type: string enum: - pass - fail - partial - blocked - missing - stale - report_only - warning - blocking - not_applicable V3DevSecOpsMetricUnit: type: string enum: - count - percent - seconds - days - ratio - state V3PlatformNodeTrustPostureListResponse: type: object additionalProperties: false properties: nodes: type: array items: "$ref": "#/components/schemas/V3PlatformNodeTrustPosture" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - nodes - pagination - meta V3PlatformNodeTrustPosture: type: object additionalProperties: false properties: node_id: type: string environment_profile: type: string status: type: string enum: - healthy - degraded - unhealthy - unknown cert_expiry_at: type: string format: date-time nullable: true cert_expiry_seconds: type: integer format: int64 nullable: true renewal_status: type: string recovery_status: type: string verifier_versions: type: object additionalProperties: type: string endpoint_profile: type: string diagnostic_freshness_seconds: type: integer format: int64 nullable: true diagnostic_checked_at: type: string format: date-time nullable: true quarantine_reason: type: string nullable: true last_successful_mtls_task_poll_at: type: string format: date-time nullable: true last_renewal_failure_reason: type: string nullable: true last_recovery_failure_reason: type: string nullable: true evidence_href: type: string nullable: true checked_at: type: string format: date-time nullable: true next_action: type: string nullable: true required: - node_id - environment_profile - status - cert_expiry_at - cert_expiry_seconds - renewal_status - recovery_status - verifier_versions - endpoint_profile - diagnostic_freshness_seconds - diagnostic_checked_at - quarantine_reason - last_successful_mtls_task_poll_at - last_renewal_failure_reason - last_recovery_failure_reason - evidence_href - checked_at - next_action V3CertificateSubjectClass: type: string enum: - node_agent - worker - control_plane_server - ingress_wildcard - unknown V3CertificateRenewalStatus: type: string enum: - current - due_soon - renewing - failed - expired - unknown V3CertificateRevocationStatus: type: string enum: - not_revoked - revoked - pending - unknown V3CertificateLifecycleStatus: type: string enum: - healthy - degraded - unhealthy - unknown V3SecretsPKICertificateLifecycleResponse: type: object additionalProperties: false description: Metadata-only Secrets/PKI certificate lifecycle read model. It never includes private key material, CSR private material, raw key PEM, CA private material, or secret-manager values. properties: items: type: array items: "$ref": "#/components/schemas/V3SecretsPKICertificateLifecycleItem" rollups: "$ref": "#/components/schemas/V3SecretsPKICertificateLifecycleRollups" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3SecretsPKICertificateLifecycleMeta" required: - items - rollups - pagination - meta V3SecretsPKICertificateLifecycleItem: type: object additionalProperties: false properties: certificate_id: type: string purpose_id: type: string subject: "$ref": "#/components/schemas/V3SecretsPKICertificateSubject" issuer: "$ref": "#/components/schemas/V3SecretsPKICertificateIssuer" lifecycle: "$ref": "#/components/schemas/V3SecretsPKICertificateLifecycleWindow" ownership: "$ref": "#/components/schemas/V3SecretsPKICertificateOwnership" status: "$ref": "#/components/schemas/V3SecretsPKICertificatePosture" evidence: "$ref": "#/components/schemas/V3SecretsPKICertificateEvidenceLinks" meta: "$ref": "#/components/schemas/V3SecretsPKICertificateItemMeta" required: - certificate_id - purpose_id - subject - issuer - lifecycle - ownership - status - evidence - meta V3SecretsPKICertificateSubject: type: object additionalProperties: false properties: subject_class: "$ref": "#/components/schemas/V3CertificateSubjectClass" subject_ref: type: string common_name: type: string organization: type: string organizational_unit: type: string required: - subject_class - subject_ref - common_name - organization - organizational_unit V3SecretsPKICertificateIssuer: type: object additionalProperties: false properties: issuer: type: string issuer_ref: type: string ca_fingerprint: type: string required: - issuer - issuer_ref - ca_fingerprint V3SecretsPKICertificateLifecycleWindow: type: object additionalProperties: false properties: not_before: type: string format: date-time nullable: true not_after: type: string format: date-time nullable: true remaining_seconds: type: integer format: int64 renewal_status: "$ref": "#/components/schemas/V3CertificateRenewalStatus" renewal_due_at: type: string format: date-time nullable: true last_renewed_at: type: string format: date-time nullable: true revocation_status: "$ref": "#/components/schemas/V3CertificateRevocationStatus" serial_ref: type: string required: - not_before - not_after - remaining_seconds - renewal_status - renewal_due_at - last_renewed_at - revocation_status - serial_ref V3SecretsPKICertificateOwnership: type: object additionalProperties: false properties: owner_domain: type: string rotation_owner: type: string enum: - platform_automated - platform_ops - iam_facade - keycloak_admin - stripe_platform evidence_component_id: type: string required: - owner_domain - rotation_owner - evidence_component_id V3SecretsPKICertificatePosture: type: object additionalProperties: false properties: status: "$ref": "#/components/schemas/V3CertificateLifecycleStatus" blocking_reasons: type: array items: type: string operator_next_action: type: string required: - status - blocking_reasons - operator_next_action V3SecretsPKICertificateEvidenceLinks: type: object additionalProperties: false properties: certificate_lifecycle_href: type: string node_lifecycle_href: type: string audit_href: type: string required: - certificate_lifecycle_href - audit_href V3SecretsPKICertificateItemMeta: type: object additionalProperties: false properties: sources: type: array items: type: string private_key_material_included: type: boolean required: - sources - private_key_material_included V3SecretsPKICertificateLifecycleRollups: type: object additionalProperties: false properties: total: type: integer healthy: type: integer degraded: type: integer unhealthy: type: integer unknown: type: integer due_soon: type: integer expired: type: integer revoked: type: integer required: - total - healthy - degraded - unhealthy - unknown - due_soon - expired - revoked V3SecretsPKICertificateLifecycleMeta: type: object additionalProperties: false properties: private_key_material_included: type: boolean raw_csr_material_included: type: boolean required: - private_key_material_included - raw_csr_material_included V3RegistryPullErrorClass: type: string enum: - registry_auth_denied - registry_unreachable - dns_failure - tls_trust_failure - digest_not_found - manifest_platform_mismatch - pull_timeout - runtime_unavailable - credential_missing - credential_expired - rate_limited - unknown V3RegistryPullDiagnosisResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3RegistryPullDiagnosisItem" rollups: "$ref": "#/components/schemas/V3RegistryPullDiagnosisRollups" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3RegistryPullDiagnosisMeta" required: - items - rollups - pagination - meta V3RegistryPullDiagnosisItem: type: object additionalProperties: false properties: diagnosis_id: type: string artifact: "$ref": "#/components/schemas/V3RegistryPullDiagnosisArtifact" target: "$ref": "#/components/schemas/V3RegistryPullDiagnosisTarget" runtime: "$ref": "#/components/schemas/V3RegistryPullDiagnosisRuntime" failure: "$ref": "#/components/schemas/V3RegistryPullDiagnosisFailure" credential: "$ref": "#/components/schemas/V3RegistryPullDiagnosisCredential" evidence: "$ref": "#/components/schemas/V3RegistryPullDiagnosisEvidence" next_action: "$ref": "#/components/schemas/V3RegistryPullDiagnosisNextAction" required: - diagnosis_id - artifact - target - runtime - failure - credential - evidence - next_action V3RegistryPullDiagnosisArtifact: type: object additionalProperties: false properties: artifact_id: type: string artifact_name: type: string artifact_ref: type: string digest: type: string source_type: type: string required: - artifact_id - artifact_name - artifact_ref - digest - source_type V3RegistryPullDiagnosisTarget: type: object additionalProperties: false properties: environment_profile: type: string node_id: type: string node_name: type: string allocation_id: type: string workload_id: type: string app_slug: type: string app_version: type: string required: - environment_profile - node_id - node_name - allocation_id - workload_id - app_slug - app_version V3RegistryPullDiagnosisRuntime: type: object additionalProperties: false properties: task_id: type: string task_type: type: string workflow_id: type: string worker: type: string engine: type: string required: - task_id - task_type - workflow_id - worker - engine V3RegistryPullDiagnosisFailure: type: object additionalProperties: false properties: error_class: "$ref": "#/components/schemas/V3RegistryPullErrorClass" summary: type: string last_seen_at: type: string format: date-time nullable: true retryable: type: boolean required: - error_class - summary - last_seen_at - retryable V3RegistryPullDiagnosisCredential: type: object additionalProperties: false properties: purpose_id: type: string delivery_mode: type: string present: type: boolean expired: type: boolean secret_href: type: string nullable: true required: - purpose_id - delivery_mode - present - expired - secret_href V3RegistryPullDiagnosisEvidence: type: object additionalProperties: false properties: node_task_href: type: string logs_href: type: string artifact_status_href: type: string trust_href: type: string required: - node_task_href - logs_href - artifact_status_href - trust_href V3RegistryPullDiagnosisNextAction: type: object additionalProperties: false properties: action: type: string owner: type: string runbook_id: type: string safe_to_retry: type: boolean required: - action - owner - runbook_id - safe_to_retry V3RegistryPullDiagnosisRollups: type: object additionalProperties: false properties: total: type: integer retryable: type: integer registry_auth_denied: type: integer tls_trust_failure: type: integer pull_timeout: type: integer credential_missing: type: integer registry_unreachable: type: integer dns_failure: type: integer digest_not_found: type: integer manifest_platform_mismatch: type: integer runtime_unavailable: type: integer credential_expired: type: integer rate_limited: type: integer unknown: type: integer required: - total - retryable - registry_auth_denied - tls_trust_failure - pull_timeout - credential_missing - registry_unreachable - dns_failure - digest_not_found - manifest_platform_mismatch - runtime_unavailable - credential_expired - rate_limited - unknown V3RegistryPullDiagnosisMeta: type: object additionalProperties: false properties: sources: type: array items: type: string secret_material_included: type: boolean required: - sources - secret_material_included V3PlatformVaultReadinessStatus: type: string enum: - healthy - degraded - unhealthy - unknown V3PlatformVaultReadCheck: type: string enum: - pass - fail - skipped - unknown - not_checked V3PlatformVaultReadinessListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3PlatformVaultReadinessItem" rollups: "$ref": "#/components/schemas/V3PlatformVaultReadinessRollups" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3PlatformVaultReadinessMeta" required: - items - rollups - pagination - meta V3PlatformVaultReadinessItem: type: object additionalProperties: false properties: environment_profile: type: string cluster_id: type: string vault: "$ref": "#/components/schemas/V3PlatformVaultStatusSummary" mounts: type: array items: "$ref": "#/components/schemas/V3PlatformVaultMountReadiness" policies: type: array items: "$ref": "#/components/schemas/V3PlatformVaultPolicyReadiness" preflight: "$ref": "#/components/schemas/V3PlatformVaultPreflightReadiness" status: "$ref": "#/components/schemas/V3PlatformVaultOperatorStatus" evidence: "$ref": "#/components/schemas/V3PlatformVaultReadinessEvidence" meta: "$ref": "#/components/schemas/V3PlatformVaultReadinessMeta" required: - environment_profile - cluster_id - vault - mounts - policies - preflight - status - evidence - meta V3PlatformVaultStatusSummary: type: object additionalProperties: false properties: initialized: type: boolean sealed: type: boolean ha_enabled: type: boolean storage_ready: type: boolean last_status_at: type: string format: date-time nullable: true required: - initialized - sealed - ha_enabled - storage_ready - last_status_at V3PlatformVaultMountReadiness: type: object additionalProperties: false properties: mount: type: string expected: type: boolean present: type: boolean read_check: "$ref": "#/components/schemas/V3PlatformVaultReadCheck" write_check: "$ref": "#/components/schemas/V3PlatformVaultReadCheck" purpose_ids: type: array items: type: string evidence_href: type: string nullable: true required: - mount - expected - present - read_check - write_check - purpose_ids V3PlatformVaultPolicyReadiness: type: object additionalProperties: false properties: policy_id: type: string expected: type: boolean present: type: boolean read_check: "$ref": "#/components/schemas/V3PlatformVaultReadCheck" scope: type: string evidence_href: type: string nullable: true required: - policy_id - expected - present - read_check - scope V3PlatformVaultPreflightReadiness: type: object additionalProperties: false properties: deploy_preflight_status: "$ref": "#/components/schemas/V3PlatformVaultReadCheck" last_deploy_run_id: type: string nullable: true last_checked_at: type: string format: date-time nullable: true safe_status_logged: type: boolean required: - deploy_preflight_status - last_deploy_run_id - last_checked_at - safe_status_logged V3PlatformVaultOperatorStatus: type: object additionalProperties: false properties: status: "$ref": "#/components/schemas/V3PlatformVaultReadinessStatus" blocking_reasons: type: array items: type: string operator_next_action: type: string runbook_href: type: string required: - status - blocking_reasons - operator_next_action - runbook_href V3PlatformVaultReadinessEvidence: type: object additionalProperties: false properties: readiness_evidence_href: type: string nullable: true deploy_preflight_href: type: string nullable: true breakglass_evidence_href: type: string nullable: true required: - readiness_evidence_href - deploy_preflight_href - breakglass_evidence_href V3PlatformVaultReadinessRollups: type: object additionalProperties: false properties: total: type: integer healthy: type: integer degraded: type: integer unhealthy: type: integer unknown: type: integer sealed: type: integer missing_mounts: type: integer failed_read_checks: type: integer required: - total - healthy - degraded - unhealthy - unknown - sealed - missing_mounts - failed_read_checks V3PlatformVaultReadinessMeta: type: object additionalProperties: false properties: sources: type: array items: type: string secret_material_included: type: boolean root_or_unseal_material_included: type: boolean read_model: "$ref": "#/components/schemas/V3ReadModelMeta" required: - secret_material_included - root_or_unseal_material_included V3PlatformRotationEvidenceResult: type: string enum: - success - failed - partial - skipped - unknown V3PlatformRotationEvidenceListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3PlatformRotationEvidenceItem" rollups: "$ref": "#/components/schemas/V3PlatformRotationEvidenceRollups" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3PlatformRotationEvidenceMeta" required: - items - rollups - pagination - meta V3PlatformRotationEvidenceItem: type: object additionalProperties: false properties: rotation_id: type: string purpose_id: type: string environment_profile: type: string rotation: "$ref": "#/components/schemas/V3PlatformRotationEvidenceSummary" actor: "$ref": "#/components/schemas/V3PlatformRotationEvidenceActor" approval: "$ref": "#/components/schemas/V3PlatformRotationEvidenceApproval" version_refs: "$ref": "#/components/schemas/V3PlatformRotationEvidenceVersionRefs" validation: "$ref": "#/components/schemas/V3PlatformRotationEvidenceValidation" audit: "$ref": "#/components/schemas/V3PlatformRotationEvidenceAudit" evidence: "$ref": "#/components/schemas/V3PlatformRotationEvidenceLinks" meta: "$ref": "#/components/schemas/V3PlatformRotationEvidenceMeta" required: - rotation_id - purpose_id - environment_profile - rotation - actor - approval - version_refs - validation - audit - evidence - meta V3PlatformRotationEvidenceSummary: type: object additionalProperties: false properties: rotation_owner: type: string started_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true result: "$ref": "#/components/schemas/V3PlatformRotationEvidenceResult" next_due_at: type: string format: date-time nullable: true grace_exception: type: boolean required: - rotation_owner - started_at - completed_at - result - next_due_at - grace_exception V3PlatformRotationEvidenceActor: type: object additionalProperties: false properties: actor_user_id: type: string actor_role: type: string actor_type: type: string required: - actor_user_id - actor_role - actor_type V3PlatformRotationEvidenceApproval: type: object additionalProperties: false properties: approval_ref: type: string nullable: true approval_required: type: boolean approved_by: type: string nullable: true approved_at: type: string format: date-time nullable: true required: - approval_ref - approval_required - approved_by - approved_at V3PlatformRotationEvidenceVersionRefs: type: object additionalProperties: false properties: old_version_ref: type: string nullable: true new_version_ref: type: string nullable: true old_value_exposed: type: boolean new_value_exposed: type: boolean required: - old_version_ref - new_version_ref - old_value_exposed - new_value_exposed V3PlatformRotationValidationCheck: type: object additionalProperties: false properties: check_id: type: string status: "$ref": "#/components/schemas/V3PlatformVaultReadCheck" summary: type: string required: - check_id - status - summary V3PlatformRotationEvidenceValidation: type: object additionalProperties: false properties: checks: type: array items: "$ref": "#/components/schemas/V3PlatformRotationValidationCheck" post_rotation_smoke_status: "$ref": "#/components/schemas/V3PlatformVaultReadCheck" required: - checks - post_rotation_smoke_status V3PlatformRotationEvidenceAudit: type: object additionalProperties: false properties: audit_action: type: string audit_href: type: string nullable: true correlation_id: type: string nullable: true required: - audit_action - audit_href - correlation_id V3PlatformRotationEvidenceLinks: type: object additionalProperties: false properties: status_href: type: string nullable: true custody_href: type: string nullable: true runbook_href: type: string required: - status_href - custody_href - runbook_href V3PlatformRotationEvidenceRollups: type: object additionalProperties: false properties: total: type: integer success: type: integer failed: type: integer partial: type: integer skipped: type: integer unknown: type: integer grace_exceptions: type: integer overdue_next_rotation: type: integer required: - total - success - failed - partial - skipped - unknown - grace_exceptions - overdue_next_rotation V3PlatformRotationEvidenceMeta: type: object additionalProperties: false properties: sources: type: array items: type: string secret_material_included: type: boolean raw_provider_output_included: type: boolean read_model: "$ref": "#/components/schemas/V3ReadModelMeta" required: - secret_material_included - raw_provider_output_included V3PlatformSecretsPKIBreakglassEvidenceListResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3PlatformSecretsPKIBreakglassEvidenceItem" rollups: "$ref": "#/components/schemas/V3PlatformSecretsPKIBreakglassEvidenceRollups" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3PlatformVaultReadinessMeta" required: - items - rollups - pagination - meta V3PlatformSecretsPKIBreakglassStatus: type: string enum: - open - remediating - closed - overdue - rejected - unknown V3PlatformSecretsPKIBreakglassEvidenceItem: type: object additionalProperties: false properties: breakglass_id: type: string environment_profile: type: string approval: "$ref": "#/components/schemas/V3PlatformSecretsPKIBreakglassApproval" actor: "$ref": "#/components/schemas/V3PlatformRotationEvidenceActor" scope: "$ref": "#/components/schemas/V3PlatformSecretsPKIBreakglassScope" window: "$ref": "#/components/schemas/V3PlatformSecretsPKIBreakglassWindow" actions: type: array items: "$ref": "#/components/schemas/V3PlatformSecretsPKIBreakglassAction" remediation: "$ref": "#/components/schemas/V3PlatformSecretsPKIBreakglassRemediation" audit: "$ref": "#/components/schemas/V3PlatformSecretsPKIBreakglassAudit" evidence: "$ref": "#/components/schemas/V3PlatformSecretsPKIBreakglassEvidenceLinks" meta: "$ref": "#/components/schemas/V3PlatformVaultReadinessMeta" required: - breakglass_id - environment_profile - approval - actor - scope - window - actions - remediation - audit - evidence - meta V3PlatformSecretsPKIBreakglassApproval: type: object additionalProperties: false properties: approval_ref: type: string nullable: true approved_by: type: string nullable: true approved_at: type: string format: date-time nullable: true reason: type: string required: - approval_ref - approved_by - approved_at - reason V3PlatformSecretsPKIBreakglassScope: type: object additionalProperties: false properties: scope: type: string systems: type: array items: type: string purpose_ids: type: array items: type: string mutation_allowed: type: boolean required: - scope - systems - purpose_ids - mutation_allowed V3PlatformSecretsPKIBreakglassWindow: type: object additionalProperties: false properties: opened_at: type: string format: date-time nullable: true expires_at: type: string format: date-time nullable: true closed_at: type: string format: date-time nullable: true status: "$ref": "#/components/schemas/V3PlatformSecretsPKIBreakglassStatus" required: - opened_at - expires_at - closed_at - status V3PlatformSecretsPKIBreakglassAction: type: object additionalProperties: false properties: action_id: type: string action_type: type: string result: "$ref": "#/components/schemas/V3PlatformRotationEvidenceResult" safe_output_only: type: boolean required: - action_id - action_type - result - safe_output_only V3PlatformSecretsPKIBreakglassRemediation: type: object additionalProperties: false properties: root_token_replaced: type: boolean runtime_root_token_usage_removed: type: boolean operational_token_verified: type: boolean deploy_retried_from_ci: type: boolean post_action_review_ref: type: string nullable: true required: - root_token_replaced - runtime_root_token_usage_removed - operational_token_verified - deploy_retried_from_ci - post_action_review_ref V3PlatformSecretsPKIBreakglassAudit: type: object additionalProperties: false properties: audit_href: type: string nullable: true correlation_id: type: string nullable: true required: - audit_href - correlation_id V3PlatformSecretsPKIBreakglassEvidenceLinks: type: object additionalProperties: false properties: runbook_href: type: string vault_readiness_href: type: string nullable: true rotation_evidence_href: type: string nullable: true required: - runbook_href - vault_readiness_href - rotation_evidence_href V3PlatformSecretsPKIBreakglassEvidenceRollups: type: object additionalProperties: false properties: total: type: integer open: type: integer remediating: type: integer closed: type: integer overdue: type: integer rejected: type: integer unknown: type: integer missing_remediation: type: integer required: - total - open - remediating - closed - overdue - rejected - unknown - missing_remediation V3SecretsPKIMaterialKind: type: string enum: - certificate - service_token - provider_credential - runtime_secret - signing_key V3SecretsPKICustodyTool: type: string enum: - vault - step_ca - cert_manager - kubernetes_secret V3SecretsPKIDeliveryMode: type: string enum: - vault_wrapped - mounted_secret - runtime_injection - certificate_renewal V3SecretsPKIRotationOwner: type: string enum: - platform_automated - platform_ops - iam_facade - keycloak_admin - stripe_platform V3SecretsPKIStorageTier: type: string enum: - vault_transit - vault_kv - kubernetes_secret - ephemeral V3SecretsPKILifecycle: type: string enum: - draft - active - deprecated - retired V3SecretsPKIPurposeStatus: type: string enum: - healthy - degraded - unhealthy - unknown V3SecretsPKIPurposeInventoryResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3SecretsPKIPurposeInventoryItem" rollups: "$ref": "#/components/schemas/V3SecretsPKIPurposeInventoryRollups" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3SecretsPKIPurposeInventoryMeta" required: - items - rollups - pagination - meta V3SecretsPKIPurposeInventoryItem: type: object additionalProperties: false properties: purpose_id: type: string owner_product_id: type: string material_kind: "$ref": "#/components/schemas/V3SecretsPKIMaterialKind" custody: "$ref": "#/components/schemas/V3SecretsPKIPurposeCustody" rotation: "$ref": "#/components/schemas/V3SecretsPKIPurposeRotation" evidence: "$ref": "#/components/schemas/V3SecretsPKIPurposeEvidence" controls: "$ref": "#/components/schemas/V3SecretsPKIPurposeControls" meta: "$ref": "#/components/schemas/V3SecretsPKIPurposeItemMeta" required: - purpose_id - owner_product_id - material_kind - custody - rotation - evidence - controls - meta V3SecretsPKIPurposeCustody: type: object additionalProperties: false properties: custody_tool: "$ref": "#/components/schemas/V3SecretsPKICustodyTool" storage_tier: "$ref": "#/components/schemas/V3SecretsPKIStorageTier" delivery_mode: "$ref": "#/components/schemas/V3SecretsPKIDeliveryMode" one_time_reveal: type: boolean product_custody_allowed: type: boolean required: - custody_tool - storage_tier - delivery_mode - one_time_reveal - product_custody_allowed V3SecretsPKIPurposeRotation: type: object additionalProperties: false properties: rotation_owner: "$ref": "#/components/schemas/V3SecretsPKIRotationOwner" rotation_period: type: string description: Human-readable rotation cadence, for example 24h, 30d, or 90d. grace_period: type: string next_due_at: type: string format: date-time nullable: true last_rotated_at: type: string format: date-time nullable: true required: - rotation_owner - rotation_period - grace_period - next_due_at - last_rotated_at V3SecretsPKIPurposeEvidence: type: object additionalProperties: false properties: evidence_component_id: type: string status: "$ref": "#/components/schemas/V3SecretsPKIPurposeStatus" status_reason: type: string status_href: type: string nullable: true rotation_evidence_href: type: string nullable: true audit_href: type: string required: - evidence_component_id - status - status_reason - status_href - rotation_evidence_href - audit_href V3SecretsPKIPurposeControls: type: object additionalProperties: false properties: audit_action: type: string revocation_path_ref: type: string emergency_disable_action: type: string lifecycle: "$ref": "#/components/schemas/V3SecretsPKILifecycle" required: - audit_action - revocation_path_ref - emergency_disable_action - lifecycle V3SecretsPKIPurposeItemMeta: type: object additionalProperties: false properties: sources: type: array items: type: string secret_material_included: type: boolean enum: - false required: - sources - secret_material_included V3SecretsPKIPurposeInventoryRollups: type: object additionalProperties: false properties: total: type: integer healthy: type: integer degraded: type: integer unhealthy: type: integer unknown: type: integer one_time_reveal: type: integer product_custody_exceptions: type: integer required: - total - healthy - degraded - unhealthy - unknown - one_time_reveal - product_custody_exceptions V3SecretsPKIPurposeInventoryMeta: type: object additionalProperties: false properties: environment_profile: type: string secret_material_included: type: boolean enum: - false raw_vault_material_included: type: boolean enum: - false generated_at: type: string format: date-time registry_source: type: string runtime_evidence_source: type: string missing_evidence_classifies_as: "$ref": "#/components/schemas/V3SecretsPKIPurposeStatus" required: - environment_profile - secret_material_included - raw_vault_material_included - generated_at - registry_source - runtime_evidence_source - missing_evidence_classifies_as V3PlatformRegistryAppArtifactKind: type: string enum: - oci - model - dataset - bundle - unknown V3PlatformRegistryAppArtifactSourceType: type: string enum: - oci_registry - platform_registry - external_registry - uploaded - unknown V3PlatformRegistryAppArtifactTrustState: type: string enum: - verified - pending - failed - waived - unknown V3PlatformRegistryAppArtifactApp: type: object additionalProperties: false properties: app_slug: type: string app_version: type: string catalog_status: type: string manifest_profile_kind: type: string required: - app_slug - app_version - catalog_status - manifest_profile_kind V3PlatformRegistryAppArtifactRef: type: object additionalProperties: false properties: artifact_id: type: string artifact_name: type: string artifact_kind: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactKind" source_type: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactSourceType" repository: type: string image_ref: type: string digest: type: string platform_os: type: string platform_arch: type: string required: - artifact_id - artifact_name - artifact_kind - source_type - repository - image_ref - digest - platform_os - platform_arch V3PlatformRegistryAppArtifactOwnership: type: object additionalProperties: false properties: org_id: type: string project_id: type: string visibility: type: string required: - org_id - project_id - visibility V3PlatformRegistryAppArtifactTrust: type: object additionalProperties: false properties: trust_state: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactTrustState" artifact_trust_href: type: string nullable: true required: - trust_state - artifact_trust_href V3PlatformRegistryAppArtifactLaunch: type: object additionalProperties: false properties: launch_eligible: type: boolean eligibility_reasons: type: array items: type: string required_manifest_artifact: type: boolean digest_required: type: boolean allocation_arch_compatible: type: boolean last_validation_at: type: string format: date-time nullable: true required: - launch_eligible - eligibility_reasons - required_manifest_artifact - digest_required - allocation_arch_compatible - last_validation_at V3PlatformRegistryAppArtifactEvidence: type: object additionalProperties: false properties: launch_contract_href: type: string nullable: true sdk_contract_href: type: string nullable: true pull_diagnosis_href: type: string nullable: true required: - launch_contract_href - sdk_contract_href - pull_diagnosis_href V3PlatformRegistryAppArtifactItem: type: object additionalProperties: false properties: app: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactApp" artifact: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactRef" ownership: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactOwnership" trust: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactTrust" launch: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactLaunch" evidence: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactEvidence" required: - app - artifact - ownership - trust - launch - evidence V3PlatformRegistryAppArtifactRollups: type: object additionalProperties: false properties: launch_eligible: type: integer not_eligible: type: integer missing_digest: type: integer trust_not_verified: type: integer arch_mismatch: type: integer missing_manifest_artifact: type: integer required: - launch_eligible - not_eligible - missing_digest - trust_not_verified - arch_mismatch - missing_manifest_artifact V3PlatformRegistryAppArtifactMeta: type: object additionalProperties: false properties: sources: type: array items: type: string credential_material_included: type: boolean required: - sources - credential_material_included V3PlatformRegistryAppArtifactsResponse: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactItem" rollups: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactRollups" pagination: "$ref": "#/components/schemas/Pagination" meta: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactMeta" required: - items - rollups - pagination - meta V3PlatformIAMMFAReadinessResponse: type: object additionalProperties: false description: Read-only MFA product-readiness posture for platform operators. Provider and claim states are intentionally fail-closed when no accepted sanitized evidence snapshot exists. properties: summary: "$ref": "#/components/schemas/V3PlatformIAMMFAReadinessSummary" provider: "$ref": "#/components/schemas/V3PlatformIAMMFAProviderState" population: "$ref": "#/components/schemas/V3PlatformIAMMFAPopulation" drift: "$ref": "#/components/schemas/V3PlatformIAMMFADrift" reset: "$ref": "#/components/schemas/V3PlatformIAMMFAStateBlock" rollback: "$ref": "#/components/schemas/V3PlatformIAMMFAStateBlock" break_glass: "$ref": "#/components/schemas/V3PlatformIAMMFABreakGlass" claim_proof: "$ref": "#/components/schemas/V3PlatformIAMMFATaskState" superadmin_phishing_resistant: "$ref": "#/components/schemas/V3PlatformIAMMFASuperadminPhishingResistant" sensitive_gate: "$ref": "#/components/schemas/V3PlatformIAMMFASensitiveGate" step_up_runtime: "$ref": "#/components/schemas/V3PlatformIAMMFAStepUpRuntime" non_human_exclusions: "$ref": "#/components/schemas/V3PlatformIAMMFANonHumanExclusions" operations: type: array items: "$ref": "#/components/schemas/V3PlatformIAMMFADisabledOperation" evidence: "$ref": "#/components/schemas/V3PlatformIAMMFAEvidence" meta: "$ref": "#/components/schemas/V3ReadModelMeta" required: - summary - provider - population - drift - reset - rollback - break_glass - claim_proof - superadmin_phishing_resistant - sensitive_gate - step_up_runtime - non_human_exclusions - operations - evidence - meta V3PlatformIAMMFAReadinessSummary: type: object additionalProperties: false properties: policy_posture: type: string enum: - not_configured - configured - partial - blocked - unknown - error compliance_state: type: string enum: - compliant - non_compliant - not_applicable reason: type: string target_privileged_humans: type: integer minimum: 0 provider_unqueried: type: integer minimum: 0 non_human_excluded: type: integer minimum: 0 required: - policy_posture - compliance_state - reason - target_privileged_humans - provider_unqueried - non_human_excluded V3PlatformIAMMFAProviderState: type: object additionalProperties: false properties: state: "$ref": "#/components/schemas/V3PlatformIAMMFAEvidenceState" source_realm_state: "$ref": "#/components/schemas/V3PlatformIAMMFAEvidenceState" flow_readback_state: "$ref": "#/components/schemas/V3PlatformIAMMFAEvidenceState" selector_state: "$ref": "#/components/schemas/V3PlatformIAMMFAEvidenceState" factor_snapshot_state: "$ref": "#/components/schemas/V3PlatformIAMMFAEvidenceState" last_readback_at: type: string format: date-time nullable: true last_evidence_ref: type: string nullable: true evidence_href: type: string per_request_provider_query: type: boolean required: - state - source_realm_state - flow_readback_state - selector_state - factor_snapshot_state - last_readback_at - last_evidence_ref - evidence_href - per_request_provider_query V3PlatformIAMMFAEvidenceState: type: string enum: - configured - pass - blocked - unknown - provider_unqueried - provider_pending - stale - error V3PlatformIAMMFAPopulation: type: object additionalProperties: false properties: human_users: type: integer minimum: 0 platform_superadmin: type: integer minimum: 0 platform_admin: type: integer minimum: 0 platform_ops: type: integer minimum: 0 privileged_humans: type: integer minimum: 0 normal_humans: type: integer minimum: 0 non_human_not_applicable: type: integer minimum: 0 required: - human_users - platform_superadmin - platform_admin - platform_ops - privileged_humans - normal_humans - non_human_not_applicable V3PlatformIAMMFADrift: type: object additionalProperties: false properties: selector_missing: type: integer minimum: 0 factor_missing: type: integer minimum: 0 provider_unqueried: type: integer minimum: 0 provider_pending: type: integer minimum: 0 stale: type: integer minimum: 0 error: type: integer minimum: 0 compliant: type: integer minimum: 0 rows: type: array items: "$ref": "#/components/schemas/V3PlatformIAMMFADriftRow" required: - selector_missing - factor_missing - provider_unqueried - provider_pending - stale - error - compliant - rows V3PlatformIAMMFADriftRow: type: object additionalProperties: false properties: user_id: type: string format: uuid username: type: string platform_role: type: string selector_state: "$ref": "#/components/schemas/V3PlatformIAMMFAEvidenceState" factor_state: "$ref": "#/components/schemas/V3PlatformIAMMFAEvidenceState" evidence_href: type: string nullable: true required: - user_id - username - platform_role - selector_state - factor_state - evidence_href V3PlatformIAMMFAStateBlock: type: object additionalProperties: false properties: state: type: string compliance_state: type: string enum: - compliant - non_compliant - not_applicable nullable: true readiness: type: string nullable: true last_proof_ref: type: string nullable: true evidence_href: type: string required: - state - compliance_state - readiness - last_proof_ref - evidence_href V3PlatformIAMMFABreakGlass: type: object additionalProperties: false properties: state: type: string owner_present: type: boolean approver_present: type: boolean expiry_present: type: boolean custody_class_present: type: boolean evidence_href: type: string required: - state - owner_present - approver_present - expiry_present - custody_class_present - evidence_href V3PlatformIAMMFATaskState: type: object additionalProperties: false properties: state: type: string task_id: type: string reason: type: string evidence_href: type: string required: - state - task_id - reason - evidence_href V3PlatformIAMMFASensitiveGate: type: object additionalProperties: false properties: availability: type: string enum: - unavailable - blocked - proof_pending - ready_for_design - implemented state: type: string task_id: type: string reason: type: string required: - availability - state - task_id - reason V3PlatformIAMMFASuperadminPhishingResistant: type: object additionalProperties: false properties: state: type: string enum: - blocked - exception_required - proven - not_applicable required_superadmins: type: integer minimum: 0 proven_superadmins: type: integer minimum: 0 exception_superadmins: type: integer minimum: 0 task_id: type: string reason: type: string evidence_href: type: string required: - state - required_superadmins - proven_superadmins - exception_superadmins - task_id - reason - evidence_href V3PlatformIAMMFAStepUpRuntime: type: object additionalProperties: false properties: state: type: string enum: - blocked - design_ready - implemented enforcement_state: type: string enum: - not_enforced - fail_closed - enforcing catalog_state: type: string enum: - missing - partial - accepted representative_operation: type: string task_id: type: string reason: type: string evidence_href: type: string required: - state - enforcement_state - catalog_state - representative_operation - task_id - reason - evidence_href V3PlatformIAMMFANonHumanExclusions: type: object additionalProperties: false properties: state: type: string enum: - excluded - unknown - error service_accounts: type: integer minimum: 0 api_keys: type: integer minimum: 0 role_bindings: type: integer minimum: 0 requirement_state: type: string enum: - not_applicable - unknown - error reason: type: string required: - state - service_accounts - api_keys - role_bindings - requirement_state - reason V3PlatformIAMMFADisabledOperation: type: object additionalProperties: false properties: key: type: string label: type: string enabled: type: boolean disabled_reason: type: string method: type: string nullable: true href: type: string nullable: true required: - key - label - enabled - disabled_reason - method - href V3PlatformIAMMFAEvidence: type: object additionalProperties: false properties: artifact_refs: type: array items: "$ref": "#/components/schemas/V3PlatformIAMMFAEvidenceRef" runtime_audit_state: "$ref": "#/components/schemas/V3PlatformIAMMFAEvidenceState" required: - artifact_refs - runtime_audit_state V3PlatformIAMMFAEvidenceRef: type: object additionalProperties: false properties: label: type: string href: type: string state: type: string required: - label - href - state V3PlatformIAMMFAFactorResetRequest: type: object additionalProperties: false properties: target_user_id: type: string format: uuid requested_action: type: string enum: - force_reenroll - remove_lost_factor reason: type: string maxLength: 500 ticket_id: type: string maxLength: 200 nullable: true description: Support or approval ticket reference. At least one of ticket_id or evidence_ref must be present. evidence_ref: type: string maxLength: 500 nullable: true description: Sanitized evidence or packet reference. At least one of ticket_id or evidence_ref must be present. required: - target_user_id - requested_action - reason V3PlatformIAMMFAFactorResetRequestResponse: type: object additionalProperties: false properties: request_id: type: string status: type: string enum: - submitted execution_state: type: string enum: - packet_required support_required: type: boolean approval_required: type: boolean target_user_id: type: string format: uuid requested_action: type: string enum: - force_reenroll - remove_lost_factor evidence_href: type: string audit_action: type: string message: type: string required: - request_id - status - execution_state - support_required - approval_required - target_user_id - requested_action - evidence_href - audit_action - message responses: BadRequest: description: Bad request content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" Unauthorized: description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" Forbidden: description: Forbidden content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" NotFound: description: Not found content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" Conflict: description: Conflict content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" ServiceUnavailable: description: Service unavailable content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" TooManyRequests: description: Too many requests — rate limit exceeded headers: X-RateLimit-Limit: schema: type: integer description: Request limit per window. X-RateLimit-Remaining: schema: type: integer description: Requests remaining in current window. Retry-After: schema: type: integer description: Seconds until the rate limit window resets. content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" paths: "/api/v1/bootstrap/nodes/{bootstrap_token}/script": get: tags: - InternalNodes operationId: nodeBootstrapScript security: [] summary: Fetch brokered node bootstrap script using a node-bound bootstrap token parameters: - "$ref": "#/components/parameters/XRequestId" - name: bootstrap_token in: path required: true schema: type: string minLength: 1 - name: mode in: query schema: type: string enum: - manual - cloud_init default: manual responses: '200': description: Shell script content: text/plain: schema: type: string '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/bootstrap/nodes/{bootstrap_token}/package": get: tags: - InternalNodes operationId: nodeBootstrapPackage security: [] summary: Download brokered node bootstrap package using a node-bound bootstrap token parameters: - "$ref": "#/components/parameters/XRequestId" - name: bootstrap_token in: path required: true schema: type: string minLength: 1 - name: arch in: query required: false description: Worker CPU architecture. Omitted defaults to the environment default bootstrap package. schema: type: string enum: - amd64 - arm64 - x86_64 - aarch64 responses: '200': description: Bootstrap package archive content: application/gzip: schema: type: string format: binary '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/bootstrap/nodes/{bootstrap_token}/registry-credential": get: tags: - InternalNodes operationId: nodeBootstrapRegistryCredential security: [] summary: Fetch brokered registry pull credential using a node-bound bootstrap token parameters: - "$ref": "#/components/parameters/XRequestId" - name: bootstrap_token in: path required: true schema: type: string minLength: 1 responses: '200': description: Registry pull credential for node bootstrap runtime configuration content: application/json: schema: "$ref": "#/components/schemas/NodeBootstrapRegistryCredential" '204': description: No registry pull credential is configured for this environment '401': "$ref": "#/components/responses/Unauthorized" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/bootstrap/nodes/{bootstrap_token}/progress": post: tags: - InternalNodes operationId: nodeBootstrapProgress security: [] summary: Report first-boot MAAS bootstrap progress using a node-bound bootstrap token parameters: - "$ref": "#/components/parameters/XRequestId" - name: bootstrap_token in: path required: true schema: type: string minLength: 1 requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/NodeBootstrapProgressRequest" responses: '202': description: Progress marker accepted content: application/json: schema: "$ref": "#/components/schemas/NodeBootstrapProgressResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '503': "$ref": "#/components/responses/ServiceUnavailable" "/internal/v1/nodes/enroll": post: tags: - InternalNodes operationId: internalNodeEnroll security: [] summary: Internal node enrollment endpoint (token-authenticated bootstrap) parameters: - "$ref": "#/components/parameters/XRequestId" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/InternalNodeEnrollmentRequest" responses: '200': description: Enrollment certificate bundle content: application/json: schema: "$ref": "#/components/schemas/InternalNodeEnrollmentResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/internal/v1/nodes/{node_id}/cert/renew": post: tags: - InternalNodes operationId: internalNodeCertRenew security: [] summary: Internal node certificate renewal endpoint (mTLS-authenticated) parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/InternalNodeIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/InternalNodeCertRenewRequest" responses: '200': description: Renewed certificate content: application/json: schema: "$ref": "#/components/schemas/InternalNodeCertRenewResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/internal/v1/nodes/{node_id}/tasks/wait": get: tags: - InternalNodes operationId: internalNodeWaitTask security: [] summary: Internal long-poll endpoint for node task dispatch parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/InternalNodeIdPath" responses: '200': description: Task available content: application/json: schema: "$ref": "#/components/schemas/InternalNodeTask" '204': description: No task currently available '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/internal/v1/nodes/{node_id}/tasks/{task_id}/result": post: tags: - InternalNodes operationId: internalNodeTaskResult security: [] summary: Internal endpoint for node task completion reporting parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/InternalNodeIdPath" - "$ref": "#/components/parameters/InternalTaskIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/InternalNodeTaskResultRequest" responses: '200': description: Task result accepted content: application/json: schema: "$ref": "#/components/schemas/InternalNodeTaskResultResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/internal/v1/nodes/{node_id}/terminal/stream": post: tags: - InternalNodes operationId: internalNodeTerminalStream security: [] summary: Internal bidirectional relay stream for terminal frames description: | Internal-only stream channel used by terminal relay mode (`TERMINAL_MODE=node_agent_stream`). Node identity must be mTLS-authenticated and path node_id must match certificate identity. parameters: - "$ref": "#/components/parameters/InternalNodeIdPath" requestBody: required: true content: application/x-ndjson: schema: type: array items: "$ref": "#/components/schemas/InternalTerminalStreamFrame" responses: '200': description: Stream accepted content: application/x-ndjson: schema: type: array items: "$ref": "#/components/schemas/InternalTerminalStreamFrame" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/internal/v1/node-logs/loki/api/v1/push": post: tags: - InternalNodes operationId: internalNodeLogLokiPush summary: Internal node log gateway Loki push endpoint description: | Node-local collectors push Loki-compatible batches to `gpuaas-node-log-gateway`. The gateway validates node internal auth, caps request size, and forwards to the in-cluster Loki backend. Worker nodes must not write directly to raw Loki in production. security: - nodeBearerAuth: [] parameters: - "$ref": "#/components/parameters/XRequestId" requestBody: required: true content: application/json: schema: type: object additionalProperties: true application/x-protobuf: schema: type: string format: binary responses: '204': description: Batch accepted and forwarded to the log backend '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '413': description: Log batch exceeded the gateway request-size limit content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" '502': description: Log backend unavailable or rejected the batch content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" '503': "$ref": "#/components/responses/ServiceUnavailable" "/internal/v1/app-proxy/routes/{route_id}/report": post: tags: - InternalAppProxy operationId: internalAppProxyRouteReport security: [] summary: Internal endpoint for app proxy route reconciliation reporting description: | Internal-only control-plane endpoint used by a platform proxy controller or gateway reconciler. It records observed route state without making the public API a data-plane proxy. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: route_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/InternalAppProxyRouteReportRequest" responses: '200': description: Route report accepted content: application/json: schema: "$ref": "#/components/schemas/InternalAppProxyRouteReportResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" "/api/v1/platform-proxy/route-authz": get: tags: - Allocations operationId: authorizePlatformProxyRouteGet summary: Authorize a managed-ingress proxy route request description: | Internal proxy-runtime authorization check for managed-ingress routes. The caller presents the original GPUaaS bearer token; the API validates token scope, route ownership, app lifecycle, route lifecycle, and endpoint client auth mode. On success, the response returns `204` with trusted `X-GPUaaS-*` headers for the proxy hop to inject upstream. Browser clients should not call this endpoint directly. parameters: - "$ref": "#/components/parameters/XRequestId" - name: X-GPUaaS-Proxy-Host in: header required: false schema: type: string description: Public route host being authorized. If absent, the API uses trusted forwarded host headers or request host. - name: X-GPUaaS-Proxy-Path in: header required: false schema: type: string description: Public route path being authorized. If absent, the API uses trusted forwarded URI headers or request path. - name: X-GPUaaS-Proxy-Method in: header required: false schema: type: string description: Original request method being authorized. responses: '204': description: Proxy route request is authorized. headers: X-GPUaaS-Org-ID: schema: type: string X-GPUaaS-Project-ID: schema: type: string X-GPUaaS-Actor-Type: schema: type: string X-GPUaaS-Actor-ID: schema: type: string X-GPUaaS-App-Instance-ID: schema: type: string X-GPUaaS-Proxy-Route-ID: schema: type: string X-GPUaaS-Proxy-Pool-ID: schema: type: string X-GPUaaS-Endpoint-Name: schema: type: string X-GPUaaS-Route-Family: schema: type: string enum: - platform_admin - browser_app - api_app - terminal_ws '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" post: tags: - Allocations operationId: authorizePlatformProxyRoutePost summary: Authorize a managed-ingress proxy route request description: Same behavior as `GET /api/v1/platform-proxy/route-authz`; provided for proxy runtimes that prefer POST subrequests. parameters: - "$ref": "#/components/parameters/XRequestId" - name: X-GPUaaS-Proxy-Host in: header required: false schema: type: string - name: X-GPUaaS-Proxy-Path in: header required: false schema: type: string - name: X-GPUaaS-Proxy-Method in: header required: false schema: type: string responses: '204': description: Proxy route request is authorized. '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/proxy-routes/resolve": get: tags: - AdminOps operationId: adminResolveManagedIngressRoute summary: Resolve a managed-ingress URL or host for ops description: | Admin/operator read endpoint for resolving a managed-ingress public URL, host, and optional request path to the owning app-instance proxy route, backend route path, allocation, node, proxy pool, Pomerium ingress, and runbook/evidence pivots. This response is correlation-safe and must not include workload tokens, Pomerium cookies, OIDC state, authorization headers, or full auth query strings. parameters: - "$ref": "#/components/parameters/XRequestId" - name: url in: query required: false schema: type: string description: Full managed-ingress URL reported by a user. Query strings are ignored by the resolver. - name: host in: query required: false schema: type: string description: Public managed-ingress host. Required when url is omitted. - name: path in: query required: false schema: type: string description: Optional request path used to disambiguate path-prefix routes. responses: '200': description: Managed-ingress route resolved. content: application/json: schema: "$ref": "#/components/schemas/ManagedIngressRouteResolveResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/platform-proxy/route-forward/{proxy_path}": get: tags: - Allocations operationId: forwardPlatformProxyRoute summary: Forward an authorized managed-ingress API route request description: | Internal proxy-runtime forwarding endpoint for `api_bearer` managed-ingress routes. Pomerium routes API-client traffic here after host-based edge matching. The API validates the caller bearer token against GPUaaS route/app/project state, strips caller-controlled identity headers, injects trusted `X-GPUaaS-*` context, and forwards to the app upstream. Browser clients should not call this endpoint directly. parameters: - "$ref": "#/components/parameters/XRequestId" - name: proxy_path in: path required: true schema: type: string description: Original app API path after Pomerium prefix rewrite. - name: X-GPUaaS-Proxy-Host in: header required: true schema: type: string description: GPUaaS-owned public route host set by the proxy runtime. responses: '200': description: Proxied upstream response. Status and body are app-defined. content: application/json: schema: type: object additionalProperties: true application/octet-stream: schema: type: string format: binary '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" post: tags: - Allocations operationId: forwardPlatformProxyRoutePost summary: Forward an authorized managed-ingress API route request description: | Same forwarding contract as `GET /api/v1/platform-proxy/route-forward/{proxy_path}`. Used by API-client managed-ingress routes such as OpenAI-compatible chat/completions where the app-defined request body is proxied after GPUaaS bearer-token route authorization. parameters: - "$ref": "#/components/parameters/XRequestId" - name: proxy_path in: path required: true schema: type: string description: Original app API path after Pomerium prefix rewrite. - name: X-GPUaaS-Proxy-Host in: header required: true schema: type: string description: GPUaaS-owned public route host set by the proxy runtime. requestBody: required: false content: application/json: schema: type: object additionalProperties: true application/octet-stream: schema: type: string format: binary responses: '200': description: Proxied upstream response. Status and body are app-defined. content: application/json: schema: type: object additionalProperties: true application/octet-stream: schema: type: string format: binary '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/healthz": get: tags: - Health operationId: getHealth security: [] parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Health status content: application/json: schema: "$ref": "#/components/schemas/HealthResponse" '400': "$ref": "#/components/responses/BadRequest" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/auth/oidc/authorize": get: tags: - Auth operationId: getOidcAuthorizeUrl description: | OIDC authorize bootstrap. In tenant federation mode, server resolves tenant/provider mapping (OIDC) using verified domain bindings and/or advisory hints. `tenant_hint` and `identity_hint` are advisory only; server decides effective tenant context. security: [] parameters: - "$ref": "#/components/parameters/XRequestId" - name: redirect_uri in: query required: true schema: type: string format: uri - name: code_challenge in: query required: true schema: type: string minLength: 43 maxLength: 128 - name: code_challenge_method in: query required: true schema: type: string enum: - S256 - name: tenant_hint in: query required: false description: Advisory tenant hint for federation discovery. Format is tenant slug; never trusted without server-side resolution. schema: type: string minLength: 2 maxLength: 63 pattern: "^[a-z0-9][a-z0-9-]{1,62}$" - name: identity_hint in: query required: false description: Advisory enterprise identity hint (work email). Personal identities should use personal sign-in flow. schema: type: string format: email - name: provider_hint in: query required: false description: Advisory social provider shortcut for the platform IdP broker. The server validates supported values and remains authoritative. schema: type: string enum: - github - google - huggingface - name: action in: query required: false description: Product-owned OIDC required-action bootstrap. `mfa_setup` starts the provider MFA enrollment/update flow without exposing the provider account console as a user destination. schema: type: string enum: - mfa_setup responses: '200': description: OIDC authorization URL and state content: application/json: schema: "$ref": "#/components/schemas/OidcAuthorizeResponse" '400': "$ref": "#/components/responses/BadRequest" "/api/v1/auth/oidc/exchange": post: tags: - Auth operationId: exchangeOidcCode description: | Exchange callback code for GPUaaS session token. In federation-aware flows, callback state must be single-use and issuer/provider bound to the resolved tenant org_id. security: [] parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/OidcExchangeRequest" responses: '200': description: Token exchange success content: application/json: schema: "$ref": "#/components/schemas/AuthSessionResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '429': "$ref": "#/components/responses/TooManyRequests" "/api/v1/auth/saml/authorize": get: tags: - Auth operationId: getSamlAuthorizeUrl description: | SAML authorize bootstrap. Resolves tenant/provider mapping (SAML) using verified domain bindings and/or an advisory tenant hint, then returns IdP redirect URL and opaque state. security: [] parameters: - "$ref": "#/components/parameters/XRequestId" - name: redirect_uri in: query required: true description: Post-authentication redirect destination after successful ACS processing. Stored server-side in state; not sent to IdP. ACS URL remains fixed at `/api/v1/auth/saml/callback`. schema: type: string format: uri - name: tenant_hint in: query required: false description: Advisory tenant hint for federation discovery. Format is tenant slug; never trusted without server-side resolution. schema: type: string minLength: 2 maxLength: 63 pattern: "^[a-z0-9][a-z0-9-]{1,62}$" responses: '200': description: SAML redirect URL and state content: application/json: schema: "$ref": "#/components/schemas/SamlAuthorizeResponse" '400': "$ref": "#/components/responses/BadRequest" "/api/v1/auth/saml/callback": post: tags: - Auth operationId: exchangeSamlAssertion description: | Assertion Consumer Service (ACS) callback for SAML response handling. Callback state must be single-use and bound to resolved tenant/provider. This endpoint consumes standard SAML POST binding fields (`SAMLResponse`, `RelayState`). `Idempotency-Key` remains optional here; browser/IdP-driven callbacks primarily rely on single-use RelayState for replay protection. security: [] parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/x-www-form-urlencoded: schema: "$ref": "#/components/schemas/SamlCallbackRequest" responses: '200': description: SAML exchange success content: application/json: schema: "$ref": "#/components/schemas/AuthSessionResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '429': "$ref": "#/components/responses/TooManyRequests" "/api/v1/auth/personal/login": post: tags: - Auth operationId: loginPersonal summary: Personal account password login description: | Direct login flow for personal accounts. Enterprise sign-in should use tenant federation endpoints. security: [] parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/LoginRequest" responses: '200': description: Login success content: application/json: schema: "$ref": "#/components/schemas/LoginResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '429': "$ref": "#/components/responses/TooManyRequests" "/api/v1/auth/personal/signup": post: tags: - Auth operationId: signupPersonal summary: Personal account signup description: 'Creates a user and atomically bootstraps personal tenant + default project membership. ' security: [] parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/SignupRequest" responses: '201': description: Signup success content: application/json: schema: "$ref": "#/components/schemas/SignupResponse" '400': "$ref": "#/components/responses/BadRequest" '409': "$ref": "#/components/responses/Conflict" '429': "$ref": "#/components/responses/TooManyRequests" "/api/v1/auth/token/refresh": post: tags: - Auth operationId: refreshToken summary: Exchange a refresh token for a new access token description: | Public endpoint for session renewal. Supports refresh tokens issued for OIDC-backed sessions; OIDC remains the primary authentication model for production sign-in. security: [] parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/RefreshTokenRequest" responses: '200': description: New access token issued content: application/json: schema: "$ref": "#/components/schemas/RefreshTokenResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '429': "$ref": "#/components/responses/TooManyRequests" "/api/v1/auth/logout": post: tags: - Auth operationId: logout summary: Invalidate the current session and revoke tokens requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/LogoutRequest" parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" responses: '200': description: Session invalidated content: application/json: schema: "$ref": "#/components/schemas/OkResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/account/identity-links": get: tags: - Auth operationId: listMyIdentityLinks summary: List linked identity providers for the current user description: | Returns explicit identity-provider links for the authenticated account. Raw OAuth tokens, refresh tokens, and provider credential material are never returned. parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Identity links for the current user content: application/json: schema: "$ref": "#/components/schemas/UserIdentityLinkListResponse" '401': "$ref": "#/components/responses/Unauthorized" '503': "$ref": "#/components/responses/ServiceUnavailable" post: tags: - Auth operationId: createMyIdentityLink summary: Create an explicit identity-provider link for the current user description: | Creates a linked identity only after explicit proof such as a verified current-session provider callback, admin approval, or invite redemption. Duplicate email alone is not proof. The mutation is audited and idempotent. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateIdentityLinkRequest" responses: '201': description: Identity link created content: application/json: schema: "$ref": "#/components/schemas/CreateIdentityLinkResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/users/me": get: tags: - Users operationId: getMe parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Current user content: application/json: schema: "$ref": "#/components/schemas/UserWithBalance" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/projects": get: tags: - Projects operationId: listProjects parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Projects visible to current user content: application/json: schema: "$ref": "#/components/schemas/ProjectListResponse" '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" post: tags: - Projects operationId: createProject parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateProjectRequest" responses: '201': description: Project created content: application/json: schema: "$ref": "#/components/schemas/CreateProjectResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}": patch: tags: - Projects operationId: updateProject parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/UpdateProjectRequest" responses: '200': description: Project updated content: application/json: schema: "$ref": "#/components/schemas/CreateProjectResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" delete: tags: - Projects operationId: deleteProject parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" responses: '200': description: Project deleted content: application/json: schema: "$ref": "#/components/schemas/DeleteProjectResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/projects/{project_id}/set-default": post: tags: - Projects operationId: setDefaultProject parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" responses: '200': description: Default project updated for current user content: application/json: schema: "$ref": "#/components/schemas/CreateProjectResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/apps/catalog": get: tags: - Apps operationId: listAppCatalog summary: List platform app catalog entries available to the caller parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: category in: query required: false schema: type: string - name: status in: query required: false schema: type: string enum: - active - deprecated - disabled responses: '200': description: App catalog entries content: application/json: schema: "$ref": "#/components/schemas/AppCatalogListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/apps/catalog/{app_slug}/versions": get: tags: - Apps operationId: listAppCatalogVersions summary: List published versions for an app catalog entry parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/AppSlugPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: App catalog versions content: application/json: schema: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AppCatalogVersion" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/apps/registry": get: tags: - AppArtifacts operationId: getAppRegistryInfo summary: Get platform OCI registry baseline information for the current environment parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Platform OCI registry information content: application/json: schema: "$ref": "#/components/schemas/OciRegistryInfo" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/releases": get: tags: - PlatformReleases operationId: listPlatformReleases summary: List published platform releases and developer-downloadable artifacts parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Platform release catalog content: application/json: schema: "$ref": "#/components/schemas/PlatformReleaseListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/platform/releases/{version}": get: tags: - PlatformReleases operationId: getPlatformRelease summary: Get a single published platform release manifest parameters: - "$ref": "#/components/parameters/XRequestId" - name: version in: path required: true schema: type: string minLength: 1 responses: '200': description: Platform release manifest content: application/json: schema: "$ref": "#/components/schemas/PlatformRelease" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/platform/releases/{version}/artifacts/{artifact_id}/download": get: tags: - PlatformReleases operationId: downloadPlatformReleaseArtifact summary: Download a platform release artifact tarball description: Developer-facing artifacts are available to any authenticated user. Operator-only artifacts require the admin role. parameters: - "$ref": "#/components/parameters/XRequestId" - name: version in: path required: true schema: type: string minLength: 1 - name: artifact_id in: path required: true schema: type: string enum: - cli - go-sdk - python-sdk - node-agent - node-agent-bootstrap responses: '200': description: Artifact archive content: application/gzip: schema: type: string format: binary '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/platform/releases/{version}/artifacts/{artifact_id}/pull-intent": post: tags: - PlatformReleases operationId: createPlatformReleaseArtifactPullIntent summary: Issue a wrapped short-lived pull intent for a platform release artifact description: Returns registry metadata and Vault-wrapped pull credentials. Developer-facing artifacts are available to any authenticated user. Operator-only artifacts require the admin role. parameters: - "$ref": "#/components/parameters/XRequestId" - name: version in: path required: true schema: type: string minLength: 1 - name: artifact_id in: path required: true schema: type: string enum: - cli - go-sdk - python-sdk - node-agent - node-agent-bootstrap responses: '201': description: Platform release artifact pull intent issued content: application/json: schema: "$ref": "#/components/schemas/ArtifactPullIntent" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/platform/dev-ca": get: tags: - PlatformReleases operationId: getPlatformDevCA summary: Get the current platform-control dev CA download metadata parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Platform-control dev CA metadata content: application/json: schema: "$ref": "#/components/schemas/PlatformDevCA" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/platform/dev-ca/download": get: tags: - PlatformReleases operationId: downloadPlatformDevCA summary: Download the current platform-control dev CA certificate parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: PEM-encoded CA certificate content: application/x-x509-ca-cert: schema: type: string format: binary '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/apps/catalog/{app_slug}/versions/{version}/publish": post: tags: - AdminApps operationId: adminPublishAppCatalogVersion summary: Publish an app catalog version parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppSlugPath" - "$ref": "#/components/parameters/AppVersionPath" responses: '200': description: App catalog version published content: application/json: schema: "$ref": "#/components/schemas/AppCatalogVersion" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/apps/catalog/{app_slug}/versions/{version}/deprecate": post: tags: - AdminApps operationId: adminDeprecateAppCatalogVersion summary: Deprecate an app catalog version parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppSlugPath" - "$ref": "#/components/parameters/AppVersionPath" responses: '200': description: App catalog version deprecated content: application/json: schema: "$ref": "#/components/schemas/AppCatalogVersion" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/apps/entitlements": get: tags: - Apps operationId: listProjectAppEntitlements summary: List app entitlements for a project parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" responses: '200': description: Project app entitlements content: application/json: schema: "$ref": "#/components/schemas/AppEntitlementListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/apps/entitlements/{app_slug}": put: tags: - Apps operationId: upsertProjectAppEntitlement summary: Enable/disable app entitlement and policy overrides for a project parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppSlugPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/UpsertAppEntitlementRequest" responses: '200': description: Updated project entitlement content: application/json: schema: "$ref": "#/components/schemas/AppEntitlement" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/app-artifacts": get: tags: - AppArtifacts operationId: listProjectAppArtifacts summary: List registered app artifacts for a project parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: app_slug in: query required: false schema: type: string - name: search in: query required: false schema: type: string - name: artifact_kind in: query required: false schema: type: string enum: - oci - blob - name: source_type in: query required: false schema: type: string enum: - oci_registry - s3 - gcs - azure_blob - https - huggingface - artifact_store - name: lifecycle_state in: query required: false schema: type: string enum: - published - promoted - deprecated - retired responses: '200': description: Project app artifacts content: application/json: schema: "$ref": "#/components/schemas/AppArtifactListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - AppArtifacts operationId: registerProjectAppArtifact summary: Register a previously published app artifact digest with the control plane parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/RegisterAppArtifactRequest" responses: '201': description: App artifact registered content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-artifacts/publish-intents": post: tags: - AppArtifacts operationId: createProjectAppArtifactPublishIntent summary: Issue a short-lived publish intent for direct artifact publication to the platform registry parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateAppArtifactPublishIntentRequest" responses: '201': description: Publish intent issued content: application/json: schema: "$ref": "#/components/schemas/AppArtifactPublishIntent" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-artifacts/{artifact_id}/pull-intent": post: tags: - AppArtifacts operationId: createProjectAppArtifactPullIntent summary: Issue a wrapped short-lived pull intent for a project app artifact description: Returns registry metadata and Vault-wrapped pull credentials. Artifact bytes remain on the registry path; clients must not cache or persist the wrapped credential. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppArtifactIdPath" responses: '201': description: App artifact pull intent issued content: application/json: schema: "$ref": "#/components/schemas/ArtifactPullIntent" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/projects/{project_id}/app-instances": get: tags: - Apps operationId: listAppInstances summary: List app instances in a project parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string enum: - requested - deploying - running - stopping - stopped - starting - restarting - upgrading - rolling_back - failed - decommissioning - decommissioned - deleting - deleted responses: '200': description: App instances content: application/json: schema: "$ref": "#/components/schemas/AppInstanceListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - Apps operationId: createAppInstance summary: Request app instance deployment in a project parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateAppInstanceRequest" responses: '202': description: App instance deployment accepted content: application/json: schema: "$ref": "#/components/schemas/AppInstance" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-artifacts/{artifact_id}/promote": post: tags: - AppArtifacts operationId: promoteProjectAppArtifact summary: Promote a registered app artifact to a named channel parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppArtifactIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/PromoteAppArtifactRequest" responses: '200': description: App artifact promoted content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-artifacts/{artifact_id}/verify": post: tags: - AppArtifacts operationId: verifyProjectAppArtifact summary: Mark a registered app artifact as verified parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppArtifactIdPath" responses: '200': description: App artifact verified content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-artifacts/{artifact_id}/revoke": post: tags: - AppArtifacts operationId: revokeProjectAppArtifact summary: Revoke trust for a registered app artifact parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppArtifactIdPath" responses: '200': description: App artifact trust revoked content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-artifacts/{artifact_id}/deprecate": post: tags: - AppArtifacts operationId: deprecateProjectAppArtifact summary: Deprecate a registered app artifact parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppArtifactIdPath" responses: '200': description: App artifact deprecated content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-artifacts/{artifact_id}/retire": post: tags: - AppArtifacts operationId: retireProjectAppArtifact summary: Retire a registered app artifact from new use parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppArtifactIdPath" responses: '200': description: App artifact retired content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}": get: tags: - Apps operationId: getAppInstance summary: Get app instance status and metadata description: | External app workers use this polling-compatible read surface to load the project-owned runtime object they are authorized to reconcile. Platform internals may use events, but app workers must treat this API as the stable runtime query contract. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" responses: '200': description: App instance content: application/json: schema: "$ref": "#/components/schemas/AppInstance" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/report": post: tags: - Apps operationId: reportAppInstance summary: Report adapter-owned status for an app instance without requiring a platform-internal worker transition parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ReportAppInstanceRequest" responses: '200': description: App instance report accepted content: application/json: schema: "$ref": "#/components/schemas/AppInstance" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" delete: tags: - Apps operationId: deleteAppInstance summary: Request app instance decommission (legacy alias) parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" responses: '202': description: App instance decommission accepted content: application/json: schema: "$ref": "#/components/schemas/AppInstance" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/bootstrap-ssh/reconcile": post: tags: - Apps operationId: reconcileAppInstanceBootstrapSshTrust summary: Reconcile app-managed bootstrap SSH trust for an app instance onto a target allocation user parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ReconcileAppInstanceBootstrapSshTrustRequest" responses: '202': description: Bootstrap SSH trust sync requested content: application/json: schema: "$ref": "#/components/schemas/AppInstanceBootstrapSshTrustState" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/members": get: tags: - Apps operationId: listAppInstanceMembers summary: List realized members for an app instance description: | List generic runtime members for an app-owned worker. Runtime-specific member semantics stay adapter-owned and are reported through the generic member envelope. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: component_key in: query required: false schema: type: string - name: status in: query required: false schema: type: string enum: - requested - reconciling - ready - draining - deleting - failed - deleted responses: '200': description: App instance members content: application/json: schema: "$ref": "#/components/schemas/AppInstanceMemberListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/members/{member_id}": get: tags: - Apps operationId: getAppInstanceMember summary: Get status and detail for an app-instance member parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" - "$ref": "#/components/parameters/AppInstanceMemberIdPath" responses: '200': description: App instance member content: application/json: schema: "$ref": "#/components/schemas/AppInstanceMember" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/members/{member_id}/report": post: tags: - Apps operationId: reportAppInstanceMember summary: Report adapter-owned status or detail for an app-instance member without requiring a member operation parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" - "$ref": "#/components/parameters/AppInstanceMemberIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ReportAppInstanceMemberRequest" responses: '200': description: App instance member report accepted content: application/json: schema: "$ref": "#/components/schemas/AppInstanceMember" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/member-operations": get: tags: - Apps operationId: listAppInstanceMemberOperations summary: List generic member lifecycle operations for an app instance description: | Polling-compatible work queue for external app workers. App workers read accepted or in-progress operations here and report progress through the corresponding report route. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string enum: - accepted - in_progress - succeeded - failed - cancelled - name: component_key in: query required: false schema: type: string responses: '200': description: App instance member operations content: application/json: schema: "$ref": "#/components/schemas/AppInstanceMemberOperationListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - Apps operationId: createAppInstanceMemberOperation summary: Request a generic member lifecycle operation for an app instance parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateAppInstanceMemberOperationRequest" responses: '202': description: App instance member operation accepted content: application/json: schema: "$ref": "#/components/schemas/AppInstanceMemberOperation" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/member-operations/{operation_id}": get: tags: - Apps operationId: getAppInstanceMemberOperation summary: Get status for an app-instance member operation parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" - "$ref": "#/components/parameters/AppInstanceMemberOperationIdPath" responses: '200': description: App instance member operation content: application/json: schema: "$ref": "#/components/schemas/AppInstanceMemberOperation" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/member-operations/{operation_id}/report": post: tags: - Apps operationId: reportAppInstanceMemberOperation summary: Report adapter-owned progress or result for an app-instance member operation parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" - "$ref": "#/components/parameters/AppInstanceMemberOperationIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ReportAppInstanceMemberOperationRequest" responses: '200': description: App instance member operation report accepted content: application/json: schema: "$ref": "#/components/schemas/AppInstanceMemberOperation" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/upgrade": post: tags: - Apps operationId: upgradeAppInstance summary: Request app instance upgrade parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/UpgradeAppInstanceRequest" responses: '202': description: App instance upgrade accepted content: application/json: schema: "$ref": "#/components/schemas/AppInstance" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/runtime-secrets": post: tags: - Apps operationId: issueAppInstanceRuntimeSecret summary: Issue a wrapped runtime secret bundle for an app instance parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/IssueAppInstanceRuntimeSecretRequest" responses: '200': description: Wrapped runtime secret bundle content: application/json: schema: "$ref": "#/components/schemas/AppInstanceRuntimeSecretBundle" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/access": get: tags: - Apps operationId: getAppInstanceAccess summary: Get app instance access bundle parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" responses: '200': description: App instance access bundle content: application/json: schema: "$ref": "#/components/schemas/AppInstanceAccessBundle" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/rollback": post: tags: - Apps operationId: rollbackAppInstance summary: Request app instance rollback parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/RollbackAppInstanceRequest" responses: '202': description: App instance rollback accepted content: application/json: schema: "$ref": "#/components/schemas/AppInstance" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/stop": post: tags: - Apps operationId: stopAppInstance summary: Request app instance stop description: 'Requests a non-destructive stop of the app runtime. The app instance remains visible and can be started again later. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" responses: '202': description: App instance stop accepted content: application/json: schema: "$ref": "#/components/schemas/AppInstance" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/start": post: tags: - Apps operationId: startAppInstance summary: Request app instance start description: Requests start for a previously stopped app instance. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" responses: '202': description: App instance start accepted content: application/json: schema: "$ref": "#/components/schemas/AppInstance" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/restart": post: tags: - Apps operationId: restartAppInstance summary: Request app instance restart description: | Requests restart for a running or failed app instance without decommissioning it. Runtime backends that cannot define safe deterministic restart semantics, such as self-managed multi-member Kubernetes/RKE2, should reject this action and expose repair/reconcile operations instead. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" responses: '202': description: App instance restart accepted content: application/json: schema: "$ref": "#/components/schemas/AppInstance" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/repair": post: tags: - Apps operationId: createAppInstanceRepairOperation summary: Request app runtime reconcile or repair description: | Creates an app-runtime repair operation for drift correction or safe runtime repair. This is the preferred action for Kubernetes/RKE2 instead of a generic restart because server, agent, and whole-runtime repair have different safety semantics. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateAppInstanceRepairRequest" responses: '202': description: App repair operation accepted content: application/json: schema: "$ref": "#/components/schemas/AppInstanceRepairOperation" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/repair-operations": get: tags: - Apps operationId: listAppInstanceRepairOperations summary: List app runtime repair operations parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: "$ref": "#/components/schemas/AppInstanceRepairOperationStatus" responses: '200': description: App repair operations content: application/json: schema: "$ref": "#/components/schemas/AppInstanceRepairOperationListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/repair-operations/{repair_operation_id}": get: tags: - Apps operationId: getAppInstanceRepairOperation summary: Get app runtime repair operation detail parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" - "$ref": "#/components/parameters/AppInstanceRepairOperationIdPath" responses: '200': description: App repair operation content: application/json: schema: "$ref": "#/components/schemas/AppInstanceRepairOperation" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/repair-operations/{repair_operation_id}/report": post: tags: - Apps operationId: reportAppInstanceRepairOperation summary: Report app-owned progress for a repair operation description: | Polling-compatible report surface for app-owned workers. Workers report step-level progress so long-running Kubernetes/RKE2 repair operations do not appear stuck. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" - "$ref": "#/components/parameters/AppInstanceRepairOperationIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ReportAppInstanceRepairOperationRequest" responses: '200': description: App repair operation report accepted content: application/json: schema: "$ref": "#/components/schemas/AppInstanceRepairOperation" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/app-instances/{app_instance_id}/decommission": post: tags: - Apps operationId: decommissionAppInstance summary: Request app instance decommission parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AppInstanceIdPath" responses: '202': description: App instance decommission accepted content: application/json: schema: "$ref": "#/components/schemas/AppInstance" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/shared-runtime-attachments/{attachment_id}/worker-operations": post: tags: - Apps operationId: createProjectSharedRuntimeWorkerOperation summary: Request worker contribution for an attached tenant-shared app runtime description: | Allows an attached consumer project to request shared worker contribution through its own project-scoped attachment path. The platform resolves the backing tenant-owned shared runtime from the attachment and enforces attachment policy. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/SharedRuntimeAttachmentIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateSharedAppRuntimeWorkerOperationRequest" responses: '202': description: Shared runtime worker operation accepted content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperation" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/orgs/{org_id}/shared-app-runtimes": get: tags: - Apps operationId: listSharedAppRuntimes summary: List tenant-owned shared app runtimes description: | List tenant-owned shared runtimes within one tenant. Delegated `shared_runtime_operator` tokens are intended for runtime-scoped reads; broader listing is primarily a user/operator surface. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OrgIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string enum: - requested - deploying - running - upgrading - rolling_back - failed - deleting - deleted responses: '200': description: Tenant-owned shared app runtimes content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - Apps operationId: createSharedAppRuntime summary: Request tenant-owned shared app runtime deployment description: Create a tenant-owned shared runtime in requested state. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/OrgIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateSharedAppRuntimeRequest" responses: '202': description: Shared app runtime deployment accepted content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntime" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}": get: tags: - Apps operationId: getSharedAppRuntime summary: Get tenant-owned shared app runtime status and metadata description: | Read one tenant-owned shared runtime. Intended machine actor is a delegated `shared_runtime_operator` token bound to the same `org_id` and `shared_runtime_id`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OrgIdPath" - name: shared_runtime_id in: path required: true schema: type: string format: uuid responses: '200': description: Shared app runtime content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntime" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" delete: tags: - Apps operationId: deleteSharedAppRuntime summary: Request deletion of a tenant-owned shared app runtime description: Request tenant-owned shared runtime deletion by transitioning it to deleting state. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/OrgIdPath" - name: shared_runtime_id in: path required: true schema: type: string format: uuid responses: '202': description: Shared app runtime deletion accepted content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntime" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/report": post: tags: - Apps operationId: reportSharedAppRuntime summary: Report tenant-owned shared app runtime lifecycle state description: | Report lifecycle progress for one tenant-owned shared runtime. Intended machine actor is a delegated `shared_runtime_operator` token bound to the same `org_id` and `shared_runtime_id`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OrgIdPath" - name: shared_runtime_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ReportSharedAppRuntimeRequest" responses: '200': description: Shared app runtime updated content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntime" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/attachments": get: tags: - Apps operationId: listSharedAppRuntimeAttachments summary: List attached consumer projects for a tenant-owned shared app runtime description: | List consumer-project attachments for one tenant-owned shared runtime. Intended machine actor is a delegated `shared_runtime_operator` token bound to the same `org_id` and `shared_runtime_id`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OrgIdPath" - name: shared_runtime_id in: path required: true schema: type: string format: uuid - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Shared runtime attachments content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeAttachmentListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - Apps operationId: createSharedAppRuntimeAttachment summary: Attach a consumer project to a tenant-owned shared app runtime description: Attach or update one consumer project relationship for a tenant-owned shared runtime. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/OrgIdPath" - name: shared_runtime_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateSharedAppRuntimeAttachmentRequest" responses: '202': description: Shared runtime attachment accepted content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeAttachment" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/attachments/{attachment_id}": get: tags: - Apps operationId: getSharedAppRuntimeAttachment summary: Get one attached consumer project relationship description: | Read one shared runtime attachment. Intended machine actor is a delegated `shared_runtime_operator` token bound to the same `org_id` and `shared_runtime_id`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OrgIdPath" - name: shared_runtime_id in: path required: true schema: type: string format: uuid - name: attachment_id in: path required: true schema: type: string format: uuid responses: '200': description: Shared runtime attachment content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeAttachment" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - Apps operationId: reportSharedAppRuntimeAttachment summary: Report attached project contribution state for a tenant-owned shared app runtime description: | Report attachment-scoped progress or contribution state for one shared runtime attachment. Intended machine actor is a delegated `shared_runtime_operator` token bound to the same `org_id` and `shared_runtime_id`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OrgIdPath" - name: shared_runtime_id in: path required: true schema: type: string format: uuid - name: attachment_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ReportSharedAppRuntimeAttachmentRequest" responses: '200': description: Shared runtime attachment updated content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeAttachment" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" delete: tags: - Apps operationId: deleteSharedAppRuntimeAttachment summary: Detach a consumer project from a tenant-owned shared app runtime description: Detach a consumer project from one tenant-owned shared runtime. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/OrgIdPath" - "$ref": "#/components/parameters/SharedRuntimeIdPath" - "$ref": "#/components/parameters/SharedRuntimeAttachmentIdPath" responses: '202': description: Shared runtime attachment deletion accepted content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeAttachment" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/workers": get: tags: - Apps operationId: listSharedAppRuntimeWorkers summary: List workers for a tenant-owned shared app runtime description: | Runtime-query surface for tenant-shared external app workers. A delegated `shared_runtime_operator` token may read workers only for its bound `org_id` and `shared_runtime_id`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OrgIdPath" - name: shared_runtime_id in: path required: true schema: type: string format: uuid - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Shared runtime workers content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeWorkerListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/workers/{worker_id}": get: tags: - Apps operationId: getSharedAppRuntimeWorker summary: Get one worker contribution for a tenant-owned shared app runtime description: | Runtime-query surface for one tenant-shared worker contribution. A delegated `shared_runtime_operator` token may read this resource only for its bound `org_id` and `shared_runtime_id`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OrgIdPath" - name: shared_runtime_id in: path required: true schema: type: string format: uuid - name: worker_id in: path required: true schema: type: string format: uuid responses: '200': description: Shared runtime worker content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeWorker" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - Apps operationId: reportSharedAppRuntimeWorker summary: Report one worker contribution for a tenant-owned shared app runtime description: | Report worker-scoped lifecycle progress for one shared runtime worker. Intended machine actor is a delegated `shared_runtime_operator` token bound to the same `org_id` and `shared_runtime_id`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OrgIdPath" - name: shared_runtime_id in: path required: true schema: type: string format: uuid - name: worker_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ReportSharedAppRuntimeWorkerRequest" responses: '200': description: Shared runtime worker updated content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeWorker" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/worker-operations": get: tags: - Apps operationId: listSharedAppRuntimeWorkerOperations summary: List worker operations for a tenant-owned shared app runtime description: | Polling-compatible work queue for tenant-shared external app workers. A delegated `shared_runtime_operator` token reads pending operations here and reports progress through the corresponding operation report route. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OrgIdPath" - name: shared_runtime_id in: path required: true schema: type: string format: uuid - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Shared runtime worker operations content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperationListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - Apps operationId: createSharedAppRuntimeWorkerOperation summary: Request a worker lifecycle change for a tenant-owned shared app runtime description: | Create an operator-visible worker lifecycle request for a tenant-owned shared runtime. Human tenant/project actors request operations; delegated app workers consume and report them through the runtime worker contract. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/OrgIdPath" - name: shared_runtime_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateSharedAppRuntimeWorkerOperationRequest" responses: '202': description: Shared runtime worker operation accepted content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperation" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/worker-operations/{operation_id}": get: tags: - Apps operationId: getSharedAppRuntimeWorkerOperation summary: Get one worker operation for a tenant-owned shared app runtime description: | Runtime-query surface for one tenant-shared worker lifecycle operation. Delegated app workers use this endpoint to recover operation state safely after restarts or polling gaps. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OrgIdPath" - "$ref": "#/components/parameters/SharedRuntimeIdPath" - "$ref": "#/components/parameters/SharedRuntimeWorkerOperationIdPath" responses: '200': description: Shared runtime worker operation content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperation" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - Apps operationId: reportSharedAppRuntimeWorkerOperation summary: Report one worker operation for a tenant-owned shared app runtime description: | Report worker-operation progress for one shared runtime worker operation. Intended machine actor is a delegated `shared_runtime_operator` token bound to the same `org_id` and `shared_runtime_id`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OrgIdPath" - "$ref": "#/components/parameters/SharedRuntimeIdPath" - "$ref": "#/components/parameters/SharedRuntimeWorkerOperationIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ReportSharedAppRuntimeWorkerOperationRequest" responses: '200': description: Shared runtime worker operation updated content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperation" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/ssh-keys": get: tags: - SshKeys operationId: listSshKeys description: 'Lists registered SSH public keys in the caller''s active scope. Without `X-Project-ID`, this returns the caller''s personal keys. With `X-Project-ID`, this returns project-scoped keys for that project. Service-account callers must provide `X-Project-ID`. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Registered SSH public keys for the current personal or project scope content: application/json: schema: "$ref": "#/components/schemas/SshPublicKeyListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - SshKeys operationId: createSshKey description: 'Registers an SSH public key in the caller''s active scope. Without `X-Project-ID`, this creates a personal key for the caller. With `X-Project-ID`, this creates a project-scoped key that can later be referenced by project-scoped automation such as service accounts. Project-scoped keys cannot be marked as default. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateSshPublicKeyRequest" responses: '201': description: SSH public key created content: application/json: schema: "$ref": "#/components/schemas/CreateSshPublicKeyResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/ssh-keys/{key_id}": delete: tags: - SshKeys operationId: deleteSshKey description: 'Revokes a registered SSH public key in the caller''s active scope. Without `X-Project-ID`, this operates on the caller''s personal keys. With `X-Project-ID`, this operates on project-scoped keys for that project. Service-account callers must provide `X-Project-ID`. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/SshKeyIdPath" responses: '200': description: SSH public key removed content: application/json: schema: "$ref": "#/components/schemas/OkResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/ssh-keys/{key_id}/default": put: tags: - SshKeys operationId: setDefaultSshKey description: Sets the caller's personal default SSH key for future allocations. Project-scoped keys are not eligible for default selection. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/SshKeyIdPath" responses: '200': description: Default SSH key updated content: application/json: schema: "$ref": "#/components/schemas/CreateSshPublicKeyResponse" '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/billing/balance": get: tags: - Billing operationId: getBillingBalance parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Balance content: application/json: schema: "$ref": "#/components/schemas/BillingBalanceResponse" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/billing/financial-posture": get: tags: - Billing operationId: getBillingFinancialPosture summary: Get caller financial posture description: 'Returns the caller-visible billing posture used by V3 billing surfaces to explain prepaid credit exhaustion, launch restrictions, affected workloads/apps, and recovery evidence without requiring operator DB inspection. ' parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Financial posture content: application/json: schema: "$ref": "#/components/schemas/BillingFinancialPostureResponse" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/billing/currency-settings": get: tags: - Billing operationId: getBillingCurrencySettings parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Tenant billing currency settings content: application/json: schema: "$ref": "#/components/schemas/BillingCurrencySettingsResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/billing/account": get: tags: - Billing operationId: getBillingAccount parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Billing account/channel shape content: application/json: schema: "$ref": "#/components/schemas/BillingAccountResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/billing/usage": get: tags: - Billing operationId: listBillingUsage parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: allocation_id in: query required: false schema: type: string format: uuid - name: app_instance_id in: query required: false schema: type: string format: uuid - name: usage_source in: query required: false schema: type: string enum: - allocation - app_runtime - "$ref": "#/components/parameters/BillingFrom" - "$ref": "#/components/parameters/BillingTo" - "$ref": "#/components/parameters/BillingUsageSort" responses: '200': description: Usage list content: application/json: schema: "$ref": "#/components/schemas/UsageListResponse" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/billing/usage/csv": get: tags: - Billing operationId: exportBillingUsageCsv parameters: - "$ref": "#/components/parameters/XRequestId" - name: allocation_id in: query required: false schema: type: string format: uuid - name: app_instance_id in: query required: false schema: type: string format: uuid - name: usage_source in: query required: false schema: type: string enum: - allocation - app_runtime - "$ref": "#/components/parameters/BillingFrom" - "$ref": "#/components/parameters/BillingTo" - "$ref": "#/components/parameters/BillingUsageSort" responses: '200': description: CSV export content: text/csv: schema: type: string format: binary '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/billing/invoices": get: tags: - Billing operationId: listBillingInvoices parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string enum: - draft - issued - due - paid - partially_paid - void - write_off responses: '200': description: Invoice list content: application/json: schema: "$ref": "#/components/schemas/BillingInvoiceListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/billing/invoices/{invoice_id}": get: tags: - Billing operationId: getBillingInvoice parameters: - "$ref": "#/components/parameters/XRequestId" - name: invoice_id in: path required: true schema: type: string format: uuid responses: '200': description: Invoice detail content: application/json: schema: "$ref": "#/components/schemas/BillingInvoiceDetail" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" "/api/v1/billing/budget-posture": get: tags: - Billing operationId: listBillingBudgetPosture parameters: - "$ref": "#/components/parameters/XRequestId" - name: scope_type in: query required: false schema: type: string enum: - tenant - project - name: project_id in: query required: false schema: type: string format: uuid responses: '200': description: Budget posture list content: application/json: schema: "$ref": "#/components/schemas/BillingBudgetPostureResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/billing/budget-decisions": post: tags: - Billing operationId: evaluateBillingBudgetDecision summary: Evaluate budget decision for a proposed launch amount description: 'Computes the side-effect-free tenant/project budget decision for a proposed launch amount. The response may warn or report that a future enforcement policy would block, but this endpoint does not mutate allocations, workloads, budgets, ledger entries, or runtime state. ' parameters: - "$ref": "#/components/parameters/XRequestId" security: - bearerAuth: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/BillingBudgetDecisionRequest" responses: '200': description: Budget decision content: application/json: schema: "$ref": "#/components/schemas/BillingBudgetDecisionResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/billing/rated-usage": get: tags: - Billing operationId: listBillingRatedUsage summary: List rated usage evidence lines parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: usage_record_id in: query required: false schema: type: string format: uuid responses: '200': description: Rated usage evidence list content: application/json: schema: "$ref": "#/components/schemas/BillingRatedUsageListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/billing/rated-usage/{rated_usage_line_id}": get: tags: - Billing operationId: getBillingRatedUsage summary: Get a rated usage evidence line parameters: - "$ref": "#/components/parameters/XRequestId" - name: rated_usage_line_id in: path required: true schema: type: string format: uuid responses: '200': description: Rated usage evidence detail content: application/json: schema: "$ref": "#/components/schemas/BillingRatedUsageLine" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" "/api/v1/billing/refunds": get: tags: - Billing operationId: listBillingRefunds summary: List caller refund requests and outcomes parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string enum: - accepted - completed - failed responses: '200': description: Refund requests content: application/json: schema: "$ref": "#/components/schemas/RefundListResponse" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/payments/checkout-session": post: tags: - Payments operationId: createChargeSession parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateChargeSessionRequest" responses: '200': description: Checkout session URL content: application/json: schema: "$ref": "#/components/schemas/SessionUrlResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/payments/customer-portal-session": post: tags: - Payments operationId: createCustomerPortalSession parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" responses: '200': description: Customer portal URL content: application/json: schema: "$ref": "#/components/schemas/SessionUrlResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/payments/webhook": post: tags: - Payments operationId: stripeWebhook security: [] parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: type: object additionalProperties: true responses: '200': description: Webhook accepted content: application/json: schema: "$ref": "#/components/schemas/OkResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/skus": get: tags: - Catalog operationId: listSkus parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: SKU list content: application/json: schema: "$ref": "#/components/schemas/SkuListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/nodes": get: tags: - Nodes operationId: listNodeSummaries parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string enum: - online - offline - maintenance - name: region_code in: query required: false schema: type: string responses: '200': description: User-facing node list content: application/json: schema: "$ref": "#/components/schemas/NodeSummaryListResponse" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/v3/shell/context": get: tags: - V3ReadModels operationId: getV3ShellContextCompat summary: Get v3 shell context read model description: 'Returns the scoped shell context needed by the v3 product shell: available modes, tenant/project selectors, region selector, balance summary, and attention counts. The response is scoped to the authenticated user and may be Redis cached using user, tenant, project, role, and mode scope in the cache key. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - in: query name: mode required: false schema: "$ref": "#/components/schemas/V3ShellMode" responses: '200': description: V3 shell context headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3ShellContextResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/regions": get: tags: - V3ReadModels operationId: listV3RegionsCompat summary: List v3 shell regions description: 'Temporary v3 migration read model for the product shell region selector. This endpoint lets UI remove hardcoded region labels while the scheduler and capacity layers evolve toward explicit multi-region support. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" responses: '200': description: V3 region list headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3RegionListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/workloads": get: tags: - V3ReadModels operationId: listV3WorkloadsCompat summary: List unified v3 workload workbench rows description: 'Returns one runtime workbench across raw compute allocations and app-backed workloads. This read model is the v3 replacement target for list pages that currently split allocations and app instances. It must enforce project scope before reading or caching rows. ' x-v3-read-model-gaps: - node, region, placement owner, and disabled reason should be normalized across compute allocations and app-backed runtimes. - workload rows should expose a billing summary with hourly and accrued cost sourced from allocation/app billing state. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - in: query name: status required: false schema: "$ref": "#/components/schemas/V3WorkloadStatus" - in: query name: kind required: false schema: "$ref": "#/components/schemas/V3WorkloadKind" - in: query name: search required: false schema: type: string maxLength: 120 - in: query name: include_history required: false description: Include archived terminal workload rows such as released runtimes and expired recovery items. Default runtime lists omit history; explicit status filters are also treated as history queries. schema: type: boolean default: false responses: '200': description: Unified v3 workload list headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3WorkloadListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/workloads/{workload_id}": get: tags: - V3ReadModels operationId: getV3WorkloadDetailCompat summary: Get unified v3 workload detail read model description: 'Returns the v3 workload detail shell data for a compute or app-backed runtime. Kind-specific connect, metrics, storage, and config data are returned as sanitized tab payloads owned by their source domains. Raw secrets and private keys must never be present in this read model. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/WorkloadIdPath" responses: '200': description: Unified v3 workload detail headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3WorkloadDetailResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/workloads/{workload_id}/credentials/{credential_id}/reconcile": post: tags: - V3ReadModels operationId: reconcileV3AppRuntimeCredentialCompat summary: Reconcile an app runtime credential binding description: Records an audited app runtime credential reconcile operation for the workload-scoped credential binding. Human users and project-scoped service accounts may call this operation; service-account calls require `X-Project-ID` to match the token `project_id` and cross-project calls fail before inventory/runtime service calls. The response is durable operation evidence only and must never include raw credential material, wrapped tokens, private keys, passwords, or provider secrets. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/WorkloadIdPath" - "$ref": "#/components/parameters/AccessCredentialIdPath" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3AppRuntimeCredentialOperationRequest" responses: '202': description: Runtime credential reconcile accepted content: application/json: schema: "$ref": "#/components/schemas/V3AppRuntimeCredentialOperationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/workloads/{workload_id}/credentials/sweep": post: tags: - V3ReadModels operationId: sweepV3AppRuntimeCredentialsCompat summary: Sweep stale app runtime credentials for a workload description: Records an audited app runtime credential sweep for a workload owner tuple. Human users and project-scoped service accounts may call this operation; service-account calls require `X-Project-ID` to match the token `project_id` and cross-project calls fail before inventory/runtime service calls. The operation soft-deletes expired or stale disabled runtime credentials and bindings, supports dry-run, and never exposes raw credential material. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/WorkloadIdPath" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3AppRuntimeCredentialSweepRequest" responses: '202': description: Runtime credential sweep accepted content: application/json: schema: "$ref": "#/components/schemas/V3AppRuntimeCredentialSweepResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/workloads/{workload_id}/credentials/{credential_id}/rotate": post: tags: - V3ReadModels operationId: rotateV3AppRuntimeCredentialCompat summary: Rotate an app runtime credential where supported description: Records an audited app runtime credential rotate operation for the workload-scoped credential binding. Human users and project-scoped service accounts may call this operation; service-account calls require `X-Project-ID` to match the token `project_id` and cross-project calls fail before inventory/runtime service calls. Rotation support is advertised by the workload credential posture capability flags. The response is durable operation evidence only and must never include raw credential material. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/WorkloadIdPath" - "$ref": "#/components/parameters/AccessCredentialIdPath" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3AppRuntimeCredentialOperationRequest" responses: '202': description: Runtime credential rotate accepted content: application/json: schema: "$ref": "#/components/schemas/V3AppRuntimeCredentialOperationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/workloads/{workload_id}/credentials/{credential_id}/disable": post: tags: - V3ReadModels operationId: disableV3AppRuntimeCredentialCompat summary: Disable an app runtime credential where supported description: Records an audited app runtime credential disable operation for the workload-scoped credential binding. Human users and project-scoped service accounts may call this operation; service-account calls require `X-Project-ID` to match the token `project_id` and cross-project calls fail before inventory/runtime service calls. The response is durable operation evidence only and must never include raw credential material. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/WorkloadIdPath" - "$ref": "#/components/parameters/AccessCredentialIdPath" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3AppRuntimeCredentialOperationRequest" responses: '202': description: Runtime credential disable accepted content: application/json: schema: "$ref": "#/components/schemas/V3AppRuntimeCredentialOperationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/tasks": get: tags: - V3ReadModels operationId: listV3TasksCompat summary: List v3 task read-model rows description: 'Returns the project-scoped long-running operation workbench used after launch, release, restart, and app lifecycle submissions. The first production implementation is allocation-backed and normalizes allocation lifecycle state into a task shape; future domains can add task sources without changing the shell contract. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - in: query name: status required: false schema: "$ref": "#/components/schemas/V3TaskStatus" responses: '200': description: V3 task list headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3TaskListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/tasks/{task_id}": get: tags: - V3ReadModels operationId: getV3TaskDetailCompat summary: Get v3 task detail read model description: 'Returns task header context plus a normalized timeline. For allocation tasks, the response enriches the synthetic lifecycle steps with the existing allocation timeline when available. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3TaskIdPath" responses: '200': description: V3 task detail headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3TaskDetailResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/compute": get: tags: - V3ReadModels operationId: getV3ComputeCatalogCompat summary: Get v3 compute catalog read model description: 'Temporary v3 migration read model for the Compute shell group. Returns project-scoped launchable SKU summaries and compatible OS image hints for the compute catalog and launch wizard. Capacity values are user-safe posture hints and must not expose raw node inventory secrets. ' x-v3-read-model-gaps: - region capacity, queue posture, and price must remain backend-owned real data for catalog browse and launch readiness. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - in: query name: resource_class required: false schema: "$ref": "#/components/schemas/V3ComputeResourceClass" - in: query name: search required: false schema: type: string maxLength: 120 - in: query name: region_code required: false schema: type: string responses: '200': description: V3 compute catalog headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3ComputeCatalogResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/launch/compute/precheck": post: tags: - V3ReadModels operationId: precheckV3ComputeLaunchCompat summary: Precheck v3 compute launch readiness description: 'Read-only launch readiness contract for the v3 compute wizard. It evaluates project scope, catalog selection, dependency presence, and safe capacity posture before the user submits a mutating allocation request. This endpoint is safe to retry and must not create allocations, credentials, buckets, or network policy objects. For provider-family compute VM SKUs, the response includes `resolved.placement.availability_state` with one of the closed states from `Compute_VM_Availability_Model_v1.md`, such as `ready_now`, `prepare_on_demand`, or `blocked_capacity`. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3ComputeLaunchPrecheckRequest" responses: '200': description: V3 compute launch readiness content: application/json: schema: "$ref": "#/components/schemas/V3LaunchPrecheckResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/apps": get: tags: - V3ReadModels operationId: listV3AppsCompat summary: List v3 managed app catalog rows description: 'Temporary v3 migration read model for the Apps shell group. Returns the catalog, featured rows, entitlement state, dependency hints, and launch links used by the v3 app catalog. It is page-shaped and may later graduate into domain-owned app catalog resources. ' x-v3-read-model-gaps: - app cards should expose required GPU/storage, runtime cost, availability, and config-owned launch blockers instead of prose-only readiness. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - in: query name: category required: false schema: type: string maxLength: 80 - in: query name: search required: false schema: type: string maxLength: 120 responses: '200': description: V3 managed app catalog headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AppCatalogResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/apps/{app_slug}": get: tags: - V3ReadModels operationId: getV3AppDetailCompat summary: Get v3 managed app detail read model description: 'Returns the app detail read model used by the v3 catalog detail and app launch entry. Secrets, signed pull credentials, service-account tokens, and provider credentials must never be present in this response. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AppSlugPath" responses: '200': description: V3 managed app detail headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AppDetailResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/launch/apps/{app_slug}/precheck": post: tags: - V3ReadModels operationId: precheckV3AppLaunchCompat summary: Precheck v3 app launch readiness description: 'Read-only launch readiness contract for the v3 app wizard. It evaluates project entitlement, version availability, dependency presence, and basic runtime intent before the user submits a mutating app-instance request. This endpoint is safe to retry and must not create app instances, service accounts, credentials, buckets, or network policy objects. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppSlugPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3AppLaunchPrecheckRequest" responses: '200': description: V3 app launch readiness content: application/json: schema: "$ref": "#/components/schemas/V3LaunchPrecheckResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/storage": get: tags: - V3ReadModels operationId: listV3StorageBucketsCompat summary: List v3 storage workbench bucket rows description: 'Temporary v3 migration read model for the Storage shell group. Returns project-scoped bucket rows with usage, mount, access, lifecycle, and attention flags. Responses must not include raw object-store credentials, signed URLs, provider secrets, or private key material. ' x-v3-read-model-gaps: - bucket rows need provider-neutral endpoint, mount hint, and copyable URI fields when those values are safe to expose. - bucket rows need explicit size/quota, share count, attachment count, and last activity timestamps for scan decisions. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - in: query name: purpose required: false schema: "$ref": "#/components/schemas/V3StorageBucketPurpose" - in: query name: status required: false schema: type: string enum: - creating - active - failed - deleting - deleted - in: query name: scope required: false schema: type: string enum: - attached - unattached - flagged - in: query name: protocol required: false schema: type: string enum: - wekafs - posix - s3 - nfs - smb - csi - in: query name: search required: false schema: type: string maxLength: 120 - in: query name: sort required: false schema: type: string default: name_asc enum: - name_asc - name_desc - updated_at_desc - updated_at_asc - used_bytes_desc - used_bytes_asc - purpose_asc - status_asc responses: '200': description: V3 storage bucket workbench list headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3StorageBucketListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - V3Storage operationId: createV3StorageBucketCompat summary: Create a v3 storage bucket description: Creates a project-scoped bucket through the currently configured storage provider. The response is provider-neutral and never returns provider credentials, mount secrets, signed URLs, or raw backend identifiers. Requires an idempotency key. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3StorageBucketCreateRequest" responses: '201': description: V3 storage bucket created content: application/json: schema: "$ref": "#/components/schemas/V3StorageBucketCreateResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/storage/{bucket_id}": get: tags: - V3ReadModels operationId: getV3StorageBucketDetailCompat summary: Get v3 storage bucket detail read model description: 'Temporary v3 migration read model for a bucket detail page. The payload is presentation-shaped and sanitized: it may include object key previews, mount summaries, lifecycle posture, and access audiences, but never credential material, signed download/upload URLs, or raw provider config. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3StorageBucketIdPath" responses: '200': description: V3 storage bucket detail headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3StorageBucketDetailResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" patch: tags: - V3Storage operationId: updateV3StorageBucketCompat summary: Update provider-neutral bucket lifecycle metadata description: Updates bucket policy metadata such as purpose, quota, retention, access protocol, and access audience. Provider credentials and backend-specific identifiers are never returned. Audited as `storage.bucket.update`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3StorageBucketIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3StorageBucketUpdateRequest" responses: '200': description: V3 storage bucket updated content: application/json: schema: "$ref": "#/components/schemas/V3StorageBucketMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" delete: tags: - V3Storage operationId: deleteV3StorageBucketCompat summary: Delete a storage bucket when no active grants or attachments remain description: Deletes provider-local data and marks the bucket deleted only after active grants and attachments have been removed. Audited as `storage.bucket.delete`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3StorageBucketIdPath" responses: '204': description: V3 storage bucket deleted '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/storage/{bucket_id}/archive": post: tags: - V3Storage operationId: archiveV3StorageBucketCompat summary: Archive a storage bucket without deleting provider data description: Moves the bucket lifecycle state to deleting for operator follow-up while preserving provider data. Requires no active grants or attachments. Audited as `storage.bucket.archive`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3StorageBucketIdPath" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3StorageBucketArchiveRequest" responses: '200': description: V3 storage bucket archived content: application/json: schema: "$ref": "#/components/schemas/V3StorageBucketMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/storage/{bucket_id}/attachments": get: tags: - V3Storage operationId: listV3StorageAttachmentsCompat summary: List runtime storage attachments for a bucket description: 'Lists provider-neutral storage attachment state for one project storage namespace. This is a read model over Temporal/node-agent/provider state and never returns provider credentials, raw mount commands, or backend cluster identifiers. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3StorageBucketIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - in: query name: search required: false schema: type: string maxLength: 120 - in: query name: state required: false schema: type: string enum: - requested - prechecking - grant_applying - grant_applied - mounting - mounted - failed - detaching - detached - detach_failed x-enum-varnames: - ListV3StorageAttachmentsParamsStateRequested - ListV3StorageAttachmentsParamsStatePrechecking - ListV3StorageAttachmentsParamsStateGrantApplying - ListV3StorageAttachmentsParamsStateGrantApplied - ListV3StorageAttachmentsParamsStateMounting - ListV3StorageAttachmentsParamsStateMounted - ListV3StorageAttachmentsParamsStateFailed - ListV3StorageAttachmentsParamsStateDetaching - ListV3StorageAttachmentsParamsStateDetached - ListV3StorageAttachmentsParamsStateDetachFailed - in: query name: scope required: false schema: type: string enum: - allocation - workload - node - in: query name: access_mode required: false schema: type: string enum: - read_only - read_write - in: query name: sort required: false schema: type: string default: updated_at_desc enum: - updated_at_desc - updated_at_asc - requested_at_desc - requested_at_asc - mount_path_asc - state_asc responses: '200': description: Storage attachments content: application/json: schema: "$ref": "#/components/schemas/V3StorageAttachmentListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3Storage operationId: createV3StorageAttachmentCompat summary: Request storage attachment to a workload or allocation description: 'Persists an idempotent storage attachment intent and starts the Temporal attach workflow. The response returns the attachment state; it does not wait for the node-agent mount to complete. Audited as `storage.attachment.request`. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3StorageBucketIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3StorageAttachmentCreateRequest" responses: '202': description: Storage attachment workflow accepted content: application/json: schema: "$ref": "#/components/schemas/V3StorageAttachmentResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/storage/{bucket_id}/attachments/{attachment_id}": get: tags: - V3Storage operationId: getV3StorageAttachmentCompat summary: Get one storage attachment parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3StorageBucketIdPath" - "$ref": "#/components/parameters/V3StorageAttachmentIdPath" responses: '200': description: Storage attachment content: application/json: schema: "$ref": "#/components/schemas/V3StorageAttachmentResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" delete: tags: - V3Storage operationId: detachV3StorageAttachmentCompat summary: Request storage attachment detach description: 'Starts or signals the Temporal detach workflow. Persistent storage is never deleted by this endpoint. Audited as `storage.attachment.detach`. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3StorageBucketIdPath" - "$ref": "#/components/parameters/V3StorageAttachmentIdPath" responses: '202': description: Storage detach workflow accepted content: application/json: schema: "$ref": "#/components/schemas/V3StorageAttachmentResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/access": get: tags: - V3ReadModels operationId: getV3AccessOverviewCompat summary: Get v3 access posture overview read model description: 'Temporary v3 migration read model for the Access shell group. Returns project-scoped counts and drift signals across memberships, service accounts, credentials, and entitlements. Raw secrets, private keys, access tokens, refresh tokens, and provider credentials must never be returned. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" responses: '200': description: V3 access overview headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccessOverviewResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/access/memberships": get: tags: - V3ReadModels operationId: listV3AccessMembershipsCompat summary: List v3 access membership rows parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: search in: query required: false schema: type: string description: Case-insensitive search across username, display name, user id, and roles. - name: access_source in: query required: false schema: type: array items: type: string enum: - project_role - tenant_role - explicit - platform_role x-enum-varnames: - ListV3AccessMembershipsParamsAccessSourceProjectRole - ListV3AccessMembershipsParamsAccessSourceTenantRole - ListV3AccessMembershipsParamsAccessSourceExplicit - ListV3AccessMembershipsParamsAccessSourcePlatformRole style: form explode: false description: Filter memberships by effective access source. Repeat or comma-separate for multi-select. - name: tenant_role in: query required: false schema: type: array items: type: string enum: - owner - admin - member - billing_viewer style: form explode: false description: Filter memberships by tenant role. Repeat or comma-separate for multi-select. - name: project_role in: query required: false schema: type: array items: type: string enum: - owner - admin - member - viewer style: form explode: false description: Filter memberships by project role. Repeat or comma-separate for multi-select. - name: sort in: query required: false schema: type: string enum: - username_asc - username_desc - tenant_role_asc - tenant_role_desc - project_role_asc - project_role_desc description: Sort order for membership rows. Defaults to username ascending. responses: '200': description: V3 access memberships headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccessMembershipListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/access/memberships/users/{user_id}/bind": post: tags: - V3ReadModels operationId: bindV3AccessUserMembershipCompat summary: Bind a user to the caller tenant and project from the v3 access workbench description: | Tenant owners/admins may bind tenant and project roles for users in their tenant. Project owners/admins may bind project-scoped roles for existing users in the same tenant; tenant role changes remain tenant-admin only. The request body supplies the project_id, desired project_role, and, when the caller is a tenant admin, the desired tenant_role. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/UserIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/TenantBindUserMembershipRequest" responses: '200': description: Membership bound content: application/json: schema: "$ref": "#/components/schemas/AdminBindUserMembershipResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/access/memberships/users/{user_id}/remove": post: tags: - V3ReadModels operationId: removeV3AccessUserMembershipCompat summary: Remove a user's V3 access membership description: | Soft-deletes the target user's project membership or tenant-scoped memberships using the tenant-admin authority. Audited as `tenant.user.membership.remove`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/UserIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3RemoveAccessMembershipRequest" responses: '200': description: Membership removal result content: application/json: schema: "$ref": "#/components/schemas/V3RemoveAccessMembershipResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/access/service-accounts": get: tags: - V3ReadModels operationId: listV3AccessServiceAccountsCompat summary: List v3 access service-account rows parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: search in: query required: false description: Case-insensitive search across service account name, id, project, status, and scope. schema: type: string - name: status in: query required: false style: form explode: true schema: type: array items: type: string enum: - active - disabled - name: scope in: query required: false style: form explode: true schema: type: array items: type: string - name: sort in: query required: false description: Sort order for service account rows. Defaults to name ascending. schema: type: string default: name_asc enum: - name_asc - name_desc - key_age_asc - key_age_desc - rotation_due_asc - rotation_due_desc responses: '200': description: V3 access service accounts headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccessServiceAccountListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - V3ReadModels operationId: createV3AccessServiceAccountCompat summary: Create a project-scoped service account from the v3 access workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateServiceAccountRequest" responses: '201': description: Service account created content: application/json: schema: "$ref": "#/components/schemas/CreateServiceAccountResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/access/service-accounts/{service_account_id}": get: tags: - V3ReadModels operationId: getV3AccessServiceAccountCompat summary: Get project-scoped service account detail from the v3 access workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/ServiceAccountIdPath" responses: '200': description: Service account detail content: application/json: schema: "$ref": "#/components/schemas/ServiceAccount" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" delete: tags: - V3ReadModels operationId: deleteV3AccessServiceAccountCompat summary: Soft-delete a project-scoped service account from the v3 access workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ServiceAccountIdPath" responses: '200': description: Service account soft-deleted content: application/json: schema: "$ref": "#/components/schemas/ServiceAccount" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/access/service-accounts/{service_account_id}/disable": post: tags: - V3ReadModels operationId: disableV3AccessServiceAccountCompat summary: Disable a project-scoped service account from the v3 access workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ServiceAccountIdPath" responses: '200': description: Service account disabled content: application/json: schema: "$ref": "#/components/schemas/ServiceAccount" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/access/service-accounts/{service_account_id}/rotate-key": post: tags: - V3ReadModels operationId: rotateV3AccessServiceAccountKeyCompat summary: Rotate a project-scoped service-account credential from the v3 access workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ServiceAccountIdPath" responses: '200': description: Service account credential rotated content: application/json: schema: "$ref": "#/components/schemas/RotateServiceAccountCredentialResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/access/credentials": get: tags: - V3ReadModels operationId: listV3AccessCredentialsCompat summary: List v3 access credential map rows description: 'Returns credential posture metadata only. The response may include labels, fingerprints, status, ownership, and expiry metadata, but never raw public key payloads, private keys, token material, or provider secrets. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: search in: query required: false description: Case-insensitive search across credential label, fingerprint, id, subject id, kind, status, and management surface. schema: type: string - name: kind in: query required: false style: form explode: true schema: type: array items: type: string enum: - ssh_key - personal_api_key - service_account_key - workload_api_key - name: status in: query required: false style: form explode: true schema: type: array items: type: string enum: - active - expiring - expired - disabled - revoked - name: managed_in in: query required: false style: form explode: true schema: type: array items: type: string enum: - account - access - platform - name: sort in: query required: false description: Sort order for the credential list. Defaults to newest credentials first. schema: type: string default: created_at_desc enum: - created_at_desc - created_at_asc - label_asc - label_desc - last_used_at_desc - last_used_at_asc - expires_at_asc - expires_at_desc responses: '200': description: V3 access credentials headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccessCredentialListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - V3ReadModels operationId: createV3AccessCredentialCompat summary: Create a project-scoped access credential from the v3 access workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ProjectCreateAccessCredentialRequest" responses: '201': description: Project access credential created content: application/json: schema: "$ref": "#/components/schemas/ProjectCreateAccessCredentialResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/access/credentials/{credential_id}": get: tags: - V3ReadModels operationId: getV3AccessCredentialCompat summary: Get project-scoped access credential metadata from the v3 access workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AccessCredentialIdPath" responses: '200': description: Project access credential metadata content: application/json: schema: "$ref": "#/components/schemas/ProjectCreateAccessCredentialResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" patch: tags: - V3ReadModels operationId: updateV3AccessCredentialCompat summary: Update project-scoped access credential metadata from the v3 access workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AccessCredentialIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ProjectUpdateAccessCredentialRequest" responses: '200': description: Project access credential updated content: application/json: schema: "$ref": "#/components/schemas/ProjectCreateAccessCredentialResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" delete: tags: - V3ReadModels operationId: deleteV3AccessCredentialCompat summary: Delete a project-scoped access credential from the v3 access workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AccessCredentialIdPath" responses: '204': description: Project access credential deleted '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/access/credentials/{credential_id}/rotate": post: tags: - V3ReadModels operationId: rotateV3AccessCredentialCompat summary: Rotate a project-scoped access credential from the v3 access workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AccessCredentialIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ProjectRotateAccessCredentialRequest" responses: '200': description: Project access credential rotated content: application/json: schema: "$ref": "#/components/schemas/ProjectCreateAccessCredentialResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/access/credentials/{credential_id}/deliver": post: tags: - V3ReadModels operationId: deliverV3AccessCredentialCompat summary: Retrieve secure delivery for a project-scoped access credential from the v3 access workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AccessCredentialIdPath" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/ProjectDeliverAccessCredentialRequest" responses: '200': description: Access credential delivery prepared content: application/json: schema: "$ref": "#/components/schemas/ProjectDeliverAccessCredentialResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/access/entitlements": get: tags: - V3ReadModels operationId: listV3AccessEntitlementsCompat summary: List v3 access entitlement rows parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - in: query name: search required: false schema: type: string description: Case-insensitive search across entitlement name, id, project, kind, version, and limits. - in: query name: kind required: false schema: type: array items: type: string enum: - app - sku - region - product - tenant - project style: form explode: false description: Filter by entitlement kind. Repeat or comma-separate for multi-select. - in: query name: status required: false schema: type: array items: type: string enum: - enabled - disabled style: form explode: false description: Filter by entitlement status. Repeat or comma-separate for multi-select. - in: query name: sort required: false schema: type: string enum: - name_asc - name_desc - kind_asc - kind_desc - status_asc - status_desc default: name_asc description: Sort order for the entitlement list. responses: '200': description: V3 access entitlements headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccessEntitlementListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/access/entitlements/{app_slug}": put: tags: - V3ReadModels operationId: upsertV3AccessAppEntitlementCompat summary: Enable or disable an app entitlement for the active v3 project parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppSlugPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/UpsertAppEntitlementRequest" responses: '200': description: Project app entitlement updated content: application/json: schema: "$ref": "#/components/schemas/AppEntitlement" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/access/audit": get: tags: - V3ReadModels operationId: listV3AccessAuditEventsCompat summary: List v3 access audit events description: 'Returns access-family audit events for membership, service-account, credential, entitlement, identity, and connectivity mutations. This is a scoped read model over platform_audit_logs and must not return credential material, token payloads, private keys, provider secrets, or raw request bodies. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - "$ref": "#/components/parameters/AuditLogSort" - name: actor_user_id in: query required: false description: Optional actor filter applied inside the resolved project scope. schema: type: string format: uuid - name: actor_role in: query required: false description: Optional actor role filters applied inside the resolved project scope. style: form explode: true schema: type: array items: type: string - name: action in: query required: false description: Optional action-prefix filters. Repeated values are ORed. style: form explode: true schema: type: array items: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: V3 access audit events headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccessAuditEventListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/access/audit/export": get: tags: - V3ReadModels operationId: exportV3AccessAuditEventsCompat summary: Export filtered v3 access audit events description: Backend-owned export for the V3 access audit surface. Export honors the same project scope, access-family filters, time range, and sort as the access audit list and returns only sanitized access audit presentation fields. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AuditLogSort" - name: format in: query required: false schema: type: string enum: - csv - json default: csv - name: actor_user_id in: query required: false description: Optional actor filter applied inside the resolved project scope. schema: type: string format: uuid - name: actor_role in: query required: false description: Optional actor role filters applied inside the resolved project scope. style: form explode: true schema: type: array items: type: string - name: action in: query required: false description: Optional action-prefix filters. Repeated values are ORed. style: form explode: true schema: type: array items: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: Filtered V3 access audit event export content: text/csv: schema: type: string format: binary application/json: schema: "$ref": "#/components/schemas/V3AccessAuditEventExportResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/account": get: tags: - V3ReadModels operationId: getV3AccountOverviewCompat summary: Get v3 account overview read model description: 'Temporary v3 migration read model for the Account shell group. Returns personal profile, linked identity counts, personal credential counts, active session count, and personal attention items. Raw tokens, refresh tokens, private keys, password hashes, and provider secrets must never be returned. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" responses: '200': description: V3 account overview headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccountOverviewResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/account/profile": get: tags: - V3ReadModels operationId: getV3AccountProfileCompat summary: Get v3 account profile and linked identities parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" responses: '200': description: V3 account profile headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccountProfileResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" patch: tags: - V3ReadModels operationId: updateV3AccountProfileCompat summary: Update v3 account profile preferences parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdHeader" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3AccountProfileUpdateRequest" responses: '200': description: Updated V3 account profile content: application/json: schema: "$ref": "#/components/schemas/V3AccountProfileResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/account/security": get: tags: - V3ReadModels operationId: getV3AccountSecurityCompat summary: Get v3 account personal security posture description: 'Returns metadata for personal SSH/API credentials and MFA posture. This endpoint owns personal records; Access endpoints may reference the same records only as a permission map. No private keys or API tokens are returned. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" responses: '200': description: V3 account security posture headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccountSecurityResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/account/security/ssh-keys": post: tags: - V3ReadModels operationId: createV3AccountSshKeyCompat summary: Register a personal SSH key from the v3 account security workbench description: Without `X-Project-ID`, this creates a personal SSH key for the caller. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateSshPublicKeyRequest" responses: '201': description: SSH public key created content: application/json: schema: "$ref": "#/components/schemas/CreateSshPublicKeyResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" get: tags: - V3ReadModels operationId: listV3AccountSshKeysCompat summary: List personal SSH keys for launch and account security workflows description: Returns caller-owned SSH public keys through the V3 account namespace. No private key material is accepted or returned. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/PageSize" - name: cursor in: query required: false schema: type: string - name: status in: query required: false schema: type: string enum: - active - revoked - name: last_used in: query required: false schema: type: string enum: - used - never - name: search in: query required: false schema: type: string description: Case-insensitive match against key name, fingerprint, or public key. - name: sort in: query required: false schema: type: string enum: - created_at_desc - created_at_asc - last_used_at_desc - last_used_at_asc - name_asc - name_desc - status_asc default: created_at_desc responses: '200': description: SSH public keys content: application/json: schema: "$ref": "#/components/schemas/SshPublicKeyListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/account/security/ssh-keys/{key_id}": delete: tags: - V3ReadModels operationId: deleteV3AccountSshKeyCompat summary: Revoke a personal SSH key from the v3 account security workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/SshKeyIdPath" responses: '200': description: SSH public key removed content: application/json: schema: "$ref": "#/components/schemas/OkResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/account/security/ssh-keys/{key_id}/default": put: tags: - V3ReadModels operationId: setDefaultV3AccountSshKeyCompat summary: Set the caller's personal default SSH key from the v3 account security workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/SshKeyIdPath" responses: '200': description: Default SSH key updated content: application/json: schema: "$ref": "#/components/schemas/CreateSshPublicKeyResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/account/security/mfa/recovery-requests": post: tags: - V3ReadModels operationId: createV3AccountMFARecoveryRequestCompat summary: Start an account MFA recovery request description: Records an audited product-owned MFA recovery request for lost or changed authenticators. This endpoint does not remove a factor directly; privileged and last-factor resets require support or operator verification. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3AccountMFARecoveryRequest" responses: '202': description: MFA recovery request submitted content: application/json: schema: "$ref": "#/components/schemas/V3AccountMFARecoveryRequestResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/account/sessions": get: tags: - V3ReadModels operationId: listV3AccountSessionsCompat summary: List v3 account sessions parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/PageSize" - name: cursor in: query required: false schema: type: string - name: status in: query required: false schema: type: string enum: - active - expired - revoked - name: risk in: query required: false schema: type: string enum: - normal - attention - name: last_seen in: query required: false schema: type: string enum: - 6h - 12h - 24h - 7d - name: device in: query required: false schema: type: string description: Case-insensitive match against device, browser, or OS label. - name: search in: query required: false schema: type: string description: Case-insensitive match against device, browser, OS, IP, location, or provider. - name: sort in: query required: false schema: type: string enum: - last_seen_desc - last_seen_asc - signed_in_desc - signed_in_asc - expires_at_desc - expires_at_asc - device_asc - status_asc - risk_desc default: last_seen_desc responses: '200': description: V3 account sessions headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccountSessionListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/account/sessions/{session_id}/revoke": post: tags: - V3ReadModels operationId: revokeV3AccountSessionCompat summary: Revoke a tracked v3 account session parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - name: session_id in: path required: true schema: type: string format: uuid requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3AccountSessionRevokeRequest" responses: '200': description: Account session revoked content: application/json: schema: "$ref": "#/components/schemas/V3AccountSessionRevokeResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/account/sessions/revoke-others": post: tags: - V3ReadModels operationId: revokeOtherV3AccountSessionsCompat summary: Revoke every tracked v3 account session except the current session parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3AccountSessionRevokeRequest" responses: '200': description: Other account sessions revoked content: application/json: schema: "$ref": "#/components/schemas/V3AccountSessionRevokeResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/allocations": get: tags: - Allocations operationId: listAllocations parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string enum: - requested - provisioning - active - restarting - restart_failed - releasing - released - failed - release_failed responses: '200': description: Allocation list content: application/json: schema: "$ref": "#/components/schemas/AllocationListResponse" '401': "$ref": "#/components/responses/Unauthorized" post: tags: - Allocations operationId: createAllocation parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateAllocationRequest" responses: '201': description: Allocation created content: application/json: schema: "$ref": "#/components/schemas/CreateAllocationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/allocations/limits": get: tags: - Allocations operationId: getAllocationLimits parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" responses: '200': description: Effective per-user allocation concurrency limits for the current scope content: application/json: schema: "$ref": "#/components/schemas/AllocationLimits" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/runtime-bundles": get: tags: - Allocations operationId: listManagedRuntimeBundles summary: List platform-managed runtime bundles description: | Lists platform-owned runtime bundles that can be layered on top of a raw allocation. Runtime bundles describe supported install paths and activation hints; arbitrary packages installed by SSH users remain outside platform ownership. parameters: - "$ref": "#/components/parameters/XRequestId" - name: status in: query required: false schema: type: string enum: - active - deprecated - disabled responses: '200': description: Managed runtime bundles content: application/json: schema: "$ref": "#/components/schemas/ManagedRuntimeBundleListResponse" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/allocations/{allocation_id}/runtime-bundles": get: tags: - Allocations operationId: listAllocationRuntimeBundles summary: List managed runtime bundle state for an allocation parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AllocationIdPath" responses: '200': description: Allocation runtime bundle state content: application/json: schema: "$ref": "#/components/schemas/AllocationRuntimeBundleListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - Allocations operationId: applyAllocationRuntimeBundle summary: Apply or change a managed runtime bundle on an allocation description: | Records the desired managed runtime bundle for an allocation. Active allocations receive a bounded node-agent task that writes a platform-owned runtime environment descriptor under /etc/gpuaas/runtime. This endpoint does not manage arbitrary user-installed packages. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AllocationIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ApplyAllocationRuntimeBundleRequest" responses: '202': description: Runtime bundle apply recorded content: application/json: schema: "$ref": "#/components/schemas/ApplyAllocationRuntimeBundleResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/allocations/{allocation_id}": get: tags: - Allocations operationId: getAllocationById parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AllocationIdPath" responses: '200': description: Allocation detail content: application/json: schema: "$ref": "#/components/schemas/Allocation" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/allocations/{allocation_id}/timeline": get: tags: - Allocations operationId: getAllocationTimeline summary: Get sanitized provisioning and release timeline for an allocation description: 'Returns allocation state milestones, durable placement claims, and node-agent task progress for the allocation. Raw task params and output are intentionally omitted because they can contain infrastructure-only or credential-like material. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AllocationIdPath" - in: query name: limit schema: type: integer minimum: 1 maximum: 200 default: 50 description: Maximum number of recent timeline items to return. - in: query name: cursor schema: type: string description: Opaque cursor returned by the previous page. responses: '200': description: Allocation task timeline content: application/json: schema: "$ref": "#/components/schemas/AllocationTimelineResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/allocations": get: tags: - Allocations operationId: listProjectAllocations parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string enum: - requested - provisioning - active - restarting - restart_failed - releasing - released - failed - release_failed responses: '200': description: Project allocation list content: application/json: schema: "$ref": "#/components/schemas/AllocationListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/projects/{project_id}/allocations/{allocation_id}": get: tags: - Allocations operationId: getProjectAllocationById parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AllocationIdPath" responses: '200': description: Project allocation detail content: application/json: schema: "$ref": "#/components/schemas/Allocation" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/allocation-groups": get: tags: - AllocationGroups operationId: listProjectAllocationGroups summary: List allocation groups in a project description: | Lists project-scoped parent resources that group normal single-node allocations. Member allocations remain the source of placement, connection, billing, and release truth. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: "$ref": "#/components/schemas/AllocationGroupStatus" - name: group_kind in: query required: false schema: "$ref": "#/components/schemas/AllocationGroupKind" responses: '200': description: Project allocation groups content: application/json: schema: "$ref": "#/components/schemas/AllocationGroupListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - AllocationGroups operationId: createProjectAllocationGroup summary: Request a grouped set of normal allocations description: | Creates a project-scoped allocation-group parent and requests member allocations. Each member is a normal allocation with its own lifecycle, billing window, and connection target. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateAllocationGroupRequest" responses: '202': description: Allocation group request accepted content: application/json: schema: "$ref": "#/components/schemas/CreateAllocationGroupResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/projects/{project_id}/allocation-groups/{allocation_group_id}": get: tags: - AllocationGroups operationId: getProjectAllocationGroup summary: Get allocation group detail parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AllocationGroupIdPath" responses: '200': description: Allocation group detail content: application/json: schema: "$ref": "#/components/schemas/AllocationGroup" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/allocation-groups/{allocation_group_id}/release": post: tags: - AllocationGroups operationId: releaseProjectAllocationGroup summary: Request release for member allocations in a group description: | Records idempotent group release intent and fans out normal allocation release requests. Member allocations keep their own release state and release_failed handling. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AllocationGroupIdPath" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/ReleaseAllocationGroupRequest" responses: '202': description: Allocation group release accepted content: application/json: schema: "$ref": "#/components/schemas/ReleaseAllocationGroupResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/orgs/{org_id}/allocations": get: tags: - Allocations operationId: listOrgAllocations description: | List tenant-scoped allocations within one tenant. Delegated `shared_runtime_operator` tokens are allowed only for runtime-bounded control-plane allocation reads; handlers further narrow results to the requesting shared runtime placement. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OrgIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string enum: - requested - provisioning - active - restarting - restart_failed - releasing - released - failed - release_failed responses: '200': description: Org allocation list content: application/json: schema: "$ref": "#/components/schemas/AllocationListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/orgs/{org_id}/allocations/{allocation_id}": get: tags: - Allocations operationId: getOrgAllocationById description: | Read one tenant-scoped allocation. Delegated `shared_runtime_operator` tokens are allowed only when the requested allocation is referenced by the bound shared runtime placement. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OrgIdPath" - "$ref": "#/components/parameters/AllocationIdPath" responses: '200': description: Org allocation detail content: application/json: schema: "$ref": "#/components/schemas/Allocation" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/allocations/{allocation_id}/release": post: tags: - Allocations operationId: releaseAllocation parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AllocationIdPath" responses: '202': description: Release accepted content: application/json: schema: "$ref": "#/components/schemas/ReleaseAllocationResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/allocations/{allocation_id}/restart": post: tags: - Allocations operationId: restartAllocation parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AllocationIdPath" responses: '202': description: Restart accepted content: application/json: schema: "$ref": "#/components/schemas/RestartAllocationResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/allocations/{allocation_id}/metrics": get: tags: - Allocations operationId: getAllocationMetrics parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AllocationIdPath" responses: '200': description: Live node metrics for this allocation content: application/json: schema: "$ref": "#/components/schemas/AllocationMetricsResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/allocations/{allocation_id}/metrics/timeseries": get: tags: - Allocations operationId: getAllocationMetricsTimeseries parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AllocationIdPath" - name: window_seconds in: query required: false schema: type: integer minimum: 60 maximum: 86400 default: 900 - name: points in: query required: false schema: type: integer minimum: 10 maximum: 240 default: 60 responses: '200': description: Time-series node metrics for this allocation content: application/json: schema: "$ref": "#/components/schemas/AllocationMetricsTimeseriesResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/allocations/{allocation_id}/terminal-token": post: tags: - Allocations operationId: createTerminalToken summary: Mint a short-lived single-use terminal session token for a WebSocket connection description: 'Non-idempotent by design. Each successful call issues a new single-use terminal token. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AllocationIdPath" - "$ref": "#/components/parameters/IdempotencyKey" responses: '200': description: Terminal token issued content: application/json: schema: "$ref": "#/components/schemas/TerminalTokenResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': description: Allocation is not in active state content: application/json: schema: "$ref": "#/components/schemas/ErrorResponse" '429': "$ref": "#/components/responses/TooManyRequests" "/api/v1/allocations/{allocation_id}/ssh-keys": put: tags: - Allocations operationId: setAllocationSshKeys summary: Replace the registered SSH key set for an allocation description: 'Replaces the allocation''s attached registered SSH key IDs. The referenced keys must already be registered for the allocation owner. When the allocation is active, the control plane also queues a bounded node-agent task to rewrite the existing allocation runtime user''s `~/.ssh/authorized_keys` file with the resolved public keys. This endpoint never creates a new runtime user and never accepts raw public key material directly. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AllocationIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/SetAllocationSshKeysRequest" responses: '200': description: Allocation SSH keys updated; active allocations will also synchronize the runtime user's authorized_keys set asynchronously content: application/json: schema: "$ref": "#/components/schemas/Allocation" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/allocations/{allocation_id}/access-grants": get: tags: - Allocations operationId: listAllocationAccessGrants summary: List project-member SSH access grants for an allocation description: 'Lists explicit project-member SSH grants for the allocation in the active project context. Grants are separate from the allocation owner''s registered SSH key set and are used for live handoff without sharing private keys. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AllocationIdPath" responses: '200': description: Allocation access grants content: application/json: schema: "$ref": "#/components/schemas/AllocationAccessGrantListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - Allocations operationId: createAllocationAccessGrant summary: Grant a project member SSH access to an allocation description: 'Creates or updates an active allocation SSH access grant for a project member. The grantee must already be a member of the allocation''s project and the SSH key must be the grantee''s personal registered key. Allocation owners and project/tenant admins can grant access. Active allocations queue a bounded node-agent task that rewrites the existing allocation runtime user''s authorized_keys set with owner keys plus active grants. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AllocationIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateAllocationAccessGrantRequest" responses: '201': description: Allocation access grant created or updated content: application/json: schema: "$ref": "#/components/schemas/CreateAllocationAccessGrantResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/allocations/{allocation_id}/access-grants/{grant_id}": delete: tags: - Allocations operationId: revokeAllocationAccessGrant summary: Revoke a project-member SSH access grant description: Revokes an active allocation SSH access grant. The allocation owner, project/tenant admins, or the grantee can revoke. Active allocations queue a bounded node-agent task to remove the grantee key from the runtime user's authorized_keys set. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AllocationIdPath" - name: grant_id in: path required: true schema: type: string format: uuid responses: '200': description: Allocation access grant revoked content: application/json: schema: "$ref": "#/components/schemas/RevokeAllocationAccessGrantResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/storage/list": get: tags: - Storage operationId: listStorage parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - name: path in: query required: false schema: type: string - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Storage list content: application/json: schema: "$ref": "#/components/schemas/StorageListResponse" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/storage/download": get: tags: - Storage operationId: downloadStorageObject parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - name: path in: query required: true schema: type: string responses: '200': description: File download content: application/octet-stream: schema: type: string format: binary '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" "/api/v1/storage/upload": put: tags: - Storage operationId: uploadStorageObject parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - name: path in: query required: true schema: type: string requestBody: required: true content: application/octet-stream: schema: type: string format: binary responses: '200': description: Upload result content: application/json: schema: "$ref": "#/components/schemas/OkResponse" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/storage/mkdir": post: tags: - Storage operationId: createStorageDirectory parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/StorageMkdirRequest" responses: '200': description: Created content: application/json: schema: "$ref": "#/components/schemas/OkResponse" '401': "$ref": "#/components/responses/Unauthorized" '409': "$ref": "#/components/responses/Conflict" "/api/v1/storage/rename": post: tags: - Storage operationId: renameStorageObject parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/StorageRenameRequest" responses: '200': description: Renamed content: application/json: schema: "$ref": "#/components/schemas/OkResponse" '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/storage/delete": delete: tags: - Storage operationId: deleteStorageObject parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - name: path in: query required: true schema: type: string responses: '200': description: Deleted content: application/json: schema: "$ref": "#/components/schemas/OkResponse" '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/service-accounts": get: tags: - ServiceAccounts operationId: listServiceAccounts parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Service account list content: application/json: schema: "$ref": "#/components/schemas/ServiceAccountListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - ServiceAccounts operationId: createServiceAccount parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateServiceAccountRequest" responses: '201': description: Service account created content: application/json: schema: "$ref": "#/components/schemas/CreateServiceAccountResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/projects/{project_id}/service-accounts/{service_account_id}/disable": post: tags: - ServiceAccounts operationId: disableServiceAccount parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/ServiceAccountIdPath" responses: '200': description: Service account disabled content: application/json: schema: "$ref": "#/components/schemas/ServiceAccount" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/service-accounts/{service_account_id}/rotate-key": post: tags: - ServiceAccounts operationId: rotateServiceAccountCredential parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/ServiceAccountIdPath" responses: '200': description: Service account key rotated content: application/json: schema: "$ref": "#/components/schemas/RotateServiceAccountCredentialResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/service-accounts/{service_account_id}": get: tags: - ServiceAccounts operationId: getServiceAccount parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/ServiceAccountIdPath" responses: '200': description: Service account detail content: application/json: schema: "$ref": "#/components/schemas/ServiceAccount" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" delete: tags: - ServiceAccounts operationId: deleteServiceAccount parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/ServiceAccountIdPath" responses: '200': description: Service account soft-deleted content: application/json: schema: "$ref": "#/components/schemas/ServiceAccount" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/access-credentials": get: tags: - ProjectAccessCredentials operationId: listProjectAccessCredentials parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Project-scoped access credentials content: application/json: schema: "$ref": "#/components/schemas/ProjectAccessCredentialListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - ProjectAccessCredentials operationId: createProjectAccessCredential parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ProjectCreateAccessCredentialRequest" responses: '201': description: Project access credential created content: application/json: schema: "$ref": "#/components/schemas/ProjectCreateAccessCredentialResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/projects/{project_id}/access-credentials/{credential_id}": get: tags: - ProjectAccessCredentials operationId: getProjectAccessCredential parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AccessCredentialIdPath" responses: '200': description: Project access credential metadata content: application/json: schema: "$ref": "#/components/schemas/ProjectCreateAccessCredentialResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" patch: tags: - ProjectAccessCredentials operationId: updateProjectAccessCredential parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AccessCredentialIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ProjectUpdateAccessCredentialRequest" responses: '200': description: Project access credential updated content: application/json: schema: "$ref": "#/components/schemas/ProjectCreateAccessCredentialResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" delete: tags: - ProjectAccessCredentials operationId: deleteProjectAccessCredential parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AccessCredentialIdPath" responses: '204': description: Project access credential deleted '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/projects/{project_id}/access-credentials/{credential_id}/rotate": post: tags: - ProjectAccessCredentials operationId: rotateProjectAccessCredential parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AccessCredentialIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ProjectRotateAccessCredentialRequest" responses: '200': description: Project access credential rotated content: application/json: schema: "$ref": "#/components/schemas/ProjectCreateAccessCredentialResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/projects/{project_id}/access-credentials/{credential_id}/deliver": post: tags: - ProjectAccessCredentials operationId: deliverProjectAccessCredential summary: Retrieve secure delivery for a project-scoped access credential parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/AccessCredentialIdPath" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/ProjectDeliverAccessCredentialRequest" responses: '200': description: Access credential delivery prepared content: application/json: schema: "$ref": "#/components/schemas/ProjectDeliverAccessCredentialResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/auth/service-account/token": post: tags: - Auth operationId: createServiceAccountToken summary: Mint short-lived access token for a project-scoped service account security: [] parameters: - "$ref": "#/components/parameters/XRequestId" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ServiceAccountTokenRequest" responses: '200': description: Service account token issued content: application/json: schema: "$ref": "#/components/schemas/ServiceAccountTokenResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/auth/shared-runtime-operator/token": post: tags: - Auth operationId: createSharedRuntimeOperatorToken summary: Mint short-lived access token for a delegated tenant-shared runtime operator identity description: | Issue a delegated machine token bound to a single tenant-owned shared runtime. Intended claim shape is `SharedRuntimeOperatorTokenClaims`. security: [] parameters: - "$ref": "#/components/parameters/XRequestId" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/SharedRuntimeOperatorTokenRequest" responses: '200': description: Shared runtime operator token issued content: application/json: schema: "$ref": "#/components/schemas/SharedRuntimeOperatorTokenResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/overview": get: tags: - AdminUsers operationId: adminGetOverview summary: Aggregated admin dashboard counters parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Admin overview counters content: application/json: schema: "$ref": "#/components/schemas/AdminOverviewResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/ops/overview": get: tags: - AdminOps operationId: adminGetOpsOverview summary: Aggregated operational telemetry summary for admin operations dashboard parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Ops overview snapshot content: application/json: schema: "$ref": "#/components/schemas/AdminOpsOverviewResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/runtime/metadata": get: tags: - AdminOps operationId: adminGetRuntimeMetadata summary: Live runtime metadata for platform-control services description: | Returns the runtime image/build/deployment metadata visible from the running API process. The first slice reports gpuaas-api itself; broader multi-service discovery can be added without changing the item shape. parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Runtime metadata snapshot content: application/json: schema: "$ref": "#/components/schemas/AdminRuntimeMetadataResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/telemetry/fleet": get: tags: - AdminOps operationId: adminGetFleetTelemetry summary: Admin telemetry fleet rollups for CPU/GPU/memory/storage with tenant/project drill-down parameters: - "$ref": "#/components/parameters/XRequestId" - name: range in: query required: false schema: type: string enum: - 15m - 1h - 6h - 24h default: 1h description: Telemetry window range. - name: points in: query required: false schema: type: integer minimum: 10 maximum: 240 default: 60 description: Number of samples requested in each returned time series. responses: '200': description: Fleet telemetry snapshot content: application/json: schema: "$ref": "#/components/schemas/AdminFleetTelemetryResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/outbox/failed": get: tags: - AdminOps operationId: adminListFailedOutboxEvents summary: List failed outbox events (historical DLQ backlog) parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Failed outbox events content: application/json: schema: "$ref": "#/components/schemas/AdminOutboxFailedListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/outbox/{event_id}/requeue": post: tags: - AdminOps operationId: adminRequeueOutboxEvent summary: Requeue a failed outbox event back to pending parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: event_id in: path required: true schema: type: string format: uuid responses: '200': description: Outbox event requeued content: application/json: schema: "$ref": "#/components/schemas/AdminOutboxMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/outbox/{event_id}/discard": post: tags: - AdminOps operationId: adminDiscardOutboxEvent summary: Discard a failed outbox event from backlog (audited) parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: event_id in: path required: true schema: type: string format: uuid responses: '200': description: Outbox event discarded content: application/json: schema: "$ref": "#/components/schemas/AdminOutboxMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/dlq/messages": get: tags: - AdminOps operationId: adminListDLQMessages summary: List DLQ stream messages for operator triage parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: subject_prefix in: query required: false schema: type: string description: Optional DLQ subject prefix filter (for example dlq.gpuaas.provisioning.). responses: '200': description: DLQ messages page content: application/json: schema: "$ref": "#/components/schemas/AdminDLQMessageListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/dlq/messages/{stream_seq}/requeue": post: tags: - AdminOps operationId: adminRequeueDLQMessage summary: Requeue a DLQ message to its original subject parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: stream_seq in: path required: true schema: type: integer format: int64 minimum: 1 responses: '200': description: DLQ message requeued content: application/json: schema: "$ref": "#/components/schemas/AdminDLQMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/dlq/messages/{stream_seq}/discard": post: tags: - AdminOps operationId: adminDiscardDLQMessage summary: Discard a DLQ message by stream sequence (audited) parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: stream_seq in: path required: true schema: type: integer format: int64 minimum: 1 responses: '200': description: DLQ message discarded content: application/json: schema: "$ref": "#/components/schemas/AdminDLQMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/runbooks": get: tags: - AdminOps operationId: adminListRunbooks summary: List operational runbooks metadata for admin ops dashboards parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Runbook metadata list content: application/json: schema: "$ref": "#/components/schemas/AdminRunbookListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/runbooks/{runbook_id}": get: tags: - AdminOps operationId: adminGetRunbook summary: Get single operational runbook metadata by stable runbook ID parameters: - "$ref": "#/components/parameters/XRequestId" - name: runbook_id in: path required: true schema: type: string minLength: 1 responses: '200': description: Runbook metadata content: application/json: schema: "$ref": "#/components/schemas/AdminRunbook" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/users": get: tags: - AdminUsers operationId: adminListUsers parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Users content: application/json: schema: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/UserWithBalance" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - AdminUsers operationId: adminCreateUser parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminCreateUserRequest" responses: '201': description: Created content: application/json: schema: "$ref": "#/components/schemas/AdminCreateUserResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/users/{user_id}/balance": post: tags: - AdminUsers operationId: adminAdjustBalance parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/UserIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminAdjustBalanceRequest" responses: '200': description: Adjusted content: application/json: schema: "$ref": "#/components/schemas/OkResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/users/{user_id}/platform-roles": get: tags: - AdminRoles operationId: adminListUserPlatformRoles parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/UserIdPath" responses: '200': description: Active platform role bindings for a user content: application/json: schema: "$ref": "#/components/schemas/AdminUserPlatformRoleListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - AdminRoles operationId: adminBindUserPlatformRole parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/UserIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminBindUserPlatformRoleRequest" responses: '200': description: Role bound (idempotent) content: application/json: schema: "$ref": "#/components/schemas/AdminUserPlatformRoleMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/users/{user_id}/platform-roles/{role}": delete: tags: - AdminRoles operationId: adminRevokeUserPlatformRole parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/UserIdPath" - "$ref": "#/components/parameters/PlatformRolePath" responses: '200': description: Role revoked (idempotent) content: application/json: schema: "$ref": "#/components/schemas/AdminUserPlatformRoleMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/access-credentials": get: tags: - AdminAccessCredentials operationId: adminListAccessCredentials parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Access credentials content: application/json: schema: "$ref": "#/components/schemas/AdminAccessCredentialListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '429': "$ref": "#/components/responses/TooManyRequests" post: tags: - AdminAccessCredentials operationId: adminCreateAccessCredential parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminCreateAccessCredentialRequest" responses: '201': description: Access credential created content: application/json: schema: "$ref": "#/components/schemas/AdminCreateAccessCredentialResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/access-credentials/{credential_id}": get: tags: - AdminAccessCredentials operationId: adminGetAccessCredential parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/AccessCredentialIdPath" responses: '200': description: Access credential content: application/json: schema: "$ref": "#/components/schemas/AdminCreateAccessCredentialResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" patch: tags: - AdminAccessCredentials operationId: adminUpdateAccessCredential parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AccessCredentialIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminUpdateAccessCredentialRequest" responses: '200': description: Access credential updated content: application/json: schema: "$ref": "#/components/schemas/AdminCreateAccessCredentialResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" delete: tags: - AdminAccessCredentials operationId: adminDeleteAccessCredential parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AccessCredentialIdPath" responses: '204': description: Access credential deleted '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/access-credentials/{credential_id}/rotate": post: tags: - AdminAccessCredentials operationId: adminRotateAccessCredential parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AccessCredentialIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminRotateAccessCredentialRequest" responses: '200': description: Access credential rotated content: application/json: schema: "$ref": "#/components/schemas/AdminCreateAccessCredentialResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/tenants/{tenant_id}/memberships": post: tags: - AdminUsers operationId: adminBindUserMembership summary: Assign user tenant/project membership (platform-admin) parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/TenantIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminBindUserMembershipRequest" responses: '200': description: Membership bound (idempotent) content: application/json: schema: "$ref": "#/components/schemas/AdminBindUserMembershipResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/tenants": get: tags: - AdminUsers operationId: adminListTenants summary: List tenants for platform-admin onboarding operations parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Tenant list content: application/json: schema: "$ref": "#/components/schemas/AdminTenantListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/tenants/{tenant_id}/projects": get: tags: - AdminUsers operationId: adminListTenantProjects summary: List projects within a tenant for platform-admin onboarding operations parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/TenantIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Tenant project list content: application/json: schema: "$ref": "#/components/schemas/AdminTenantProjectListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/tenant/users": get: tags: - Users operationId: tenantListUsers summary: List users in caller tenant for tenant-admin or project-admin access workflows parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: project_id in: query required: false schema: type: string format: uuid description: When supplied, project owners/admins for that project may list basic users in the same tenant for project-access delegation. responses: '200': description: Tenant users content: application/json: schema: "$ref": "#/components/schemas/TenantMemberListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" post: tags: - Users operationId: tenantCreateUser summary: Create tenant user and bind tenant/project roles (tenant-admin scope) parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/TenantCreateUserRequest" responses: '201': description: User created and bound content: application/json: schema: "$ref": "#/components/schemas/AdminCreateUserResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/tenant/users/{user_id}/memberships": post: tags: - Users operationId: tenantBindUserMembership summary: Bind or update user tenant/project membership in caller tenant (tenant-admin scope) parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/UserIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/TenantBindUserMembershipRequest" responses: '200': description: Membership bound content: application/json: schema: "$ref": "#/components/schemas/AdminBindUserMembershipResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/users/{user_id}/refunds": get: tags: - AdminUsers operationId: adminListUserRefunds summary: List refund requests for a user parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/UserIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string enum: - accepted - completed - failed responses: '200': description: Refund requests content: application/json: schema: "$ref": "#/components/schemas/RefundListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - AdminUsers operationId: adminCreateRefund parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/UserIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminCreateRefundRequest" responses: '201': description: Refund request created and accepted under policy content: application/json: schema: "$ref": "#/components/schemas/AdminCreateRefundResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/maas-sites": get: tags: - AdminMaasSites operationId: adminListMaasSites parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: MAAS sites content: application/json: schema: "$ref": "#/components/schemas/MaasSiteListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - AdminMaasSites operationId: adminCreateMaasSite parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminCreateMaasSiteRequest" responses: '201': description: Created MAAS site content: application/json: schema: "$ref": "#/components/schemas/MaasSite" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/maas-sites/{id}": get: tags: - AdminMaasSites operationId: adminGetMaasSite parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" responses: '200': description: MAAS site content: application/json: schema: "$ref": "#/components/schemas/MaasSite" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" patch: tags: - AdminMaasSites operationId: adminUpdateMaasSite parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminUpdateMaasSiteRequest" responses: '200': description: Updated MAAS site content: application/json: schema: "$ref": "#/components/schemas/MaasSite" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" delete: tags: - AdminMaasSites operationId: adminDisableMaasSite parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" responses: '204': description: MAAS site disabled '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/maas-sites/{id}/discovery-candidates": get: tags: - AdminMaasSites operationId: adminListMaasDiscoveryCandidates parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: search in: query schema: type: string description: Search hostname, MAAS system id, power address, or SKU. - name: review_state in: query schema: type: string enum: - active - ignored - suppressed - all default: all - name: format in: query schema: type: string enum: - json - csv default: json description: CSV export honors the same search and review-state filters. responses: '200': description: MAAS discovery candidates for onboarding content: application/json: schema: "$ref": "#/components/schemas/MaasDiscoveryCandidateListResponse" text/csv: schema: type: string '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/maas-sites/{id}/discovery-candidates/{maas_system_id}/enrichment": get: tags: - AdminMaasSites operationId: adminGetMaasDiscoveryCandidateEnrichment parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" - name: maas_system_id in: path required: true schema: type: string minLength: 1 responses: '200': description: On-demand enrichment for a MAAS discovery candidate content: application/json: schema: "$ref": "#/components/schemas/MaasDiscoveryCandidateEnrichment" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/maas-sites/{id}/discovery-candidates/{maas_system_id}/decision": put: tags: - AdminMaasSites operationId: adminUpdateMaasDiscoveryCandidateDecision parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - name: maas_system_id in: path required: true schema: type: string minLength: 1 requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminUpdateMaasDiscoveryCandidateDecisionRequest" responses: '200': description: Updated MAAS discovery candidate decision content: application/json: schema: "$ref": "#/components/schemas/MaasDiscoveryCandidateDecision" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/maas-sites/{id}/profiles": get: tags: - AdminMaasSites operationId: adminListMaasSiteProfiles parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" responses: '200': description: MAAS site profiles content: application/json: schema: "$ref": "#/components/schemas/MaasSiteProfileListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - AdminMaasSites operationId: adminCreateMaasSiteProfile parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminCreateMaasSiteProfileRequest" responses: '201': description: Created MAAS site profile content: application/json: schema: "$ref": "#/components/schemas/MaasSiteProfile" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/maas-sites/{id}/profiles/{profile_id}": get: tags: - AdminMaasSites operationId: adminGetMaasSiteProfile parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" - "$ref": "#/components/parameters/MaasSiteProfileIdPath" responses: '200': description: MAAS site profile content: application/json: schema: "$ref": "#/components/schemas/MaasSiteProfile" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" patch: tags: - AdminMaasSites operationId: adminUpdateMaasSiteProfile parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - "$ref": "#/components/parameters/MaasSiteProfileIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminUpdateMaasSiteProfileRequest" responses: '200': description: Updated MAAS site profile content: application/json: schema: "$ref": "#/components/schemas/MaasSiteProfile" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" delete: tags: - AdminMaasSites operationId: adminDisableMaasSiteProfile parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - "$ref": "#/components/parameters/MaasSiteProfileIdPath" responses: '204': description: MAAS site profile disabled '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/maas-sites/{id}/credentials": post: tags: - AdminMaasSites operationId: adminWriteMaasSiteCredentials parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminWriteMaasSiteCredentialsRequest" responses: '200': description: MAAS site credentials written and validated content: application/json: schema: "$ref": "#/components/schemas/AdminWriteMaasSiteCredentialsResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/maas-sites/{id}/probe": post: tags: - AdminMaasSites operationId: adminProbeMaasSite parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" responses: '200': description: MAAS site probed content: application/json: schema: "$ref": "#/components/schemas/MaasSiteProbeResult" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/maas-sites/{id}/roce-assignments": get: tags: - AdminMaasSites operationId: adminListMaasRoceAssignments parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" responses: '200': description: MAAS site RoCE assignments content: application/json: schema: "$ref": "#/components/schemas/MaasRoceAssignmentListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - AdminMaasSites operationId: adminBulkUpsertMaasRoceAssignments parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminBulkUpsertMaasRoceAssignmentsRequest" responses: '200': description: MAAS site RoCE assignments upserted content: application/json: schema: "$ref": "#/components/schemas/MaasRoceAssignmentListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/maas-sites/{id}/roce-assignments/{assignment_id}": delete: tags: - AdminMaasSites operationId: adminDeleteMaasRoceAssignment parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - name: assignment_id in: path required: true schema: type: string format: uuid responses: '204': description: MAAS site RoCE assignment deleted '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/maas-sites/{id}/roce-assignments/{assignment_id}/enable": post: tags: - AdminMaasSites operationId: adminEnableMaasRoceAssignment parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - name: assignment_id in: path required: true schema: type: string format: uuid responses: '200': description: MAAS site RoCE assignment enabled content: application/json: schema: "$ref": "#/components/schemas/MaasRoceAssignment" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/maas-sites/{id}/roce-assignments/{assignment_id}/disable": post: tags: - AdminMaasSites operationId: adminDisableMaasRoceAssignmentExplicit parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - name: assignment_id in: path required: true schema: type: string format: uuid requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/AdminSetMaasRoceAssignmentStatusRequest" responses: '200': description: MAAS site RoCE assignment disabled content: application/json: schema: "$ref": "#/components/schemas/MaasRoceAssignment" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/onboardings": post: tags: - AdminMaasLifecycle operationId: adminStartMaasOnboarding parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasOnboardingRequest" responses: '202': description: MAAS onboarding accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasOnboardingResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" get: tags: - AdminMaasLifecycle operationId: adminListMaasOnboardings parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: batch_id in: query schema: type: string format: uuid - name: site_id in: query schema: type: string format: uuid - name: status in: query schema: "$ref": "#/components/schemas/MaasWorkflowStatus" responses: '200': description: MAAS onboarding workflows content: application/json: schema: "$ref": "#/components/schemas/MaasOnboardingListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/onboardings/batch": post: tags: - AdminMaasLifecycle operationId: adminStartMaasBatchOnboarding parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasBatchOnboardingRequest" responses: '202': description: MAAS batch onboarding accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasBatchOnboardingResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/onboardings/{onboarding_id}": get: tags: - AdminMaasLifecycle operationId: adminGetMaasOnboarding parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OnboardingIdPath" responses: '200': description: MAAS onboarding workflow detail content: application/json: schema: "$ref": "#/components/schemas/MaasOnboardingDetail" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/onboardings/{onboarding_id}/install-output": get: tags: - AdminMaasLifecycle operationId: adminGetMaasOnboardingInstallOutput parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OnboardingIdPath" responses: '200': description: Current MAAS installation output for the onboarding machine content: application/json: schema: "$ref": "#/components/schemas/MaasOnboardingInstallOutput" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/onboardings/{onboarding_id}/maas-events": get: tags: - AdminMaasLifecycle operationId: adminGetMaasOnboardingMaasEvents parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OnboardingIdPath" - name: level in: query schema: type: string - name: limit in: query schema: type: integer minimum: 1 maximum: 200 default: 50 responses: '200': description: Recent MAAS events for the onboarding machine content: application/json: schema: "$ref": "#/components/schemas/MaasOnboardingEvents" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/onboardings/{onboarding_id}/resume": post: tags: - AdminMaasLifecycle operationId: adminResumeMaasOnboarding parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/OnboardingIdPath" responses: '202': description: MAAS onboarding resume accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasOnboardingResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/onboardings/{onboarding_id}/rerun": post: tags: - AdminMaasLifecycle operationId: adminRerunMaasOnboarding parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/OnboardingIdPath" responses: '202': description: MAAS onboarding rerun accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasOnboardingResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/decommissions": get: tags: - AdminMaasLifecycle operationId: adminListMaasDecommissions parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: node_id in: query schema: type: string format: uuid - name: site_id in: query schema: type: string format: uuid - name: status in: query schema: "$ref": "#/components/schemas/MaasWorkflowStatus" responses: '200': description: MAAS decommission workflows content: application/json: schema: "$ref": "#/components/schemas/MaasDecommissionListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/decommissions/{decommission_id}": get: tags: - AdminMaasLifecycle operationId: adminGetMaasDecommission parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/DecommissionIdPath" responses: '200': description: MAAS decommission workflow detail content: application/json: schema: "$ref": "#/components/schemas/MaasDecommissionDetail" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/decommissions/{decommission_id}/install-output": get: tags: - AdminMaasLifecycle operationId: adminGetMaasDecommissionInstallOutput parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/DecommissionIdPath" responses: '200': description: Current MAAS installation output for the decommission machine content: application/json: schema: "$ref": "#/components/schemas/MaasDecommissionInstallOutput" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/decommissions/{decommission_id}/maas-events": get: tags: - AdminMaasLifecycle operationId: adminGetMaasDecommissionMaasEvents parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/DecommissionIdPath" - name: level in: query schema: type: string - name: limit in: query schema: type: integer minimum: 1 maximum: 200 default: 50 responses: '200': description: Recent MAAS events for the decommission machine content: application/json: schema: "$ref": "#/components/schemas/MaasDecommissionEvents" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/reconciliation/status": get: tags: - AdminMaasLifecycle operationId: adminGetMaasReconciliationStatus parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: MAAS reconciliation summary content: application/json: schema: "$ref": "#/components/schemas/MaasReconciliationStatus" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/reconciliation/drift": get: tags: - AdminMaasLifecycle operationId: adminListMaasDrift parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: site_id in: query schema: type: string format: uuid responses: '200': description: MAAS reconciliation drift records content: application/json: schema: "$ref": "#/components/schemas/MaasDriftListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/nodes": get: tags: - AdminNodes operationId: adminListNodes parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string enum: - active - retired - removing - maintenance - name: region_code in: query required: false schema: type: string responses: '200': description: Nodes content: application/json: schema: "$ref": "#/components/schemas/NodeAdminListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '429': "$ref": "#/components/responses/TooManyRequests" post: tags: - AdminNodes operationId: adminCreateNode summary: Register a new host as a node after any prior node identity on that host has been fully removed parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminCreateNodeRequest" responses: '201': description: Created content: application/json: schema: "$ref": "#/components/schemas/NodeAdmin" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/nodes/{node_id}/resource-slots": get: tags: - AdminNodes operationId: adminListNodeResourceSlots summary: List approved GPU slice slot inventory for a node parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Node resource slots content: application/json: schema: "$ref": "#/components/schemas/NodeResourceSlotListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" put: tags: - AdminNodes operationId: adminUpsertNodeResourceSlots summary: Upsert admin-approved GPU slice slot inventory for a node parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminUpsertNodeResourceSlotsRequest" responses: '200': description: Upserted node resource slots content: application/json: schema: "$ref": "#/components/schemas/NodeResourceSlotListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/nodes/{node_id}/slice-topology/discovery": get: tags: - AdminNodes operationId: adminGetLatestNodeSliceTopologyDiscovery summary: Get latest node-agent GPU slice topology discovery report description: Returns the latest advisory `slice.topology_discover` node task output. The returned candidate map is not schedulable until approved through `/resource-slots`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Latest topology discovery task, or null when none has run content: application/json: schema: "$ref": "#/components/schemas/NodeSliceTopologyDiscoveryResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - AdminNodes operationId: adminStartNodeSliceTopologyDiscovery summary: Queue node-agent GPU slice topology discovery description: Queues or reuses a non-expired `slice.topology_discover` task for a node. Discovery output is advisory only and must be approved into `gpuaas_node_resource_slots`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '202': description: Discovery task queued or already in progress content: application/json: schema: "$ref": "#/components/schemas/NodeSliceTopologyDiscoveryResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/os-images": get: tags: - AdminOSImages operationId: adminListOSImages summary: List admin-managed OS images for baremetal and GPU slice runtimes parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: target in: query schema: "$ref": "#/components/schemas/OSImageTarget" - name: status in: query schema: "$ref": "#/components/schemas/OSImageStatus" - name: sku in: query schema: type: string minLength: 1 responses: '200': description: OS image catalog entries content: application/json: schema: "$ref": "#/components/schemas/OSImageListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - AdminOSImages operationId: adminCreateOSImage summary: Register an OS image catalog entry parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminCreateOSImageRequest" responses: '201': description: Created OS image content: application/json: schema: "$ref": "#/components/schemas/OSImage" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/os-images/{image_id}": delete: tags: - AdminOSImages operationId: adminRemoveOSImage summary: Disable an OS image catalog entry so it cannot be selected for new hosts or slices parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/OSImageIdPath" responses: '204': description: Disabled '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/skus": get: tags: - AdminSkus operationId: adminListSkus parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Admin SKU list content: application/json: schema: "$ref": "#/components/schemas/AdminSkuListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '429': "$ref": "#/components/responses/TooManyRequests" post: tags: - AdminSkus operationId: adminCreateSku parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminCreateSkuRequest" responses: '201': description: Created SKU content: application/json: schema: "$ref": "#/components/schemas/AdminSku" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/skus/{sku}": patch: tags: - AdminSkus operationId: adminUpdateSku parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/SkuPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminUpdateSkuRequest" responses: '200': description: Updated SKU content: application/json: schema: "$ref": "#/components/schemas/AdminSku" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/skus/{sku}/activate": post: tags: - AdminSkus operationId: adminActivateSku parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/SkuPath" responses: '200': description: Activated SKU content: application/json: schema: "$ref": "#/components/schemas/AdminSku" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/skus/{sku}/deactivate": post: tags: - AdminSkus operationId: adminDeactivateSku parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/SkuPath" responses: '200': description: Deactivated SKU content: application/json: schema: "$ref": "#/components/schemas/AdminSku" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/nodes/{node_id}/probe": post: tags: - AdminNodes operationId: adminProbeNode parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Probed content: application/json: schema: type: object additionalProperties: false properties: ok: type: boolean status: type: string enum: - active - offline required: - ok - status '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/nodes/{node_id}/enrollment-token": post: tags: - AdminNodes operationId: adminCreateNodeEnrollmentToken summary: Create a single-use node enrollment token (manual onboarding) parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '201': description: Enrollment token created content: application/json: schema: "$ref": "#/components/schemas/AdminNodeEnrollmentTokenResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/nodes/{node_id}/reissue-enrollment": post: tags: - AdminNodes operationId: adminReissueNodeEnrollment summary: Reissue recovery enrollment material for an installed node agent description: Creates a short-lived enrollment token and returns operator-ready recovery instructions without requiring node bootstrap package generation. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '201': description: Re-enrollment material created content: application/json: schema: "$ref": "#/components/schemas/AdminNodeReenrollmentResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/nodes/{node_id}/bootstrap-script": post: tags: - AdminNodes operationId: adminCreateNodeBootstrapScript summary: Create a brokered node bootstrap script and short-lived bootstrap token parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" - name: mode in: query schema: type: string enum: - manual - cloud_init default: manual description: Render mode for operator shell or cloud-init consumption. - name: runtime_api_url in: query schema: type: string format: uri description: Optional provider-reachable runtime control-plane base URL installed as GPUAAS_API_URL. If omitted, the environment default NODE_BOOTSTRAP_API_URL is used. - name: terminal_api_url in: query schema: type: string format: uri description: Optional provider-reachable terminal node-stream base URL installed as GPUAAS_TERMINAL_API_URL. If omitted, the environment default NODE_BOOTSTRAP_TERMINAL_API_URL is used. responses: '201': description: Bootstrap script created content: application/json: schema: "$ref": "#/components/schemas/AdminNodeBootstrapScriptResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/nodes/{node_id}/agent-lifecycle": get: tags: - AdminNodes operationId: adminGetNodeAgentLifecycle summary: Get the latest node-agent lifecycle state and most recent lifecycle run for a node parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Current node-agent lifecycle state content: application/json: schema: type: object additionalProperties: false properties: node_id: type: string format: uuid state: "$ref": "#/components/schemas/NodeAgentLifecycleState" latest_run: allOf: - "$ref": "#/components/schemas/NodeAgentLifecycleRun" nullable: true required: - node_id - state '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - AdminNodes operationId: adminStartNodeAgentLifecycle summary: Start a node-agent lifecycle run for upgrade or repair description: | The control plane must support explicit execution modes for secure operator flows: `reimage` and `manual_install`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminStartNodeAgentLifecycleRequest" responses: '202': description: Node-agent lifecycle accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartNodeAgentLifecycleResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/nodes/{node_id}/agent-lifecycle/recover-stale": post: tags: - AdminNodes operationId: adminRecoverStaleNodeAgentLifecycle summary: Recover a stale node-agent lifecycle run description: | Reconciles the latest pending or running node-agent lifecycle only when it is stale. The operation uses existing node task and heartbeat evidence to complete or fail the lifecycle without requiring direct SQL mutation. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminRecoverStaleNodeAgentLifecycleRequest" responses: '200': description: Stale node-agent lifecycle reconciled content: application/json: schema: "$ref": "#/components/schemas/AdminStartNodeAgentLifecycleResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/nodes/{node_id}": delete: tags: - AdminNodes operationId: adminDeleteNode summary: Retire a node (reversible) parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '204': description: Node retired '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/nodes/{node_id}/reactivate": post: tags: - AdminNodes operationId: adminReactivateNode summary: Reactivate a retired node with the same node identity parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Node reactivated content: application/json: schema: type: object additionalProperties: false properties: ok: type: boolean status: type: string enum: - offline required: - ok - status '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/nodes/{node_id}/resume-lifecycle": post: tags: - AdminNodes operationId: adminResumeNodeLifecycle summary: Resume an in-progress node lifecycle transition description: | Recovers coarse in-progress inventory lifecycle states whose owning node task may have been lost, expired, or left in a stale dispatched lease. Supported states: `draining` -> `node.drain`, `removing` -> `node.uninstall`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Node lifecycle resume accepted content: application/json: schema: "$ref": "#/components/schemas/AdminResumeNodeLifecycleResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/nodes/{node_id}/remove": delete: tags: - AdminNodes operationId: adminRemoveNode summary: Permanently remove a retired node and start host cleanup for later host reuse parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '204': description: Node removal started '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/nodes/{node_id}/detach": delete: tags: - AdminNodes operationId: adminDetachNode summary: Permanently remove a retired node from GPUaaS without touching the underlying host description: | Performs GPUaaS-only control-plane cleanup for a retired node. This operation does not call MAAS, does not uninstall host software, and does not power cycle or release the underlying machine. Use this when the host has already been repurposed or must remain untouched outside GPUaaS. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '204': description: Node detached from GPUaaS '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/nodes/{node_id}/force-detach": delete: tags: - AdminNodes operationId: adminForceDetachNode summary: Forcefully remove a stuck node from GPUaaS without waiting for host lifecycle completion description: | Performs GPUaaS-only control-plane cleanup for a node stuck in `draining`, `removing`, or `retired` when the owning node-agent lifecycle cannot complete. This operation does not call MAAS, does not uninstall host software, and does not power cycle or release the underlying machine. Use this only for unreachable, repurposed, or disposable hosts where host-side cleanup is no longer possible. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '204': description: Node force-detached from GPUaaS '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/nodes/{node_id}/decommission": post: tags: - AdminMaasLifecycle operationId: adminStartMaasDecommission parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasDecommissionRequest" responses: '202': description: MAAS decommission accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasDecommissionResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/decommissions/{decommission_id}/resume": post: tags: - AdminMaasLifecycle operationId: adminResumeMaasDecommission parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/DecommissionIdPath" responses: '202': description: MAAS decommission resume accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasDecommissionResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/decommissions/{decommission_id}/cancel": post: tags: - AdminMaasLifecycle operationId: adminCancelMaasDecommission parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/DecommissionIdPath" responses: '202': description: MAAS decommission cancel accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasDecommissionResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/decommissions/{decommission_id}/rerun": post: tags: - AdminMaasLifecycle operationId: adminRerunMaasDecommission parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/DecommissionIdPath" responses: '202': description: MAAS decommission rerun accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasDecommissionResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/users/{user_id}": get: tags: - AdminUsers operationId: adminGetUser parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/UserIdPath" responses: '200': description: User detail with balance content: application/json: schema: "$ref": "#/components/schemas/UserWithBalance" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/allocations": get: tags: - AdminAllocations operationId: adminListAllocations summary: List all allocations across all users (admin) parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: user_id in: query required: false schema: type: string format: uuid - name: node_id in: query required: false schema: type: string format: uuid - name: status in: query required: false schema: type: string enum: - requested - provisioning - active - restarting - restart_failed - releasing - released - failed - release_failed responses: '200': description: Allocation list content: application/json: schema: "$ref": "#/components/schemas/AllocationListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/allocations/limits/policy": get: tags: - AdminAllocations operationId: adminGetAllocationConcurrencyPolicy summary: Get the global concurrent-allocation policy parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Global allocation concurrency policy details content: application/json: schema: "$ref": "#/components/schemas/AdminAllocationConcurrencyPolicy" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" put: tags: - AdminAllocations operationId: adminSetAllocationConcurrencyPolicy summary: Set the global concurrent-allocation policy parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminSetAllocationConcurrencyPolicyRequest" responses: '200': description: Updated global allocation concurrency policy details content: application/json: schema: "$ref": "#/components/schemas/AdminAllocationConcurrencyPolicy" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/allocations/placement-claims/backfill": post: tags: - AdminAllocations operationId: adminBackfillAllocationPlacementClaims summary: Backfill missing baremetal node-exclusive placement claims parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" responses: '200': description: Backfill result content: application/json: schema: "$ref": "#/components/schemas/AdminBackfillAllocationPlacementClaimsResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/admin/allocations/{allocation_id}/timeline": get: tags: - AdminAllocations operationId: adminGetAllocationTimeline summary: Get sanitized provisioning and release timeline for any allocation parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/AllocationIdPath" - in: query name: limit schema: type: integer minimum: 1 maximum: 200 default: 50 description: Maximum number of recent timeline items to return. - in: query name: cursor schema: type: string description: Opaque cursor returned by the previous page. responses: '200': description: Allocation task timeline content: application/json: schema: "$ref": "#/components/schemas/AllocationTimelineResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/allocations/{allocation_id}/force-release": post: tags: - AdminAllocations operationId: adminForceReleaseAllocation summary: Force-release any active allocation regardless of owner (admin) parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AllocationIdPath" requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: reason: type: string minLength: 3 required: - reason responses: '202': description: Force release accepted content: application/json: schema: "$ref": "#/components/schemas/ReleaseAllocationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/allocations/{allocation_id}/force-cleanup": post: tags: - AdminAllocations operationId: adminForceCleanupAllocation summary: Force-clean a stuck allocation after operator verification (admin) description: 'Fails a stuck GPU-slice allocation before it becomes active. By default claimed slots are moved to cleanup_blocked so an operator must inspect the host. If runtime_verified_absent is true, the operator has verified no VM or runtime remains and claimed slots are returned to available. For provider-owned VM allocations, cleanup completes the allocation release only after provider deletion is already confirmed. For managed node-agent allocations that are already releasing, release_failed, or failed, runtime_verified_absent=true may complete release when the node-agent heartbeat is stale or missing and the operator has verified no runtime remains. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AllocationIdPath" requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: reason: type: string minLength: 3 runtime_verified_absent: type: boolean default: false description: Set true only after verifying no VM/process/runtime remains on the slice host, provider VM, or managed node. required: - reason responses: '200': description: Force cleanup applied content: application/json: schema: "$ref": "#/components/schemas/ReleaseAllocationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/audit-logs": get: tags: - AdminAudit operationId: adminListAuditLogs parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - "$ref": "#/components/parameters/AuditLogSort" - name: actor_user_id in: query required: false schema: type: string format: uuid - name: actor_role in: query required: false schema: type: string enum: - user - admin - service_account - system - name: action in: query required: false schema: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: Paginated audit logs content: application/json: schema: "$ref": "#/components/schemas/AuditLogListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/audit-logs": get: tags: - Audit operationId: listMyAuditLogs summary: List audit logs visible to the authenticated user parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - "$ref": "#/components/parameters/AuditLogSort" - name: action in: query required: false schema: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: Paginated user-scoped audit logs content: application/json: schema: "$ref": "#/components/schemas/AuditLogListResponse" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/projects/{project_id}/audit-logs": get: tags: - Audit operationId: listProjectAuditLogs summary: List audit logs visible to project administrators parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - "$ref": "#/components/parameters/AuditLogSort" - name: action in: query required: false schema: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: Paginated project-scoped audit logs content: application/json: schema: "$ref": "#/components/schemas/AuditLogListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/orgs/{org_id}/audit-logs": get: tags: - Audit operationId: listOrgAuditLogs summary: List audit logs visible to tenant administrators parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OrgIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - "$ref": "#/components/parameters/AuditLogSort" - name: action in: query required: false schema: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: Paginated tenant-scoped audit logs content: application/json: schema: "$ref": "#/components/schemas/AuditLogListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/audit-logs/export": get: tags: - AdminAudit operationId: adminExportAuditLogsCsv parameters: - "$ref": "#/components/parameters/XRequestId" - name: actor_user_id in: query required: false schema: type: string format: uuid - name: actor_role in: query required: false schema: type: string - name: action in: query required: false schema: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - "$ref": "#/components/parameters/AuditLogSort" - name: format in: query required: false schema: type: string enum: - csv - json default: csv - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: Audit log export content: text/csv: schema: type: string format: binary application/json: schema: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AuditLogEntry" export: type: object additionalProperties: false properties: format: type: string enum: - json count: type: integer minimum: 0 sort: type: string required: - format - count - sort required: - items - export '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/payments/sessions": get: tags: - AdminPayments operationId: adminListPaymentSessions summary: List payment sessions for reconciliation and support (admin) parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: user_id in: query required: false schema: type: string format: uuid - name: status in: query required: false schema: type: string enum: - initiated - checkout_completed - credited - failed_reconcile - expired - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time security: - bearerAuth: [] responses: '200': description: Payment session list content: application/json: schema: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/PaymentSession" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/payments/sessions/{payment_session_id}": get: tags: - AdminPayments operationId: adminGetPaymentSession summary: Get payment session detail for reconciliation and support parameters: - "$ref": "#/components/parameters/XRequestId" - name: payment_session_id in: path required: true schema: type: string format: uuid security: - bearerAuth: [] responses: '200': description: Payment session content: application/json: schema: "$ref": "#/components/schemas/PaymentSession" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/payments/disputes": get: tags: - AdminPayments operationId: adminListPaymentDisputes summary: List payment disputes and chargebacks for finance operations parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string enum: - opened - needs_response - evidence_due - evidence_submitted - won - lost - closed - name: provider_dispute_id in: query required: false schema: type: string security: - bearerAuth: [] responses: '200': description: Payment dispute list content: application/json: schema: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/PaymentDispute" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/payments/disputes/{dispute_id}": get: tags: - AdminPayments operationId: adminGetPaymentDispute summary: Get payment dispute lifecycle detail parameters: - "$ref": "#/components/parameters/XRequestId" - name: dispute_id in: path required: true schema: type: string format: uuid security: - bearerAuth: [] responses: '200': description: Payment dispute content: application/json: schema: "$ref": "#/components/schemas/PaymentDispute" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/payments/sessions/{payment_session_id}/reconcile": post: tags: - AdminPayments operationId: adminReconcilePaymentSession summary: Reconcile a stuck or failed payment session with an audited operator action parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: payment_session_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminReconcilePaymentSessionRequest" security: - bearerAuth: [] responses: '200': description: Reconciled payment session content: application/json: schema: "$ref": "#/components/schemas/PaymentSession" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/admin/billing/reconciliation": get: tags: - AdminPayments operationId: adminListBillingReconciliation summary: List billing reconciliation runs and current usage-ledger posture parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" security: - bearerAuth: [] responses: '200': description: Billing reconciliation posture content: application/json: schema: "$ref": "#/components/schemas/BillingReconciliationListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - AdminPayments operationId: adminRunBillingReconciliation summary: Run an immediate usage-ledger reconciliation check parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" security: - bearerAuth: [] responses: '202': description: Billing reconciliation completed and recorded content: application/json: schema: "$ref": "#/components/schemas/BillingReconciliationRun" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/billing/reconciliation/{job_id}": get: tags: - AdminPayments operationId: adminGetBillingReconciliation summary: Get a billing reconciliation run parameters: - "$ref": "#/components/parameters/XRequestId" - name: job_id in: path required: true schema: type: string format: uuid security: - bearerAuth: [] responses: '200': description: Billing reconciliation run content: application/json: schema: "$ref": "#/components/schemas/BillingReconciliationRun" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/admin/billing/diagnostics": get: tags: - AdminPayments operationId: adminGetBillingDiagnostics summary: Fetch billing evidence by correlation id for support and dispute triage parameters: - "$ref": "#/components/parameters/XRequestId" - name: correlation_id in: query required: true schema: type: string security: - bearerAuth: [] responses: '200': description: Billing diagnostic evidence content: application/json: schema: "$ref": "#/components/schemas/BillingDiagnosticsResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/billing/shadow-rating": post: tags: - AdminPayments operationId: adminDryRunShadowRating summary: Dry-run a candidate rating against selected historical usage description: 'Rates selected historical allocation gpu_hour usage records against a candidate unit price without writing rated usage lines, ledger entries, invoice lines, or audit money rows. Intended for pricing-plan shadow tests before rollout. ' parameters: - "$ref": "#/components/parameters/XRequestId" security: - bearerAuth: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/BillingShadowRatingRequest" responses: '200': description: Shadow rating dry-run output content: application/json: schema: "$ref": "#/components/schemas/BillingShadowRatingResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/billing/provider-customers": post: tags: - AdminPayments operationId: adminLinkProviderCustomer summary: Link a provider customer identity to a billing account description: 'Links an existing payment-provider customer identity to an organization billing account. This endpoint is admin-only, idempotent, and writes an audit row in the same transaction as the provider-customer link. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" security: - bearerAuth: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/LinkProviderCustomerRequest" responses: '201': description: Provider customer link content: application/json: schema: "$ref": "#/components/schemas/ProviderCustomer" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/admin/billing/financial-restrictions/{scope_type}/{scope_id}": post: tags: - AdminPayments operationId: adminSetFinancialRestriction summary: Set a non-destructive financial restriction state description: 'Records the financial restriction state for a tenant, project, or user. This endpoint only records policy state and audited disabled reasons. It does not force-release, suspend, or otherwise mutate runtimes. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: scope_type in: path required: true schema: type: string enum: - tenant - project - user - name: scope_id in: path required: true schema: type: string format: uuid security: - bearerAuth: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/SetFinancialRestrictionRequest" responses: '200': description: Financial restriction state content: application/json: schema: "$ref": "#/components/schemas/FinancialRestriction" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/launch/compute": post: tags: - V3ReadModels operationId: submitV3ComputeLaunchCompat summary: Submit v3 compute launch description: 'Mutating submit endpoint for the v3 compute wizard. The endpoint reuses the allocation creation domain path and returns a normalized task handoff so the browser can route immediately to the v3 task progress page. Clients must send an idempotency key; replaying the same body with the same key must not create a duplicate workload. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3ComputeLaunchSubmitRequest" responses: '202': description: V3 compute launch accepted content: application/json: schema: "$ref": "#/components/schemas/V3LaunchSubmitResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/launch/apps/{app_slug}": post: tags: - V3ReadModels operationId: submitV3AppLaunchCompat summary: Submit v3 app launch description: 'Mutating submit endpoint for the v3 app wizard. The endpoint reuses the app-instance domain path and returns a normalized task handoff so app-backed runtimes remain workload subtypes in the v3 shell. Clients must send an idempotency key; replaying the same body with the same key must not create a duplicate app instance. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppSlugPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3AppLaunchSubmitRequest" responses: '202': description: V3 app launch accepted content: application/json: schema: "$ref": "#/components/schemas/V3LaunchSubmitResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/overview": get: tags: - V3ReadModels operationId: getV3PlatformOverviewCompat summary: Get v3 platform overview read model description: 'Temporary v3 migration read model for the Platform landing page. It summarizes operator families, fleet posture, active allocations, API health, worker posture, and DLQ state. Requires platform ops read permission. ' parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: V3 platform overview headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformOverviewResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops": get: tags: - V3ReadModels operationId: getV3PlatformOpsCompat summary: Get v3 platform live ops read model description: Temporary v3 migration read model for live triage, active signals, service health, and investigation pivots. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: V3 platform ops headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformOpsResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops/signals/{signal_key}/acknowledge": post: tags: - V3ReadModels operationId: acknowledgeV3PlatformSignalCompat summary: Acknowledge a v3 platform operator signal description: Backend-owned acknowledgement mutation for an active admin workbench signal. Requires platform ops write permission and an idempotency key for safe retries. The backend validates the supplied fingerprint against the current read-model signal before persisting acknowledgement state. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3PlatformSignalKeyPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3PlatformSignalAcknowledgeRequest" responses: '200': description: Signal acknowledgement state content: application/json: schema: "$ref": "#/components/schemas/V3PlatformSignalAckResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/ops/signals/{signal_key}/suppress": post: tags: - V3ReadModels operationId: suppressV3PlatformSignalCompat summary: Suppress a v3 platform operator signal description: Backend-owned suppression mutation for admin workbench queue noise. Suppression requires a future expires_at timestamp and resurfaces automatically when the backend fingerprint changes. Requires platform ops write permission. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3PlatformSignalKeyPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3PlatformSignalSuppressRequest" responses: '200': description: Signal suppression state content: application/json: schema: "$ref": "#/components/schemas/V3PlatformSignalAckResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/ops/signals/{signal_key}/acknowledgement": delete: tags: - V3ReadModels operationId: clearV3PlatformSignalAcknowledgementCompat summary: Clear acknowledgement or suppression for a v3 platform signal description: Clears current acknowledgement/suppression state for an admin workbench signal without deleting the audit trail. Requires platform ops write permission. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3PlatformSignalKeyPath" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3PlatformSignalClearRequest" responses: '200': description: Signal acknowledgement cleared content: application/json: schema: "$ref": "#/components/schemas/V3PlatformSignalAckResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/lifecycle": get: tags: - V3ReadModels operationId: getV3PlatformLifecycleCompat summary: Get v3 platform lifecycle read model description: Temporary v3 migration read model for node lifecycle posture, action queue, and inventory rows. Requires platform ops read permission. x-v3-read-model-gaps: - node list rows still need site/rack, kernel/driver/CUDA/fabric facts, and heartbeat age/severity from authoritative agent or MAAS inventory. - lifecycle nodes need a dedicated backend-owned node list query with server-side status, occupancy, site, search, cursor, and sort semantics. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: V3 platform lifecycle headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformLifecycleResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/lifecycle/attention/{attention_key}/review": post: tags: - V3ReadModels operationId: reviewV3ProvisioningAttentionCompat summary: Review a v3 provisioning attention item description: Marks a backend-owned provisioning attention item as taken care of or intentionally ignored. Requires platform ops write permission, persists an audit row, and keeps reviewed items available through history/evidence while removing them from default live attention queues. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3ProvisioningAttentionKeyPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3ProvisioningAttentionReviewRequest" responses: '200': description: Provisioning attention review state content: application/json: schema: "$ref": "#/components/schemas/V3ProvisioningAttentionReviewResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/lifecycle/onboarding": get: tags: - V3ReadModels operationId: getV3PlatformOnboardingGuidanceCompat summary: Get v3 platform node onboarding guidance read model description: Guidance-first node onboarding contract for site/profile selection, bootstrap readiness, manual fallback command shape, progress steps, and future automated MAAS mutation readiness. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: V3 platform node onboarding guidance headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformOnboardingGuidanceResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - V3PlatformLifecycle operationId: startV3PlatformOnboardingCompat summary: Start a v3 platform MAAS node onboarding workflow description: V3 lifecycle wrapper for the MAAS onboarding mutation. Requires platform ops mutation permission and an Idempotency-Key. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasOnboardingRequest" responses: '202': description: V3 platform MAAS onboarding accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasOnboardingResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/lifecycle/onboarding/batch": post: tags: - V3PlatformLifecycle operationId: startV3PlatformBatchOnboardingCompat summary: Start a v3 platform MAAS batch onboarding workflow description: V3 lifecycle wrapper for batch MAAS onboarding. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasBatchOnboardingRequest" responses: '202': description: V3 platform MAAS batch onboarding accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasBatchOnboardingResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/lifecycle/onboarding/{onboarding_id}": get: tags: - V3PlatformLifecycle operationId: getV3PlatformOnboardingCompat summary: Get v3 platform onboarding workflow detail parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OnboardingIdPath" responses: '200': description: V3 platform MAAS onboarding workflow detail content: application/json: schema: "$ref": "#/components/schemas/MaasOnboardingDetail" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/lifecycle/onboarding/{onboarding_id}/install-output": get: tags: - V3PlatformLifecycle operationId: getV3PlatformOnboardingInstallOutputCompat summary: Get v3 platform onboarding install output parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OnboardingIdPath" responses: '200': description: Current MAAS installation output for the onboarding machine content: application/json: schema: "$ref": "#/components/schemas/MaasOnboardingInstallOutput" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/lifecycle/onboarding/{onboarding_id}/maas-events": get: tags: - V3PlatformLifecycle operationId: getV3PlatformOnboardingMaasEventsCompat summary: Get v3 platform onboarding MAAS events parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/OnboardingIdPath" - name: level in: query schema: type: string - name: limit in: query schema: type: integer minimum: 1 maximum: 200 default: 50 responses: '200': description: Recent MAAS events for the onboarding machine content: application/json: schema: "$ref": "#/components/schemas/MaasOnboardingEvents" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/lifecycle/onboarding/{onboarding_id}/resume": post: tags: - V3PlatformLifecycle operationId: resumeV3PlatformOnboardingCompat summary: Resume a v3 platform onboarding workflow parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/OnboardingIdPath" responses: '202': description: V3 platform onboarding resume accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasOnboardingResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/lifecycle/onboarding/{onboarding_id}/rerun": post: tags: - V3PlatformLifecycle operationId: rerunV3PlatformOnboardingCompat summary: Rerun a v3 platform onboarding workflow parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/OnboardingIdPath" responses: '202': description: V3 platform onboarding rerun accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasOnboardingResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/lifecycle/nodes/{node_id}/decommission": post: tags: - V3PlatformLifecycle operationId: startV3PlatformNodeDecommissionCompat summary: Start a v3 platform node decommission or reimage workflow description: V3 lifecycle wrapper for MAAS node decommission/reimage. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasDecommissionRequest" responses: '202': description: V3 platform MAAS decommission accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasDecommissionResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/lifecycle/decommissions/{decommission_id}": get: tags: - V3PlatformLifecycle operationId: getV3PlatformDecommissionCompat summary: Get v3 platform decommission workflow detail parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/DecommissionIdPath" responses: '200': description: V3 platform MAAS decommission workflow detail content: application/json: schema: "$ref": "#/components/schemas/MaasDecommissionDetail" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/lifecycle/decommissions/{decommission_id}/install-output": get: tags: - V3PlatformLifecycle operationId: getV3PlatformDecommissionInstallOutputCompat summary: Get v3 platform decommission install output parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/DecommissionIdPath" responses: '200': description: Current MAAS installation output for the decommission machine content: application/json: schema: "$ref": "#/components/schemas/MaasDecommissionInstallOutput" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/lifecycle/decommissions/{decommission_id}/maas-events": get: tags: - V3PlatformLifecycle operationId: getV3PlatformDecommissionMaasEventsCompat summary: Get v3 platform decommission MAAS events parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/DecommissionIdPath" - name: level in: query schema: type: string - name: limit in: query schema: type: integer minimum: 1 maximum: 200 default: 50 responses: '200': description: Recent MAAS events for the decommission machine content: application/json: schema: "$ref": "#/components/schemas/MaasDecommissionEvents" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/lifecycle/decommissions/{decommission_id}/resume": post: tags: - V3PlatformLifecycle operationId: resumeV3PlatformDecommissionCompat summary: Resume a v3 platform decommission workflow parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/DecommissionIdPath" responses: '202': description: V3 platform decommission resume accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasDecommissionResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/lifecycle/decommissions/{decommission_id}/cancel": post: tags: - V3PlatformLifecycle operationId: cancelV3PlatformDecommissionCompat summary: Cancel a v3 platform decommission workflow parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/DecommissionIdPath" responses: '202': description: V3 platform decommission cancel accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasDecommissionResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/lifecycle/decommissions/{decommission_id}/rerun": post: tags: - V3PlatformLifecycle operationId: rerunV3PlatformDecommissionCompat summary: Rerun a v3 platform decommission workflow parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/DecommissionIdPath" responses: '202': description: V3 platform decommission rerun accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartMaasDecommissionResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/lifecycle/nodes/{node_id}": get: tags: - V3ReadModels operationId: getV3PlatformNodeDetailCompat summary: Get v3 platform node detail read model description: Temporary v3 migration read model for one node's lifecycle, MAAS, agent, slot, allocation, and task posture. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: V3 platform node detail headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformNodeDetailResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" delete: tags: - V3ReadModels operationId: retireV3PlatformNodeCompat summary: Retire a v3 platform node parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '204': description: Node retired '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/lifecycle/nodes/{node_id}/cordon": post: tags: - V3ReadModels operationId: cordonV3PlatformNodeCompat summary: Cordon a platform node description: Stops new scheduling onto an active node while preserving running workloads. Requires platform admin permission and Idempotency-Key. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Node cordoned content: application/json: schema: "$ref": "#/components/schemas/V3PlatformNodeLifecycleMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/lifecycle/nodes/{node_id}/drain": post: tags: - V3ReadModels operationId: drainV3PlatformNodeCompat summary: Drain a platform node description: Cordons an active or cordoned node and queues the node.drain lifecycle task. Requires platform admin permission and Idempotency-Key. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '202': description: Node drain queued content: application/json: schema: "$ref": "#/components/schemas/V3PlatformNodeLifecycleMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/lifecycle/nodes/{node_id}/resume-scheduling": post: tags: - V3ReadModels operationId: resumeSchedulingV3PlatformNodeCompat summary: Resume scheduling for a cordoned platform node description: Returns a cordoned node to the active scheduler pool. Requires platform admin permission and Idempotency-Key. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Node scheduling resumed content: application/json: schema: "$ref": "#/components/schemas/V3PlatformNodeLifecycleMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/lifecycle/nodes/{node_id}/refresh-inventory": post: tags: - V3ReadModels operationId: refreshInventoryV3PlatformNodeCompat summary: Refresh node inventory description: Queues slice topology discovery for GPU, slot, and hardware inventory refresh. Requires platform admin permission and Idempotency-Key. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '202': description: Inventory refresh queued content: application/json: schema: "$ref": "#/components/schemas/V3PlatformNodeLifecycleMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/config/setup": get: tags: - V3ReadModels operationId: getV3PlatformSetupChecklistCompat summary: Get v3 platform setup checklist read model description: Operator first-run readiness checklist covering identity/PKI, registry, MAAS provisioning, node-agent posture, runtime inventory, telemetry, network/security placeholders, and storage provider posture. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: V3 platform setup checklist headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformSetupChecklistResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/config": get: tags: - V3ReadModels operationId: getV3PlatformConfigCompat summary: Get v3 platform configuration read model description: Temporary v3 migration read model for SKU, OS image, quota, MAAS profile, and policy posture. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: V3 platform config headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformConfigResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/config/skus": post: tags: - V3ReadModels operationId: createV3PlatformConfigSkuCompat summary: Create a GPU SKU from the v3 platform config workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminCreateSkuRequest" responses: '201': description: SKU created content: application/json: schema: "$ref": "#/components/schemas/AdminSku" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/config/skus/{sku}": patch: tags: - V3ReadModels operationId: updateV3PlatformConfigSkuCompat summary: Update a GPU SKU from the v3 platform config workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/SkuPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminUpdateSkuRequest" responses: '200': description: SKU updated content: application/json: schema: "$ref": "#/components/schemas/AdminSku" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/config/skus/{sku}/activate": post: tags: - V3ReadModels operationId: activateV3PlatformConfigSkuCompat summary: Activate a GPU SKU from the v3 platform config workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/SkuPath" responses: '200': description: SKU activated content: application/json: schema: "$ref": "#/components/schemas/AdminSku" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/config/skus/{sku}/deactivate": post: tags: - V3ReadModels operationId: deactivateV3PlatformConfigSkuCompat summary: Deactivate a GPU SKU from the v3 platform config workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/SkuPath" responses: '200': description: SKU deactivated content: application/json: schema: "$ref": "#/components/schemas/AdminSku" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/config/provider-capacity-inventory": get: tags: - V3ReadModels operationId: listV3PlatformProviderCapacityInventoryCompat summary: List provider capacity inventory reports description: Operator read model for normalized Provider Capacity Inventory v1 reports ingested from runtime provider adapters. Requires platform admin permission. parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Provider capacity inventory reports content: application/json: schema: "$ref": "#/components/schemas/ProviderCapacityInventoryListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - V3ReadModels operationId: upsertV3PlatformProviderCapacityInventoryCompat summary: Ingest a provider capacity inventory report description: Operator/API ingestion endpoint for normalized Provider Capacity Inventory v1 reports emitted by Proxmox, MAAS-LXD, or future runtime provider adapters. Requires platform admin permission and idempotency. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ProviderCapacityInventoryUpsertRequest" responses: '200': description: Provider capacity inventory persisted content: application/json: schema: "$ref": "#/components/schemas/ProviderCapacityInventory" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/config/provider-capacity-inventory/{provider_id}/refresh": post: tags: - V3ReadModels operationId: requestV3PlatformProviderCapacityRefreshCompat summary: Request provider capacity inventory refresh description: Audited operator action that records a provider capacity refresh request. The provider reconciler owns provider credentials, consumes the request on its next cycle, refreshes capacity inventory, and marks request evidence complete. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - in: path name: provider_id required: true schema: type: string requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/ProviderCapacityRefreshRequest" responses: '202': description: Provider capacity refresh requested content: application/json: schema: "$ref": "#/components/schemas/ProviderResourceLifecycle" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/config/provider-resources": get: tags: - V3ReadModels operationId: listV3PlatformProviderResourcesCompat summary: List provider resource lifecycle records description: Operator read model for provider-owned resources, lifecycle state, desired state, retry metadata, and evidence references. Requires platform admin permission. parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Provider resource lifecycle records content: application/json: schema: "$ref": "#/components/schemas/ProviderResourceLifecycleListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - V3ReadModels operationId: upsertV3PlatformProviderResourceCompat summary: Persist provider resource lifecycle state description: Operator/API ingestion endpoint for normalized Provider Lifecycle And Orphan Reconciliation state. This endpoint stores desired/observed state only and does not call Proxmox, MAAS, LXD, or other provider APIs. Requires platform admin permission and idempotency. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ProviderResourceLifecycleUpsertRequest" responses: '200': description: Provider resource lifecycle persisted content: application/json: schema: "$ref": "#/components/schemas/ProviderResourceLifecycle" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/config/provider-resources/{provider_resource_id}/retry-cleanup": post: tags: - V3ReadModels operationId: retryV3PlatformProviderResourceCleanupCompat summary: Retry provider resource cleanup or reconciliation description: Audited operator action that moves a provider resource lifecycle record back to requested retry state. The provider reconciler performs provider-side work asynchronously. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - in: path name: provider_resource_id required: true schema: type: string format: uuid requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/ProviderResourceLifecycleActionRequest" responses: '200': description: Provider resource retry requested content: application/json: schema: "$ref": "#/components/schemas/ProviderResourceLifecycle" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/config/provider-resources/{provider_resource_id}/request-delete": post: tags: - V3ReadModels operationId: requestDeleteV3PlatformProviderResourceCompat summary: Request provider resource deletion description: Audited operator action that marks provider cleanup as requested. Billing state is not extended by cleanup debt; provider deletion is reconciled asynchronously. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - in: path name: provider_resource_id required: true schema: type: string format: uuid requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/ProviderResourceLifecycleActionRequest" responses: '200': description: Provider resource deletion requested content: application/json: schema: "$ref": "#/components/schemas/ProviderResourceLifecycle" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/config/provider-resources/{provider_resource_id}/quarantine": post: tags: - V3ReadModels operationId: quarantineV3PlatformProviderResourceCompat summary: Quarantine a provider resource description: Audited operator action that blocks placement, warm-pool reuse, route publication, and storage attachment for an ambiguous provider resource. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - in: path name: provider_resource_id required: true schema: type: string format: uuid requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/ProviderResourceLifecycleActionRequest" responses: '200': description: Provider resource quarantined content: application/json: schema: "$ref": "#/components/schemas/ProviderResourceLifecycle" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/config/provider-resources/{provider_resource_id}/mark-external": post: tags: - V3ReadModels operationId: markExternalV3PlatformProviderResourceCompat summary: Mark provider resource as externally managed description: Audited operator action for provider resources discovered outside GPUaaS ownership. The resource is blocked from placement and tracked as operator-owned evidence. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - in: path name: provider_resource_id required: true schema: type: string format: uuid requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/ProviderResourceLifecycleActionRequest" responses: '200': description: Provider resource marked externally managed content: application/json: schema: "$ref": "#/components/schemas/ProviderResourceLifecycle" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/config/os-images": post: tags: - V3ReadModels operationId: createV3PlatformConfigOSImageCompat summary: Create an OS image from the v3 platform config workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminCreateOSImageRequest" responses: '201': description: OS image created content: application/json: schema: "$ref": "#/components/schemas/OSImage" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/config/os-images/{image_id}": patch: tags: - V3ReadModels operationId: updateV3PlatformConfigOSImageCompat summary: Update an OS image from the v3 platform config workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/OSImageIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminUpdateOSImageRequest" responses: '200': description: OS image updated content: application/json: schema: "$ref": "#/components/schemas/OSImage" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" delete: tags: - V3ReadModels operationId: deleteV3PlatformConfigOSImageCompat summary: Remove an OS image from the v3 platform config workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/OSImageIdPath" responses: '204': description: OS image removed '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/config/os-images/{image_id}/deprecate": post: tags: - V3ReadModels operationId: deprecateV3PlatformConfigOSImageCompat summary: Deprecate an OS image from the v3 platform config workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/OSImageIdPath" responses: '200': description: OS image deprecated content: application/json: schema: "$ref": "#/components/schemas/OSImage" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/config/os-images/{image_id}/reactivate": post: tags: - V3ReadModels operationId: reactivateV3PlatformConfigOSImageCompat summary: Reactivate an OS image from the v3 platform config workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/OSImageIdPath" responses: '200': description: OS image reactivated content: application/json: schema: "$ref": "#/components/schemas/OSImage" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/config/quotas/allocation-concurrency": get: tags: - V3ReadModels operationId: getV3PlatformConfigAllocationConcurrencyPolicyCompat summary: Get the global concurrent-allocation policy from the v3 platform config workbench parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Global allocation concurrency policy details content: application/json: schema: "$ref": "#/components/schemas/AdminAllocationConcurrencyPolicy" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" put: tags: - V3ReadModels operationId: setV3PlatformConfigAllocationConcurrencyPolicyCompat summary: Set the global concurrent-allocation policy from the v3 platform config workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminSetAllocationConcurrencyPolicyRequest" responses: '200': description: Updated global allocation concurrency policy details content: application/json: schema: "$ref": "#/components/schemas/AdminAllocationConcurrencyPolicy" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/evidence": get: tags: - V3ReadModels operationId: getV3PlatformEvidenceCompat summary: Get v3 platform evidence read model description: Temporary v3 migration read model for audit and investigation pivots. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: V3 platform evidence headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformEvidenceResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/finance": get: tags: - V3ReadModels operationId: getV3PlatformFinanceCompat summary: Get v3 platform finance operations read model description: Temporary v3 migration read model for payment-session operations and financial intervention posture. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: V3 platform finance headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformFinanceResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/finance/sessions": get: tags: - V3ReadModels operationId: getV3PlatformFinanceSessionsCompat summary: List v3 platform finance payment sessions description: Workbench read model for payment-session triage. Returns backend-owned signal keys and ack fields so clients never derive acknowledgement identity. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string - name: user_id in: query required: false schema: type: string format: uuid - name: correlation_id in: query required: false schema: type: string responses: '200': description: V3 platform finance sessions headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformFinanceSessionsResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/finance/sessions/{payment_session_id}": get: tags: - V3ReadModels operationId: getV3PlatformFinanceSessionDetailCompat summary: Get v3 platform finance payment-session detail description: Focused payment-session detail read model with diagnostics, evidence links, and manual recovery operation targets. Provider replay is intentionally not exposed by this slice. parameters: - "$ref": "#/components/parameters/XRequestId" - name: payment_session_id in: path required: true schema: type: string format: uuid responses: '200': description: V3 platform finance session detail headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformFinanceSessionDetailResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/iam": get: tags: - V3ReadModels operationId: getV3PlatformIAMCompat summary: Get v3 platform IAM read model description: Temporary v3 migration read model for users and platform role posture. Requires platform ops read permission. x-v3-read-model-gaps: - user rows need last activity, tenant/project context, status or risk, balance posture, evidence pivots, server-side sort, and scoped export. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: search in: query required: false schema: type: string description: Search users by id, username, tenant id, project id, or role. - name: format in: query required: false schema: type: string enum: - json - csv default: json description: Return the filtered list as JSON or CSV. - name: platform_role in: query required: false schema: type: string enum: - any - platform_admin - platform_ops - platform_user - platform_superadmin description: Filter users by platform role. `any` returns users with any platform role binding or legacy admin posture. - name: role in: query required: false schema: type: string enum: - admin - user description: Filter by legacy account role while platform role bindings are migrated. - name: tenant_id in: query required: false schema: type: string format: uuid description: Filter users by home tenant or tenant role binding. - name: project_id in: query required: false schema: type: string format: uuid description: Filter users by project role binding. - name: posture in: query required: false schema: type: string enum: - privileged - stale - local_password - oidc - missing_tenant description: Filter users by backend-computed IAM posture. - name: review in: query required: false schema: type: string enum: - stale_identity description: Filter users into a governance review queue using backend-owned identity posture signals available in the read model. - name: sort in: query required: false schema: type: string enum: - username_asc - username_desc - role_asc - role_desc - last_activity_desc - last_activity_asc - created_at_desc - created_at_asc default: username_asc description: Stable server-side sort for cursor pagination. responses: '200': description: V3 platform IAM headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformIAMResponse" text/csv: schema: type: string '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/storage/{bucket_id}/grants": get: tags: - V3Storage operationId: listV3StorageGrantsCompat summary: List storage grants for a bucket description: 'Contract baseline for provider-neutral storage sharing. Returns GPUaaS grant records and compiled-policy posture only; provider credentials, raw WEKA policy JSON, and provider admin identifiers are never returned. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3StorageBucketIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - in: query name: search required: false schema: type: string maxLength: 120 - in: query name: status required: false schema: type: string enum: - active - revoked - expired - in: query name: subject_kind required: false schema: "$ref": "#/components/schemas/V3StoragePrincipalKind" - in: query name: permission required: false schema: "$ref": "#/components/schemas/V3StoragePermission" - in: query name: sort required: false schema: type: string default: created_at_desc enum: - created_at_desc - created_at_asc - expires_at_desc - expires_at_asc - subject_asc - subject_desc responses: '200': description: Storage grants content: application/json: schema: "$ref": "#/components/schemas/V3StorageGrantListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3Storage operationId: createV3StorageGrantCompat summary: Create a bucket or prefix storage grant description: 'Creates a GPUaaS-owned storage grant. Provider adapters compile this grant into provider policy, for example WEKA IAM or bucket policy, but GPUaaS remains the source of truth. This mutation is idempotent and audited as `storage.grant.create`. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3StorageBucketIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3StorageGrantCreateRequest" responses: '201': description: Storage grant created content: application/json: schema: "$ref": "#/components/schemas/V3StorageGrantResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/storage/{bucket_id}/grants/{grant_id}": delete: tags: - V3Storage operationId: revokeV3StorageGrantCompat summary: Revoke a storage grant description: 'Revokes future provider credential issuance for a grant and asks the provider adapter to remove or narrow compiled policy where supported. Active STS credentials may remain valid until expiry if the provider cannot revoke individual sessions. Audited as `storage.grant.revoke`. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3StorageBucketIdPath" - "$ref": "#/components/parameters/V3StorageGrantIdPath" responses: '200': description: Storage grant revoked content: application/json: schema: "$ref": "#/components/schemas/V3StorageGrantRevokeResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/storage/{bucket_id}/credentials": post: tags: - V3Storage operationId: issueV3StorageCredentialCompat summary: Issue short-lived scoped storage credentials description: 'Issues direct S3-compatible credentials after GPUaaS IAM and storage grant checks. This endpoint may return provider credential material exactly once to the caller and must not be used by read models, cached responses, or browser local storage. For WEKA this maps to STS/session credentials when available. Audited as `auth.provider_credential.issue` and `storage.credential.issue`. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3StorageBucketIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3StorageCredentialIssueRequest" responses: '201': description: Scoped storage credential issued content: application/json: schema: "$ref": "#/components/schemas/V3StorageCredentialIssueResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/access/quotas": get: tags: - V3ReadModels operationId: getV3AccessQuotaPostureCompat summary: Get v3 access quota posture description: 'Returns the selected project/user effective allocation quota posture: concurrent allocation limit, current usage, launch headroom, and guidance links. This is the user/project quota surface; platform-level quota policy editing remains under Platform Config. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" responses: '200': description: V3 access quota posture headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccessQuotaResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/apps/artifacts": get: tags: - V3Apps operationId: listV3AppArtifactsCompat summary: List registered app artifacts for the active V3 project description: Lists project-scoped app artifacts through the V3 project header contract. Registry credentials, wrapped pull tokens, and provider secrets are never returned by this list response. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: app_slug in: query required: false schema: type: string - name: search in: query required: false schema: type: string - name: artifact_kind in: query required: false schema: type: string enum: - oci - blob - name: source_type in: query required: false schema: type: string enum: - oci_registry - s3 - gcs - azure_blob - https - huggingface - artifact_store - name: lifecycle_state in: query required: false schema: type: string enum: - published - promoted - deprecated - retired - name: trust_state in: query required: false schema: type: string enum: - unverified - verified - failed_verification - revoked - name: sort in: query required: false schema: type: string enum: - name_asc - name_desc - updated_at_desc - updated_at_asc - created_at_desc - created_at_asc - size_desc - size_asc default: updated_at_desc - name: format in: query required: false schema: type: string enum: - json - csv default: json responses: '200': description: V3 app artifacts content: application/json: schema: "$ref": "#/components/schemas/AppArtifactListResponse" text/csv: schema: type: string '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3Apps operationId: registerV3AppArtifactCompat summary: Register a published app artifact digest for the active V3 project description: Registers a previously published app artifact using the V3 project header contract. Audited by the app-artifact service and replay-protected by the V3 idempotency gate. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/RegisterAppArtifactRequest" responses: '201': description: V3 app artifact registered content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/apps/artifacts/publish-intents": post: tags: - V3Apps operationId: createV3AppArtifactPublishIntentCompat summary: Issue a short-lived app artifact publish intent description: Issues a short-lived publish intent for direct artifact publication. The response may contain wrapped credential delivery material; clients must not persist or log credential fields. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateAppArtifactPublishIntentRequest" responses: '201': description: V3 app artifact publish intent issued content: application/json: schema: "$ref": "#/components/schemas/AppArtifactPublishIntent" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/apps/artifacts/{artifact_id}/pull-intent": post: tags: - V3Apps operationId: createV3AppArtifactPullIntentCompat summary: Issue a short-lived pull intent for a V3 app artifact description: Returns registry metadata and Vault-wrapped pull credentials for a project app artifact. Artifact bytes remain on the registry path; clients must not cache or persist the wrapped credential. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AppArtifactIdPath" responses: '201': description: V3 app artifact pull intent issued content: application/json: schema: "$ref": "#/components/schemas/ArtifactPullIntent" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/apps/artifacts/{artifact_id}/promote": post: tags: - V3Apps operationId: promoteV3AppArtifactCompat summary: Promote a V3 app artifact to a channel parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppArtifactIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/PromoteAppArtifactRequest" responses: '200': description: V3 app artifact promoted content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/apps/artifacts/{artifact_id}/verify": post: tags: - V3Apps operationId: verifyV3AppArtifactCompat summary: Mark a V3 app artifact as verified parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppArtifactIdPath" responses: '200': description: V3 app artifact verified content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/apps/artifacts/{artifact_id}/revoke": post: tags: - V3Apps operationId: revokeV3AppArtifactCompat summary: Revoke trust for a V3 app artifact parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppArtifactIdPath" responses: '200': description: V3 app artifact trust revoked content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/apps/artifacts/{artifact_id}/deprecate": post: tags: - V3Apps operationId: deprecateV3AppArtifactCompat summary: Deprecate a V3 app artifact parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppArtifactIdPath" responses: '200': description: V3 app artifact deprecated content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/apps/artifacts/{artifact_id}/retire": post: tags: - V3Apps operationId: retireV3AppArtifactCompat summary: Retire a V3 app artifact from new use parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppArtifactIdPath" responses: '200': description: V3 app artifact retired content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/finance/users/{user_id}/refunds": get: tags: - V3PlatformFinance operationId: listV3PlatformFinanceUserRefundsCompat summary: List refund workflows for a user through the V3 finance boundary description: Lists refund workflow rows for a user. This is an actionable workflow surface; usage and ledger rows remain immutable read-only records. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/UserIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string enum: - accepted - completed - failed - name: correlation_id in: query required: false schema: type: string - name: time_range in: query required: false description: Relative time window applied to refund created_at. Use `custom` with `from` and/or `to` for explicit windows. schema: type: string enum: - 6h - 12h - 24h - 7d - custom - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time - name: sort in: query required: false schema: type: string enum: - id_asc - id_desc - created_at_desc - created_at_asc - updated_at_desc - updated_at_asc - status_asc - status_desc - amount_desc - amount_asc default: id_asc - name: format in: query required: false schema: type: string enum: - json - csv default: json responses: '200': description: V3 finance user refund workflows content: application/json: schema: "$ref": "#/components/schemas/RefundListResponse" text/csv: schema: type: string '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3PlatformFinance operationId: createV3PlatformFinanceUserRefundCompat summary: Create a ledger-safe refund workflow for a user description: Creates an audited refund workflow. This endpoint does not mutate ledger rows directly; any ledger correction remains append-only and owned by the finance service boundary. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/UserIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminCreateRefundRequest" responses: '201': description: V3 finance refund workflow created content: application/json: schema: "$ref": "#/components/schemas/AdminCreateRefundResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/finance/payment-sessions": get: tags: - V3PlatformFinance operationId: listV3PlatformFinancePaymentSessionsRawCompat summary: List raw payment sessions for V3 finance operators description: Raw payment-session support list for reconciliation workflows. Prefer `/api/v1/v3/platform/finance/sessions` for the operator workbench read model. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: user_id in: query required: false schema: type: string format: uuid - name: status in: query required: false schema: type: string enum: - initiated - checkout_completed - credited - failed_reconcile - expired - name: correlation_id in: query required: false schema: type: string - name: time_range in: query required: false description: Relative time window applied to payment-session created_at. Use `custom` with `from` and/or `to` for explicit windows. schema: type: string enum: - 6h - 12h - 24h - 7d - custom - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time - name: sort in: query required: false schema: type: string enum: - id_asc - id_desc - created_at_desc - created_at_asc - initiated_at_desc - initiated_at_asc - status_asc - status_desc - requested_amount_desc - requested_amount_asc - credited_amount_desc - credited_amount_asc default: id_asc - name: format in: query required: false schema: type: string enum: - json - csv default: json responses: '200': description: V3 finance raw payment sessions content: application/json: schema: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/PaymentSession" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination text/csv: schema: type: string '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/finance/payment-sessions/{payment_session_id}": get: tags: - V3PlatformFinance operationId: getV3PlatformFinancePaymentSessionRawCompat summary: Get a raw payment session for V3 finance operators parameters: - "$ref": "#/components/parameters/XRequestId" - name: payment_session_id in: path required: true schema: type: string format: uuid responses: '200': description: V3 finance raw payment session content: application/json: schema: "$ref": "#/components/schemas/PaymentSession" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/finance/payment-sessions/{payment_session_id}/reconcile": post: tags: - V3PlatformFinance operationId: reconcileV3PlatformFinancePaymentSessionCompat summary: Reconcile a payment session through a ledger-safe V3 finance action description: Reconciles a stuck or failed payment session. `post_credit` appends an immutable ledger entry and marks the session credited; state-only actions mark expired or failed with an audited operator reason. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: payment_session_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminReconcilePaymentSessionRequest" responses: '200': description: V3 finance payment session reconciled content: application/json: schema: "$ref": "#/components/schemas/PaymentSession" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/storage/{bucket_id}/objects/download": get: tags: - V3Storage operationId: downloadV3StorageObjectCompat summary: Download an object from a v3 storage bucket description: Downloads object bytes through the active V3 project context. The `path` query may be either bucket-relative or include the bucket prefix; the server normalizes it and rejects paths outside the bucket. No auth material is accepted in the query string. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3StorageBucketIdPath" - "$ref": "#/components/parameters/V3StorageObjectPathQuery" responses: '200': description: Storage object bytes content: application/octet-stream: schema: type: string format: binary '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/storage/{bucket_id}/objects/upload": put: tags: - V3Storage operationId: uploadV3StorageObjectCompat summary: Upload object bytes to a v3 storage bucket description: Uploads object bytes through the active V3 project context. The `path` query may be bucket-relative or include the bucket prefix; the server normalizes it and rejects paths outside the bucket. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3StorageBucketIdPath" - "$ref": "#/components/parameters/V3StorageObjectPathQuery" requestBody: required: true content: application/octet-stream: schema: type: string format: binary responses: '200': description: Storage object uploaded content: application/json: schema: "$ref": "#/components/schemas/OkResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/storage/{bucket_id}/objects/mkdir": post: tags: - V3Storage operationId: createV3StorageDirectoryCompat summary: Create a directory marker in a v3 storage bucket description: Creates a provider-neutral directory marker through the active V3 project context. The supplied path may be bucket-relative or include the bucket prefix. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3StorageBucketIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3StorageObjectPathRequest" responses: '200': description: Storage directory created content: application/json: schema: "$ref": "#/components/schemas/OkResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/storage/{bucket_id}/objects": delete: tags: - V3Storage operationId: deleteV3StorageObjectCompat summary: Delete an object or prefix from a v3 storage bucket description: Deletes an object or prefix through the active V3 project context. The `path` query may be bucket-relative or include the bucket prefix; the server normalizes it and rejects paths outside the bucket. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3StorageBucketIdPath" - "$ref": "#/components/parameters/V3StorageObjectPathQuery" responses: '200': description: Storage object deleted content: application/json: schema: "$ref": "#/components/schemas/OkResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/lifecycle/maas-sites": get: tags: - V3ReadModels operationId: listV3PlatformMaasSitesCompat summary: List v3 MAAS provisioning sites parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: MAAS sites content: application/json: schema: "$ref": "#/components/schemas/MaasSiteListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - V3ReadModels operationId: createV3PlatformMaasSiteCompat summary: Register a v3 MAAS provisioning site parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminCreateMaasSiteRequest" responses: '201': description: Created MAAS site content: application/json: schema: "$ref": "#/components/schemas/MaasSite" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/lifecycle/maas-sites/{id}": get: tags: - V3ReadModels operationId: getV3PlatformMaasSiteCompat summary: Get a v3 MAAS provisioning site parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" responses: '200': description: MAAS site content: application/json: schema: "$ref": "#/components/schemas/MaasSite" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" patch: tags: - V3ReadModels operationId: updateV3PlatformMaasSiteCompat summary: Update a v3 MAAS provisioning site parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminUpdateMaasSiteRequest" responses: '200': description: Updated MAAS site content: application/json: schema: "$ref": "#/components/schemas/MaasSite" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" delete: tags: - V3ReadModels operationId: disableV3PlatformMaasSiteCompat summary: Disable a v3 MAAS provisioning site parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" responses: '204': description: MAAS site disabled '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/lifecycle/maas-sites/{id}/discovery-candidates": get: tags: - V3ReadModels operationId: listV3PlatformMaasDiscoveryCandidatesCompat summary: List v3 MAAS discovery candidates parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: search in: query schema: type: string description: Search hostname, MAAS system id, power address, or SKU. - name: review_state in: query schema: type: string enum: - active - ignored - suppressed - all default: all - name: format in: query schema: type: string enum: - json - csv default: json description: CSV export honors the same search and review-state filters. responses: '200': description: MAAS discovery candidates content: application/json: schema: "$ref": "#/components/schemas/MaasDiscoveryCandidateListResponse" text/csv: schema: type: string '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/lifecycle/maas-sites/{id}/discovery-candidates/export": get: tags: - V3ReadModels operationId: exportV3PlatformMaasDiscoveryCandidatesCompat summary: Export filtered v3 MAAS discovery candidates description: Backend-owned export for MAAS discovery candidates. Export honors the same authorization scope, search, review-state filter, and cursor/page-size contract as the discovery candidate list; omit cursor and page_size to export all matching rows. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: search in: query schema: type: string description: Search hostname, MAAS system id, power address, or SKU. - name: review_state in: query schema: type: string enum: - active - ignored - suppressed - all default: all - name: format in: query schema: type: string enum: - csv - json default: csv responses: '200': description: Filtered MAAS discovery candidates content: text/csv: schema: type: string application/json: schema: "$ref": "#/components/schemas/MaasDiscoveryCandidateListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/lifecycle/maas-sites/{id}/discovery-candidates/{maas_system_id}/enrichment": get: tags: - V3ReadModels operationId: getV3PlatformMaasDiscoveryCandidateEnrichmentCompat summary: Get v3 MAAS discovery candidate enrichment parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" - name: maas_system_id in: path required: true schema: type: string minLength: 1 responses: '200': description: MAAS discovery candidate enrichment content: application/json: schema: "$ref": "#/components/schemas/MaasDiscoveryCandidateEnrichment" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/lifecycle/maas-sites/{id}/discovery-candidates/{maas_system_id}/decision": put: tags: - V3ReadModels operationId: updateV3PlatformMaasDiscoveryCandidateDecisionCompat summary: Review a v3 MAAS discovery candidate parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - name: maas_system_id in: path required: true schema: type: string minLength: 1 requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminUpdateMaasDiscoveryCandidateDecisionRequest" responses: '200': description: Updated MAAS discovery candidate decision content: application/json: schema: "$ref": "#/components/schemas/MaasDiscoveryCandidateDecision" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/lifecycle/maas-sites/{id}/profiles": get: tags: - V3ReadModels operationId: listV3PlatformMaasSiteProfilesCompat summary: List v3 MAAS provisioning profiles parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" responses: '200': description: MAAS site profiles content: application/json: schema: "$ref": "#/components/schemas/MaasSiteProfileListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3ReadModels operationId: createV3PlatformMaasSiteProfileCompat summary: Create a v3 MAAS provisioning profile parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminCreateMaasSiteProfileRequest" responses: '201': description: Created MAAS site profile content: application/json: schema: "$ref": "#/components/schemas/MaasSiteProfile" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/lifecycle/maas-sites/{id}/profiles/{profile_id}": get: tags: - V3ReadModels operationId: getV3PlatformMaasSiteProfileCompat summary: Get a v3 MAAS provisioning profile parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" - "$ref": "#/components/parameters/MaasSiteProfileIdPath" responses: '200': description: MAAS site profile content: application/json: schema: "$ref": "#/components/schemas/MaasSiteProfile" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" patch: tags: - V3ReadModels operationId: updateV3PlatformMaasSiteProfileCompat summary: Update a v3 MAAS provisioning profile parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - "$ref": "#/components/parameters/MaasSiteProfileIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminUpdateMaasSiteProfileRequest" responses: '200': description: Updated MAAS site profile content: application/json: schema: "$ref": "#/components/schemas/MaasSiteProfile" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" delete: tags: - V3ReadModels operationId: disableV3PlatformMaasSiteProfileCompat summary: Disable a v3 MAAS provisioning profile parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - "$ref": "#/components/parameters/MaasSiteProfileIdPath" responses: '204': description: MAAS site profile disabled '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/lifecycle/maas-sites/{id}/credentials": post: tags: - V3ReadModels operationId: writeV3PlatformMaasSiteCredentialsCompat summary: Write v3 MAAS site credentials parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminWriteMaasSiteCredentialsRequest" responses: '200': description: MAAS site credentials written and validated content: application/json: schema: "$ref": "#/components/schemas/AdminWriteMaasSiteCredentialsResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/lifecycle/maas-sites/{id}/probe": post: tags: - V3ReadModels operationId: probeV3PlatformMaasSiteCompat summary: Probe a v3 MAAS site parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" responses: '200': description: MAAS site probed content: application/json: schema: "$ref": "#/components/schemas/MaasSiteProbeResult" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/lifecycle/maas-sites/{id}/roce-assignments": get: tags: - V3ReadModels operationId: listV3PlatformMaasRoceAssignmentsCompat summary: List v3 MAAS RoCE assignments parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" responses: '200': description: MAAS site RoCE assignments content: application/json: schema: "$ref": "#/components/schemas/MaasRoceAssignmentListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3ReadModels operationId: upsertV3PlatformMaasRoceAssignmentsCompat summary: Upsert v3 MAAS RoCE assignments parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminBulkUpsertMaasRoceAssignmentsRequest" responses: '200': description: MAAS site RoCE assignments upserted content: application/json: schema: "$ref": "#/components/schemas/MaasRoceAssignmentListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/lifecycle/maas-sites/{id}/roce-assignments/{assignment_id}": delete: tags: - V3ReadModels operationId: deleteV3PlatformMaasRoceAssignmentCompat summary: Delete a v3 MAAS RoCE assignment parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - name: assignment_id in: path required: true schema: type: string format: uuid responses: '204': description: MAAS site RoCE assignment deleted '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/lifecycle/maas-sites/{id}/roce-assignments/{assignment_id}/enable": post: tags: - V3ReadModels operationId: enableV3PlatformMaasRoceAssignmentCompat summary: Enable a v3 MAAS RoCE assignment parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - name: assignment_id in: path required: true schema: type: string format: uuid responses: '200': description: MAAS site RoCE assignment enabled content: application/json: schema: "$ref": "#/components/schemas/MaasRoceAssignment" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/lifecycle/maas-sites/{id}/roce-assignments/{assignment_id}/disable": post: tags: - V3ReadModels operationId: disableV3PlatformMaasRoceAssignmentCompat summary: Disable a v3 MAAS RoCE assignment parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - name: assignment_id in: path required: true schema: type: string format: uuid requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/AdminSetMaasRoceAssignmentStatusRequest" responses: '200': description: MAAS site RoCE assignment disabled content: application/json: schema: "$ref": "#/components/schemas/MaasRoceAssignment" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/lifecycle/reconciliation/status": get: tags: - V3ReadModels operationId: getV3PlatformMaasReconciliationStatusCompat summary: Get v3 MAAS reconciliation status parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: MAAS reconciliation summary content: application/json: schema: "$ref": "#/components/schemas/MaasReconciliationStatus" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/lifecycle/reconciliation/drift": get: tags: - V3ReadModels operationId: listV3PlatformMaasDriftCompat summary: List v3 MAAS reconciliation drift parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: site_id in: query schema: type: string format: uuid - name: search in: query description: Search host, hostname, node id, MAAS system id, MAAS status, power state, IPs, or drift details. schema: type: string - name: time_range in: query description: Optional time window for last reconciled or resolved drift rows. schema: type: string enum: - 6h - 12h - 24h - 7d - custom - name: from in: query description: Inclusive RFC3339 lower bound when time_range=custom. schema: type: string format: date-time - name: to in: query description: Inclusive RFC3339 upper bound when time_range=custom. schema: type: string format: date-time - name: sort in: query schema: type: string default: node_id_asc enum: - node_id_asc - node_id_desc - last_reconciled_at_desc - last_reconciled_at_asc - hostname_asc - hostname_desc - rule_asc - rule_desc - name: format in: query schema: type: string default: json enum: - json - csv responses: '200': description: MAAS reconciliation drift records content: application/json: schema: "$ref": "#/components/schemas/MaasDriftListResponse" text/csv: schema: type: string '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/lifecycle/onboardings": get: tags: - V3ReadModels operationId: listV3PlatformMaasOnboardingsCompat summary: List v3 MAAS onboarding workflow runs parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: site_id in: query schema: type: string format: uuid - name: batch_id in: query schema: type: string - name: status in: query schema: type: string - name: search in: query schema: type: string description: Search hostname, onboarding id, node id, MAAS system id, SKU, or IPMI IP. - name: time_range in: query schema: type: string enum: - 6h - 12h - 24h - 7d - custom description: Requested-at time window. Use custom with from and/or to. - name: from in: query schema: type: string format: date-time - name: to in: query schema: type: string format: date-time - name: sort in: query schema: type: string enum: - requested_at_desc - requested_at_asc - updated_at_desc - updated_at_asc - status_asc - status_desc - hostname_asc - hostname_desc default: requested_at_desc - name: format in: query schema: type: string enum: - json - csv default: json responses: '200': description: MAAS onboarding workflow runs content: application/json: schema: "$ref": "#/components/schemas/MaasOnboardingListResponse" text/csv: schema: type: string '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/lifecycle/decommissions": get: tags: - V3ReadModels operationId: listV3PlatformMaasDecommissionsCompat summary: List v3 MAAS decommission workflow runs parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: site_id in: query schema: type: string format: uuid - name: node_id in: query schema: type: string - name: status in: query schema: type: string - name: search in: query schema: type: string description: Search host, hostname, node id, decommission id, MAAS system id, or management IP. - name: time_range in: query schema: type: string enum: - 6h - 12h - 24h - 7d - custom description: Requested-at time window. Use custom with from and/or to. - name: from in: query schema: type: string format: date-time - name: to in: query schema: type: string format: date-time - name: sort in: query schema: type: string enum: - requested_at_desc - requested_at_asc - updated_at_desc - updated_at_asc - status_asc - status_desc - hostname_asc - hostname_desc default: requested_at_desc - name: format in: query schema: type: string enum: - json - csv default: json responses: '200': description: MAAS decommission workflow runs content: application/json: schema: "$ref": "#/components/schemas/MaasDecommissionListResponse" text/csv: schema: type: string '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/lifecycle/nodes/{node_id}/resource-slots": get: tags: - V3ReadModels operationId: listV3PlatformNodeResourceSlotsCompat summary: List v3 platform node resource slots parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Node resource slots content: application/json: schema: "$ref": "#/components/schemas/NodeResourceSlotListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" put: tags: - V3ReadModels operationId: upsertV3PlatformNodeResourceSlotsCompat summary: Upsert v3 platform node resource slots parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminUpsertNodeResourceSlotsRequest" responses: '200': description: Upserted node resource slots content: application/json: schema: "$ref": "#/components/schemas/NodeResourceSlotListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/lifecycle/nodes/{node_id}/slice-topology/discovery": get: tags: - V3ReadModels operationId: getV3PlatformNodeSliceTopologyDiscoveryCompat summary: Get v3 platform node slice topology discovery parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Latest topology discovery task, or null when none has run content: application/json: schema: "$ref": "#/components/schemas/NodeSliceTopologyDiscoveryResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3ReadModels operationId: startV3PlatformNodeSliceTopologyDiscoveryCompat summary: Queue v3 platform node slice topology discovery parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '202': description: Discovery task queued or already in progress content: application/json: schema: "$ref": "#/components/schemas/NodeSliceTopologyDiscoveryResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/lifecycle/nodes/{node_id}/probe": post: tags: - V3ReadModels operationId: probeV3PlatformNodeCompat summary: Probe a v3 platform node parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Probed content: application/json: schema: type: object additionalProperties: false properties: ok: type: boolean status: type: string enum: - active - offline required: - ok - status '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/lifecycle/nodes/{node_id}/reissue-enrollment": post: tags: - V3ReadModels operationId: reissueV3PlatformNodeEnrollmentCompat summary: Reissue v3 platform node enrollment material parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '201': description: Re-enrollment material created content: application/json: schema: "$ref": "#/components/schemas/AdminNodeReenrollmentResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/lifecycle/nodes/{node_id}/bootstrap-script": post: tags: - V3ReadModels operationId: createV3PlatformNodeBootstrapScriptCompat summary: Create v3 platform node bootstrap material parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" - name: mode in: query schema: type: string enum: - manual - cloud_init default: manual - name: runtime_api_url in: query schema: type: string format: uri description: Optional provider-reachable runtime control-plane base URL installed as GPUAAS_API_URL. If omitted, the environment default NODE_BOOTSTRAP_API_URL is used. - name: terminal_api_url in: query schema: type: string format: uri description: Optional provider-reachable terminal node-stream base URL installed as GPUAAS_TERMINAL_API_URL. If omitted, the environment default NODE_BOOTSTRAP_TERMINAL_API_URL is used. responses: '201': description: Bootstrap script created content: application/json: schema: "$ref": "#/components/schemas/AdminNodeBootstrapScriptResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/lifecycle/nodes/{node_id}/agent-lifecycle": get: tags: - V3ReadModels operationId: getV3PlatformNodeAgentLifecycleCompat summary: Get v3 platform node-agent lifecycle state parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Current node-agent lifecycle state content: application/json: schema: type: object additionalProperties: false properties: node_id: type: string format: uuid state: "$ref": "#/components/schemas/NodeAgentLifecycleState" latest_run: allOf: - "$ref": "#/components/schemas/NodeAgentLifecycleRun" nullable: true required: - node_id - state '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3ReadModels operationId: startV3PlatformNodeAgentLifecycleCompat summary: Start a v3 platform node-agent lifecycle run parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminStartNodeAgentLifecycleRequest" responses: '202': description: Node-agent lifecycle accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartNodeAgentLifecycleResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/lifecycle/nodes/{node_id}/agent-lifecycle/recover-stale": post: tags: - V3ReadModels operationId: recoverStaleV3PlatformNodeAgentLifecycleCompat summary: Recover a stale v3 platform node-agent lifecycle run parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminRecoverStaleNodeAgentLifecycleRequest" responses: '200': description: Stale node-agent lifecycle reconciled content: application/json: schema: "$ref": "#/components/schemas/AdminStartNodeAgentLifecycleResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/lifecycle/nodes/{node_id}/reactivate": post: tags: - V3ReadModels operationId: reactivateV3PlatformNodeCompat summary: Reactivate a retired v3 platform node parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Node reactivated content: application/json: schema: type: object additionalProperties: false properties: ok: type: boolean status: type: string required: - ok - status '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/lifecycle/nodes/{node_id}/resume-lifecycle": post: tags: - V3ReadModels operationId: resumeV3PlatformNodeLifecycleCompat summary: Resume a v3 platform node lifecycle transition parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Node lifecycle resume accepted content: application/json: schema: "$ref": "#/components/schemas/AdminResumeNodeLifecycleResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/lifecycle/nodes/{node_id}/remove": delete: tags: - V3ReadModels operationId: removeV3PlatformNodeCompat summary: Permanently remove a retired v3 platform node parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '204': description: Node removal started '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/lifecycle/nodes/{node_id}/detach": delete: tags: - V3ReadModels operationId: detachV3PlatformNodeCompat summary: Detach a retired v3 platform node from GPUaaS only parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '204': description: Node detached from GPUaaS '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/lifecycle/nodes/{node_id}/force-detach": delete: tags: - V3ReadModels operationId: forceDetachV3PlatformNodeCompat summary: Force-detach a stuck v3 platform node from GPUaaS only parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '204': description: Node force-detached from GPUaaS '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/evidence/audit": get: tags: - V3ReadModels operationId: listV3PlatformEvidenceAuditLogsCompat summary: List v3 platform audit evidence rows description: Platform evidence audit drawer feed. This is the V3 platform-owned alias for platform audit-log review and supports the same filters as the frozen admin audit list while the broader user/project/tenant evidence ownership is migrated. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - "$ref": "#/components/parameters/AuditLogSort" - name: actor_user_id in: query required: false schema: type: string format: uuid - name: actor_role in: query required: false style: form explode: true schema: type: array items: type: string - name: action in: query required: false style: form explode: true schema: type: array items: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: V3 platform audit evidence rows content: application/json: schema: "$ref": "#/components/schemas/AuditLogListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/evidence/audit/export": get: tags: - V3ReadModels operationId: exportV3PlatformEvidenceAuditLogsCompat summary: Export filtered v3 platform audit evidence rows description: Backend-owned export for platform Evidence. Export honors the same authorization scope, filters, time range, and sort as the platform audit evidence list. JSON includes sanitized presentation fields; CSV is intended for operator review and compliance handoff. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/AuditLogSort" - name: format in: query required: false schema: type: string enum: - csv - json default: csv - name: actor_user_id in: query required: false schema: type: string format: uuid - name: actor_role in: query required: false style: form explode: true schema: type: array items: type: string - name: action in: query required: false style: form explode: true schema: type: array items: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: Filtered platform audit evidence export content: text/csv: schema: type: string format: binary application/json: schema: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AuditLogEntry" export: type: object additionalProperties: false properties: format: type: string enum: - json count: type: integer minimum: 0 sort: type: string required: - format - count - sort required: - items - export '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/apps/instances/{app_instance_id}": get: tags: - V3Apps operationId: getV3AppInstanceCompat summary: Get V3 app runtime instance description: V3 project-scoped alias for app runtime management. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AppInstanceIdPath" responses: '200': description: V3 app runtime instance content: application/json: schema: "$ref": "#/components/schemas/AppInstance" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/apps/instances/{app_instance_id}/members": get: tags: - V3Apps operationId: listV3AppInstanceMembersCompat summary: List V3 app runtime members parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AppInstanceIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: component_key in: query required: false schema: type: string - name: status in: query required: false schema: type: string responses: '200': description: V3 app runtime members content: application/json: schema: "$ref": "#/components/schemas/AppInstanceMemberListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/apps/instances/{app_instance_id}/member-operations": get: tags: - V3Apps operationId: listV3AppInstanceMemberOperationsCompat summary: List V3 app runtime member operations parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AppInstanceIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: component_key in: query required: false schema: type: string - name: status in: query required: false schema: type: string responses: '200': description: V3 app runtime member operations content: application/json: schema: "$ref": "#/components/schemas/AppInstanceMemberOperationListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3Apps operationId: createV3AppInstanceMemberOperationCompat summary: Queue a V3 app runtime member operation parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppInstanceIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateAppInstanceMemberOperationRequest" responses: '202': description: V3 app runtime member operation queued content: application/json: schema: "$ref": "#/components/schemas/AppInstanceMemberOperation" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/apps/instances/{app_instance_id}/upgrade": post: tags: - V3Apps operationId: upgradeV3AppInstanceCompat summary: Upgrade a V3 app runtime parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppInstanceIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/UpgradeAppInstanceRequest" responses: '202': description: V3 app runtime upgrade queued content: application/json: schema: "$ref": "#/components/schemas/AppInstance" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/apps/instances/{app_instance_id}/rollback": post: tags: - V3Apps operationId: rollbackV3AppInstanceCompat summary: Roll back a V3 app runtime parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppInstanceIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/RollbackAppInstanceRequest" responses: '202': description: V3 app runtime rollback queued content: application/json: schema: "$ref": "#/components/schemas/AppInstance" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/apps/instances/{app_instance_id}/stop": post: tags: - V3Apps operationId: stopV3AppInstanceCompat summary: Stop a V3 app runtime parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppInstanceIdPath" responses: '202': description: V3 app runtime stop queued content: application/json: schema: "$ref": "#/components/schemas/V3AppInstanceOperationResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/apps/instances/{app_instance_id}/start": post: tags: - V3Apps operationId: startV3AppInstanceCompat summary: Start a V3 app runtime parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppInstanceIdPath" responses: '202': description: V3 app runtime start queued content: application/json: schema: "$ref": "#/components/schemas/V3AppInstanceOperationResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/apps/instances/{app_instance_id}/restart": post: tags: - V3Apps operationId: restartV3AppInstanceCompat summary: Restart a V3 app runtime parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppInstanceIdPath" responses: '202': description: V3 app runtime restart queued content: application/json: schema: "$ref": "#/components/schemas/V3AppInstanceOperationResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/apps/instances/{app_instance_id}/repair": post: tags: - V3Apps operationId: repairV3AppInstanceCompat summary: Queue V3 app runtime repair parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppInstanceIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateAppInstanceRepairRequest" responses: '202': description: V3 app runtime repair queued content: application/json: schema: "$ref": "#/components/schemas/AppInstanceRepairOperation" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/apps/instances/{app_instance_id}/decommission": post: tags: - V3Apps operationId: decommissionV3AppInstanceCompat summary: Decommission a V3 app runtime parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppInstanceIdPath" responses: '202': description: V3 app runtime decommission queued content: application/json: schema: "$ref": "#/components/schemas/V3AppInstanceOperationResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/schedulers/shared-runtimes": get: tags: - V3Schedulers operationId: listV3SharedAppRuntimesCompat summary: List V3 tenant-shared scheduler runtimes description: V3 tenant-scoped alias for tenant-owned shared app runtimes. parameters: - "$ref": "#/components/parameters/XRequestId" - name: X-Tenant-ID in: header required: true schema: type: string format: uuid - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string responses: '200': description: V3 tenant-shared scheduler runtimes content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/schedulers/shared-runtimes/{shared_runtime_id}": get: tags: - V3Schedulers operationId: getV3SharedAppRuntimeCompat summary: Get V3 tenant-shared scheduler runtime parameters: - "$ref": "#/components/parameters/XRequestId" - name: X-Tenant-ID in: header required: true schema: type: string format: uuid - "$ref": "#/components/parameters/SharedRuntimeIdPath" responses: '200': description: V3 tenant-shared scheduler runtime content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntime" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/schedulers/shared-runtimes/{shared_runtime_id}/attachments": get: tags: - V3Schedulers operationId: listV3SharedAppRuntimeAttachmentsCompat summary: List V3 tenant-shared runtime project attachments parameters: - "$ref": "#/components/parameters/XRequestId" - name: X-Tenant-ID in: header required: true schema: type: string format: uuid - "$ref": "#/components/parameters/SharedRuntimeIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: V3 tenant-shared runtime attachments content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeAttachmentListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/schedulers/shared-runtimes/{shared_runtime_id}/workers": get: tags: - V3Schedulers operationId: listV3SharedAppRuntimeWorkersCompat summary: List V3 tenant-shared runtime workers parameters: - "$ref": "#/components/parameters/XRequestId" - name: X-Tenant-ID in: header required: true schema: type: string format: uuid - "$ref": "#/components/parameters/SharedRuntimeIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string responses: '200': description: V3 tenant-shared runtime workers content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeWorkerListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/schedulers/shared-runtimes/{shared_runtime_id}/worker-operations": get: tags: - V3Schedulers operationId: listV3SharedAppRuntimeWorkerOperationsCompat summary: List V3 tenant-shared runtime worker operations parameters: - "$ref": "#/components/parameters/XRequestId" - name: X-Tenant-ID in: header required: true schema: type: string format: uuid - "$ref": "#/components/parameters/SharedRuntimeIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string responses: '200': description: V3 tenant-shared runtime worker operations content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperationListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3Schedulers operationId: createV3SharedAppRuntimeWorkerOperationCompat summary: Request a V3 tenant-shared runtime worker lifecycle change description: | Tenant operators request worker lifecycle changes through the V3 scheduler workbench. The operation is consumed by the shared-runtime operator contract. parameters: - "$ref": "#/components/parameters/XRequestId" - name: X-Tenant-ID in: header required: true schema: type: string format: uuid - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/SharedRuntimeIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateSharedAppRuntimeWorkerOperationRequest" responses: '202': description: V3 shared runtime worker operation accepted content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperation" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/developer/releases": get: tags: - V3Developer operationId: listV3DeveloperReleasesCompat summary: List V3 developer-downloadable platform releases parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: V3 platform release catalog content: application/json: schema: "$ref": "#/components/schemas/PlatformReleaseListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/developer/releases/{version}": get: tags: - V3Developer operationId: getV3DeveloperReleaseCompat summary: Get a V3 developer platform release manifest parameters: - "$ref": "#/components/parameters/XRequestId" - name: version in: path required: true schema: type: string minLength: 1 responses: '200': description: V3 platform release manifest content: application/json: schema: "$ref": "#/components/schemas/PlatformRelease" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/developer/releases/{version}/artifacts/{artifact_id}/download": get: tags: - V3Developer operationId: downloadV3DeveloperReleaseArtifactCompat summary: Download a V3 developer platform release artifact parameters: - "$ref": "#/components/parameters/XRequestId" - name: version in: path required: true schema: type: string minLength: 1 - name: artifact_id in: path required: true schema: type: string minLength: 1 responses: '200': description: Artifact archive content: application/gzip: schema: type: string format: binary '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/developer/releases/{version}/artifacts/{artifact_id}/pull-intent": post: tags: - V3Developer operationId: createV3DeveloperReleaseArtifactPullIntentCompat summary: Issue a V3 developer platform release artifact pull intent parameters: - "$ref": "#/components/parameters/XRequestId" - name: version in: path required: true schema: type: string minLength: 1 - name: artifact_id in: path required: true schema: type: string minLength: 1 responses: '201': description: V3 platform release artifact pull intent issued content: application/json: schema: "$ref": "#/components/schemas/ArtifactPullIntent" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/developer/dev-ca": get: tags: - V3Developer operationId: getV3DeveloperDevCACompat summary: Get V3 platform-control dev CA download metadata parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Platform-control dev CA metadata content: application/json: schema: "$ref": "#/components/schemas/PlatformDevCA" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/developer/dev-ca/download": get: tags: - V3Developer operationId: downloadV3DeveloperDevCACompat summary: Download the V3 platform-control dev CA certificate parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: PEM-encoded CA certificate content: application/x-x509-ca-cert: schema: type: string format: binary '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/ops/outbox/failed": get: tags: - V3ReadModels operationId: listV3PlatformOpsFailedOutboxEventsCompat summary: List failed outbox events for the V3 platform ops workbench parameters: - "$ref": "#/components/parameters/XRequestId" - name: cursor in: query schema: type: string - name: page_size in: query schema: type: integer minimum: 1 maximum: 200 responses: '200': description: Failed outbox events content: application/json: schema: "$ref": "#/components/schemas/AdminOutboxFailedListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/ops/outbox/{event_id}/requeue": post: tags: - V3ReadModels operationId: requeueV3PlatformOpsOutboxEventCompat summary: Requeue a failed outbox event from the V3 platform ops workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: event_id in: path required: true schema: type: string format: uuid responses: '200': description: Outbox event requeued content: application/json: schema: "$ref": "#/components/schemas/AdminOutboxMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/ops/outbox/{event_id}/discard": post: tags: - V3ReadModels operationId: discardV3PlatformOpsOutboxEventCompat summary: Discard a failed outbox event from the V3 platform ops workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: event_id in: path required: true schema: type: string format: uuid responses: '200': description: Outbox event discarded content: application/json: schema: "$ref": "#/components/schemas/AdminOutboxMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/ops/dlq/messages": get: tags: - V3ReadModels operationId: listV3PlatformOpsDLQMessagesCompat summary: List DLQ stream messages for the V3 platform ops workbench parameters: - "$ref": "#/components/parameters/XRequestId" - name: cursor in: query schema: type: string - name: page_size in: query schema: type: integer minimum: 1 maximum: 200 - name: subject_prefix in: query schema: type: string description: Optional DLQ subject prefix filter, for example dlq.gpuaas.provisioning. responses: '200': description: DLQ messages page content: application/json: schema: "$ref": "#/components/schemas/AdminDLQMessageListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/ops/dlq/messages/{stream_seq}/requeue": post: tags: - V3ReadModels operationId: requeueV3PlatformOpsDLQMessageCompat summary: Requeue a DLQ message from the V3 platform ops workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: stream_seq in: path required: true schema: type: integer format: uint64 minimum: 1 responses: '200': description: DLQ message requeued content: application/json: schema: "$ref": "#/components/schemas/AdminDLQMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/ops/dlq/messages/{stream_seq}/discard": post: tags: - V3ReadModels operationId: discardV3PlatformOpsDLQMessageCompat summary: Discard a DLQ message from the V3 platform ops workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: stream_seq in: path required: true schema: type: integer format: uint64 minimum: 1 responses: '200': description: DLQ message discarded content: application/json: schema: "$ref": "#/components/schemas/AdminDLQMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/v3/platform/finance/reconciliation": get: tags: - V3PlatformFinance operationId: listV3PlatformFinanceReconciliationCompat summary: List billing reconciliation runs through the V3 finance boundary description: Lists usage-ledger reconciliation posture and recent runs for the operator finance workbench. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: format in: query required: false schema: type: string enum: - json - csv default: json - name: status in: query required: false style: form explode: true schema: type: array items: type: string enum: - running - completed - failed - name: time_range in: query required: false schema: type: string enum: - 6h - 12h - 24h - 7d - custom - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time - name: sort in: query required: false schema: type: string enum: - created_at_desc - created_at_asc - checked_at_desc - checked_at_asc - status_asc - status_desc default: created_at_desc - name: search in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string responses: '200': description: V3 finance billing reconciliation posture content: application/json: schema: "$ref": "#/components/schemas/BillingReconciliationListResponse" text/csv: schema: type: string format: binary '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - V3PlatformFinance operationId: runV3PlatformFinanceReconciliationCompat summary: Run usage-ledger reconciliation through the V3 finance boundary description: Starts an audited, idempotent reconciliation run for finance operators. Ledger corrections remain append-only and are not performed directly by this read-model action. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" responses: '202': description: V3 finance billing reconciliation completed and recorded content: application/json: schema: "$ref": "#/components/schemas/BillingReconciliationRun" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/finance/reconciliation/{job_id}": get: tags: - V3PlatformFinance operationId: getV3PlatformFinanceReconciliationCompat summary: Get a billing reconciliation run through the V3 finance boundary parameters: - "$ref": "#/components/parameters/XRequestId" - name: job_id in: path required: true schema: type: string format: uuid responses: '200': description: V3 finance billing reconciliation run content: application/json: schema: "$ref": "#/components/schemas/BillingReconciliationRun" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/finance/diagnostics": get: tags: - V3PlatformFinance operationId: getV3PlatformFinanceDiagnosticsCompat summary: Fetch billing evidence by correlation id through the V3 finance boundary parameters: - "$ref": "#/components/parameters/XRequestId" - name: correlation_id in: query required: true schema: type: string responses: '200': description: V3 finance billing diagnostic evidence content: application/json: schema: "$ref": "#/components/schemas/BillingDiagnosticsResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops/telemetry/fleet": get: tags: - V3PlatformOps operationId: getV3PlatformOpsFleetTelemetryCompat summary: Get fleet telemetry rollups through the V3 ops boundary description: Read-only fleet telemetry subworkbench for platform operators. Returns CPU, GPU, memory, storage, and tenant/project rollups over a bounded window. parameters: - "$ref": "#/components/parameters/XRequestId" - name: range in: query required: false schema: type: string enum: - 15m - 1h - 6h - 24h - name: points in: query required: false schema: type: integer minimum: 10 maximum: 240 responses: '200': description: V3 ops fleet telemetry snapshot content: application/json: schema: "$ref": "#/components/schemas/AdminFleetTelemetryResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/allocations/{allocation_id}/access-grants": get: tags: - V3Workloads operationId: listV3AllocationAccessGrantsCompat summary: List V3 allocation SSH access grants parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AllocationIdPath" responses: '200': description: V3 allocation access grants content: application/json: schema: "$ref": "#/components/schemas/AllocationAccessGrantListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3Workloads operationId: createV3AllocationAccessGrantCompat summary: Grant V3 allocation SSH access to a project member parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AllocationIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateAllocationAccessGrantRequest" responses: '201': description: V3 allocation access grant created or updated content: application/json: schema: "$ref": "#/components/schemas/CreateAllocationAccessGrantResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/allocations/{allocation_id}/access-grants/{grant_id}": delete: tags: - V3Workloads operationId: revokeV3AllocationAccessGrantCompat summary: Revoke a V3 allocation SSH access grant parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AllocationIdPath" - name: grant_id in: path required: true schema: type: string format: uuid responses: '200': description: V3 allocation access grant revoked content: application/json: schema: "$ref": "#/components/schemas/RevokeAllocationAccessGrantResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/allocations/{allocation_id}/ssh-keys": put: tags: - V3Workloads operationId: setV3AllocationSshKeysCompat summary: Set V3 allocation owner SSH keys parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AllocationIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/SetAllocationSshKeysRequest" responses: '200': description: V3 allocation SSH keys updated content: application/json: schema: type: object additionalProperties: false properties: allocation: "$ref": "#/components/schemas/Allocation" runtime_sync_queued: type: boolean description: True when an active allocation runtime authorized_keys sync task was queued. required: - allocation - runtime_sync_queued '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/schedulers/shared-runtime-attachments/{attachment_id}/worker-operations": post: tags: - V3Schedulers operationId: createV3ProjectSharedRuntimeWorkerOperationCompat summary: Request V3 project worker contribution for an attached shared runtime description: | Consumer projects use this V3 path to request add, drain, or remove operations against a tenant-shared runtime attachment. The platform resolves tenant ownership and enforces the attachment contribution policy. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/SharedRuntimeAttachmentIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateSharedAppRuntimeWorkerOperationRequest" responses: '202': description: V3 project shared runtime worker operation accepted content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperation" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/account/evidence/audit": get: tags: - V3Account operationId: listV3AccountEvidenceAuditLogsCompat summary: List V3 account-scoped audit evidence parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - "$ref": "#/components/parameters/AuditLogSort" - name: action in: query required: false style: form explode: true schema: type: array items: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: V3 account audit evidence content: application/json: schema: "$ref": "#/components/schemas/AuditLogListResponse" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/v3/project/evidence/audit": get: tags: - V3Project operationId: listV3ProjectEvidenceAuditLogsCompat summary: List V3 current-project audit evidence parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - "$ref": "#/components/parameters/AuditLogSort" - name: actor_user_id in: query required: false description: Optional actor filter applied inside the resolved project scope. schema: type: string format: uuid - name: actor_role in: query required: false description: Optional actor role filters applied inside the resolved project scope. style: form explode: true schema: type: array items: type: string - name: action in: query required: false style: form explode: true schema: type: array items: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: V3 project audit evidence content: application/json: schema: "$ref": "#/components/schemas/AuditLogListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/access/evidence/audit": get: tags: - V3Access operationId: listV3TenantEvidenceAuditLogsCompat summary: List V3 tenant-scoped audit evidence parameters: - "$ref": "#/components/parameters/XRequestId" - name: X-Tenant-ID in: header required: false schema: type: string format: uuid - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - "$ref": "#/components/parameters/AuditLogSort" - name: actor_user_id in: query required: false description: Optional actor filter applied inside the resolved tenant scope. schema: type: string format: uuid - name: actor_role in: query required: false description: Optional actor role filters applied inside the resolved tenant scope. style: form explode: true schema: type: array items: type: string - name: action in: query required: false style: form explode: true schema: type: array items: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: V3 tenant audit evidence content: application/json: schema: "$ref": "#/components/schemas/AuditLogListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/lifecycle/nodes": get: tags: - V3ReadModels operationId: listV3PlatformLifecycleNodesCompat summary: List v3 platform lifecycle nodes description: Backend-owned lifecycle node list query with cursor pagination, server-side status, occupancy, site, host/search filters, and deterministic sort semantics for the v3 node lifecycle workbench. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: search in: query required: false schema: type: string - name: status in: query required: false schema: type: string enum: - registered - bootstrap_issued - enrolling - active - cordoned - offline - quarantined - draining - retired - removing - name: occupancy in: query required: false schema: type: string enum: - free - in_use - name: site_id in: query required: false schema: type: string format: uuid - name: sort in: query required: false schema: type: string enum: - host_asc - host_desc - health_desc - health_asc - last_activity_desc - last_activity_asc default: host_asc responses: '200': description: V3 platform lifecycle nodes headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformLifecycleNodesResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/evidence/bundles": get: tags: - V3ReadModels operationId: listV3PlatformEvidenceBundlesCompat summary: List platform release and UAT evidence bundles description: Platform-owned read model for release, UAT, security, guard, and operator evidence bundles. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: environment_profile in: query required: false schema: type: string - name: product_scope in: query required: false schema: type: string - name: gate_state in: query required: false schema: type: string enum: - pass - fail - partial - blocked - missing responses: '200': description: Platform evidence bundles content: application/json: schema: "$ref": "#/components/schemas/V3PlatformEvidenceBundleListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - V3ReadModels operationId: createV3PlatformEvidenceBundleCompat summary: Create a platform evidence bundle description: Creates a platform-owned evidence bundle from release, UAT, security, CI, and guard report inputs. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateV3PlatformEvidenceBundleRequest" responses: '201': description: Platform evidence bundle created content: application/json: schema: "$ref": "#/components/schemas/V3PlatformEvidenceBundleDetailResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/evidence/bundles/{bundle_id}": get: tags: - V3ReadModels operationId: getV3PlatformEvidenceBundleCompat summary: Get platform evidence bundle detail parameters: - "$ref": "#/components/parameters/XRequestId" - name: bundle_id in: path required: true schema: type: string format: uuid responses: '200': description: Platform evidence bundle detail content: application/json: schema: "$ref": "#/components/schemas/V3PlatformEvidenceBundleDetailResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/evidence/bundles/{bundle_id}/items": post: tags: - V3ReadModels operationId: recordV3PlatformEvidenceItemCompat summary: Attach an evidence item to a platform evidence bundle parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: bundle_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateV3PlatformEvidenceItemRequest" responses: '201': description: Evidence item attached content: application/json: schema: "$ref": "#/components/schemas/V3PlatformEvidenceItem" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/v3/platform/status/public": get: tags: - V3ReadModels operationId: getV3PlatformPublicStatusCompat summary: Get customer-safe platform status description: Public platform health projection for authenticated users. Omits internal component details, artifact paths, gate item IDs, and raw SLO values. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string responses: '200': description: Customer-safe platform status content: application/json: schema: "$ref": "#/components/schemas/V3PlatformPublicStatusResponse" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/v3/platform/status/readiness": get: tags: - V3ReadModels operationId: getV3PlatformStatusReadinessCompat summary: Get platform readiness status description: Environment/profile readiness read model backed by evidence freshness, release gates, guard reports, incidents, and capacity posture. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: product_scope in: query required: false schema: type: string responses: '200': description: Platform readiness status content: application/json: schema: "$ref": "#/components/schemas/V3PlatformStatusReadinessResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/status/components": get: tags: - V3ReadModels operationId: listV3PlatformStatusComponentsCompat summary: List platform component status parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: component_type in: query required: false schema: type: string - name: status in: query required: false schema: type: string enum: - healthy - degraded - unhealthy - unknown - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Platform component status content: application/json: schema: "$ref": "#/components/schemas/V3PlatformComponentStatusListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/status/guards": get: tags: - V3ReadModels operationId: getV3PlatformStatusGuardsCompat summary: Get latest platform-foundation guard report summary parameters: - "$ref": "#/components/parameters/XRequestId" - name: guard_id in: query required: false schema: type: string - name: mode in: query required: false schema: type: string enum: - report_only - warning - blocking - blocking_new - blocking_all - name: source_commit in: query required: false schema: type: string - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Platform guard status content: application/json: schema: "$ref": "#/components/schemas/V3PlatformGuardStatusResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops/registry/environment-artifacts": get: tags: - V3PlatformOps operationId: listV3PlatformRegistryEnvironmentArtifactsCompat summary: List environment artifact inventory for platform operators description: Platform-owned read model for answering which immutable image or artifact digest is deployed in an environment. Digest evidence is authoritative; mutable tags are display/search hints only. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: environment_profile in: query required: false schema: type: string - name: namespace in: query required: false schema: type: string - name: component in: query required: false schema: type: string - name: artifact_kind in: query required: false schema: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactKind" - name: image_ref in: query required: false schema: type: string - name: digest in: query required: false schema: type: string - name: source_sha in: query required: false schema: type: string - name: release_id in: query required: false schema: type: string - name: rollout_revision in: query required: false schema: type: string - name: status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactStatus" responses: '200': description: Environment artifact inventory content: application/json: schema: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactsResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops/registry/artifact-trust": get: tags: - V3PlatformOps operationId: listV3PlatformRegistryArtifactTrustCompat summary: List artifact trust status for platform operators description: Platform-owned read model for signature, SBOM, provenance, scanner summary, waiver, promotion eligibility, and expiry. Missing evidence fails closed as not_ready. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: digest in: query required: false schema: type: string - name: image_ref in: query required: false schema: type: string - name: artifact_name in: query required: false schema: type: string - name: source_sha in: query required: false schema: type: string - name: release_id in: query required: false schema: type: string - name: environment_profile in: query required: false schema: type: string - name: trust_status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustStatus" - name: promotion_eligible in: query required: false schema: type: boolean responses: '200': description: Artifact trust status content: application/json: schema: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/workflows": get: tags: - V3ReadModels operationId: listV3PlatformTemporalWorkflowsCompat summary: Search platform workflow records description: Read-only platform workflow search backed by persisted product/platform records and safe workflow metadata. The initial implementation does not query live Temporal Search Attributes and rejects broad unfiltered searches. parameters: - "$ref": "#/components/parameters/XRequestId" - name: family in: query required: false schema: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowFamily" - name: status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowStatus" - name: workflow_id in: query required: false schema: type: string - name: workflow_run_id in: query required: false schema: type: string - name: org_id in: query required: false schema: type: string format: uuid - name: project_id in: query required: false schema: type: string format: uuid - name: allocation_id in: query required: false schema: type: string format: uuid - name: node_id in: query required: false schema: type: string - name: actor_user_id in: query required: false schema: type: string format: uuid - name: correlation_id in: query required: false schema: type: string - name: time_range in: query required: false schema: type: string enum: - 6h - 12h - 24h - 7d - custom - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Platform workflow search results content: application/json: schema: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowSearchResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/workflows/{workflow_id}/retry-history": get: tags: - V3ReadModels operationId: getV3PlatformTemporalWorkflowRetryHistoryCompat summary: Get platform workflow retry history description: Returns safe retry/resume/rerun history for a persisted platform workflow. Initial sources are MAAS onboarding/decommission events and node-agent lifecycle records; raw Temporal payloads are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: workflow_id in: path required: true schema: type: string - name: workflow_run_id in: query required: false schema: type: string - name: family in: query required: false schema: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowFamily" - name: include_superseded in: query required: false schema: type: boolean default: true - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Platform workflow retry history content: application/json: schema: "$ref": "#/components/schemas/V3PlatformTemporalRetryHistoryResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/v3/platform/workflow-schedules": get: tags: - V3ReadModels operationId: listV3PlatformWorkflowSchedulesCompat summary: List platform workflow schedule status description: Returns operator-safe status for scheduled workflow automation. Initial source is the MAAS reconciliation Temporal schedule status already exposed through the API server Temporal adapter; raw workflow payloads are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: family in: query required: false schema: type: string enum: - maas_reconciliation - name: status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformTemporalScheduleStatus" - name: include_disabled in: query required: false schema: type: boolean default: true - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Platform workflow schedule status rows content: application/json: schema: "$ref": "#/components/schemas/V3PlatformWorkflowSchedulesResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/workflow-activities/stuck": get: tags: - V3ReadModels operationId: listV3PlatformStuckWorkflowActivitiesCompat summary: List stuck or retrying platform workflow activities description: Returns operator-safe diagnostics for workflows that appear stuck, retrying, waiting, or failed. Initial sources are MAAS onboarding and decommission product records; raw Temporal activity payloads are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: family in: query required: false schema: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowFamily" - name: status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformTemporalStuckActivityStatus" - name: owner_domain in: query required: false schema: type: string - name: workflow_id in: query required: false schema: type: string - name: workflow_run_id in: query required: false schema: type: string - name: min_age_seconds in: query required: false schema: type: integer minimum: 0 - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Stuck workflow activity diagnostics content: application/json: schema: "$ref": "#/components/schemas/V3PlatformTemporalStuckActivitiesResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops/observability/health-snapshot": get: tags: - V3ReadModels operationId: getV3PlatformObservabilityHealthSnapshotCompat summary: Get platform observability health snapshot description: Returns an operator-safe platform health snapshot before direct Grafana, Prometheus, Loki, or Tempo pivots. Raw telemetry samples, logs, traces, and payloads are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: component_type in: query required: false schema: "$ref": "#/components/schemas/V3PlatformObservabilityComponentType" - name: status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformObservabilityHealthStatus" - name: include_evidence in: query required: false schema: type: boolean default: true - name: include_prometheus_queries in: query required: false schema: type: boolean default: false responses: '200': description: Platform observability health snapshot content: application/json: schema: "$ref": "#/components/schemas/V3PlatformObservabilityHealthSnapshotResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops/observability/correlation-timeline": get: tags: - V3ReadModels operationId: getV3PlatformObservabilityCorrelationTimelineCompat summary: Get platform observability correlation timeline description: Returns an operator-safe timeline across audit rows, evidence items, domain events, and workflow records for a narrowed correlation pivot. Raw logs, trace spans, workflow payloads, tokens, stack traces, and runtime payloads are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: correlation_id in: query required: false schema: type: string - name: request_id in: query required: false schema: type: string - name: trace_id in: query required: false schema: type: string - name: workflow_id in: query required: false schema: type: string - name: workflow_run_id in: query required: false schema: type: string - name: task_id in: query required: false schema: type: string - name: event_id in: query required: false schema: type: string - name: target_type in: query required: false schema: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineTargetType" - name: target_id in: query required: false schema: type: string - name: time_range in: query required: false schema: type: string enum: - 1h - 6h - 12h - 24h - 7d - custom - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time - name: source in: query required: false schema: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineSource" - name: include_log_excerpts in: query required: false schema: type: boolean default: false - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Platform observability correlation timeline content: application/json: schema: "$ref": "#/components/schemas/V3PlatformObservabilityCorrelationTimelineResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops/observability/logs": get: tags: - V3ReadModels operationId: listV3PlatformObservabilityLogsCompat summary: List bounded platform observability log summaries description: Returns sanitized log summary pivots from persisted platform evidence, audit, and event records. Broad service-only and time-only browsing is rejected; raw Loki payloads are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: correlation_id in: query schema: type: string - name: request_id in: query schema: type: string - name: trace_id in: query schema: type: string - name: workflow_id in: query schema: type: string - name: task_id in: query schema: type: string - name: event_id in: query schema: type: string - name: target_type in: query schema: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineTargetType" - name: target_id in: query schema: type: string - name: service in: query schema: type: string - name: severity in: query schema: "$ref": "#/components/schemas/V3PlatformObservabilityLogSeverity" - name: time_range in: query schema: type: string enum: - 15m - 1h - 6h - 12h - 24h - custom - name: from in: query schema: type: string format: date-time - name: to in: query schema: type: string format: date-time - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Bounded platform observability log summaries content: application/json: schema: "$ref": "#/components/schemas/V3PlatformObservabilityLogsResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops/observability/traces": get: tags: - V3ReadModels operationId: listV3PlatformObservabilityTracesCompat summary: List bounded platform trace summaries description: Returns sanitized trace summaries from persisted platform evidence, audit, and event trace identifiers. Raw Tempo spans are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: trace_id in: query schema: type: string - name: correlation_id in: query schema: type: string - name: request_id in: query schema: type: string - name: workflow_id in: query schema: type: string - name: task_id in: query schema: type: string - name: target_type in: query schema: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineTargetType" - name: target_id in: query schema: type: string - name: time_range in: query schema: type: string enum: - 15m - 1h - 6h - 12h - 24h - custom - name: from in: query schema: type: string format: date-time - name: to in: query schema: type: string format: date-time - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Bounded platform trace summaries content: application/json: schema: "$ref": "#/components/schemas/V3PlatformObservabilityTracesResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops/observability/alerts": get: tags: - V3ReadModels operationId: listV3PlatformObservabilityAlertsCompat summary: List platform observability alert routing evidence description: Returns operator-safe alert state, route ownership, runbook mapping, and drill freshness evidence. Raw Prometheus samples and notification secrets are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query schema: type: string - name: severity in: query schema: "$ref": "#/components/schemas/V3PlatformObservabilityAlertSeverity" - name: owner_team in: query schema: type: string - name: service in: query schema: type: string - name: domain in: query schema: type: string - name: state in: query schema: "$ref": "#/components/schemas/V3PlatformObservabilityAlertState" - name: runbook_id in: query schema: type: string - name: include_inactive in: query schema: type: boolean default: false - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Platform observability alert routing evidence content: application/json: schema: "$ref": "#/components/schemas/V3PlatformObservabilityAlertsResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops/observability/slo-evidence": get: tags: - V3ReadModels operationId: listV3PlatformObservabilitySLOEvidenceCompat summary: List platform observability SLO evidence description: Returns operator-safe SLO/error-budget evidence and release-gate posture. Raw Prometheus samples, Grafana screenshots, and notification secrets are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query schema: type: string - name: service in: query schema: type: string - name: slo_id in: query schema: type: string - name: time_range in: query schema: type: string enum: - 1h - 6h - 24h - 7d - 30d - custom - name: from in: query schema: type: string format: date-time - name: to in: query schema: type: string format: date-time - name: release_id in: query schema: type: string - name: include_query_outcomes in: query schema: type: boolean default: true - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Platform observability SLO evidence content: application/json: schema: "$ref": "#/components/schemas/V3PlatformObservabilitySLOEvidenceResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/status/breakglass": get: tags: - V3ReadModels operationId: listV3PlatformStatusBreakglassCompat summary: List platform break-glass evidence description: Read-only Status/Ops projection of break-glass activation, approval, expiry, revocation, use-log, and post-use review evidence derived from platform audit metadata. This endpoint never exposes credentials, secret material, or provider tokens. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: stage in: query required: false schema: "$ref": "#/components/schemas/V3PlatformBreakglassEvidenceStage" - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Platform break-glass evidence content: application/json: schema: "$ref": "#/components/schemas/V3PlatformBreakglassEvidenceListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/edge/routes": get: tags: - V3ReadModels operationId: listV3PlatformEdgeRoutesCompat summary: List provider-neutral edge route readiness description: Read-only platform operations model for DNS, TLS, Pomerium, ingress or tunnel, upstream, smoke evidence freshness, and operator next action across supported edge profiles. The response is provider-neutral and must not expose Cloudflare-native payloads, DNS provider records, tunnel credentials, tokens, or mutable provider operations. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: edge_profile in: query required: false schema: "$ref": "#/components/schemas/V3PlatformEdgeProfile" - name: route_family in: query required: false schema: "$ref": "#/components/schemas/V3PlatformEdgeRouteFamily" - name: status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformEdgeReadinessStatus" - name: stale_only in: query required: false schema: type: boolean default: false - name: search in: query required: false schema: type: string maxLength: 160 - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Provider-neutral edge route readiness content: application/json: schema: "$ref": "#/components/schemas/V3PlatformEdgeRouteListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/status/devsecops/metrics": get: tags: - V3ReadModels operationId: listV3PlatformDevSecOpsMetricsCompat summary: List DevSecOps control metrics description: Paginated platform Status/Ops read model for DevSecOps control posture, stale evidence, release gates, scan enforcement, supply-chain coverage, and escape-rate classification. This is a projection over evidence/status sources, not a parallel security metrics store. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: product_scope in: query required: false schema: type: string - name: family in: query required: false schema: "$ref": "#/components/schemas/V3DevSecOpsMetricFamily" - name: state in: query required: false schema: "$ref": "#/components/schemas/V3DevSecOpsMetricState" - name: owner in: query required: false schema: type: string - name: release_branch in: query required: false schema: type: string - name: source_commit in: query required: false schema: type: string - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: DevSecOps control metrics content: application/json: schema: "$ref": "#/components/schemas/V3DevSecOpsMetricListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/status/node-trust": get: tags: - V3ReadModels operationId: listV3PlatformStatusNodeTrustCompat summary: List node trust posture description: Sanitized node-trust read model backed by Status/Ops component rows. Exposes certificate expiry, renewal and recovery posture, verifier versions, endpoint profile, diagnostic freshness, and quarantine reason without secret material. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: node_id in: query required: false schema: type: string - name: status in: query required: false schema: type: string enum: - healthy - degraded - unhealthy - unknown - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Node trust posture content: application/json: schema: "$ref": "#/components/schemas/V3PlatformNodeTrustPostureListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops/secrets-pki/certificates": get: tags: - V3ReadModels operationId: listV3PlatformOpsSecretsPKICertificatesCompat summary: List Secrets/PKI certificate lifecycle posture description: Read-only metadata projection for internal certificate expiry, renewal, revocation, issuer, subject class, owner domain, and evidence links. Requires platform ops read permission. The response never includes private keys, CSR private material, raw key PEM, CA private material, or secret-manager values. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: purpose_id in: query required: false schema: type: string - name: subject_class in: query required: false schema: "$ref": "#/components/schemas/V3CertificateSubjectClass" - name: issuer in: query required: false schema: type: string - name: owner_domain in: query required: false schema: type: string - name: renewal_status in: query required: false schema: "$ref": "#/components/schemas/V3CertificateRenewalStatus" - name: revocation_status in: query required: false schema: "$ref": "#/components/schemas/V3CertificateRevocationStatus" - name: node_id in: query required: false schema: type: string format: uuid - name: worker_id in: query required: false schema: type: string - "$ref": "#/components/parameters/Cursor" - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 200 responses: '200': description: Secrets/PKI certificate lifecycle posture headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3SecretsPKICertificateLifecycleResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops/registry/pull-diagnosis": get: tags: - V3ReadModels operationId: listV3PlatformOpsRegistryPullDiagnosisCompat summary: List registry pull failure diagnoses description: Read-only, metadata-only registry pull diagnosis projection for artifact, node, workload, credential-purpose, and evidence links. Requires platform ops read permission and at least one narrowing filter. The response never includes registry passwords, bearer tokens, refresh tokens, private keys, raw Vault payloads, credential environment variables, or raw node-agent logs. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: node_id in: query required: false schema: type: string format: uuid - name: node_name in: query required: false schema: type: string - name: allocation_id in: query required: false schema: type: string format: uuid - name: workload_id in: query required: false schema: type: string - name: app_slug in: query required: false schema: type: string - name: app_version in: query required: false schema: type: string - name: artifact_id in: query required: false schema: type: string - name: artifact_name in: query required: false schema: type: string - name: artifact_ref in: query required: false schema: type: string - name: digest in: query required: false schema: type: string - name: task_id in: query required: false schema: type: string - name: workflow_id in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: error_class in: query required: false schema: "$ref": "#/components/schemas/V3RegistryPullErrorClass" - "$ref": "#/components/parameters/Cursor" - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 200 responses: '200': description: Registry pull failure diagnosis metadata headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3RegistryPullDiagnosisResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops/secrets-pki/vault-readiness": get: tags: - V3ReadModels operationId: listV3PlatformSecretsPKIVaultReadinessCompat summary: List Vault readiness evidence description: Sanitized Secrets/PKI Vault readiness read model for operator review. The response exposes initialized, sealed, mount, policy, read-check, deploy preflight, evidence-link, and next-action status only. It never returns root tokens, unseal keys, operational tokens, AppRole material, wrapped tokens, registry passwords, private keys, raw Vault responses, or secret values. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: cluster_id in: query required: false schema: type: string - name: mount in: query required: false schema: type: string - name: purpose_id in: query required: false schema: type: string - name: status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformVaultReadinessStatus" - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Vault readiness evidence content: application/json: schema: "$ref": "#/components/schemas/V3PlatformVaultReadinessListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops/secrets-pki/rotation-evidence": get: tags: - V3ReadModels operationId: listV3PlatformSecretsPKIRotationEvidenceCompat summary: List Secrets/PKI rotation evidence description: Sanitized rotation evidence read model for operators. The endpoint reports purpose, actor, approval reference, version references, validation checks, audit action, result, next due date, and evidence links only. It does not execute live rotation and never returns secret values, private keys, raw provider output, Vault tokens, unseal keys, wrapped-token bytes, registry passwords, or one-time credential material. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: purpose_id in: query required: false schema: type: string - name: rotation_id in: query required: false schema: type: string - name: actor_user_id in: query required: false schema: type: string format: uuid - name: rotation_owner in: query required: false schema: type: string enum: - platform_automated - platform_ops - iam_facade - keycloak_admin - stripe_platform - name: result in: query required: false schema: "$ref": "#/components/schemas/V3PlatformRotationEvidenceResult" - name: approval_ref in: query required: false schema: type: string - name: started_after in: query required: false schema: type: string format: date-time - name: completed_before in: query required: false schema: type: string format: date-time - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Secrets/PKI rotation evidence content: application/json: schema: "$ref": "#/components/schemas/V3PlatformRotationEvidenceListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops/secrets-pki/breakglass-evidence": get: tags: - V3ReadModels operationId: listV3PlatformSecretsPKIBreakglassEvidenceCompat summary: List Secrets/PKI break-glass evidence description: Sanitized break-glass evidence read model for operators and reviewers. The endpoint reports approval reference, actor, scope, time window, safe action summaries, post-action remediation, audit links, and evidence links only. It does not execute live break-glass, unseal Vault, rotate root tokens, or mutate production secrets. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: breakglass_id in: query required: false schema: type: string - name: approval_ref in: query required: false schema: type: string - name: actor_user_id in: query required: false schema: type: string format: uuid - name: scope in: query required: false schema: type: string - name: status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformSecretsPKIBreakglassStatus" - name: opened_after in: query required: false schema: type: string format: date-time - name: closed_before in: query required: false schema: type: string format: date-time - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Secrets/PKI break-glass evidence content: application/json: schema: "$ref": "#/components/schemas/V3PlatformSecretsPKIBreakglassEvidenceListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops/secrets-pki/purposes": get: tags: - V3PlatformOps operationId: listV3PlatformSecretsPKIPurposeInventoryCompat summary: List secrets PKI purpose inventory description: Platform-ops read model over the shared Secrets/PKI purpose registry. Returns custody, rotation, lifecycle, and runtime trust evidence metadata for each purpose. It never returns raw secret, token, key, Vault, certificate, or provider credential material. Missing runtime trust evidence is classified as unknown or unhealthy, never healthy. parameters: - "$ref": "#/components/parameters/XRequestId" - name: purpose_id in: query required: false schema: type: string - name: owner_product_id in: query required: false schema: type: string - name: material_kind in: query required: false schema: "$ref": "#/components/schemas/V3SecretsPKIMaterialKind" - name: custody_tool in: query required: false schema: "$ref": "#/components/schemas/V3SecretsPKICustodyTool" - name: delivery_mode in: query required: false schema: "$ref": "#/components/schemas/V3SecretsPKIDeliveryMode" - name: rotation_owner in: query required: false schema: "$ref": "#/components/schemas/V3SecretsPKIRotationOwner" - name: evidence_component_id in: query required: false schema: type: string - name: status in: query required: false schema: "$ref": "#/components/schemas/V3SecretsPKIPurposeStatus" - name: environment_profile in: query required: false schema: type: string default: prod - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 25 responses: '200': description: Secrets PKI purpose inventory headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3SecretsPKIPurposeInventoryResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/ops/registry/app-artifacts": get: tags: - V3PlatformOps operationId: listV3PlatformRegistryAppArtifactsCompat summary: List app artifact launch eligibility for platform operators description: Platform-owned app artifact operator status read model for launch eligibility, digest readiness, trust state, target architecture compatibility, and evidence links. Registry credentials and runtime secrets are never returned. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: org_id in: query required: false schema: type: string format: uuid - name: project_id in: query required: false schema: type: string format: uuid - name: app_slug in: query required: false schema: type: string - name: app_version in: query required: false schema: type: string - name: artifact_name in: query required: false schema: type: string - name: artifact_kind in: query required: false schema: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactKind" - name: source_type in: query required: false schema: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactSourceType" - name: platform_os in: query required: false schema: type: string - name: platform_arch in: query required: false schema: type: string - name: digest in: query required: false schema: type: string - name: trust_state in: query required: false schema: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactTrustState" - name: launch_eligible in: query required: false schema: type: boolean responses: '200': description: App artifact operator launch eligibility status content: application/json: schema: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactsResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/v3/platform/iam/mfa-readiness": get: tags: - V3ReadModels operationId: getV3PlatformIAMMFAReadinessCompat summary: Get v3 platform IAM MFA readiness read model description: Read-only operator readiness model for MFA product-complete posture. This endpoint must not query Keycloak or any identity provider per request, must not mutate IAM state, and must treat unknown, pending, stale, provider_unqueried, and error states as non-compliant/fail-closed. parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: V3 platform IAM MFA readiness headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformIAMMFAReadinessResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/shell/context": get: tags: - V3ReadModels operationId: getV3ShellContext summary: Get v3 shell context read model description: 'Returns the scoped shell context needed by the v3 product shell: available modes, tenant/project selectors, region selector, balance summary, and attention counts. The response is scoped to the authenticated user and may be Redis cached using user, tenant, project, role, and mode scope in the cache key. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - in: query name: mode required: false schema: "$ref": "#/components/schemas/V3ShellMode" responses: '200': description: V3 shell context headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3ShellContextResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/regions": get: tags: - V3ReadModels operationId: listV3Regions summary: List v3 shell regions description: 'Temporary v3 migration read model for the product shell region selector. This endpoint lets UI remove hardcoded region labels while the scheduler and capacity layers evolve toward explicit multi-region support. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" responses: '200': description: V3 region list headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3RegionListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/workloads": get: tags: - V3ReadModels operationId: listV3Workloads summary: List unified v3 workload workbench rows description: 'Returns one runtime workbench across raw compute allocations and app-backed workloads. This read model is the v3 replacement target for list pages that currently split allocations and app instances. It must enforce project scope before reading or caching rows. ' x-v3-read-model-gaps: - node, region, placement owner, and disabled reason should be normalized across compute allocations and app-backed runtimes. - workload rows should expose a billing summary with hourly and accrued cost sourced from allocation/app billing state. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - in: query name: status required: false schema: "$ref": "#/components/schemas/V3WorkloadStatus" - in: query name: kind required: false schema: "$ref": "#/components/schemas/V3WorkloadKind" - in: query name: search required: false schema: type: string maxLength: 120 - in: query name: include_history required: false description: Include archived terminal workload rows such as released runtimes and expired recovery items. Default runtime lists omit history; explicit status filters are also treated as history queries. schema: type: boolean default: false responses: '200': description: Unified v3 workload list headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3WorkloadListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/workloads/{workload_id}": get: tags: - V3ReadModels operationId: getV3WorkloadDetail summary: Get unified v3 workload detail read model description: 'Returns the v3 workload detail shell data for a compute or app-backed runtime. Kind-specific connect, metrics, storage, and config data are returned as sanitized tab payloads owned by their source domains. Raw secrets and private keys must never be present in this read model. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/WorkloadIdPath" responses: '200': description: Unified v3 workload detail headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3WorkloadDetailResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/workloads/{workload_id}/credentials/{credential_id}/reconcile": post: tags: - V3ReadModels operationId: reconcileV3AppRuntimeCredential summary: Reconcile an app runtime credential binding description: Records an audited app runtime credential reconcile operation for the workload-scoped credential binding. Human users and project-scoped service accounts may call this operation; service-account calls require `X-Project-ID` to match the token `project_id` and cross-project calls fail before inventory/runtime service calls. The response is durable operation evidence only and must never include raw credential material, wrapped tokens, private keys, passwords, or provider secrets. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/WorkloadIdPath" - "$ref": "#/components/parameters/AccessCredentialIdPath" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3AppRuntimeCredentialOperationRequest" responses: '202': description: Runtime credential reconcile accepted content: application/json: schema: "$ref": "#/components/schemas/V3AppRuntimeCredentialOperationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/workloads/{workload_id}/credentials/sweep": post: tags: - V3ReadModels operationId: sweepV3AppRuntimeCredentials summary: Sweep stale app runtime credentials for a workload description: Records an audited app runtime credential sweep for a workload owner tuple. Human users and project-scoped service accounts may call this operation; service-account calls require `X-Project-ID` to match the token `project_id` and cross-project calls fail before inventory/runtime service calls. The operation soft-deletes expired or stale disabled runtime credentials and bindings, supports dry-run, and never exposes raw credential material. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/WorkloadIdPath" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3AppRuntimeCredentialSweepRequest" responses: '202': description: Runtime credential sweep accepted content: application/json: schema: "$ref": "#/components/schemas/V3AppRuntimeCredentialSweepResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/workloads/{workload_id}/credentials/{credential_id}/rotate": post: tags: - V3ReadModels operationId: rotateV3AppRuntimeCredential summary: Rotate an app runtime credential where supported description: Records an audited app runtime credential rotate operation for the workload-scoped credential binding. Human users and project-scoped service accounts may call this operation; service-account calls require `X-Project-ID` to match the token `project_id` and cross-project calls fail before inventory/runtime service calls. Rotation support is advertised by the workload credential posture capability flags. The response is durable operation evidence only and must never include raw credential material. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/WorkloadIdPath" - "$ref": "#/components/parameters/AccessCredentialIdPath" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3AppRuntimeCredentialOperationRequest" responses: '202': description: Runtime credential rotate accepted content: application/json: schema: "$ref": "#/components/schemas/V3AppRuntimeCredentialOperationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/workloads/{workload_id}/credentials/{credential_id}/disable": post: tags: - V3ReadModels operationId: disableV3AppRuntimeCredential summary: Disable an app runtime credential where supported description: Records an audited app runtime credential disable operation for the workload-scoped credential binding. Human users and project-scoped service accounts may call this operation; service-account calls require `X-Project-ID` to match the token `project_id` and cross-project calls fail before inventory/runtime service calls. The response is durable operation evidence only and must never include raw credential material. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/WorkloadIdPath" - "$ref": "#/components/parameters/AccessCredentialIdPath" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3AppRuntimeCredentialOperationRequest" responses: '202': description: Runtime credential disable accepted content: application/json: schema: "$ref": "#/components/schemas/V3AppRuntimeCredentialOperationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/tasks": get: tags: - V3ReadModels operationId: listV3Tasks summary: List v3 task read-model rows description: 'Returns the project-scoped long-running operation workbench used after launch, release, restart, and app lifecycle submissions. The first production implementation is allocation-backed and normalizes allocation lifecycle state into a task shape; future domains can add task sources without changing the shell contract. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - in: query name: status required: false schema: "$ref": "#/components/schemas/V3TaskStatus" responses: '200': description: V3 task list headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3TaskListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/tasks/{task_id}": get: tags: - V3ReadModels operationId: getV3TaskDetail summary: Get v3 task detail read model description: 'Returns task header context plus a normalized timeline. For allocation tasks, the response enriches the synthetic lifecycle steps with the existing allocation timeline when available. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3TaskIdPath" responses: '200': description: V3 task detail headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3TaskDetailResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/compute": get: tags: - V3ReadModels operationId: getV3ComputeCatalog summary: Get v3 compute catalog read model description: 'Temporary v3 migration read model for the Compute shell group. Returns project-scoped launchable SKU summaries and compatible OS image hints for the compute catalog and launch wizard. Capacity values are user-safe posture hints and must not expose raw node inventory secrets. ' x-v3-read-model-gaps: - region capacity, queue posture, and price must remain backend-owned real data for catalog browse and launch readiness. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - in: query name: resource_class required: false schema: "$ref": "#/components/schemas/V3ComputeResourceClass" - in: query name: search required: false schema: type: string maxLength: 120 - in: query name: region_code required: false schema: type: string responses: '200': description: V3 compute catalog headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3ComputeCatalogResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/launch/compute/precheck": post: tags: - V3ReadModels operationId: precheckV3ComputeLaunch summary: Precheck v3 compute launch readiness description: 'Read-only launch readiness contract for the v3 compute wizard. It evaluates project scope, catalog selection, dependency presence, and safe capacity posture before the user submits a mutating allocation request. This endpoint is safe to retry and must not create allocations, credentials, buckets, or network policy objects. For provider-family compute VM SKUs, the response includes `resolved.placement.availability_state` with one of the closed states from `Compute_VM_Availability_Model_v1.md`, such as `ready_now`, `prepare_on_demand`, or `blocked_capacity`. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3ComputeLaunchPrecheckRequest" responses: '200': description: V3 compute launch readiness content: application/json: schema: "$ref": "#/components/schemas/V3LaunchPrecheckResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/launch/compute": post: tags: - V3ReadModels operationId: submitV3ComputeLaunch summary: Submit v3 compute launch description: 'Mutating submit endpoint for the v3 compute wizard. The endpoint reuses the allocation creation domain path and returns a normalized task handoff so the browser can route immediately to the v3 task progress page. Clients must send an idempotency key; replaying the same body with the same key must not create a duplicate workload. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3ComputeLaunchSubmitRequest" responses: '202': description: V3 compute launch accepted content: application/json: schema: "$ref": "#/components/schemas/V3LaunchSubmitResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/apps": get: tags: - V3ReadModels operationId: listV3Apps summary: List v3 managed app catalog rows description: 'Temporary v3 migration read model for the Apps shell group. Returns the catalog, featured rows, entitlement state, dependency hints, and launch links used by the v3 app catalog. It is page-shaped and may later graduate into domain-owned app catalog resources. ' x-v3-read-model-gaps: - app cards should expose required GPU/storage, runtime cost, availability, and config-owned launch blockers instead of prose-only readiness. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - in: query name: category required: false schema: type: string maxLength: 80 - in: query name: search required: false schema: type: string maxLength: 120 responses: '200': description: V3 managed app catalog headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AppCatalogResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/apps/artifacts": get: tags: - V3Apps operationId: listV3AppArtifacts summary: List registered app artifacts for the active V3 project description: Lists project-scoped app artifacts through the V3 project header contract. Registry credentials, wrapped pull tokens, and provider secrets are never returned by this list response. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: app_slug in: query required: false schema: type: string - name: search in: query required: false schema: type: string - name: artifact_kind in: query required: false schema: type: string enum: - oci - blob - name: source_type in: query required: false schema: type: string enum: - oci_registry - s3 - gcs - azure_blob - https - huggingface - artifact_store - name: lifecycle_state in: query required: false schema: type: string enum: - published - promoted - deprecated - retired - name: trust_state in: query required: false schema: type: string enum: - unverified - verified - failed_verification - revoked - name: sort in: query required: false schema: type: string enum: - name_asc - name_desc - updated_at_desc - updated_at_asc - created_at_desc - created_at_asc - size_desc - size_asc default: updated_at_desc - name: format in: query required: false schema: type: string enum: - json - csv default: json responses: '200': description: V3 app artifacts content: application/json: schema: "$ref": "#/components/schemas/AppArtifactListResponse" text/csv: schema: type: string '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3Apps operationId: registerV3AppArtifact summary: Register a published app artifact digest for the active V3 project description: Registers a previously published app artifact using the V3 project header contract. Audited by the app-artifact service and replay-protected by the V3 idempotency gate. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/RegisterAppArtifactRequest" responses: '201': description: V3 app artifact registered content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/lifecycle/maas-sites": get: tags: - V3ReadModels operationId: listV3PlatformMaasSites summary: List v3 MAAS provisioning sites parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: MAAS sites content: application/json: schema: "$ref": "#/components/schemas/MaasSiteListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - V3ReadModels operationId: createV3PlatformMaasSite summary: Register a v3 MAAS provisioning site parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminCreateMaasSiteRequest" responses: '201': description: Created MAAS site content: application/json: schema: "$ref": "#/components/schemas/MaasSite" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/lifecycle/maas-sites/{id}": get: tags: - V3ReadModels operationId: getV3PlatformMaasSite summary: Get a v3 MAAS provisioning site parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" responses: '200': description: MAAS site content: application/json: schema: "$ref": "#/components/schemas/MaasSite" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" patch: tags: - V3ReadModels operationId: updateV3PlatformMaasSite summary: Update a v3 MAAS provisioning site parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminUpdateMaasSiteRequest" responses: '200': description: Updated MAAS site content: application/json: schema: "$ref": "#/components/schemas/MaasSite" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" delete: tags: - V3ReadModels operationId: disableV3PlatformMaasSite summary: Disable a v3 MAAS provisioning site parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" responses: '204': description: MAAS site disabled '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/lifecycle/maas-sites/{id}/discovery-candidates": get: tags: - V3ReadModels operationId: listV3PlatformMaasDiscoveryCandidates summary: List v3 MAAS discovery candidates parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: search in: query schema: type: string description: Search hostname, MAAS system id, power address, or SKU. - name: review_state in: query schema: type: string enum: - active - ignored - suppressed - all default: all - name: format in: query schema: type: string enum: - json - csv default: json description: CSV export honors the same search and review-state filters. responses: '200': description: MAAS discovery candidates content: application/json: schema: "$ref": "#/components/schemas/MaasDiscoveryCandidateListResponse" text/csv: schema: type: string '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/platform/lifecycle/maas-sites/{id}/discovery-candidates/export": get: tags: - V3ReadModels operationId: exportV3PlatformMaasDiscoveryCandidates summary: Export filtered v3 MAAS discovery candidates description: Backend-owned export for MAAS discovery candidates. Export honors the same authorization scope, search, review-state filter, and cursor/page-size contract as the discovery candidate list; omit cursor and page_size to export all matching rows. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: search in: query schema: type: string description: Search hostname, MAAS system id, power address, or SKU. - name: review_state in: query schema: type: string enum: - active - ignored - suppressed - all default: all - name: format in: query schema: type: string enum: - csv - json default: csv responses: '200': description: Filtered MAAS discovery candidates content: text/csv: schema: type: string application/json: schema: "$ref": "#/components/schemas/MaasDiscoveryCandidateListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/platform/lifecycle/maas-sites/{id}/discovery-candidates/{maas_system_id}/enrichment": get: tags: - V3ReadModels operationId: getV3PlatformMaasDiscoveryCandidateEnrichment summary: Get v3 MAAS discovery candidate enrichment parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" - name: maas_system_id in: path required: true schema: type: string minLength: 1 responses: '200': description: MAAS discovery candidate enrichment content: application/json: schema: "$ref": "#/components/schemas/MaasDiscoveryCandidateEnrichment" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/platform/lifecycle/maas-sites/{id}/discovery-candidates/{maas_system_id}/decision": put: tags: - V3ReadModels operationId: updateV3PlatformMaasDiscoveryCandidateDecision summary: Review a v3 MAAS discovery candidate parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - name: maas_system_id in: path required: true schema: type: string minLength: 1 requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminUpdateMaasDiscoveryCandidateDecisionRequest" responses: '200': description: Updated MAAS discovery candidate decision content: application/json: schema: "$ref": "#/components/schemas/MaasDiscoveryCandidateDecision" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/platform/lifecycle/maas-sites/{id}/profiles": get: tags: - V3ReadModels operationId: listV3PlatformMaasSiteProfiles summary: List v3 MAAS provisioning profiles parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" responses: '200': description: MAAS site profiles content: application/json: schema: "$ref": "#/components/schemas/MaasSiteProfileListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3ReadModels operationId: createV3PlatformMaasSiteProfile summary: Create a v3 MAAS provisioning profile parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminCreateMaasSiteProfileRequest" responses: '201': description: Created MAAS site profile content: application/json: schema: "$ref": "#/components/schemas/MaasSiteProfile" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/lifecycle/maas-sites/{id}/profiles/{profile_id}": get: tags: - V3ReadModels operationId: getV3PlatformMaasSiteProfile summary: Get a v3 MAAS provisioning profile parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" - "$ref": "#/components/parameters/MaasSiteProfileIdPath" responses: '200': description: MAAS site profile content: application/json: schema: "$ref": "#/components/schemas/MaasSiteProfile" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" patch: tags: - V3ReadModels operationId: updateV3PlatformMaasSiteProfile summary: Update a v3 MAAS provisioning profile parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - "$ref": "#/components/parameters/MaasSiteProfileIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminUpdateMaasSiteProfileRequest" responses: '200': description: Updated MAAS site profile content: application/json: schema: "$ref": "#/components/schemas/MaasSiteProfile" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" delete: tags: - V3ReadModels operationId: disableV3PlatformMaasSiteProfile summary: Disable a v3 MAAS provisioning profile parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - "$ref": "#/components/parameters/MaasSiteProfileIdPath" responses: '204': description: MAAS site profile disabled '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/lifecycle/maas-sites/{id}/credentials": post: tags: - V3ReadModels operationId: writeV3PlatformMaasSiteCredentials summary: Write v3 MAAS site credentials parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminWriteMaasSiteCredentialsRequest" responses: '200': description: MAAS site credentials written and validated content: application/json: schema: "$ref": "#/components/schemas/AdminWriteMaasSiteCredentialsResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/platform/lifecycle/maas-sites/{id}/probe": post: tags: - V3ReadModels operationId: probeV3PlatformMaasSite summary: Probe a v3 MAAS site parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" responses: '200': description: MAAS site probed content: application/json: schema: "$ref": "#/components/schemas/MaasSiteProbeResult" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/developer/releases": get: tags: - V3Developer operationId: listV3DeveloperReleases summary: List V3 developer-downloadable platform releases parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: V3 platform release catalog content: application/json: schema: "$ref": "#/components/schemas/PlatformReleaseListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/developer/releases/{version}": get: tags: - V3Developer operationId: getV3DeveloperRelease summary: Get a V3 developer platform release manifest parameters: - "$ref": "#/components/parameters/XRequestId" - name: version in: path required: true schema: type: string minLength: 1 responses: '200': description: V3 platform release manifest content: application/json: schema: "$ref": "#/components/schemas/PlatformRelease" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/developer/releases/{version}/artifacts/{artifact_id}/download": get: tags: - V3Developer operationId: downloadV3DeveloperReleaseArtifact summary: Download a V3 developer platform release artifact parameters: - "$ref": "#/components/parameters/XRequestId" - name: version in: path required: true schema: type: string minLength: 1 - name: artifact_id in: path required: true schema: type: string minLength: 1 responses: '200': description: Artifact archive content: application/gzip: schema: type: string format: binary '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/developer/releases/{version}/artifacts/{artifact_id}/pull-intent": post: tags: - V3Developer operationId: createV3DeveloperReleaseArtifactPullIntent summary: Issue a V3 developer platform release artifact pull intent parameters: - "$ref": "#/components/parameters/XRequestId" - name: version in: path required: true schema: type: string minLength: 1 - name: artifact_id in: path required: true schema: type: string minLength: 1 responses: '201': description: V3 platform release artifact pull intent issued content: application/json: schema: "$ref": "#/components/schemas/ArtifactPullIntent" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/developer/dev-ca": get: tags: - V3Developer operationId: getV3DeveloperDevCA summary: Get V3 platform-control dev CA download metadata parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: Platform-control dev CA metadata content: application/json: schema: "$ref": "#/components/schemas/PlatformDevCA" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/developer/dev-ca/download": get: tags: - V3Developer operationId: downloadV3DeveloperDevCA summary: Download the V3 platform-control dev CA certificate parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: PEM-encoded CA certificate content: application/x-x509-ca-cert: schema: type: string format: binary '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/apps/artifacts/publish-intents": post: tags: - V3Apps operationId: createV3AppArtifactPublishIntent summary: Issue a short-lived app artifact publish intent description: Issues a short-lived publish intent for direct artifact publication. The response may contain wrapped credential delivery material; clients must not persist or log credential fields. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateAppArtifactPublishIntentRequest" responses: '201': description: V3 app artifact publish intent issued content: application/json: schema: "$ref": "#/components/schemas/AppArtifactPublishIntent" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/apps/artifacts/{artifact_id}/pull-intent": post: tags: - V3Apps operationId: createV3AppArtifactPullIntent summary: Issue a short-lived pull intent for a V3 app artifact description: Returns registry metadata and Vault-wrapped pull credentials for a project app artifact. Artifact bytes remain on the registry path; clients must not cache or persist the wrapped credential. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AppArtifactIdPath" responses: '201': description: V3 app artifact pull intent issued content: application/json: schema: "$ref": "#/components/schemas/ArtifactPullIntent" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/apps/artifacts/{artifact_id}/promote": post: tags: - V3Apps operationId: promoteV3AppArtifact summary: Promote a V3 app artifact to a channel parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppArtifactIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/PromoteAppArtifactRequest" responses: '200': description: V3 app artifact promoted content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/apps/artifacts/{artifact_id}/verify": post: tags: - V3Apps operationId: verifyV3AppArtifact summary: Mark a V3 app artifact as verified parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppArtifactIdPath" responses: '200': description: V3 app artifact verified content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/apps/artifacts/{artifact_id}/revoke": post: tags: - V3Apps operationId: revokeV3AppArtifact summary: Revoke trust for a V3 app artifact parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppArtifactIdPath" responses: '200': description: V3 app artifact trust revoked content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/apps/artifacts/{artifact_id}/deprecate": post: tags: - V3Apps operationId: deprecateV3AppArtifact summary: Deprecate a V3 app artifact parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppArtifactIdPath" responses: '200': description: V3 app artifact deprecated content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/apps/artifacts/{artifact_id}/retire": post: tags: - V3Apps operationId: retireV3AppArtifact summary: Retire a V3 app artifact from new use parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppArtifactIdPath" responses: '200': description: V3 app artifact retired content: application/json: schema: "$ref": "#/components/schemas/AppArtifact" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/apps/{app_slug}": get: tags: - V3ReadModels operationId: getV3AppDetail summary: Get v3 managed app detail read model description: 'Returns the app detail read model used by the v3 catalog detail and app launch entry. Secrets, signed pull credentials, service-account tokens, and provider credentials must never be present in this response. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AppSlugPath" responses: '200': description: V3 managed app detail headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AppDetailResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/apps/instances/{app_instance_id}": get: tags: - V3Apps operationId: getV3AppInstance summary: Get V3 app runtime instance description: V3 project-scoped alias for app runtime management. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AppInstanceIdPath" responses: '200': description: V3 app runtime instance content: application/json: schema: "$ref": "#/components/schemas/AppInstance" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/apps/instances/{app_instance_id}/members": get: tags: - V3Apps operationId: listV3AppInstanceMembers summary: List V3 app runtime members parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AppInstanceIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: component_key in: query required: false schema: type: string - name: status in: query required: false schema: type: string responses: '200': description: V3 app runtime members content: application/json: schema: "$ref": "#/components/schemas/AppInstanceMemberListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/apps/instances/{app_instance_id}/member-operations": get: tags: - V3Apps operationId: listV3AppInstanceMemberOperations summary: List V3 app runtime member operations parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AppInstanceIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: component_key in: query required: false schema: type: string - name: status in: query required: false schema: type: string responses: '200': description: V3 app runtime member operations content: application/json: schema: "$ref": "#/components/schemas/AppInstanceMemberOperationListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3Apps operationId: createV3AppInstanceMemberOperation summary: Queue a V3 app runtime member operation parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppInstanceIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateAppInstanceMemberOperationRequest" responses: '202': description: V3 app runtime member operation queued content: application/json: schema: "$ref": "#/components/schemas/AppInstanceMemberOperation" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/apps/instances/{app_instance_id}/upgrade": post: tags: - V3Apps operationId: upgradeV3AppInstance summary: Upgrade a V3 app runtime parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppInstanceIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/UpgradeAppInstanceRequest" responses: '202': description: V3 app runtime upgrade queued content: application/json: schema: "$ref": "#/components/schemas/AppInstance" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/apps/instances/{app_instance_id}/rollback": post: tags: - V3Apps operationId: rollbackV3AppInstance summary: Roll back a V3 app runtime parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppInstanceIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/RollbackAppInstanceRequest" responses: '202': description: V3 app runtime rollback queued content: application/json: schema: "$ref": "#/components/schemas/AppInstance" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/apps/instances/{app_instance_id}/stop": post: tags: - V3Apps operationId: stopV3AppInstance summary: Stop a V3 app runtime parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppInstanceIdPath" responses: '202': description: V3 app runtime stop queued content: application/json: schema: "$ref": "#/components/schemas/V3AppInstanceOperationResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/apps/instances/{app_instance_id}/start": post: tags: - V3Apps operationId: startV3AppInstance summary: Start a V3 app runtime parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppInstanceIdPath" responses: '202': description: V3 app runtime start queued content: application/json: schema: "$ref": "#/components/schemas/V3AppInstanceOperationResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/apps/instances/{app_instance_id}/restart": post: tags: - V3Apps operationId: restartV3AppInstance summary: Restart a V3 app runtime parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppInstanceIdPath" responses: '202': description: V3 app runtime restart queued content: application/json: schema: "$ref": "#/components/schemas/V3AppInstanceOperationResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/apps/instances/{app_instance_id}/decommission": post: tags: - V3Apps operationId: decommissionV3AppInstance summary: Decommission a V3 app runtime parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppInstanceIdPath" responses: '202': description: V3 app runtime decommission queued content: application/json: schema: "$ref": "#/components/schemas/V3AppInstanceOperationResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/schedulers/shared-runtimes": get: tags: - V3Schedulers operationId: listV3SharedAppRuntimes summary: List V3 tenant-shared scheduler runtimes description: V3 tenant-scoped alias for tenant-owned shared app runtimes. parameters: - "$ref": "#/components/parameters/XRequestId" - name: X-Tenant-ID in: header required: true schema: type: string format: uuid - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string responses: '200': description: V3 tenant-shared scheduler runtimes content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/schedulers/shared-runtimes/{shared_runtime_id}": get: tags: - V3Schedulers operationId: getV3SharedAppRuntime summary: Get V3 tenant-shared scheduler runtime parameters: - "$ref": "#/components/parameters/XRequestId" - name: X-Tenant-ID in: header required: true schema: type: string format: uuid - "$ref": "#/components/parameters/SharedRuntimeIdPath" responses: '200': description: V3 tenant-shared scheduler runtime content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntime" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/schedulers/shared-runtimes/{shared_runtime_id}/attachments": get: tags: - V3Schedulers operationId: listV3SharedAppRuntimeAttachments summary: List V3 tenant-shared runtime project attachments parameters: - "$ref": "#/components/parameters/XRequestId" - name: X-Tenant-ID in: header required: true schema: type: string format: uuid - "$ref": "#/components/parameters/SharedRuntimeIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: V3 tenant-shared runtime attachments content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeAttachmentListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/schedulers/shared-runtimes/{shared_runtime_id}/workers": get: tags: - V3Schedulers operationId: listV3SharedAppRuntimeWorkers summary: List V3 tenant-shared runtime workers parameters: - "$ref": "#/components/parameters/XRequestId" - name: X-Tenant-ID in: header required: true schema: type: string format: uuid - "$ref": "#/components/parameters/SharedRuntimeIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string responses: '200': description: V3 tenant-shared runtime workers content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeWorkerListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/schedulers/shared-runtimes/{shared_runtime_id}/worker-operations": get: tags: - V3Schedulers operationId: listV3SharedAppRuntimeWorkerOperations summary: List V3 tenant-shared runtime worker operations parameters: - "$ref": "#/components/parameters/XRequestId" - name: X-Tenant-ID in: header required: true schema: type: string format: uuid - "$ref": "#/components/parameters/SharedRuntimeIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string responses: '200': description: V3 tenant-shared runtime worker operations content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperationListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3Schedulers operationId: createV3SharedAppRuntimeWorkerOperation summary: Request a V3 tenant-shared runtime worker lifecycle change description: | Tenant operators request worker lifecycle changes through the V3 scheduler workbench. The operation is consumed by the shared-runtime operator contract. parameters: - "$ref": "#/components/parameters/XRequestId" - name: X-Tenant-ID in: header required: true schema: type: string format: uuid - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/SharedRuntimeIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateSharedAppRuntimeWorkerOperationRequest" responses: '202': description: V3 shared runtime worker operation accepted content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperation" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/schedulers/shared-runtime-attachments/{attachment_id}/worker-operations": post: tags: - V3Schedulers operationId: createV3ProjectSharedRuntimeWorkerOperation summary: Request V3 project worker contribution for an attached shared runtime description: | Consumer projects use this V3 path to request add, drain, or remove operations against a tenant-shared runtime attachment. The platform resolves tenant ownership and enforces the attachment contribution policy. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/SharedRuntimeAttachmentIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateSharedAppRuntimeWorkerOperationRequest" responses: '202': description: V3 project shared runtime worker operation accepted content: application/json: schema: "$ref": "#/components/schemas/SharedAppRuntimeWorkerOperation" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/account/evidence/audit": get: tags: - V3Account operationId: listV3AccountEvidenceAuditLogs summary: List V3 account-scoped audit evidence parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - "$ref": "#/components/parameters/AuditLogSort" - name: action in: query required: false style: form explode: true schema: type: array items: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: V3 account audit evidence content: application/json: schema: "$ref": "#/components/schemas/AuditLogListResponse" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/project/evidence/audit": get: tags: - V3Project operationId: listV3ProjectEvidenceAuditLogs summary: List V3 current-project audit evidence parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - "$ref": "#/components/parameters/AuditLogSort" - name: actor_user_id in: query required: false description: Optional actor filter applied inside the resolved project scope. schema: type: string format: uuid - name: actor_role in: query required: false description: Optional actor role filters applied inside the resolved project scope. style: form explode: true schema: type: array items: type: string - name: action in: query required: false style: form explode: true schema: type: array items: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: V3 project audit evidence content: application/json: schema: "$ref": "#/components/schemas/AuditLogListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/access/evidence/audit": get: tags: - V3Access operationId: listV3TenantEvidenceAuditLogs summary: List V3 tenant-scoped audit evidence parameters: - "$ref": "#/components/parameters/XRequestId" - name: X-Tenant-ID in: header required: false schema: type: string format: uuid - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - "$ref": "#/components/parameters/AuditLogSort" - name: actor_user_id in: query required: false description: Optional actor filter applied inside the resolved tenant scope. schema: type: string format: uuid - name: actor_role in: query required: false description: Optional actor role filters applied inside the resolved tenant scope. style: form explode: true schema: type: array items: type: string - name: action in: query required: false style: form explode: true schema: type: array items: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: V3 tenant audit evidence content: application/json: schema: "$ref": "#/components/schemas/AuditLogListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/launch/apps/{app_slug}/precheck": post: tags: - V3ReadModels operationId: precheckV3AppLaunch summary: Precheck v3 app launch readiness description: 'Read-only launch readiness contract for the v3 app wizard. It evaluates project entitlement, version availability, dependency presence, and basic runtime intent before the user submits a mutating app-instance request. This endpoint is safe to retry and must not create app instances, service accounts, credentials, buckets, or network policy objects. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppSlugPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3AppLaunchPrecheckRequest" responses: '200': description: V3 app launch readiness content: application/json: schema: "$ref": "#/components/schemas/V3LaunchPrecheckResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/launch/apps/{app_slug}": post: tags: - V3ReadModels operationId: submitV3AppLaunch summary: Submit v3 app launch description: 'Mutating submit endpoint for the v3 app wizard. The endpoint reuses the app-instance domain path and returns a normalized task handoff so app-backed runtimes remain workload subtypes in the v3 shell. Clients must send an idempotency key; replaying the same body with the same key must not create a duplicate app instance. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/AppSlugPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3AppLaunchSubmitRequest" responses: '202': description: V3 app launch accepted content: application/json: schema: "$ref": "#/components/schemas/V3LaunchSubmitResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/storage": get: tags: - V3ReadModels operationId: listV3StorageBuckets summary: List v3 storage workbench bucket rows description: 'Temporary v3 migration read model for the Storage shell group. Returns project-scoped bucket rows with usage, mount, access, lifecycle, and attention flags. Responses must not include raw object-store credentials, signed URLs, provider secrets, or private key material. ' x-v3-read-model-gaps: - bucket rows need provider-neutral endpoint, mount hint, and copyable URI fields when those values are safe to expose. - bucket rows need explicit size/quota, share count, attachment count, and last activity timestamps for scan decisions. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - in: query name: purpose required: false schema: "$ref": "#/components/schemas/V3StorageBucketPurpose" - in: query name: status required: false schema: type: string enum: - creating - active - failed - deleting - deleted - in: query name: scope required: false schema: type: string enum: - attached - unattached - flagged - in: query name: protocol required: false schema: type: string enum: - wekafs - posix - s3 - nfs - smb - csi - in: query name: search required: false schema: type: string maxLength: 120 - in: query name: sort required: false schema: type: string default: name_asc enum: - name_asc - name_desc - updated_at_desc - updated_at_asc - used_bytes_desc - used_bytes_asc - purpose_asc - status_asc responses: '200': description: V3 storage bucket workbench list headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3StorageBucketListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - V3Storage operationId: createV3StorageBucket summary: Create a v3 storage bucket description: Creates a project-scoped bucket through the currently configured storage provider. The response is provider-neutral and never returns provider credentials, mount secrets, signed URLs, or raw backend identifiers. Requires an idempotency key. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3StorageBucketCreateRequest" responses: '201': description: V3 storage bucket created content: application/json: schema: "$ref": "#/components/schemas/V3StorageBucketCreateResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/storage/{bucket_id}": get: tags: - V3ReadModels operationId: getV3StorageBucketDetail summary: Get v3 storage bucket detail read model description: 'Temporary v3 migration read model for a bucket detail page. The payload is presentation-shaped and sanitized: it may include object key previews, mount summaries, lifecycle posture, and access audiences, but never credential material, signed download/upload URLs, or raw provider config. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3StorageBucketIdPath" responses: '200': description: V3 storage bucket detail headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3StorageBucketDetailResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" patch: tags: - V3Storage operationId: updateV3StorageBucket summary: Update provider-neutral bucket lifecycle metadata description: Updates bucket policy metadata such as purpose, quota, retention, access protocol, and access audience. Provider credentials and backend-specific identifiers are never returned. Audited as `storage.bucket.update`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3StorageBucketIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3StorageBucketUpdateRequest" responses: '200': description: V3 storage bucket updated content: application/json: schema: "$ref": "#/components/schemas/V3StorageBucketMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" delete: tags: - V3Storage operationId: deleteV3StorageBucket summary: Delete a storage bucket when no active grants or attachments remain description: Deletes provider-local data and marks the bucket deleted only after active grants and attachments have been removed. Audited as `storage.bucket.delete`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3StorageBucketIdPath" responses: '204': description: V3 storage bucket deleted '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/storage/{bucket_id}/archive": post: tags: - V3Storage operationId: archiveV3StorageBucket summary: Archive a storage bucket without deleting provider data description: Moves the bucket lifecycle state to deleting for operator follow-up while preserving provider data. Requires no active grants or attachments. Audited as `storage.bucket.archive`. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3StorageBucketIdPath" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3StorageBucketArchiveRequest" responses: '200': description: V3 storage bucket archived content: application/json: schema: "$ref": "#/components/schemas/V3StorageBucketMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/storage/{bucket_id}/objects/download": get: tags: - V3Storage operationId: downloadV3StorageObject summary: Download an object from a v3 storage bucket description: Downloads object bytes through the active V3 project context. The `path` query may be either bucket-relative or include the bucket prefix; the server normalizes it and rejects paths outside the bucket. No auth material is accepted in the query string. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3StorageBucketIdPath" - "$ref": "#/components/parameters/V3StorageObjectPathQuery" responses: '200': description: Storage object bytes content: application/octet-stream: schema: type: string format: binary '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/storage/{bucket_id}/objects/upload": put: tags: - V3Storage operationId: uploadV3StorageObject summary: Upload object bytes to a v3 storage bucket description: Uploads object bytes through the active V3 project context. The `path` query may be bucket-relative or include the bucket prefix; the server normalizes it and rejects paths outside the bucket. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3StorageBucketIdPath" - "$ref": "#/components/parameters/V3StorageObjectPathQuery" requestBody: required: true content: application/octet-stream: schema: type: string format: binary responses: '200': description: Storage object uploaded content: application/json: schema: "$ref": "#/components/schemas/OkResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/storage/{bucket_id}/objects/mkdir": post: tags: - V3Storage operationId: createV3StorageDirectory summary: Create a directory marker in a v3 storage bucket description: Creates a provider-neutral directory marker through the active V3 project context. The supplied path may be bucket-relative or include the bucket prefix. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3StorageBucketIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3StorageObjectPathRequest" responses: '200': description: Storage directory created content: application/json: schema: "$ref": "#/components/schemas/OkResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/storage/{bucket_id}/objects": delete: tags: - V3Storage operationId: deleteV3StorageObject summary: Delete an object or prefix from a v3 storage bucket description: Deletes an object or prefix through the active V3 project context. The `path` query may be bucket-relative or include the bucket prefix; the server normalizes it and rejects paths outside the bucket. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3StorageBucketIdPath" - "$ref": "#/components/parameters/V3StorageObjectPathQuery" responses: '200': description: Storage object deleted content: application/json: schema: "$ref": "#/components/schemas/OkResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/storage/{bucket_id}/attachments": get: tags: - V3Storage operationId: listV3StorageAttachments summary: List runtime storage attachments for a bucket description: 'Lists provider-neutral storage attachment state for one project storage namespace. This is a read model over Temporal/node-agent/provider state and never returns provider credentials, raw mount commands, or backend cluster identifiers. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3StorageBucketIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - in: query name: search required: false schema: type: string maxLength: 120 - in: query name: state required: false schema: type: string enum: - requested - prechecking - grant_applying - grant_applied - mounting - mounted - failed - detaching - detached - detach_failed x-enum-varnames: - ListV3StorageAttachmentsParamsStateRequested - ListV3StorageAttachmentsParamsStatePrechecking - ListV3StorageAttachmentsParamsStateGrantApplying - ListV3StorageAttachmentsParamsStateGrantApplied - ListV3StorageAttachmentsParamsStateMounting - ListV3StorageAttachmentsParamsStateMounted - ListV3StorageAttachmentsParamsStateFailed - ListV3StorageAttachmentsParamsStateDetaching - ListV3StorageAttachmentsParamsStateDetached - ListV3StorageAttachmentsParamsStateDetachFailed - in: query name: scope required: false schema: type: string enum: - allocation - workload - node - in: query name: access_mode required: false schema: type: string enum: - read_only - read_write - in: query name: sort required: false schema: type: string default: updated_at_desc enum: - updated_at_desc - updated_at_asc - requested_at_desc - requested_at_asc - mount_path_asc - state_asc responses: '200': description: Storage attachments content: application/json: schema: "$ref": "#/components/schemas/V3StorageAttachmentListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3Storage operationId: createV3StorageAttachment summary: Request storage attachment to a workload or allocation description: 'Persists an idempotent storage attachment intent and starts the Temporal attach workflow. The response returns the attachment state; it does not wait for the node-agent mount to complete. Audited as `storage.attachment.request`. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3StorageBucketIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3StorageAttachmentCreateRequest" responses: '202': description: Storage attachment workflow accepted content: application/json: schema: "$ref": "#/components/schemas/V3StorageAttachmentResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/storage/{bucket_id}/attachments/{attachment_id}": get: tags: - V3Storage operationId: getV3StorageAttachment summary: Get one storage attachment parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3StorageBucketIdPath" - "$ref": "#/components/parameters/V3StorageAttachmentIdPath" responses: '200': description: Storage attachment content: application/json: schema: "$ref": "#/components/schemas/V3StorageAttachmentResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" delete: tags: - V3Storage operationId: detachV3StorageAttachment summary: Request storage attachment detach description: 'Starts or signals the Temporal detach workflow. Persistent storage is never deleted by this endpoint. Audited as `storage.attachment.detach`. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3StorageBucketIdPath" - "$ref": "#/components/parameters/V3StorageAttachmentIdPath" responses: '202': description: Storage detach workflow accepted content: application/json: schema: "$ref": "#/components/schemas/V3StorageAttachmentResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/storage/{bucket_id}/grants": get: tags: - V3Storage operationId: listV3StorageGrants summary: List storage grants for a bucket description: 'Contract baseline for provider-neutral storage sharing. Returns GPUaaS grant records and compiled-policy posture only; provider credentials, raw WEKA policy JSON, and provider admin identifiers are never returned. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/V3StorageBucketIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - in: query name: search required: false schema: type: string maxLength: 120 - in: query name: status required: false schema: type: string enum: - active - revoked - expired - in: query name: subject_kind required: false schema: "$ref": "#/components/schemas/V3StoragePrincipalKind" - in: query name: permission required: false schema: "$ref": "#/components/schemas/V3StoragePermission" - in: query name: sort required: false schema: type: string default: created_at_desc enum: - created_at_desc - created_at_asc - expires_at_desc - expires_at_asc - subject_asc - subject_desc responses: '200': description: Storage grants content: application/json: schema: "$ref": "#/components/schemas/V3StorageGrantListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3Storage operationId: createV3StorageGrant summary: Create a bucket or prefix storage grant description: 'Creates a GPUaaS-owned storage grant. Provider adapters compile this grant into provider policy, for example WEKA IAM or bucket policy, but GPUaaS remains the source of truth. This mutation is idempotent and audited as `storage.grant.create`. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3StorageBucketIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3StorageGrantCreateRequest" responses: '201': description: Storage grant created content: application/json: schema: "$ref": "#/components/schemas/V3StorageGrantResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/storage/{bucket_id}/grants/{grant_id}": delete: tags: - V3Storage operationId: revokeV3StorageGrant summary: Revoke a storage grant description: 'Revokes future provider credential issuance for a grant and asks the provider adapter to remove or narrow compiled policy where supported. Active STS credentials may remain valid until expiry if the provider cannot revoke individual sessions. Audited as `storage.grant.revoke`. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3StorageBucketIdPath" - "$ref": "#/components/parameters/V3StorageGrantIdPath" responses: '200': description: Storage grant revoked content: application/json: schema: "$ref": "#/components/schemas/V3StorageGrantRevokeResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/storage/{bucket_id}/credentials": post: tags: - V3Storage operationId: issueV3StorageCredential summary: Issue short-lived scoped storage credentials description: 'Issues direct S3-compatible credentials after GPUaaS IAM and storage grant checks. This endpoint may return provider credential material exactly once to the caller and must not be used by read models, cached responses, or browser local storage. For WEKA this maps to STS/session credentials when available. Audited as `auth.provider_credential.issue` and `storage.credential.issue`. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3StorageBucketIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3StorageCredentialIssueRequest" responses: '201': description: Scoped storage credential issued content: application/json: schema: "$ref": "#/components/schemas/V3StorageCredentialIssueResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/access": get: tags: - V3ReadModels operationId: getV3AccessOverview summary: Get v3 access posture overview read model description: 'Temporary v3 migration read model for the Access shell group. Returns project-scoped counts and drift signals across memberships, service accounts, credentials, and entitlements. Raw secrets, private keys, access tokens, refresh tokens, and provider credentials must never be returned. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" responses: '200': description: V3 access overview headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccessOverviewResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/access/memberships": get: tags: - V3ReadModels operationId: listV3AccessMemberships summary: List v3 access membership rows parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: search in: query required: false schema: type: string description: Case-insensitive search across username, display name, user id, and roles. - name: access_source in: query required: false schema: type: array items: type: string enum: - project_role - tenant_role - explicit - platform_role x-enum-varnames: - ListV3AccessMembershipsParamsAccessSourceProjectRole - ListV3AccessMembershipsParamsAccessSourceTenantRole - ListV3AccessMembershipsParamsAccessSourceExplicit - ListV3AccessMembershipsParamsAccessSourcePlatformRole style: form explode: false description: Filter memberships by effective access source. Repeat or comma-separate for multi-select. - name: tenant_role in: query required: false schema: type: array items: type: string enum: - owner - admin - member - billing_viewer style: form explode: false description: Filter memberships by tenant role. Repeat or comma-separate for multi-select. - name: project_role in: query required: false schema: type: array items: type: string enum: - owner - admin - member - viewer style: form explode: false description: Filter memberships by project role. Repeat or comma-separate for multi-select. - name: sort in: query required: false schema: type: string enum: - username_asc - username_desc - tenant_role_asc - tenant_role_desc - project_role_asc - project_role_desc description: Sort order for membership rows. Defaults to username ascending. responses: '200': description: V3 access memberships headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccessMembershipListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/access/service-accounts": get: tags: - V3ReadModels operationId: listV3AccessServiceAccounts summary: List v3 access service-account rows parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: search in: query required: false description: Case-insensitive search across service account name, id, project, status, and scope. schema: type: string - name: status in: query required: false style: form explode: true schema: type: array items: type: string enum: - active - disabled - name: scope in: query required: false style: form explode: true schema: type: array items: type: string - name: sort in: query required: false description: Sort order for service account rows. Defaults to name ascending. schema: type: string default: name_asc enum: - name_asc - name_desc - key_age_asc - key_age_desc - rotation_due_asc - rotation_due_desc responses: '200': description: V3 access service accounts headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccessServiceAccountListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/access/credentials": get: tags: - V3ReadModels operationId: listV3AccessCredentials summary: List v3 access credential map rows description: 'Returns credential posture metadata only. The response may include labels, fingerprints, status, ownership, and expiry metadata, but never raw public key payloads, private keys, token material, or provider secrets. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: search in: query required: false description: Case-insensitive search across credential label, fingerprint, id, subject id, kind, status, and management surface. schema: type: string - name: kind in: query required: false style: form explode: true schema: type: array items: type: string enum: - ssh_key - personal_api_key - service_account_key - workload_api_key - name: status in: query required: false style: form explode: true schema: type: array items: type: string enum: - active - expiring - expired - disabled - revoked - name: managed_in in: query required: false style: form explode: true schema: type: array items: type: string enum: - account - access - platform - name: sort in: query required: false description: Sort order for the credential list. Defaults to newest credentials first. schema: type: string default: created_at_desc enum: - created_at_desc - created_at_asc - label_asc - label_desc - last_used_at_desc - last_used_at_asc - expires_at_asc - expires_at_desc responses: '200': description: V3 access credentials headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccessCredentialListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/access/entitlements": get: tags: - V3ReadModels operationId: listV3AccessEntitlements summary: List v3 access entitlement rows parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - in: query name: search required: false schema: type: string description: Case-insensitive search across entitlement name, id, project, kind, version, and limits. - in: query name: kind required: false schema: type: array items: type: string enum: - app - sku - region - product - tenant - project style: form explode: false description: Filter by entitlement kind. Repeat or comma-separate for multi-select. - in: query name: status required: false schema: type: array items: type: string enum: - enabled - disabled style: form explode: false description: Filter by entitlement status. Repeat or comma-separate for multi-select. - in: query name: sort required: false schema: type: string enum: - name_asc - name_desc - kind_asc - kind_desc - status_asc - status_desc default: name_asc description: Sort order for the entitlement list. responses: '200': description: V3 access entitlements headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccessEntitlementListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/access/quotas": get: tags: - V3ReadModels operationId: getV3AccessQuotaPosture summary: Get v3 access quota posture description: 'Returns the selected project/user effective allocation quota posture: concurrent allocation limit, current usage, launch headroom, and guidance links. This is the user/project quota surface; platform-level quota policy editing remains under Platform Config. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" responses: '200': description: V3 access quota posture headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccessQuotaResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/access/audit": get: tags: - V3ReadModels operationId: listV3AccessAuditEvents summary: List v3 access audit events description: 'Returns access-family audit events for membership, service-account, credential, entitlement, identity, and connectivity mutations. This is a scoped read model over platform_audit_logs and must not return credential material, token payloads, private keys, provider secrets, or raw request bodies. ' parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - "$ref": "#/components/parameters/AuditLogSort" - name: actor_user_id in: query required: false description: Optional actor filter applied inside the resolved project scope. schema: type: string format: uuid - name: actor_role in: query required: false description: Optional actor role filters applied inside the resolved project scope. style: form explode: true schema: type: array items: type: string - name: action in: query required: false description: Optional action-prefix filters. Repeated values are ORed. style: form explode: true schema: type: array items: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: V3 access audit events headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccessAuditEventListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/access/audit/export": get: tags: - V3ReadModels operationId: exportV3AccessAuditEvents summary: Export filtered v3 access audit events description: Backend-owned export for the V3 access audit surface. Export honors the same project scope, access-family filters, time range, and sort as the access audit list and returns only sanitized access audit presentation fields. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/ProjectIdHeader" - "$ref": "#/components/parameters/AuditLogSort" - name: format in: query required: false schema: type: string enum: - csv - json default: csv - name: actor_user_id in: query required: false description: Optional actor filter applied inside the resolved project scope. schema: type: string format: uuid - name: actor_role in: query required: false description: Optional actor role filters applied inside the resolved project scope. style: form explode: true schema: type: array items: type: string - name: action in: query required: false description: Optional action-prefix filters. Repeated values are ORed. style: form explode: true schema: type: array items: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: Filtered V3 access audit event export content: text/csv: schema: type: string format: binary application/json: schema: "$ref": "#/components/schemas/V3AccessAuditEventExportResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/account": get: tags: - V3ReadModels operationId: getV3AccountOverview summary: Get v3 account overview read model description: 'Temporary v3 migration read model for the Account shell group. Returns personal profile, linked identity counts, personal credential counts, active session count, and personal attention items. Raw tokens, refresh tokens, private keys, password hashes, and provider secrets must never be returned. ' parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: V3 account overview headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccountOverviewResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/account/profile": get: tags: - V3ReadModels operationId: getV3AccountProfile summary: Get v3 account profile and linked identities parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: V3 account profile headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccountProfileResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" patch: tags: - V3ReadModels operationId: updateV3AccountProfile summary: Update v3 account profile preferences parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3AccountProfileUpdateRequest" responses: '200': description: Updated V3 account profile content: application/json: schema: "$ref": "#/components/schemas/V3AccountProfileResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/account/security": get: tags: - V3ReadModels operationId: getV3AccountSecurity summary: Get v3 account personal security posture description: 'Returns metadata for personal SSH/API credentials and MFA posture. This endpoint owns personal records; Access endpoints may reference the same records only as a permission map. No private keys or API tokens are returned. ' parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: V3 account security posture headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccountSecurityResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/account/security/ssh-keys": get: tags: - V3ReadModels operationId: listV3AccountSshKeys summary: List personal SSH keys for launch and account security workflows description: Returns caller-owned SSH public keys through the V3 account namespace. No private key material is accepted or returned. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/PageSize" - name: cursor in: query required: false schema: type: string - name: status in: query required: false schema: type: string enum: - active - revoked - name: last_used in: query required: false schema: type: string enum: - used - never - name: search in: query required: false schema: type: string description: Case-insensitive match against key name, fingerprint, or public key. - name: sort in: query required: false schema: type: string enum: - created_at_desc - created_at_asc - last_used_at_desc - last_used_at_asc - name_asc - name_desc - status_asc default: created_at_desc responses: '200': description: SSH public keys content: application/json: schema: "$ref": "#/components/schemas/SshPublicKeyListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/account/security/mfa/recovery-requests": post: tags: - V3ReadModels operationId: createV3AccountMFARecoveryRequest summary: Start an account MFA recovery request description: Records an audited product-owned MFA recovery request for lost or changed authenticators. This endpoint does not remove a factor directly; privileged and last-factor resets require support or operator verification. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3AccountMFARecoveryRequest" responses: '202': description: MFA recovery request submitted content: application/json: schema: "$ref": "#/components/schemas/V3AccountMFARecoveryRequestResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/account/sessions": get: tags: - V3ReadModels operationId: listV3AccountSessions summary: List v3 account sessions parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/PageSize" - name: cursor in: query required: false schema: type: string - name: status in: query required: false schema: type: string enum: - active - expired - revoked - name: risk in: query required: false schema: type: string enum: - normal - attention - name: last_seen in: query required: false schema: type: string enum: - 6h - 12h - 24h - 7d - name: device in: query required: false schema: type: string description: Case-insensitive match against device, browser, or OS label. - name: search in: query required: false schema: type: string description: Case-insensitive match against device, browser, OS, IP, location, or provider. - name: sort in: query required: false schema: type: string enum: - last_seen_desc - last_seen_asc - signed_in_desc - signed_in_asc - expires_at_desc - expires_at_asc - device_asc - status_asc - risk_desc default: last_seen_desc responses: '200': description: V3 account sessions headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3AccountSessionListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/account/sessions/{session_id}/revoke": post: tags: - V3ReadModels operationId: revokeV3AccountSession summary: Revoke a tracked v3 account session parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: session_id in: path required: true schema: type: string format: uuid requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3AccountSessionRevokeRequest" responses: '200': description: Account session revoked content: application/json: schema: "$ref": "#/components/schemas/V3AccountSessionRevokeResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/account/sessions/revoke-others": post: tags: - V3ReadModels operationId: revokeOtherV3AccountSessions summary: Revoke every tracked v3 account session except the current session parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3AccountSessionRevokeRequest" responses: '200': description: Other account sessions revoked content: application/json: schema: "$ref": "#/components/schemas/V3AccountSessionRevokeResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/overview": get: tags: - V3ReadModels operationId: getV3PlatformOverview summary: Get v3 platform overview read model description: 'Temporary v3 migration read model for the Platform landing page. It summarizes operator families, fleet posture, active allocations, API health, worker posture, and DLQ state. Requires platform ops read permission. ' parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: V3 platform overview headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformOverviewResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops": get: tags: - V3ReadModels operationId: getV3PlatformOps summary: Get v3 platform live ops read model description: Temporary v3 migration read model for live triage, active signals, service health, and investigation pivots. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: V3 platform ops headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformOpsResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops/telemetry/fleet": get: tags: - V3PlatformOps operationId: getV3PlatformOpsFleetTelemetry summary: Get fleet telemetry rollups through the V3 ops boundary description: Read-only fleet telemetry subworkbench for platform operators. Returns CPU, GPU, memory, storage, and tenant/project rollups over a bounded window. parameters: - "$ref": "#/components/parameters/XRequestId" - name: range in: query required: false schema: type: string enum: - 15m - 1h - 6h - 24h - name: points in: query required: false schema: type: integer minimum: 10 maximum: 240 responses: '200': description: V3 ops fleet telemetry snapshot content: application/json: schema: "$ref": "#/components/schemas/AdminFleetTelemetryResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops/registry/environment-artifacts": get: tags: - V3PlatformOps operationId: listV3PlatformRegistryEnvironmentArtifacts summary: List environment artifact inventory for platform operators description: Platform-owned read model for answering which immutable image or artifact digest is deployed in an environment. Digest evidence is authoritative; mutable tags are display/search hints only. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: environment_profile in: query required: false schema: type: string - name: namespace in: query required: false schema: type: string - name: component in: query required: false schema: type: string - name: artifact_kind in: query required: false schema: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactKind" - name: image_ref in: query required: false schema: type: string - name: digest in: query required: false schema: type: string - name: source_sha in: query required: false schema: type: string - name: release_id in: query required: false schema: type: string - name: rollout_revision in: query required: false schema: type: string - name: status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactStatus" responses: '200': description: Environment artifact inventory content: application/json: schema: "$ref": "#/components/schemas/V3PlatformRegistryEnvironmentArtifactsResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops/registry/artifact-trust": get: tags: - V3PlatformOps operationId: listV3PlatformRegistryArtifactTrust summary: List artifact trust status for platform operators description: Platform-owned read model for signature, SBOM, provenance, scanner summary, waiver, promotion eligibility, and expiry. Missing evidence fails closed as not_ready. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: digest in: query required: false schema: type: string - name: image_ref in: query required: false schema: type: string - name: artifact_name in: query required: false schema: type: string - name: source_sha in: query required: false schema: type: string - name: release_id in: query required: false schema: type: string - name: environment_profile in: query required: false schema: type: string - name: trust_status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustStatus" - name: promotion_eligible in: query required: false schema: type: boolean responses: '200': description: Artifact trust status content: application/json: schema: "$ref": "#/components/schemas/V3PlatformRegistryArtifactTrustResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops/registry/app-artifacts": get: tags: - V3PlatformOps operationId: listV3PlatformRegistryAppArtifacts summary: List app artifact launch eligibility for platform operators description: Platform-owned app artifact operator status read model for launch eligibility, digest readiness, trust state, target architecture compatibility, and evidence links. Registry credentials and runtime secrets are never returned. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: org_id in: query required: false schema: type: string format: uuid - name: project_id in: query required: false schema: type: string format: uuid - name: app_slug in: query required: false schema: type: string - name: app_version in: query required: false schema: type: string - name: artifact_name in: query required: false schema: type: string - name: artifact_kind in: query required: false schema: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactKind" - name: source_type in: query required: false schema: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactSourceType" - name: platform_os in: query required: false schema: type: string - name: platform_arch in: query required: false schema: type: string - name: digest in: query required: false schema: type: string - name: trust_state in: query required: false schema: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactTrustState" - name: launch_eligible in: query required: false schema: type: boolean responses: '200': description: App artifact operator launch eligibility status content: application/json: schema: "$ref": "#/components/schemas/V3PlatformRegistryAppArtifactsResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops/outbox/failed": get: tags: - V3ReadModels operationId: listV3PlatformOpsFailedOutboxEvents summary: List failed outbox events for the V3 platform ops workbench parameters: - "$ref": "#/components/parameters/XRequestId" - name: cursor in: query schema: type: string - name: page_size in: query schema: type: integer minimum: 1 maximum: 200 responses: '200': description: Failed outbox events content: application/json: schema: "$ref": "#/components/schemas/AdminOutboxFailedListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/platform/ops/outbox/{event_id}/requeue": post: tags: - V3ReadModels operationId: requeueV3PlatformOpsOutboxEvent summary: Requeue a failed outbox event from the V3 platform ops workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: event_id in: path required: true schema: type: string format: uuid responses: '200': description: Outbox event requeued content: application/json: schema: "$ref": "#/components/schemas/AdminOutboxMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/platform/ops/outbox/{event_id}/discard": post: tags: - V3ReadModels operationId: discardV3PlatformOpsOutboxEvent summary: Discard a failed outbox event from the V3 platform ops workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: event_id in: path required: true schema: type: string format: uuid responses: '200': description: Outbox event discarded content: application/json: schema: "$ref": "#/components/schemas/AdminOutboxMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/platform/ops/dlq/messages": get: tags: - V3ReadModels operationId: listV3PlatformOpsDLQMessages summary: List DLQ stream messages for the V3 platform ops workbench parameters: - "$ref": "#/components/parameters/XRequestId" - name: cursor in: query schema: type: string - name: page_size in: query schema: type: integer minimum: 1 maximum: 200 - name: subject_prefix in: query schema: type: string description: Optional DLQ subject prefix filter, for example dlq.gpuaas.provisioning. responses: '200': description: DLQ messages page content: application/json: schema: "$ref": "#/components/schemas/AdminDLQMessageListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/platform/ops/dlq/messages/{stream_seq}/requeue": post: tags: - V3ReadModels operationId: requeueV3PlatformOpsDLQMessage summary: Requeue a DLQ message from the V3 platform ops workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: stream_seq in: path required: true schema: type: integer format: uint64 minimum: 1 responses: '200': description: DLQ message requeued content: application/json: schema: "$ref": "#/components/schemas/AdminDLQMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/platform/ops/dlq/messages/{stream_seq}/discard": post: tags: - V3ReadModels operationId: discardV3PlatformOpsDLQMessage summary: Discard a DLQ message from the V3 platform ops workbench parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: stream_seq in: path required: true schema: type: integer format: uint64 minimum: 1 responses: '200': description: DLQ message discarded content: application/json: schema: "$ref": "#/components/schemas/AdminDLQMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/platform/ops/signals/{signal_key}/acknowledge": post: tags: - V3ReadModels operationId: acknowledgeV3PlatformSignal summary: Acknowledge a v3 platform operator signal description: Backend-owned acknowledgement mutation for an active admin workbench signal. Requires platform ops write permission and an idempotency key for safe retries. The backend validates the supplied fingerprint against the current read-model signal before persisting acknowledgement state. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3PlatformSignalKeyPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3PlatformSignalAcknowledgeRequest" responses: '200': description: Signal acknowledgement state content: application/json: schema: "$ref": "#/components/schemas/V3PlatformSignalAckResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/ops/signals/{signal_key}/suppress": post: tags: - V3ReadModels operationId: suppressV3PlatformSignal summary: Suppress a v3 platform operator signal description: Backend-owned suppression mutation for admin workbench queue noise. Suppression requires a future expires_at timestamp and resurfaces automatically when the backend fingerprint changes. Requires platform ops write permission. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3PlatformSignalKeyPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3PlatformSignalSuppressRequest" responses: '200': description: Signal suppression state content: application/json: schema: "$ref": "#/components/schemas/V3PlatformSignalAckResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/ops/signals/{signal_key}/acknowledgement": delete: tags: - V3ReadModels operationId: clearV3PlatformSignalAcknowledgement summary: Clear acknowledgement or suppression for a v3 platform signal description: Clears current acknowledgement/suppression state for an admin workbench signal without deleting the audit trail. Requires platform ops write permission. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3PlatformSignalKeyPath" requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/V3PlatformSignalClearRequest" responses: '200': description: Signal acknowledgement cleared content: application/json: schema: "$ref": "#/components/schemas/V3PlatformSignalAckResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/platform/lifecycle": get: tags: - V3ReadModels operationId: getV3PlatformLifecycle summary: Get v3 platform lifecycle read model description: Temporary v3 migration read model for node lifecycle posture, action queue, and inventory rows. Requires platform ops read permission. x-v3-read-model-gaps: - node list rows still need site/rack, kernel/driver/CUDA/fabric facts, and heartbeat age/severity from authoritative agent or MAAS inventory. - lifecycle nodes need a dedicated backend-owned node list query with server-side status, occupancy, site, search, cursor, and sort semantics. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: V3 platform lifecycle headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformLifecycleResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/lifecycle/nodes": get: tags: - V3ReadModels operationId: listV3PlatformLifecycleNodes summary: List v3 platform lifecycle nodes description: Backend-owned lifecycle node list query with cursor pagination, server-side status, occupancy, site, host/search filters, and deterministic sort semantics for the v3 node lifecycle workbench. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: search in: query required: false schema: type: string - name: status in: query required: false schema: type: string enum: - registered - bootstrap_issued - enrolling - active - cordoned - offline - quarantined - draining - retired - removing - name: occupancy in: query required: false schema: type: string enum: - free - in_use - name: site_id in: query required: false schema: type: string format: uuid - name: sort in: query required: false schema: type: string enum: - host_asc - host_desc - health_desc - health_asc - last_activity_desc - last_activity_asc default: host_asc responses: '200': description: V3 platform lifecycle nodes headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformLifecycleNodesResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/lifecycle/attention/{attention_key}/review": post: tags: - V3ReadModels operationId: reviewV3ProvisioningAttention summary: Review a v3 provisioning attention item description: Marks a backend-owned provisioning attention item as taken care of or intentionally ignored. Requires platform ops write permission, persists an audit row, and keeps reviewed items available through history/evidence while removing them from default live attention queues. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/V3ProvisioningAttentionKeyPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3ProvisioningAttentionReviewRequest" responses: '200': description: Provisioning attention review state content: application/json: schema: "$ref": "#/components/schemas/V3ProvisioningAttentionReviewResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/lifecycle/maas-sites/{id}/roce-assignments": get: tags: - V3ReadModels operationId: listV3PlatformMaasRoceAssignments summary: List v3 MAAS RoCE assignments parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/MaasSiteIdPath" responses: '200': description: MAAS site RoCE assignments content: application/json: schema: "$ref": "#/components/schemas/MaasRoceAssignmentListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3ReadModels operationId: upsertV3PlatformMaasRoceAssignments summary: Upsert v3 MAAS RoCE assignments parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminBulkUpsertMaasRoceAssignmentsRequest" responses: '200': description: MAAS site RoCE assignments upserted content: application/json: schema: "$ref": "#/components/schemas/MaasRoceAssignmentListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/platform/lifecycle/maas-sites/{id}/roce-assignments/{assignment_id}": delete: tags: - V3ReadModels operationId: deleteV3PlatformMaasRoceAssignment summary: Delete a v3 MAAS RoCE assignment parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - name: assignment_id in: path required: true schema: type: string format: uuid responses: '204': description: MAAS site RoCE assignment deleted '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/platform/lifecycle/maas-sites/{id}/roce-assignments/{assignment_id}/enable": post: tags: - V3ReadModels operationId: enableV3PlatformMaasRoceAssignment summary: Enable a v3 MAAS RoCE assignment parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - name: assignment_id in: path required: true schema: type: string format: uuid responses: '200': description: MAAS site RoCE assignment enabled content: application/json: schema: "$ref": "#/components/schemas/MaasRoceAssignment" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/platform/lifecycle/maas-sites/{id}/roce-assignments/{assignment_id}/disable": post: tags: - V3ReadModels operationId: disableV3PlatformMaasRoceAssignment summary: Disable a v3 MAAS RoCE assignment parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/MaasSiteIdPath" - name: assignment_id in: path required: true schema: type: string format: uuid requestBody: required: false content: application/json: schema: "$ref": "#/components/schemas/AdminSetMaasRoceAssignmentStatusRequest" responses: '200': description: MAAS site RoCE assignment disabled content: application/json: schema: "$ref": "#/components/schemas/MaasRoceAssignment" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/platform/lifecycle/reconciliation/status": get: tags: - V3ReadModels operationId: getV3PlatformMaasReconciliationStatus summary: Get v3 MAAS reconciliation status parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: MAAS reconciliation summary content: application/json: schema: "$ref": "#/components/schemas/MaasReconciliationStatus" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/lifecycle/reconciliation/drift": get: tags: - V3ReadModels operationId: listV3PlatformMaasDrift summary: List v3 MAAS reconciliation drift parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: site_id in: query schema: type: string format: uuid - name: search in: query description: Search host, hostname, node id, MAAS system id, MAAS status, power state, IPs, or drift details. schema: type: string - name: time_range in: query description: Optional time window for last reconciled or resolved drift rows. schema: type: string enum: - 6h - 12h - 24h - 7d - custom - name: from in: query description: Inclusive RFC3339 lower bound when time_range=custom. schema: type: string format: date-time - name: to in: query description: Inclusive RFC3339 upper bound when time_range=custom. schema: type: string format: date-time - name: sort in: query schema: type: string default: node_id_asc enum: - node_id_asc - node_id_desc - last_reconciled_at_desc - last_reconciled_at_asc - hostname_asc - hostname_desc - rule_asc - rule_desc - name: format in: query schema: type: string default: json enum: - json - csv responses: '200': description: MAAS reconciliation drift records content: application/json: schema: "$ref": "#/components/schemas/MaasDriftListResponse" text/csv: schema: type: string '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/lifecycle/onboardings": get: tags: - V3ReadModels operationId: listV3PlatformMaasOnboardings summary: List v3 MAAS onboarding workflow runs parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: site_id in: query schema: type: string format: uuid - name: batch_id in: query schema: type: string - name: status in: query schema: type: string - name: search in: query schema: type: string description: Search hostname, onboarding id, node id, MAAS system id, SKU, or IPMI IP. - name: time_range in: query schema: type: string enum: - 6h - 12h - 24h - 7d - custom description: Requested-at time window. Use custom with from and/or to. - name: from in: query schema: type: string format: date-time - name: to in: query schema: type: string format: date-time - name: sort in: query schema: type: string enum: - requested_at_desc - requested_at_asc - updated_at_desc - updated_at_asc - status_asc - status_desc - hostname_asc - hostname_desc default: requested_at_desc - name: format in: query schema: type: string enum: - json - csv default: json responses: '200': description: MAAS onboarding workflow runs content: application/json: schema: "$ref": "#/components/schemas/MaasOnboardingListResponse" text/csv: schema: type: string '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/lifecycle/decommissions": get: tags: - V3ReadModels operationId: listV3PlatformMaasDecommissions summary: List v3 MAAS decommission workflow runs parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: site_id in: query schema: type: string format: uuid - name: node_id in: query schema: type: string - name: status in: query schema: type: string - name: search in: query schema: type: string description: Search host, hostname, node id, decommission id, MAAS system id, or management IP. - name: time_range in: query schema: type: string enum: - 6h - 12h - 24h - 7d - custom description: Requested-at time window. Use custom with from and/or to. - name: from in: query schema: type: string format: date-time - name: to in: query schema: type: string format: date-time - name: sort in: query schema: type: string enum: - requested_at_desc - requested_at_asc - updated_at_desc - updated_at_asc - status_asc - status_desc - hostname_asc - hostname_desc default: requested_at_desc - name: format in: query schema: type: string enum: - json - csv default: json responses: '200': description: MAAS decommission workflow runs content: application/json: schema: "$ref": "#/components/schemas/MaasDecommissionListResponse" text/csv: schema: type: string '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/lifecycle/onboarding": get: tags: - V3ReadModels operationId: getV3PlatformOnboardingGuidance summary: Get v3 platform node onboarding guidance read model description: Guidance-first node onboarding contract for site/profile selection, bootstrap readiness, manual fallback command shape, progress steps, and future automated MAAS mutation readiness. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: V3 platform node onboarding guidance headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformOnboardingGuidanceResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/lifecycle/nodes/{node_id}": get: tags: - V3ReadModels operationId: getV3PlatformNodeDetail summary: Get v3 platform node detail read model description: Temporary v3 migration read model for one node's lifecycle, MAAS, agent, slot, allocation, and task posture. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: V3 platform node detail headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformNodeDetailResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" delete: tags: - V3ReadModels operationId: retireV3PlatformNode summary: Retire a v3 platform node parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '204': description: Node retired '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/lifecycle/nodes/{node_id}/cordon": post: tags: - V3ReadModels operationId: cordonV3PlatformNode summary: Cordon a platform node description: Stops new scheduling onto an active node while preserving running workloads. Requires platform admin permission and Idempotency-Key. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Node cordoned content: application/json: schema: "$ref": "#/components/schemas/V3PlatformNodeLifecycleMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/lifecycle/nodes/{node_id}/drain": post: tags: - V3ReadModels operationId: drainV3PlatformNode summary: Drain a platform node description: Cordons an active or cordoned node and queues the node.drain lifecycle task. Requires platform admin permission and Idempotency-Key. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '202': description: Node drain queued content: application/json: schema: "$ref": "#/components/schemas/V3PlatformNodeLifecycleMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/lifecycle/nodes/{node_id}/resume-scheduling": post: tags: - V3ReadModels operationId: resumeSchedulingV3PlatformNode summary: Resume scheduling for a cordoned platform node description: Returns a cordoned node to the active scheduler pool. Requires platform admin permission and Idempotency-Key. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Node scheduling resumed content: application/json: schema: "$ref": "#/components/schemas/V3PlatformNodeLifecycleMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/lifecycle/nodes/{node_id}/refresh-inventory": post: tags: - V3ReadModels operationId: refreshInventoryV3PlatformNode summary: Refresh node inventory description: Queues slice topology discovery for GPU, slot, and hardware inventory refresh. Requires platform admin permission and Idempotency-Key. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '202': description: Inventory refresh queued content: application/json: schema: "$ref": "#/components/schemas/V3PlatformNodeLifecycleMutationResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/lifecycle/nodes/{node_id}/resource-slots": get: tags: - V3ReadModels operationId: listV3PlatformNodeResourceSlots summary: List v3 platform node resource slots parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Node resource slots content: application/json: schema: "$ref": "#/components/schemas/NodeResourceSlotListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" put: tags: - V3ReadModels operationId: upsertV3PlatformNodeResourceSlots summary: Upsert v3 platform node resource slots parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminUpsertNodeResourceSlotsRequest" responses: '200': description: Upserted node resource slots content: application/json: schema: "$ref": "#/components/schemas/NodeResourceSlotListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/platform/lifecycle/nodes/{node_id}/slice-topology/discovery": get: tags: - V3ReadModels operationId: getV3PlatformNodeSliceTopologyDiscovery summary: Get v3 platform node slice topology discovery parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Latest topology discovery task, or null when none has run content: application/json: schema: "$ref": "#/components/schemas/NodeSliceTopologyDiscoveryResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3ReadModels operationId: startV3PlatformNodeSliceTopologyDiscovery summary: Queue v3 platform node slice topology discovery parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '202': description: Discovery task queued or already in progress content: application/json: schema: "$ref": "#/components/schemas/NodeSliceTopologyDiscoveryResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/lifecycle/nodes/{node_id}/probe": post: tags: - V3ReadModels operationId: probeV3PlatformNode summary: Probe a v3 platform node parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Probed content: application/json: schema: type: object additionalProperties: false properties: ok: type: boolean status: type: string enum: - active - offline required: - ok - status '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/platform/lifecycle/nodes/{node_id}/reissue-enrollment": post: tags: - V3ReadModels operationId: reissueV3PlatformNodeEnrollment summary: Reissue v3 platform node enrollment material parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '201': description: Re-enrollment material created content: application/json: schema: "$ref": "#/components/schemas/AdminNodeReenrollmentResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/platform/lifecycle/nodes/{node_id}/bootstrap-script": post: tags: - V3ReadModels operationId: createV3PlatformNodeBootstrapScript summary: Create v3 platform node bootstrap material parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" - name: mode in: query schema: type: string enum: - manual - cloud_init default: manual - name: runtime_api_url in: query schema: type: string format: uri description: Optional provider-reachable runtime control-plane base URL installed as GPUAAS_API_URL. If omitted, the environment default NODE_BOOTSTRAP_API_URL is used. - name: terminal_api_url in: query schema: type: string format: uri description: Optional provider-reachable terminal node-stream base URL installed as GPUAAS_TERMINAL_API_URL. If omitted, the environment default NODE_BOOTSTRAP_TERMINAL_API_URL is used. responses: '201': description: Bootstrap script created content: application/json: schema: "$ref": "#/components/schemas/AdminNodeBootstrapScriptResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '503': "$ref": "#/components/responses/ServiceUnavailable" "/api/v1/platform/lifecycle/nodes/{node_id}/agent-lifecycle": get: tags: - V3ReadModels operationId: getV3PlatformNodeAgentLifecycle summary: Get v3 platform node-agent lifecycle state parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Current node-agent lifecycle state content: application/json: schema: type: object additionalProperties: false properties: node_id: type: string format: uuid state: "$ref": "#/components/schemas/NodeAgentLifecycleState" latest_run: allOf: - "$ref": "#/components/schemas/NodeAgentLifecycleRun" nullable: true required: - node_id - state '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3ReadModels operationId: startV3PlatformNodeAgentLifecycle summary: Start a v3 platform node-agent lifecycle run parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminStartNodeAgentLifecycleRequest" responses: '202': description: Node-agent lifecycle accepted content: application/json: schema: "$ref": "#/components/schemas/AdminStartNodeAgentLifecycleResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/lifecycle/nodes/{node_id}/reactivate": post: tags: - V3ReadModels operationId: reactivateV3PlatformNode summary: Reactivate a retired v3 platform node parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Node reactivated content: application/json: schema: type: object additionalProperties: false properties: ok: type: boolean status: type: string required: - ok - status '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/lifecycle/nodes/{node_id}/resume-lifecycle": post: tags: - V3ReadModels operationId: resumeV3PlatformNodeLifecycle summary: Resume a v3 platform node lifecycle transition parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '200': description: Node lifecycle resume accepted content: application/json: schema: "$ref": "#/components/schemas/AdminResumeNodeLifecycleResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/lifecycle/nodes/{node_id}/remove": delete: tags: - V3ReadModels operationId: removeV3PlatformNode summary: Permanently remove a retired v3 platform node parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '204': description: Node removal started '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/lifecycle/nodes/{node_id}/detach": delete: tags: - V3ReadModels operationId: detachV3PlatformNode summary: Detach a retired v3 platform node from GPUaaS only parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '204': description: Node detached from GPUaaS '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/lifecycle/nodes/{node_id}/force-detach": delete: tags: - V3ReadModels operationId: forceDetachV3PlatformNode summary: Force-detach a stuck v3 platform node from GPUaaS only parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/NodeIdPath" responses: '204': description: Node force-detached from GPUaaS '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/config/setup": get: tags: - V3ReadModels operationId: getV3PlatformSetupChecklist summary: Get v3 platform setup checklist read model description: Operator first-run readiness checklist covering identity/PKI, registry, MAAS provisioning, node-agent posture, runtime inventory, telemetry, network/security placeholders, and storage provider posture. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: V3 platform setup checklist headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformSetupChecklistResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/config": get: tags: - V3ReadModels operationId: getV3PlatformConfig summary: Get v3 platform configuration read model description: Temporary v3 migration read model for SKU, OS image, quota, MAAS profile, and policy posture. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: V3 platform config headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformConfigResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/evidence": get: tags: - V3ReadModels operationId: getV3PlatformEvidence summary: Get v3 platform evidence read model description: Temporary v3 migration read model for audit and investigation pivots. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: V3 platform evidence headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformEvidenceResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/evidence/bundles": get: tags: - V3ReadModels operationId: listV3PlatformEvidenceBundles summary: List platform release and UAT evidence bundles description: Platform-owned read model for release, UAT, security, guard, and operator evidence bundles. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: environment_profile in: query required: false schema: type: string - name: product_scope in: query required: false schema: type: string - name: gate_state in: query required: false schema: type: string enum: - pass - fail - partial - blocked - missing responses: '200': description: Platform evidence bundles content: application/json: schema: "$ref": "#/components/schemas/V3PlatformEvidenceBundleListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - V3ReadModels operationId: createV3PlatformEvidenceBundle summary: Create a platform evidence bundle description: Creates a platform-owned evidence bundle from release, UAT, security, CI, and guard report inputs. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateV3PlatformEvidenceBundleRequest" responses: '201': description: Platform evidence bundle created content: application/json: schema: "$ref": "#/components/schemas/V3PlatformEvidenceBundleDetailResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/evidence/bundles/{bundle_id}": get: tags: - V3ReadModels operationId: getV3PlatformEvidenceBundle summary: Get platform evidence bundle detail parameters: - "$ref": "#/components/parameters/XRequestId" - name: bundle_id in: path required: true schema: type: string format: uuid responses: '200': description: Platform evidence bundle detail content: application/json: schema: "$ref": "#/components/schemas/V3PlatformEvidenceBundleDetailResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/platform/evidence/bundles/{bundle_id}/items": post: tags: - V3ReadModels operationId: recordV3PlatformEvidenceItem summary: Attach an evidence item to a platform evidence bundle parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: bundle_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateV3PlatformEvidenceItemRequest" responses: '201': description: Evidence item attached content: application/json: schema: "$ref": "#/components/schemas/V3PlatformEvidenceItem" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/evidence/audit": get: tags: - V3ReadModels operationId: listV3PlatformEvidenceAuditLogs summary: List v3 platform audit evidence rows description: Platform evidence audit drawer feed. This is the V3 platform-owned alias for platform audit-log review and supports the same filters as the frozen admin audit list while the broader user/project/tenant evidence ownership is migrated. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - "$ref": "#/components/parameters/AuditLogSort" - name: actor_user_id in: query required: false schema: type: string format: uuid - name: actor_role in: query required: false style: form explode: true schema: type: array items: type: string - name: action in: query required: false style: form explode: true schema: type: array items: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: V3 platform audit evidence rows content: application/json: schema: "$ref": "#/components/schemas/AuditLogListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/status/public": get: tags: - V3ReadModels operationId: getV3PlatformPublicStatus summary: Get customer-safe platform status description: Public platform health projection for authenticated users. Omits internal component details, artifact paths, gate item IDs, and raw SLO values. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string responses: '200': description: Customer-safe platform status content: application/json: schema: "$ref": "#/components/schemas/V3PlatformPublicStatusResponse" '401': "$ref": "#/components/responses/Unauthorized" "/api/v1/platform/status/readiness": get: tags: - V3ReadModels operationId: getV3PlatformStatusReadiness summary: Get platform readiness status description: Environment/profile readiness read model backed by evidence freshness, release gates, guard reports, incidents, and capacity posture. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: product_scope in: query required: false schema: type: string responses: '200': description: Platform readiness status content: application/json: schema: "$ref": "#/components/schemas/V3PlatformStatusReadinessResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/status/components": get: tags: - V3ReadModels operationId: listV3PlatformStatusComponents summary: List platform component status parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: component_type in: query required: false schema: type: string - name: status in: query required: false schema: type: string enum: - healthy - degraded - unhealthy - unknown - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Platform component status content: application/json: schema: "$ref": "#/components/schemas/V3PlatformComponentStatusListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/status/node-trust": get: tags: - V3ReadModels operationId: listV3PlatformStatusNodeTrust summary: List node trust posture description: Sanitized node-trust read model backed by Status/Ops component rows. Exposes certificate expiry, renewal and recovery posture, verifier versions, endpoint profile, diagnostic freshness, and quarantine reason without secret material. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: node_id in: query required: false schema: type: string - name: status in: query required: false schema: type: string enum: - healthy - degraded - unhealthy - unknown - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Node trust posture content: application/json: schema: "$ref": "#/components/schemas/V3PlatformNodeTrustPostureListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/status/guards": get: tags: - V3ReadModels operationId: getV3PlatformStatusGuards summary: Get latest platform-foundation guard report summary parameters: - "$ref": "#/components/parameters/XRequestId" - name: guard_id in: query required: false schema: type: string - name: mode in: query required: false schema: type: string enum: - report_only - warning - blocking - blocking_new - blocking_all - name: source_commit in: query required: false schema: type: string - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Platform guard status content: application/json: schema: "$ref": "#/components/schemas/V3PlatformGuardStatusResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/status/breakglass": get: tags: - V3ReadModels operationId: listV3PlatformStatusBreakglass summary: List platform break-glass evidence description: Read-only Status/Ops projection of break-glass activation, approval, expiry, revocation, use-log, and post-use review evidence derived from platform audit metadata. This endpoint never exposes credentials, secret material, or provider tokens. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: stage in: query required: false schema: "$ref": "#/components/schemas/V3PlatformBreakglassEvidenceStage" - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Platform break-glass evidence content: application/json: schema: "$ref": "#/components/schemas/V3PlatformBreakglassEvidenceListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/evidence/audit/export": get: tags: - V3ReadModels operationId: exportV3PlatformEvidenceAuditLogs summary: Export filtered v3 platform audit evidence rows description: Backend-owned export for platform Evidence. Export honors the same authorization scope, filters, time range, and sort as the platform audit evidence list. JSON includes sanitized presentation fields; CSV is intended for operator review and compliance handoff. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/AuditLogSort" - name: format in: query required: false schema: type: string enum: - csv - json default: csv - name: actor_user_id in: query required: false schema: type: string format: uuid - name: actor_role in: query required: false style: form explode: true schema: type: array items: type: string - name: action in: query required: false style: form explode: true schema: type: array items: type: string - name: target_type in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time responses: '200': description: Filtered platform audit evidence export content: text/csv: schema: type: string format: binary application/json: schema: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/AuditLogEntry" export: type: object additionalProperties: false properties: format: type: string enum: - json count: type: integer minimum: 0 sort: type: string required: - format - count - sort required: - items - export '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/workflows": get: tags: - V3ReadModels operationId: listV3PlatformTemporalWorkflows summary: Search platform workflow records description: Read-only platform workflow search backed by persisted product/platform records and safe workflow metadata. The initial implementation does not query live Temporal Search Attributes and rejects broad unfiltered searches. parameters: - "$ref": "#/components/parameters/XRequestId" - name: family in: query required: false schema: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowFamily" - name: status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowStatus" - name: workflow_id in: query required: false schema: type: string - name: workflow_run_id in: query required: false schema: type: string - name: org_id in: query required: false schema: type: string format: uuid - name: project_id in: query required: false schema: type: string format: uuid - name: allocation_id in: query required: false schema: type: string format: uuid - name: node_id in: query required: false schema: type: string - name: actor_user_id in: query required: false schema: type: string format: uuid - name: correlation_id in: query required: false schema: type: string - name: time_range in: query required: false schema: type: string enum: - 6h - 12h - 24h - 7d - custom - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Platform workflow search results content: application/json: schema: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowSearchResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/workflows/{workflow_id}/retry-history": get: tags: - V3ReadModels operationId: getV3PlatformTemporalWorkflowRetryHistory summary: Get platform workflow retry history description: Returns safe retry/resume/rerun history for a persisted platform workflow. Initial sources are MAAS onboarding/decommission events and node-agent lifecycle records; raw Temporal payloads are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: workflow_id in: path required: true schema: type: string - name: workflow_run_id in: query required: false schema: type: string - name: family in: query required: false schema: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowFamily" - name: include_superseded in: query required: false schema: type: boolean default: true - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Platform workflow retry history content: application/json: schema: "$ref": "#/components/schemas/V3PlatformTemporalRetryHistoryResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/platform/workflow-schedules": get: tags: - V3ReadModels operationId: listV3PlatformWorkflowSchedules summary: List platform workflow schedule status description: Returns operator-safe status for scheduled workflow automation. Initial source is the MAAS reconciliation Temporal schedule status already exposed through the API server Temporal adapter; raw workflow payloads are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: family in: query required: false schema: type: string enum: - maas_reconciliation - name: status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformTemporalScheduleStatus" - name: include_disabled in: query required: false schema: type: boolean default: true - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Platform workflow schedule status rows content: application/json: schema: "$ref": "#/components/schemas/V3PlatformWorkflowSchedulesResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/workflow-activities/stuck": get: tags: - V3ReadModels operationId: listV3PlatformStuckWorkflowActivities summary: List stuck or retrying platform workflow activities description: Returns operator-safe diagnostics for workflows that appear stuck, retrying, waiting, or failed. Initial sources are MAAS onboarding and decommission product records; raw Temporal activity payloads are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: family in: query required: false schema: "$ref": "#/components/schemas/V3PlatformTemporalWorkflowFamily" - name: status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformTemporalStuckActivityStatus" - name: owner_domain in: query required: false schema: type: string - name: workflow_id in: query required: false schema: type: string - name: workflow_run_id in: query required: false schema: type: string - name: min_age_seconds in: query required: false schema: type: integer minimum: 0 - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Stuck workflow activity diagnostics content: application/json: schema: "$ref": "#/components/schemas/V3PlatformTemporalStuckActivitiesResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops/observability/health-snapshot": get: tags: - V3ReadModels operationId: getV3PlatformObservabilityHealthSnapshot summary: Get platform observability health snapshot description: Returns an operator-safe platform health snapshot before direct Grafana, Prometheus, Loki, or Tempo pivots. Raw telemetry samples, logs, traces, and payloads are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: component_type in: query required: false schema: "$ref": "#/components/schemas/V3PlatformObservabilityComponentType" - name: status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformObservabilityHealthStatus" - name: include_evidence in: query required: false schema: type: boolean default: true - name: include_prometheus_queries in: query required: false schema: type: boolean default: false responses: '200': description: Platform observability health snapshot content: application/json: schema: "$ref": "#/components/schemas/V3PlatformObservabilityHealthSnapshotResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops/observability/correlation-timeline": get: tags: - V3ReadModels operationId: getV3PlatformObservabilityCorrelationTimeline summary: Get platform observability correlation timeline description: Returns an operator-safe timeline across audit rows, evidence items, domain events, and workflow records for a narrowed correlation pivot. Raw logs, trace spans, workflow payloads, tokens, stack traces, and runtime payloads are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: correlation_id in: query required: false schema: type: string - name: request_id in: query required: false schema: type: string - name: trace_id in: query required: false schema: type: string - name: workflow_id in: query required: false schema: type: string - name: workflow_run_id in: query required: false schema: type: string - name: task_id in: query required: false schema: type: string - name: event_id in: query required: false schema: type: string - name: target_type in: query required: false schema: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineTargetType" - name: target_id in: query required: false schema: type: string - name: time_range in: query required: false schema: type: string enum: - 1h - 6h - 12h - 24h - 7d - custom - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time - name: source in: query required: false schema: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineSource" - name: include_log_excerpts in: query required: false schema: type: boolean default: false - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Platform observability correlation timeline content: application/json: schema: "$ref": "#/components/schemas/V3PlatformObservabilityCorrelationTimelineResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops/observability/logs": get: tags: - V3ReadModels operationId: listV3PlatformObservabilityLogs summary: List bounded platform observability log summaries description: Returns sanitized log summary pivots from persisted platform evidence, audit, and event records. Broad service-only and time-only browsing is rejected; raw Loki payloads are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: correlation_id in: query schema: type: string - name: request_id in: query schema: type: string - name: trace_id in: query schema: type: string - name: workflow_id in: query schema: type: string - name: task_id in: query schema: type: string - name: event_id in: query schema: type: string - name: target_type in: query schema: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineTargetType" - name: target_id in: query schema: type: string - name: service in: query schema: type: string - name: severity in: query schema: "$ref": "#/components/schemas/V3PlatformObservabilityLogSeverity" - name: time_range in: query schema: type: string enum: - 15m - 1h - 6h - 12h - 24h - custom - name: from in: query schema: type: string format: date-time - name: to in: query schema: type: string format: date-time - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Bounded platform observability log summaries content: application/json: schema: "$ref": "#/components/schemas/V3PlatformObservabilityLogsResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops/observability/traces": get: tags: - V3ReadModels operationId: listV3PlatformObservabilityTraces summary: List bounded platform trace summaries description: Returns sanitized trace summaries from persisted platform evidence, audit, and event trace identifiers. Raw Tempo spans are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: trace_id in: query schema: type: string - name: correlation_id in: query schema: type: string - name: request_id in: query schema: type: string - name: workflow_id in: query schema: type: string - name: task_id in: query schema: type: string - name: target_type in: query schema: "$ref": "#/components/schemas/V3PlatformCorrelationTimelineTargetType" - name: target_id in: query schema: type: string - name: time_range in: query schema: type: string enum: - 15m - 1h - 6h - 12h - 24h - custom - name: from in: query schema: type: string format: date-time - name: to in: query schema: type: string format: date-time - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Bounded platform trace summaries content: application/json: schema: "$ref": "#/components/schemas/V3PlatformObservabilityTracesResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops/observability/alerts": get: tags: - V3ReadModels operationId: listV3PlatformObservabilityAlerts summary: List platform observability alert routing evidence description: Returns operator-safe alert state, route ownership, runbook mapping, and drill freshness evidence. Raw Prometheus samples and notification secrets are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query schema: type: string - name: severity in: query schema: "$ref": "#/components/schemas/V3PlatformObservabilityAlertSeverity" - name: owner_team in: query schema: type: string - name: service in: query schema: type: string - name: domain in: query schema: type: string - name: state in: query schema: "$ref": "#/components/schemas/V3PlatformObservabilityAlertState" - name: runbook_id in: query schema: type: string - name: include_inactive in: query schema: type: boolean default: false - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Platform observability alert routing evidence content: application/json: schema: "$ref": "#/components/schemas/V3PlatformObservabilityAlertsResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops/observability/slo-evidence": get: tags: - V3ReadModels operationId: listV3PlatformObservabilitySLOEvidence summary: List platform observability SLO evidence description: Returns operator-safe SLO/error-budget evidence and release-gate posture. Raw Prometheus samples, Grafana screenshots, and notification secrets are excluded. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query schema: type: string - name: service in: query schema: type: string - name: slo_id in: query schema: type: string - name: time_range in: query schema: type: string enum: - 1h - 6h - 24h - 7d - 30d - custom - name: from in: query schema: type: string format: date-time - name: to in: query schema: type: string format: date-time - name: release_id in: query schema: type: string - name: include_query_outcomes in: query schema: type: boolean default: true - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Platform observability SLO evidence content: application/json: schema: "$ref": "#/components/schemas/V3PlatformObservabilitySLOEvidenceResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/finance": get: tags: - V3ReadModels operationId: getV3PlatformFinance summary: Get v3 platform finance operations read model description: Temporary v3 migration read model for payment-session operations and financial intervention posture. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: V3 platform finance headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformFinanceResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/finance/sessions": get: tags: - V3ReadModels operationId: getV3PlatformFinanceSessions summary: List v3 platform finance payment sessions description: Workbench read model for payment-session triage. Returns backend-owned signal keys and ack fields so clients never derive acknowledgement identity. Requires platform ops read permission. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string - name: user_id in: query required: false schema: type: string format: uuid - name: correlation_id in: query required: false schema: type: string responses: '200': description: V3 platform finance sessions headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformFinanceSessionsResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/finance/sessions/{payment_session_id}": get: tags: - V3ReadModels operationId: getV3PlatformFinanceSessionDetail summary: Get v3 platform finance payment-session detail description: Focused payment-session detail read model with diagnostics, evidence links, and manual recovery operation targets. Provider replay is intentionally not exposed by this slice. parameters: - "$ref": "#/components/parameters/XRequestId" - name: payment_session_id in: path required: true schema: type: string format: uuid responses: '200': description: V3 platform finance session detail headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformFinanceSessionDetailResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/platform/finance/reconciliation": get: tags: - V3PlatformFinance operationId: listV3PlatformFinanceReconciliation summary: List billing reconciliation runs through the V3 finance boundary description: Lists usage-ledger reconciliation posture and recent runs for the operator finance workbench. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: format in: query required: false schema: type: string enum: - json - csv default: json - name: status in: query required: false style: form explode: true schema: type: array items: type: string enum: - running - completed - failed - name: time_range in: query required: false schema: type: string enum: - 6h - 12h - 24h - 7d - custom - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time - name: sort in: query required: false schema: type: string enum: - created_at_desc - created_at_asc - checked_at_desc - checked_at_asc - status_asc - status_desc default: created_at_desc - name: search in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string responses: '200': description: V3 finance billing reconciliation posture content: application/json: schema: "$ref": "#/components/schemas/BillingReconciliationListResponse" text/csv: schema: type: string format: binary '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" post: tags: - V3PlatformFinance operationId: runV3PlatformFinanceReconciliation summary: Run usage-ledger reconciliation through the V3 finance boundary description: Starts an audited, idempotent reconciliation run for finance operators. Ledger corrections remain append-only and are not performed directly by this read-model action. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" responses: '202': description: V3 finance billing reconciliation completed and recorded content: application/json: schema: "$ref": "#/components/schemas/BillingReconciliationRun" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/finance/reconciliation/{job_id}": get: tags: - V3PlatformFinance operationId: getV3PlatformFinanceReconciliation summary: Get a billing reconciliation run through the V3 finance boundary parameters: - "$ref": "#/components/parameters/XRequestId" - name: job_id in: path required: true schema: type: string format: uuid responses: '200': description: V3 finance billing reconciliation run content: application/json: schema: "$ref": "#/components/schemas/BillingReconciliationRun" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/platform/finance/diagnostics": get: tags: - V3PlatformFinance operationId: getV3PlatformFinanceDiagnostics summary: Fetch billing evidence by correlation id through the V3 finance boundary parameters: - "$ref": "#/components/parameters/XRequestId" - name: correlation_id in: query required: true schema: type: string responses: '200': description: V3 finance billing diagnostic evidence content: application/json: schema: "$ref": "#/components/schemas/BillingDiagnosticsResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/finance/users/{user_id}/refunds": get: tags: - V3PlatformFinance operationId: listV3PlatformFinanceUserRefunds summary: List refund workflows for a user through the V3 finance boundary description: Lists refund workflow rows for a user. This is an actionable workflow surface; usage and ledger rows remain immutable read-only records. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/UserIdPath" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: status in: query required: false schema: type: string enum: - accepted - completed - failed - name: correlation_id in: query required: false schema: type: string - name: time_range in: query required: false description: Relative time window applied to refund created_at. Use `custom` with `from` and/or `to` for explicit windows. schema: type: string enum: - 6h - 12h - 24h - 7d - custom - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time - name: sort in: query required: false schema: type: string enum: - id_asc - id_desc - created_at_desc - created_at_asc - updated_at_desc - updated_at_asc - status_asc - status_desc - amount_desc - amount_asc default: id_asc - name: format in: query required: false schema: type: string enum: - json - csv default: json responses: '200': description: V3 finance user refund workflows content: application/json: schema: "$ref": "#/components/schemas/RefundListResponse" text/csv: schema: type: string '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" post: tags: - V3PlatformFinance operationId: createV3PlatformFinanceUserRefund summary: Create a ledger-safe refund workflow for a user description: Creates an audited refund workflow. This endpoint does not mutate ledger rows directly; any ledger correction remains append-only and owned by the finance service boundary. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - "$ref": "#/components/parameters/UserIdPath" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminCreateRefundRequest" responses: '201': description: V3 finance refund workflow created content: application/json: schema: "$ref": "#/components/schemas/AdminCreateRefundResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/finance/payment-sessions": get: tags: - V3PlatformFinance operationId: listV3PlatformFinancePaymentSessionsRaw summary: List raw payment sessions for V3 finance operators description: Raw payment-session support list for reconciliation workflows. Prefer `/api/v1/platform/finance/sessions` for the operator workbench read model. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: user_id in: query required: false schema: type: string format: uuid - name: status in: query required: false schema: type: string enum: - initiated - checkout_completed - credited - failed_reconcile - expired - name: correlation_id in: query required: false schema: type: string - name: time_range in: query required: false description: Relative time window applied to payment-session created_at. Use `custom` with `from` and/or `to` for explicit windows. schema: type: string enum: - 6h - 12h - 24h - 7d - custom - name: from in: query required: false schema: type: string format: date-time - name: to in: query required: false schema: type: string format: date-time - name: sort in: query required: false schema: type: string enum: - id_asc - id_desc - created_at_desc - created_at_asc - initiated_at_desc - initiated_at_asc - status_asc - status_desc - requested_amount_desc - requested_amount_asc - credited_amount_desc - credited_amount_asc default: id_asc - name: format in: query required: false schema: type: string enum: - json - csv default: json responses: '200': description: V3 finance raw payment sessions content: application/json: schema: type: object additionalProperties: false properties: items: type: array items: "$ref": "#/components/schemas/PaymentSession" pagination: "$ref": "#/components/schemas/Pagination" required: - items - pagination text/csv: schema: type: string '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/finance/payment-sessions/{payment_session_id}": get: tags: - V3PlatformFinance operationId: getV3PlatformFinancePaymentSessionRaw summary: Get a raw payment session for V3 finance operators parameters: - "$ref": "#/components/parameters/XRequestId" - name: payment_session_id in: path required: true schema: type: string format: uuid responses: '200': description: V3 finance raw payment session content: application/json: schema: "$ref": "#/components/schemas/PaymentSession" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/api/v1/platform/finance/payment-sessions/{payment_session_id}/reconcile": post: tags: - V3PlatformFinance operationId: reconcileV3PlatformFinancePaymentSession summary: Reconcile a payment session through a ledger-safe V3 finance action description: Reconciles a stuck or failed payment session. `post_credit` appends an immutable ledger entry and marks the session credited; state-only actions mark expired or failed with an audited operator reason. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" - name: payment_session_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/AdminReconcilePaymentSessionRequest" responses: '200': description: V3 finance payment session reconciled content: application/json: schema: "$ref": "#/components/schemas/PaymentSession" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" "/api/v1/platform/iam": get: tags: - V3ReadModels operationId: getV3PlatformIAM summary: Get v3 platform IAM read model description: Temporary v3 migration read model for users and platform role posture. Requires platform ops read permission. x-v3-read-model-gaps: - user rows need last activity, tenant/project context, status or risk, balance posture, evidence pivots, server-side sort, and scoped export. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" - name: search in: query required: false schema: type: string description: Search users by id, username, tenant id, project id, or role. - name: format in: query required: false schema: type: string enum: - json - csv default: json description: Return the filtered list as JSON or CSV. - name: platform_role in: query required: false schema: type: string enum: - any - platform_admin - platform_ops - platform_user - platform_superadmin description: Filter users by platform role. `any` returns users with any platform role binding or legacy admin posture. - name: role in: query required: false schema: type: string enum: - admin - user description: Filter by legacy account role while platform role bindings are migrated. - name: tenant_id in: query required: false schema: type: string format: uuid description: Filter users by home tenant or tenant role binding. - name: project_id in: query required: false schema: type: string format: uuid description: Filter users by project role binding. - name: posture in: query required: false schema: type: string enum: - privileged - stale - local_password - oidc - missing_tenant description: Filter users by backend-computed IAM posture. - name: review in: query required: false schema: type: string enum: - stale_identity description: Filter users into a governance review queue using backend-owned identity posture signals available in the read model. - name: sort in: query required: false schema: type: string enum: - username_asc - username_desc - role_asc - role_desc - last_activity_desc - last_activity_asc - created_at_desc - created_at_asc default: username_asc description: Stable server-side sort for cursor pagination. responses: '200': description: V3 platform IAM headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformIAMResponse" text/csv: schema: type: string '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/iam/mfa-readiness": get: tags: - V3ReadModels operationId: getV3PlatformIAMMFAReadiness summary: Get v3 platform IAM MFA readiness read model description: Read-only operator readiness model for MFA product-complete posture. This endpoint must not query Keycloak or any identity provider per request, must not mutate IAM state, and must treat unknown, pending, stale, provider_unqueried, and error states as non-compliant/fail-closed. parameters: - "$ref": "#/components/parameters/XRequestId" responses: '200': description: V3 platform IAM MFA readiness headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3PlatformIAMMFAReadinessResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/edge/routes": get: tags: - V3ReadModels operationId: listV3PlatformEdgeRoutes summary: List provider-neutral edge route readiness description: Read-only platform operations model for DNS, TLS, Pomerium, ingress or tunnel, upstream, smoke evidence freshness, and operator next action across supported edge profiles. The response is provider-neutral and must not expose Cloudflare-native payloads, DNS provider records, tunnel credentials, tokens, or mutable provider operations. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: edge_profile in: query required: false schema: "$ref": "#/components/schemas/V3PlatformEdgeProfile" - name: route_family in: query required: false schema: "$ref": "#/components/schemas/V3PlatformEdgeRouteFamily" - name: status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformEdgeReadinessStatus" - name: stale_only in: query required: false schema: type: boolean default: false - name: search in: query required: false schema: type: string maxLength: 160 - "$ref": "#/components/parameters/Cursor" - "$ref": "#/components/parameters/PageSize" responses: '200': description: Provider-neutral edge route readiness content: application/json: schema: "$ref": "#/components/schemas/V3PlatformEdgeRouteListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/status/devsecops/metrics": get: tags: - V3ReadModels operationId: listV3PlatformDevSecOpsMetrics summary: List DevSecOps control metrics description: Paginated platform Status/Ops read model for DevSecOps control posture, stale evidence, release gates, scan enforcement, supply-chain coverage, and escape-rate classification. This is a projection over evidence/status sources, not a parallel security metrics store. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: product_scope in: query required: false schema: type: string - name: family in: query required: false schema: "$ref": "#/components/schemas/V3DevSecOpsMetricFamily" - name: state in: query required: false schema: "$ref": "#/components/schemas/V3DevSecOpsMetricState" - name: owner in: query required: false schema: type: string - name: release_branch in: query required: false schema: type: string - name: source_commit in: query required: false schema: type: string - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: DevSecOps control metrics content: application/json: schema: "$ref": "#/components/schemas/V3DevSecOpsMetricListResponse" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops/secrets-pki/certificates": get: tags: - V3ReadModels operationId: listV3PlatformOpsSecretsPKICertificates summary: List Secrets/PKI certificate lifecycle posture description: Read-only metadata projection for internal certificate expiry, renewal, revocation, issuer, subject class, owner domain, and evidence links. Requires platform ops read permission. The response never includes private keys, CSR private material, raw key PEM, CA private material, or secret-manager values. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: purpose_id in: query required: false schema: type: string - name: subject_class in: query required: false schema: "$ref": "#/components/schemas/V3CertificateSubjectClass" - name: issuer in: query required: false schema: type: string - name: owner_domain in: query required: false schema: type: string - name: renewal_status in: query required: false schema: "$ref": "#/components/schemas/V3CertificateRenewalStatus" - name: revocation_status in: query required: false schema: "$ref": "#/components/schemas/V3CertificateRevocationStatus" - name: node_id in: query required: false schema: type: string format: uuid - name: worker_id in: query required: false schema: type: string - "$ref": "#/components/parameters/Cursor" - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 200 responses: '200': description: Secrets/PKI certificate lifecycle posture headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3SecretsPKICertificateLifecycleResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops/registry/pull-diagnosis": get: tags: - V3ReadModels operationId: listV3PlatformOpsRegistryPullDiagnosis summary: List registry pull failure diagnoses description: Read-only, metadata-only registry pull diagnosis projection for artifact, node, workload, credential-purpose, and evidence links. Requires platform ops read permission and at least one narrowing filter. The response never includes registry passwords, bearer tokens, refresh tokens, private keys, raw Vault payloads, credential environment variables, or raw node-agent logs. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: node_id in: query required: false schema: type: string format: uuid - name: node_name in: query required: false schema: type: string - name: allocation_id in: query required: false schema: type: string format: uuid - name: workload_id in: query required: false schema: type: string - name: app_slug in: query required: false schema: type: string - name: app_version in: query required: false schema: type: string - name: artifact_id in: query required: false schema: type: string - name: artifact_name in: query required: false schema: type: string - name: artifact_ref in: query required: false schema: type: string - name: digest in: query required: false schema: type: string - name: task_id in: query required: false schema: type: string - name: workflow_id in: query required: false schema: type: string - name: correlation_id in: query required: false schema: type: string - name: error_class in: query required: false schema: "$ref": "#/components/schemas/V3RegistryPullErrorClass" - "$ref": "#/components/parameters/Cursor" - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 200 responses: '200': description: Registry pull failure diagnosis metadata headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3RegistryPullDiagnosisResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops/secrets-pki/vault-readiness": get: tags: - V3ReadModels operationId: listV3PlatformSecretsPKIVaultReadiness summary: List Vault readiness evidence description: Sanitized Secrets/PKI Vault readiness read model for operator review. The response exposes initialized, sealed, mount, policy, read-check, deploy preflight, evidence-link, and next-action status only. It never returns root tokens, unseal keys, operational tokens, AppRole material, wrapped tokens, registry passwords, private keys, raw Vault responses, or secret values. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: cluster_id in: query required: false schema: type: string - name: mount in: query required: false schema: type: string - name: purpose_id in: query required: false schema: type: string - name: status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformVaultReadinessStatus" - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Vault readiness evidence content: application/json: schema: "$ref": "#/components/schemas/V3PlatformVaultReadinessListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops/secrets-pki/rotation-evidence": get: tags: - V3ReadModels operationId: listV3PlatformSecretsPKIRotationEvidence summary: List Secrets/PKI rotation evidence description: Sanitized rotation evidence read model for operators. The endpoint reports purpose, actor, approval reference, version references, validation checks, audit action, result, next due date, and evidence links only. It does not execute live rotation and never returns secret values, private keys, raw provider output, Vault tokens, unseal keys, wrapped-token bytes, registry passwords, or one-time credential material. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: purpose_id in: query required: false schema: type: string - name: rotation_id in: query required: false schema: type: string - name: actor_user_id in: query required: false schema: type: string format: uuid - name: rotation_owner in: query required: false schema: type: string enum: - platform_automated - platform_ops - iam_facade - keycloak_admin - stripe_platform - name: result in: query required: false schema: "$ref": "#/components/schemas/V3PlatformRotationEvidenceResult" - name: approval_ref in: query required: false schema: type: string - name: started_after in: query required: false schema: type: string format: date-time - name: completed_before in: query required: false schema: type: string format: date-time - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Secrets/PKI rotation evidence content: application/json: schema: "$ref": "#/components/schemas/V3PlatformRotationEvidenceListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops/secrets-pki/breakglass-evidence": get: tags: - V3ReadModels operationId: listV3PlatformSecretsPKIBreakglassEvidence summary: List Secrets/PKI break-glass evidence description: Sanitized break-glass evidence read model for operators and reviewers. The endpoint reports approval reference, actor, scope, time window, safe action summaries, post-action remediation, audit links, and evidence links only. It does not execute live break-glass, unseal Vault, rotate root tokens, or mutate production secrets. parameters: - "$ref": "#/components/parameters/XRequestId" - name: environment_profile in: query required: false schema: type: string - name: breakglass_id in: query required: false schema: type: string - name: approval_ref in: query required: false schema: type: string - name: actor_user_id in: query required: false schema: type: string format: uuid - name: scope in: query required: false schema: type: string - name: status in: query required: false schema: "$ref": "#/components/schemas/V3PlatformSecretsPKIBreakglassStatus" - name: opened_after in: query required: false schema: type: string format: date-time - name: closed_before in: query required: false schema: type: string format: date-time - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Secrets/PKI break-glass evidence content: application/json: schema: "$ref": "#/components/schemas/V3PlatformSecretsPKIBreakglassEvidenceListResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/ops/secrets-pki/purposes": get: tags: - V3PlatformOps operationId: listV3PlatformSecretsPKIPurposeInventory summary: List secrets PKI purpose inventory description: Platform-ops read model over the shared Secrets/PKI purpose registry. Returns custody, rotation, lifecycle, and runtime trust evidence metadata for each purpose. It never returns raw secret, token, key, Vault, certificate, or provider credential material. Missing runtime trust evidence is classified as unknown or unhealthy, never healthy. parameters: - "$ref": "#/components/parameters/XRequestId" - name: purpose_id in: query required: false schema: type: string - name: owner_product_id in: query required: false schema: type: string - name: material_kind in: query required: false schema: "$ref": "#/components/schemas/V3SecretsPKIMaterialKind" - name: custody_tool in: query required: false schema: "$ref": "#/components/schemas/V3SecretsPKICustodyTool" - name: delivery_mode in: query required: false schema: "$ref": "#/components/schemas/V3SecretsPKIDeliveryMode" - name: rotation_owner in: query required: false schema: "$ref": "#/components/schemas/V3SecretsPKIRotationOwner" - name: evidence_component_id in: query required: false schema: type: string - name: status in: query required: false schema: "$ref": "#/components/schemas/V3SecretsPKIPurposeStatus" - name: environment_profile in: query required: false schema: type: string default: prod - name: cursor in: query required: false schema: type: string - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 25 responses: '200': description: Secrets PKI purpose inventory headers: X-Read-Model-Cache: schema: type: string enum: - hit - miss - bypass - stale content: application/json: schema: "$ref": "#/components/schemas/V3SecretsPKIPurposeInventoryResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/api/v1/platform/iam/mfa/factor-resets": post: tags: - V3ReadModels operationId: createV3PlatformIAMMFAFactorResetRequest summary: Submit an operator MFA factor reset request description: Records an audited support-assisted request to remove a lost factor or force re-enrollment for a target user. This endpoint does not mutate Keycloak or any provider directly; provider execution remains packet-driven and approval-gated. parameters: - "$ref": "#/components/parameters/XRequestId" - "$ref": "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/V3PlatformIAMMFAFactorResetRequest" responses: '202': description: MFA factor reset request submitted content: application/json: schema: "$ref": "#/components/schemas/V3PlatformIAMMFAFactorResetRequestResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" x-notes: secure_key_download: rule: Use Authorization header for key retrieval; do not place auth tokens in query strings. pagination: rule: All V3 list endpoints support cursor/page_size and return a pagination block with next_cursor and page_size. User-facing V3 surfaces must not render unbounded tables by default; if a response is already bounded and complete, the UI may use a documented show-more cap instead of requesting another cursor page. v3_table_query_capability: rule: V3 table query capability is backend-owned for every high-volume or operator-facing table. Durable list/read-model endpoints must expose cursor pagination, bounded page_size, server-side sort, typed search/domain filters, and time range filters when rows are naturally time-scoped. Export is an explicit endpoint-level capability, must reuse the same filters/sort/time range as the table query, and must preserve the owning domain authorization and audit requirements.