Cloud World Model API Keys API

openapi: 3.2.0
info:
  title: Cloudworldmodel Ai API Keys 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 API Keys 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: API Keys
  description: Manage API keys for authentication
paths:
  /keys:
    x-stability: stable
    post:
      tags:
      - API Keys
      summary: Create a new API key
      description: 'Creates a new API key for authenticating to the RL Training API.

        The full key is returned only once - store it securely.'
      operationId: createApiKey
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: Human-readable name for the API key
                  example: Production Agent Key
                scopes:
                  type: array
                  items:
                    type: string
                    enum:
                    - read
                    - write
                    - admin
                  default:
                  - read
                  - write
                  description: Permission scopes for the key
                rateLimit:
                  type: integer
                  default: 1000
                  description: Requests per hour limit
                  example: 1000
                expiresAt:
                  type: string
                  format: date-time
                  description: Optional expiration date
                  example: '2025-12-31T23:59:59Z'
                userId:
                  type: string
                  description: Optional user ID to associate with the key
      responses:
        '201':
          description: API key created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  key:
                    type: string
                    description: The full API key (shown only once)
                    example: cwm_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
                  keyPrefix:
                    type: string
                    description: Key prefix for identification
                    example: cwm_live_a1b2c3d4...
                  name:
                    type: string
                  scopes:
                    type: array
                    items:
                      type: string
                  rateLimit:
                    type: integer
                  createdAt:
                    type: string
                    format: date-time
                  expiresAt:
                    type: string
                    format: date-time
                  message:
                    type: string
                    example: Store this API key securely. You won't be able to see it again.
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      tags:
      - API Keys
      summary: List API keys
      description: Lists all API keys. Only shows key prefixes for security.
      operationId: listApiKeys
      security: []
      parameters:
      - name: userId
        in: query
        schema:
          type: string
        description: Optional filter by user ID
      responses:
        '200':
          description: List of API keys
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    keyPrefix:
                      type: string
                      example: cwm_live_a1b2c3d4...
                    name:
                      type: string
                    scopes:
                      type: array
                      items:
                        type: string
                    rateLimit:
                      type: integer
                    isActive:
                      type: boolean
                    createdAt:
                      type: string
                      format: date-time
                    lastUsedAt:
                      type: string
                      format: date-time
                    expiresAt:
                      type: string
                      format: date-time
        '500':
          $ref: '#/components/responses/InternalError'
    servers:
    - url: https://www.cloudworldmodel.ai/api
      description: Production
    - url: http://localhost:5000/api
      description: Local development
  /keys/{keyId}:
    x-stability: stable
    delete:
      tags:
      - API Keys
      summary: Revoke an API key
      description: Revokes an API key, preventing further use
      operationId: revokeApiKey
      security: []
      parameters:
      - name: keyId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: API key revoked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: API key revoked successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    servers:
    - url: https://www.cloudworldmodel.ai/api
      description: Production
    - url: http://localhost:5000/api
      description: Local development
components:
  schemas:
    FieldError:
      type: object
      description: A single structured field-level error returned on HTTP 400 responses
      required:
      - code
      - pointer
      - message
      properties:
        code:
          $ref: '#/components/schemas/ValidationErrorCode'
        pointer:
          type: string
          description: JSON Pointer (RFC 6901) to the field that caused the error, or an empty string for request-level errors
          example: /resources/0/provider
        message:
          type: string
          description: Human-readable description of the error
          example: Unknown provider 'gce'; valid values are aws, gcp, azure, oci, digitalocean
        suggestion:
          type: string
          description: Optional actionable hint for self-correction
          example: 'Use one of: aws, gcp, azure, oci, digitalocean'
        suggestions:
          type: array
          description: For UNKNOWN_REGION errors, the 3-5 closest matching regions ranked by similarity to the invalid input
          items:
            type: object
            required:
            - regionKey
            - regionLabel
            properties:
              regionKey:
                type: string
                description: Canonical shortcode for the region
                example: use2
              regionLabel:
                type: string
                description: Standard provider label for the region
                example: us-east-2
    ValidationErrorCode:
      type: string
      description: Machine-readable error code indicating the category of validation failure
      enum:
      - INVALID_FIELD
      - MISSING_REQUIRED
      - UNKNOWN_PROVIDER
      - UNKNOWN_SIZE
      - UNKNOWN_REGION
      - INVALID_REQUEST
    ValidationErrorResponse:
      type: object
      description: Response body for HTTP 400 errors — either a single error or an array of field errors
      oneOf:
      - type: object
        required:
        - error
        properties:
          error:
            $ref: '#/components/schemas/FieldError'
      - type: object
        required:
        - errors
        properties:
          errors:
            type: array
            items:
              $ref: '#/components/schemas/FieldError'
            minItems: 1
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message
          example: Simulation not found
        details:
          type: array
          description: Detailed validation errors (for 400 responses)
          items:
            type: object
  responses:
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request data — structured field-level error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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