---
title: "Create an iOS instance"
method: POST
path: "/v1/ios_instances"
---

# Create an iOS instance

`POST /v1/ios_instances`

## Query parameters

- `wait` boolean
- `reuseIfExists` boolean

## Request body

- IOSInstanceCreate
  - `metadata` object
    - `displayName` string
    - `labels` object
  - `spec` object
    - `sandbox` object
      - `xcode` object
        - `enabled` boolean
    - `clues` object[]
      - `kind` 'ClientIP', required
      - `clientIp` string
    - `model` 'iphone' | 'ipad' | 'watch' — The model for the Apple Simulator. Default is iphone.
    - `region` string — Where the instance will be created. If not given, the region is decided based on scheduling clues (client IP) and availability. A region is a preference, not a hard pin: the request always overflows to every other available region, ordered by proximity, when the preferred ones are full. Accepted values: * A specific region name (e.g. "us-west1"). It is tried first, then the remaining regions in order of proximity to it. Scheduling clues (client IP) are ignored when a region is given. * A region group name (e.g. "us", "eu"). Its member regions are tried first in their listed order, then the remaining regions by proximity to the first member. * A pipe-separated, ordered list of regions (e.g. "us-east1|us-west1"). Those are tried first in the given order, then the remaining regions by proximity to the first.
    - `inactivityTimeout` string, duration — After how many minutes of inactivity should the instance be terminated. The timer starts once the instance becomes ready. Example values 1m, 10m, 3h. Default is 3m. Providing "0" uses the organization's default inactivity timeout.
    - `hardTimeout` string, duration — After how many minutes should the instance be terminated. Example values 1m, 10m, 3h. Default is "0" which means no hard timeout.
    - `forceBundleId` string — Keeps this app in the foreground after it is first observed there. This does not launch the app when the simulator starts. Once armed, closing or backgrounding the app causes it to be brought back to the foreground.
    - `initialAssets` object[]
      - `kind` 'App' | 'Keychain', required
      - `source` 'URL' | 'AssetName' | 'AssetID', required
      - `url` string
      - `assetName` string
      - `assetId` string
      - `encryptionKey` string — Base64/base64url-encoded 32-byte key used to decrypt Keychain assets. Required when kind is Keychain.
      - `launchMode` 'ForegroundIfRunning' | 'RelaunchIfRunning' | 'FailIfRunning' — Launch mode specifies how to launch the app after installation.
    - `jurisdiction` 'us' | 'eu' | 'as' — Restricts scheduling to regions in the given jurisdiction. Unlike region, this is a hard constraint: the request never overflows to a region outside the jurisdiction and fails when no region in the jurisdiction has capacity. A region belongs to a jurisdiction when its name starts with the jurisdiction prefix, e.g. "eu-north1" is in "eu". A region preference pointing outside the jurisdiction is ignored.

## Response `200`

OK

- IOSInstance
  - `metadata` object, required
    - `id` string, required
    - `displayName` string
    - `organizationId` string, required
    - `createdAt` string, date-time, required
    - `terminatedAt` string, date-time
    - `labels` object
  - `spec` object, required
    - `region` string, required — The region where the instance will be created. If not given, will be decided based on scheduling clues and availability.
    - `inactivityTimeout` string, duration, required — After how many minutes of inactivity should the instance be terminated. The timer starts once the instance becomes ready. Example values 1m, 10m, 3h. Default is 3m. Providing "0" uses the organization's default inactivity timeout.
    - `hardTimeout` string, duration — After how many minutes should the instance be terminated. Example values 1m, 10m, 3h. Default is "0" which means no hard timeout.
  - `status` object, required
    - `state` 'unknown' | 'creating' | 'assigned' | 'ready' | 'terminated', required
    - `apiUrl` string
    - `endpointWebSocketUrl` string
    - `signedStreamUrl` string
    - `targetHttpPortUrlPrefix` string
    - `mcpUrl` string
    - `sandbox` IOSSandboxStatus
      - `xcode` object
        - `url` string
    - `token` string, required
    - `errorMessage` string
    - `terminationReason` string — Machine-readable reason the instance was terminated. Always present once state is "terminated", never present before that. New values may be added over time, so treat any unrecognized value as "Unknown". Known values: - "UserRequested": terminated by a delete request to the API. - "InactivityTimeout": the timeout given in spec.inactivityTimeout elapsed. - "HardTimeout": the timeout given in spec.hardTimeout elapsed. - "Unknown": terminated for a cause the platform did not attribute, including instances that failed to get ready during creation. See errorMessage for details when available.

## Other responses

- `default` — Error

---

[API](https://skmtc.net/limrun-inc/apis/limrun-api.md) · [All operations](https://skmtc.net/limrun-inc/apis/limrun-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/limrun-inc/limrun-api/revisions/0a3cd7959546/schema)