Cloud World Model Multi Cloud API

openapi: 3.2.0
info:
  title: Cloudworldmodel Ai Multi Cloud API
  version: 1.0.0
  contact:
    name: Cloud World Model API Support
    url: https://www.cloudworldmodel.ai
    email: api@cloudworldmodel.ai
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  description: 'Operations tagged Multi-Cloud across 2 of this provider''s published API definitions: cloudworldmodel-ai-openapi.json, cloudworldmodel-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://www.cloudworldmodel.ai/api
  description: Production
- url: http://localhost:5000/api
  description: Local development
security: []
tags:
- name: Multi-Cloud
paths:
  /multi-cloud/jobs/{jobId}/verdict:
    post:
      operationId: finalizeMultiCloudVerdict
      summary: Evaluate a candidate with completed resilience evidence
      description: 'Requires an owned completed exploration job. First send strategyId without resilienceEvidence to obtain the candidateFingerprint. Retain it with the actual tested architecture and workload, then submit a completed caller-attested report bound to that fingerprint. This endpoint does not independently verify reports or authenticate them as CWM chaos jobs. Estimated evidence cannot authorize ship. All cost, latency, error-budget and recorded resilience checks must pass. Optional budgets apply only to this evaluation. Read-only, non-persisted computation: subsequent results reads remain unchanged. Supports API keys and wallet-session bearer tokens.'
      tags:
      - Multi-Cloud
      security:
      - BearerAuth: []
      parameters:
      - name: jobId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreProvisionFinalizeRequest'
      responses:
        '200':
          description: Candidate verdict with provenance and explicit reasons.
          content:
            application/json:
              schema:
                type: object
                required:
                - preProvisionVerdict
                properties:
                  preProvisionVerdict:
                    $ref: '#/components/schemas/PreProvisionVerdict'
        '400':
          description: Invalid evidence, fields, or future completion timestamp.
        '401':
          description: Authentication required.
        '403':
          description: Read scope required.
        '404':
          description: Job or candidate not found, or job is not owned by the caller.
        '409':
          description: Job is incomplete or report fingerprint does not match.
        '429':
          description: Rate limit exceeded.
    servers:
    - url: https://www.cloudworldmodel.ai/api
      description: Production
    - url: http://localhost:5000/api
      description: Local development
components:
  schemas:
    PreProvisionVerdict:
      type: object
      description: Conservative machine-readable verdict for the highest-ranked returned strategy. Exploration alone cannot return ship. The verdict endpoint can return ship when cost, latency, error-budget and recorded caller-attested resilience checks all pass. This is a planning decision, not independent verification or a production guarantee.
      required:
      - decision
      - strategy
      - candidateFingerprint
      - reasons
      - evidence
      - uncertainty
      properties:
        decision:
          type: string
          enum:
          - ship
          - hold
          - ship_with_changes
          description: hold means a known supplied budget or latency requirement failed, or no candidate is available. ship_with_changes means the visible checks have no known failure but evidence or explicit budgets are missing. ship requires every required check to pass.
        candidateFingerprint:
          type: string
          nullable: true
          description: SHA-256 identity of the candidate ID, allocations, suggested resources and workload. Retain with test inputs; null when no candidate exists.
        strategy:
          oneOf:
          - $ref: '#/components/schemas/PreProvisionVerdictStrategy'
          - type: 'null'
          description: Strategy evaluated by this verdict; null when no candidate is available.
        reasons:
          type: array
          items:
            type: object
            required:
            - code
            - message
            properties:
              code:
                type: string
                enum:
                - no_candidate_strategy
                - cost_budget_exceeded
                - latency_slo_missed
                - error_budget_exceeded
                - resilience_validation_required
                - resilience_check_failed
                - resilience_evidence_insufficient
                - required_checks_incomplete
                - required_checks_passed
              message:
                type: string
        evidence:
          type: object
          required:
          - cost
          - latency
          - errorRate
          - resilience
          properties:
            cost:
              type: object
              required:
              - estimatedPerHour
              - budgetCheck
              properties:
                estimatedPerHour:
                  type: number
                  nullable: true
                  description: Modeled total cost per hour, including modeled egress.
                budgetCheck:
                  type: string
                  enum:
                  - pass
                  - fail
                  - not_provided
            latency:
              type: object
              required:
              - estimatedP95Ms
              - requirementMs
              - sloCheck
              - headroomPct
              properties:
                estimatedP95Ms:
                  type: number
                  nullable: true
                requirementMs:
                  type: number
                sloCheck:
                  type: string
                  enum:
                  - pass
                  - fail
                  - not_evaluated
                headroomPct:
                  type: number
                  nullable: true
            errorRate:
              type: object
              required:
              - modeledFraction
              - budgetCheck
              properties:
                modeledFraction:
                  type: number
                  nullable: true
                  description: Allocation-count-based modeled proxy, not an observed failure rate.
                budgetCheck:
                  type: string
                  enum:
                  - pass
                  - fail
                  - not_provided
            resilience:
              type: object
              required:
              - status
              - reason
              properties:
                status:
                  type: string
                  enum:
                  - not_evaluated
                  - pass
                  - fail
                reason:
                  type: string
                provenance:
                  type: string
                  enum:
                  - recorded
                  - estimated
                verification:
                  type: string
                  enum:
                  - caller_attested
                report:
                  $ref: '#/components/schemas/CompletedResilienceEvidence'
        uncertainty:
          type: object
          required:
          - dataSource
          - externallyValidated
          - providerRateTrust
          - limitations
          properties:
            dataSource:
              type: string
              enum:
              - simulation-model
            externallyValidated:
              type: boolean
              enum:
              - false
            providerRateTrust:
              type: object
              additionalProperties:
                type: string
                enum:
                - on-demand
                - spot
                - estimated
            limitations:
              type: array
              items:
                type: string
    CompletedResilienceEvidence:
      type: object
      additionalProperties: false
      description: Caller-attested completed test report for the exact candidateFingerprint. Keep the fingerprint with the actual test inputs; never relabel a report from another architecture or workload. Recorded means observations recorded during the test, not externally verified production evidence. Estimated reports remain unevaluated for deployment gating.
      required:
      - candidateFingerprint
      - reportRef
      - status
      - completedAt
      - provenance
      - failureInjected
      - recoveryObserved
      - finalHealthy
      - resilienceCheck
      - scope
      properties:
        candidateFingerprint:
          type: string
          pattern: ^[a-f0-9]{64}$
        reportRef:
          type: string
          minLength: 1
          maxLength: 500
        status:
          type: string
          enum:
          - completed
        completedAt:
          type: string
          format: date-time
          description: Actual completion timestamp, not in the future.
        provenance:
          type: string
          enum:
          - recorded
          - estimated
        failureInjected:
          type: boolean
        recoveryObserved:
          type: boolean
        finalHealthy:
          type: boolean
        resilienceCheck:
          type: string
          enum:
          - pass
          - fail
          - not_evaluated
        scope:
          type: string
          minLength: 1
          maxLength: 2000
          description: Tested failures, test coverage, and pass criteria.
    PreProvisionFinalizeRequest:
      type: object
      additionalProperties: false
      required:
      - strategyId
      properties:
        strategyId:
          type: string
          minLength: 1
          maxLength: 200
        maxCostPerHour:
          type: number
          exclusiveMinimum: 0
          description: Optional explicit hourly cost budget, replacing the exploration budget check for this evaluation only.
        errorBudgetPct:
          type: number
          minimum: 0
          maximum: 100
          description: Optional explicit error budget percentage, replacing the exploration error-budget check for this evaluation only.
        resilienceEvidence:
          $ref: '#/components/schemas/CompletedResilienceEvidence'
    PreProvisionVerdictStrategy:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
        name:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key or Wallet Session JWT
      description: 'API key or wallet-session JWT authentication using Bearer tokens in the Authorization header.


        **How to authenticate:**

        1. Create an API key using POST /api/keys

        2. Include the key in the Authorization header: `Bearer cwm_live_<your_key>`

        3. All RL environment endpoints require authentication


        **Rate Limits:**

        - Default: 1000 requests/hour per key

        - Configurable per key

        - Returns 429 when exceeded

        '
    UiSessionCookie:
      type: apiKey
      in: cookie
      name: cwm_ui_session
      description: 'HttpOnly browser-workspace session cookie issued by

        `POST /api/ui/simulations`. It authorizes UI mutations for simulations

        owned by that browser workspace.

        '
    x402:
      type: apiKey
      in: header
      name: X-PAYMENT
      description: "x402 v2 Base micropayment option. Select the Base entry from\n`GET /api/billing/x402/config` `paymentOptions`, then send its signed USDC\nmicro-payment in the `X-PAYMENT` header to get full access to the metered\nendpoint in a single round-trip — no account, no API key, no sign-up required.\n\n**402 → pay → retry loop:**\n1. Call the endpoint without an `X-PAYMENT` header.\n2. Receive a `402 Payment Required` response. The body is a\n   standard JSON `PaymentRequired` object. The same payload is also\n   echoed as a base64-encoded string in the `PAYMENT-REQUIRED`\n   response header for clients that cannot access the body.\n3. Decode the `PaymentRequired` body (or the `PAYMENT-REQUIRED`\n   header) to read the exact `payTo` wallet,\n   USDC amount, network, and facilitator URL.\n4. Construct and sign the payment with your x402 client library.\n5. Retry the Base request with the `X-PAYMENT` header — the server\n   verifies via `https://facilitator.payai.network` and responds `200`.\n\n**Optional Solana:** When `paymentOptions` advertises a Solana entry, callers\nmay instead select it and use `PAYMENT-SIGNATURE`. Solana is an additional\noption; use `X-PAYMENT` for the Base option shown by this security scheme.\n\n**Discovery:** `GET /api/billing/x402/config` returns the live `payTo`\naddress, canonical `paymentOptions`, per-call-type USDC amounts, facilitator\nURL, and the credits-per-USDC conversion rate. Always fetch this before\nhardcoding any amounts or a payment header.\n\n**Price range:** $0.0030 per 3-credit call — $0.0050 per 5-credit\ncall (see `x-x402-price-usdc` on each\noperation for the exact amount).\n\n**Facilitator:** `https://facilitator.payai.network` (PayAI-operated,\nverifies the advertised Base and optional Solana options).\n"
    x402Solana:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: 'Optional x402 v2 Solana payment alternative. Use this security option only

        when `GET /api/billing/x402/config` `paymentOptions` advertises a Solana

        network, then send its signed Solana USDC payment payload in the

        `PAYMENT-SIGNATURE` header. Include the option''s `feePayer` detail when

        constructing the transaction.


        For the primary Base payment option, select the `x402` security option

        instead and send its signed payment payload in the `X-PAYMENT` header.

        '
x-refined-from:
- cloudworldmodel-ai-openapi.json
- cloudworldmodel-ai-openapi.yml