> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a job run



## OpenAPI

````yaml https://api.cloud.wherobots.com/openapi.json post /runs
openapi: 3.1.0
info:
  title: Wherobots Cloud API
  description: |-
    Wherobots Cloud API OpenAPI specification.

        These are the API docs for the Wherobots API. You can use this to test out the API and see what it does.
        The underlying OPENAPI spec can be found at /openapi.json. This can be used to generate clients for the API.

        The Authorize button below will allow you to input an access token to authenticate to our API.
        Then all of the requests on the page should work.
        
  version: 0.0.1
servers:
  - url: https://api.cloud.wherobots.com
    description: Wherobots Cloud API
security: []
paths:
  /runs:
    post:
      tags:
        - runs
      summary: Create a job run
      operationId: createJobRun
      parameters:
        - name: region
          in: query
          required: true
          schema:
            type: string
            title: Region
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRunPayload-Input'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunView'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
        - bearerToken: []
        - wherobotsApiKey: []
components:
  schemas:
    CreateRunPayload-Input:
      properties:
        runtime:
          $ref: '#/components/schemas/RuntimeId'
        version:
          anyOf:
            - type: string
            - type: 'null'
          title: Version
        name:
          type: string
          maxLength: 255
          minLength: 8
          pattern: ^[a-zA-Z0-9_\-\.]+$
          title: Name
        runPython:
          anyOf:
            - $ref: '#/components/schemas/RunPythonPayload'
            - type: 'null'
        runJar:
          anyOf:
            - $ref: '#/components/schemas/RunJarPayload'
            - type: 'null'
        timeoutSeconds:
          type: integer
          title: Timeoutseconds
          default: 3600
        environment:
          $ref: '#/components/schemas/RunEnvironment-Input'
          default:
            sparkConfigs: {}
            dependencies: []
      type: object
      required:
        - runtime
        - name
      title: CreateRunPayload
    RunView:
      properties:
        id:
          type: string
          title: Id
        createTime:
          type: string
          format: date-time
          title: Createtime
        updateTime:
          type: string
          format: date-time
          title: Updatetime
        name:
          type: string
          title: Name
        status:
          $ref: '#/components/schemas/RunStatus'
        triggeredBy:
          $ref: '#/components/schemas/OrganizationCustomer'
        startTime:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Starttime
        completeTime:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completetime
        kubeApp:
          anyOf:
            - $ref: '#/components/schemas/RunKubeApp'
            - type: 'null'
        payload:
          $ref: '#/components/schemas/CreateRunPayload-Output'
      type: object
      required:
        - id
        - createTime
        - updateTime
        - name
        - status
        - triggeredBy
        - payload
      title: RunView
    ErrorBody:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/ErrorInfo'
          type: array
          title: Errors
          description: A list of errors that occurred
        requestId:
          type: string
          title: Requestid
          description: A unique identifier for the request that caused the error
      type: object
      required:
        - errors
        - requestId
      title: ErrorBody
    RuntimeId:
      type: string
      enum:
        - TINY
        - SMALL
        - MEDIUM
        - LARGE
        - XLARGE
        - XXLARGE
        - micro
        - tiny
        - small
        - medium
        - large
        - x-large
        - 2x-large
        - 4x-large
        - medium-himem
        - large-himem
        - x-large-himem
        - 2x-large-himem
        - 4x-large-himem
        - x-large-hicpu
        - 2x-large-hicpu
        - x-large-matcher
        - 2x-large-matcher
        - micro-a10-gpu
        - tiny-a10-gpu
        - small-a10-gpu
        - medium-a10-gpu
        - large-a10-gpu
        - x-large-a10-gpu
      title: RuntimeId
    RunPythonPayload:
      properties:
        uri:
          type: string
          title: Uri
        args:
          items:
            type: string
          type: array
          title: Args
          default: []
      type: object
      required:
        - uri
      title: RunPythonPayload
      description: Model for the payload of Run with type == "python"
    RunJarPayload:
      properties:
        uri:
          type: string
          title: Uri
        args:
          items:
            type: string
          type: array
          title: Args
          default: []
        mainClass:
          anyOf:
            - type: string
            - type: 'null'
          title: Mainclass
      type: object
      required:
        - uri
      title: RunJarPayload
      description: Model for the payload of Run with type == "python"
    RunEnvironment-Input:
      properties:
        sparkDriverDiskGB:
          anyOf:
            - type: integer
            - type: 'null'
          title: Sparkdriverdiskgb
        sparkExecutorDiskGB:
          anyOf:
            - type: integer
            - type: 'null'
          title: Sparkexecutordiskgb
        sparkConfigs:
          additionalProperties:
            type: string
          type: object
          title: Sparkconfigs
        dependencies:
          items:
            anyOf:
              - $ref: '#/components/schemas/PyPiDependency'
              - $ref: '#/components/schemas/FileDependency-Input'
          type: array
          title: Dependencies
      type: object
      title: RunEnvironment
      description: >-
        Model for runtime environment configs, include spark cluster configs,
        dependencies.

        When we have new configs like Dax configs, env vars, etc, we can add
        them here.
    RunStatus:
      type: string
      enum:
        - PENDING
        - RUNNING
        - FAILED
        - COMPLETED
        - CANCELLED
        - TIMED_OUT
      title: RunStatus
    OrganizationCustomer:
      properties:
        id:
          type: string
          title: Id
        createTime:
          type: string
          format: date-time
          title: Createtime
        updateTime:
          type: string
          format: date-time
          title: Updatetime
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        roles:
          items:
            $ref: '#/components/schemas/Role-Output'
          type: array
          title: Roles
      type: object
      required:
        - id
        - createTime
        - updateTime
        - roles
      title: OrganizationCustomer
    RunKubeApp:
      properties:
        id:
          type: string
          title: Id
        createTime:
          type: string
          format: date-time
          title: Createtime
        updateTime:
          type: string
          format: date-time
          title: Updatetime
        instanceId:
          type: string
          title: Instanceid
        appType:
          $ref: '#/components/schemas/AppType'
        status:
          $ref: '#/components/schemas/AppStatus'
        createdById:
          anyOf:
            - type: string
            - type: 'null'
          title: Createdbyid
        apiPayload:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Apipayload
        appMeta:
          anyOf:
            - $ref: '#/components/schemas/RunAppMeta'
            - type: 'null'
        events:
          items:
            $ref: '#/components/schemas/KubeAppEvent'
          type: array
          title: Events
          default: []
        cpuUsage:
          type: integer
          title: Cpuusage
        regionName:
          type: string
          title: Regionname
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: Return the latest trace info that is valuable for troubleshooting
          readOnly: true
      type: object
      required:
        - id
        - createTime
        - updateTime
        - instanceId
        - appType
        - status
        - createdById
        - cpuUsage
        - regionName
        - message
      title: RunKubeApp
    CreateRunPayload-Output:
      properties:
        runtime:
          $ref: '#/components/schemas/RuntimeId'
        version:
          anyOf:
            - type: string
            - type: 'null'
          title: Version
        name:
          type: string
          maxLength: 255
          minLength: 8
          pattern: ^[a-zA-Z0-9_\-\.]+$
          title: Name
        runPython:
          anyOf:
            - $ref: '#/components/schemas/RunPythonPayload'
            - type: 'null'
        runJar:
          anyOf:
            - $ref: '#/components/schemas/RunJarPayload'
            - type: 'null'
        timeoutSeconds:
          type: integer
          title: Timeoutseconds
          default: 3600
        environment:
          $ref: '#/components/schemas/RunEnvironment-Output'
          default:
            sparkConfigs: {}
            dependencies: []
      type: object
      required:
        - runtime
        - name
      title: CreateRunPayload
    ErrorInfo:
      properties:
        code:
          $ref: '#/components/schemas/ErrorClass'
          description: The error code
        message:
          type: string
          title: Message
          description: A human-readable message describing the error
        details:
          type: string
          title: Details
          description: Details about the error
        path:
          type: string
          title: Path
          description: The path to the field that caused the error
        suggestion:
          type: string
          title: Suggestion
          description: Suggested action to resolve the error
          default: >-
            Contact us at support@wherobots.com to get help with resolving your
            error.
        documentation_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Documentation Url
          description: URL to related documentation
        field:
          anyOf:
            - type: string
            - type: 'null'
          title: Field
          description: The field that caused the error if applicable
      type: object
      required:
        - code
        - message
        - details
        - path
      title: ErrorInfo
    PyPiDependency:
      properties:
        sourceType:
          $ref: '#/components/schemas/DependencySourceType'
          default: PYPI
        libraryName:
          type: string
          title: Libraryname
        libraryVersion:
          anyOf:
            - type: string
            - type: 'null'
          title: Libraryversion
      type: object
      required:
        - libraryName
      title: PyPiDependency
      description: Model for the dependency of a run
    FileDependency-Input:
      properties:
        sourceType:
          $ref: '#/components/schemas/DependencySourceType'
          default: FILE
        filePath:
          type: string
          title: Filepath
      type: object
      required:
        - filePath
      title: FileDependency
      description: Model for the dependency of a run
    Role-Output:
      properties:
        id:
          type: string
          title: Id
        createTime:
          type: string
          format: date-time
          title: Createtime
        updateTime:
          type: string
          format: date-time
          title: Updatetime
        name:
          type: string
          title: Name
        organizationId:
          type: string
          title: Organizationid
        policies:
          items:
            $ref: '#/components/schemas/Policy'
          type: array
          title: Policies
      type: object
      required:
        - id
        - createTime
        - updateTime
        - name
        - organizationId
        - policies
      title: Role
    AppType:
      type: string
      enum:
        - JUPYTER
        - SQL_SESSION
        - RUN
      title: AppType
    AppStatus:
      type: string
      enum:
        - PENDING
        - PREPARING
        - PREPARE_FAILED
        - REQUESTED
        - DEPLOYING
        - DEPLOY_FAILED
        - DEPLOYED
        - INITIALIZING
        - INIT_FAILED
        - READY
        - DESTROY_REQUESTED
        - DESTROYING
        - DESTROY_FAILED
        - DESTROYED
      title: AppStatus
    RunAppMeta:
      properties:
        spark_ui_url:
          type: string
          title: Spark Ui Url
          default: ''
        spark_eventlogs_url:
          type: string
          title: Spark Eventlogs Url
          default: ''
        resolved_version:
          anyOf:
            - type: string
            - type: 'null'
          title: Resolved Version
      type: object
      title: RunAppMeta
      description: Run-specific metadata fields
    KubeAppEvent:
      properties:
        id:
          type: string
          title: Id
        createTime:
          type: string
          format: date-time
          title: Createtime
        updateTime:
          type: string
          format: date-time
          title: Updatetime
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
        eventMeta:
          anyOf:
            - $ref: '#/components/schemas/RunEventMeta'
            - $ref: '#/components/schemas/KubeAppCreationMeta'
            - type: 'null'
          title: Eventmeta
      type: object
      required:
        - id
        - createTime
        - updateTime
      title: KubeAppEvent
    RunEnvironment-Output:
      properties:
        sparkDriverDiskGB:
          anyOf:
            - type: integer
            - type: 'null'
          title: Sparkdriverdiskgb
        sparkExecutorDiskGB:
          anyOf:
            - type: integer
            - type: 'null'
          title: Sparkexecutordiskgb
        sparkConfigs:
          additionalProperties:
            type: string
          type: object
          title: Sparkconfigs
        dependencies:
          items:
            anyOf:
              - $ref: '#/components/schemas/PyPiDependency'
              - $ref: '#/components/schemas/FileDependency-Output'
          type: array
          title: Dependencies
      type: object
      title: RunEnvironment
      description: >-
        Model for runtime environment configs, include spark cluster configs,
        dependencies.

        When we have new configs like Dax configs, env vars, etc, we can add
        them here.
    ErrorClass:
      type: string
      enum:
        - BAD_REQUEST_ERROR
        - CONFLICT_ERROR
        - INVALID_INPUT_ERROR
        - INTERNAL_SERVER_ERROR
        - UNAUTHORIZED_ERROR
        - INSUFFICIENT_PERMISSIONS_ERROR
        - THIRD_PARTY_PERMISSIONS_ERROR
        - NOT_FOUND_ERROR
        - INSUFFICIENT_QUOTA_ERROR
        - REQUEST_ENTITY_TOO_LARGE
        - UNITY_CATALOG_CONNECTION_FAILED
        - RATE_LIMIT_ERROR
        - TIMEOUT_ERROR
        - ACCOUNT_NOT_PROVISIONED
      title: ErrorClass
    DependencySourceType:
      type: string
      enum:
        - PYPI
        - FILE
      title: DependencySourceType
      description: Enum for the source type of dependency
    Policy:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
        createTime:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Createtime
        updateTime:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updatetime
        provider:
          $ref: '#/components/schemas/Provider'
        locator:
          type: string
          title: Locator
        action:
          type: string
          title: Action
        effect:
          $ref: '#/components/schemas/Effect'
      type: object
      required:
        - provider
        - locator
        - action
        - effect
      title: Policy
    RunEventMeta:
      properties:
        end_timestamp:
          anyOf:
            - type: integer
            - type: 'null'
          title: End Timestamp
        start_timestamp:
          anyOf:
            - type: integer
            - type: 'null'
          title: Start Timestamp
      type: object
      title: RunEventMeta
    KubeAppCreationMeta:
      properties:
        use_v2_workflow:
          type: boolean
          title: Use V2 Workflow
          default: false
      type: object
      title: KubeAppCreationMeta
      description: >-
        ``event_meta`` shape for ``EventCode.APP_START_CREATION``.


        Captures decisions pinned at kube_app creation time so cancel/destroy
        can

        consult them later without re-deriving. Currently only carries the v2

        dispatcher marker — set to ``True`` when the LaunchDarkly flag routes
        the

        kube_app through the unified ``KubeAppWorkflow`` (ENGP-336 Stream E).

        Legacy creates leave ``event_meta`` ``None`` so this model isn't even

        constructed; cleanup at v2 100% rollout deletes this class.
    FileDependency-Output:
      properties:
        sourceType:
          $ref: '#/components/schemas/DependencySourceType'
          default: FILE
        filePath:
          type: string
          title: Filepath
        fileType:
          $ref: '#/components/schemas/DependencyFileType'
          description: Get the type of the file
          readOnly: true
      type: object
      required:
        - filePath
        - fileType
      title: FileDependency
      description: Model for the dependency of a run
    Provider:
      type: string
      enum:
        - WHEROBOTS
        - AWS
      title: Provider
    Effect:
      type: string
      enum:
        - ALLOW
        - DENY
      title: Effect
    DependencyFileType:
      type: string
      enum:
        - JAR
        - PYTHON_WHEEL
        - ZIP
        - OTHER
      title: DependencyFileType
      description: Enum for the file type of dependency
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
    wherobotsApiKey:
      type: apiKey
      description: A Wherobots-generated API key
      in: header
      name: X-API-Key

````