Instances

List instances in a session

GET/api/v1/sessions/{sessionId}/instances

Instances attached to the session, newest first. Visible to every member of the organization that owns the session.

Path parameters

sessionIdstring · uuidrequired

Session UUID

Header parameters

X-Organization-Idstring

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Returns

objectstringrequired

dataarrayrequired

Show child attributes

idstring · uuidrequired

The instance's own id

statusstringrequired

Lifecycle: provisioning -> ready, then released, or failed if provisioning could not complete

osstringrequired

Instance operating system. Only macos is supported today.

imagestringrequired

Server-assigned base image the instance booted from

machineobjectrequired

The compute backing an instance.

Show child attributes

archstringrequired

CPU architecture. Only arm64 is supported today.

cpuCoresintegerrequired

memoryMbintegerrequired

diskMbintegerrequired

createdAtstring · date-timerequired

When the instance was allocated (billing start)

readyAtstring · date-timenullable

When the instance finished provisioning; null while provisioning

releasedAtstring · date-timenullable

When the instance was released (billing end); null while active

nextCursorstringnullable

Cursor for the next page; absent when there are no more results

Request

curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/instances \
  -X GET \
  -H 'Authorization: Bearer mob_...'

Response

Instances attached to the session

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "status": "provisioning",
      "os": "macos",
      "image": "macos-15-xcode-16",
      "machine": {
        "arch": "arm64",
        "cpuCores": 8,
        "memoryMb": 16384,
        "diskMb": 262144
      },
      "createdAt": "2026-01-01T00:00:00Z",
      "readyAt": "2026-01-01T00:00:00Z",
      "releasedAt": "2026-01-01T00:00:00Z"
    }
  ],
  "nextCursor": "string"
}

Allocate an instance

POST/api/v1/sessions/{sessionId}/instances

Allocates a new instance (a build/automation machine) attached to the session. Provisioning is asynchronous: the instance is returned immediately with status "provisioning" and becomes usable once its status is "ready". Poll GET /sessions/{sessionId}/instances/{instanceId} to observe readiness.

Path parameters

sessionIdstring · uuidrequired

Session UUID

Header parameters

X-Organization-Idstring

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Body parameters

osstringrequired

Instance operating system. Only macos is supported today.

Returns

A build/automation machine allocated to a session.

idstring · uuidrequired

The instance's own id

statusstringrequired

Lifecycle: provisioning -> ready, then released, or failed if provisioning could not complete

osstringrequired

Instance operating system. Only macos is supported today.

imagestringrequired

Server-assigned base image the instance booted from

machineobjectrequired

The compute backing an instance.

Show child attributes

archstringrequired

CPU architecture. Only arm64 is supported today.

cpuCoresintegerrequired

memoryMbintegerrequired

diskMbintegerrequired

createdAtstring · date-timerequired

When the instance was allocated (billing start)

readyAtstring · date-timenullable

When the instance finished provisioning; null while provisioning

releasedAtstring · date-timenullable

When the instance was released (billing end); null while active

Request

curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/instances \
  -X POST \
  -H 'Authorization: Bearer mob_...' \
  -H 'Content-Type: application/json' \
  -d '{"os":"macos"}'

Response

Instance allocated; provisioning has started

{
  "id": "string",
  "status": "provisioning",
  "os": "macos",
  "image": "macos-15-xcode-16",
  "machine": {
    "arch": "arm64",
    "cpuCores": 8,
    "memoryMb": 16384,
    "diskMb": 262144
  },
  "createdAt": "2026-01-01T00:00:00Z",
  "readyAt": "2026-01-01T00:00:00Z",
  "releasedAt": "2026-01-01T00:00:00Z"
}

Get an instance

GET/api/v1/sessions/{sessionId}/instances/{instanceId}

Returns an instance attached to the session. Visible to every member of the organization that owns the session.

Path parameters

sessionIdstring · uuidrequired

Session UUID

instanceIdstring · uuidrequired

Instance UUID

Header parameters

X-Organization-Idstring

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Returns

A build/automation machine allocated to a session.

idstring · uuidrequired

The instance's own id

statusstringrequired

Lifecycle: provisioning -> ready, then released, or failed if provisioning could not complete

osstringrequired

Instance operating system. Only macos is supported today.

imagestringrequired

Server-assigned base image the instance booted from

machineobjectrequired

The compute backing an instance.

Show child attributes

archstringrequired

CPU architecture. Only arm64 is supported today.

cpuCoresintegerrequired

memoryMbintegerrequired

diskMbintegerrequired

createdAtstring · date-timerequired

When the instance was allocated (billing start)

readyAtstring · date-timenullable

When the instance finished provisioning; null while provisioning

releasedAtstring · date-timenullable

When the instance was released (billing end); null while active

Request

curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/instances/{instanceId} \
  -X GET \
  -H 'Authorization: Bearer mob_...'

Response

Instance detail

{
  "id": "string",
  "status": "provisioning",
  "os": "macos",
  "image": "macos-15-xcode-16",
  "machine": {
    "arch": "arm64",
    "cpuCores": 8,
    "memoryMb": 16384,
    "diskMb": 262144
  },
  "createdAt": "2026-01-01T00:00:00Z",
  "readyAt": "2026-01-01T00:00:00Z",
  "releasedAt": "2026-01-01T00:00:00Z"
}

Release an instance

POST/api/v1/sessions/{sessionId}/instances/{instanceId}/release

Releases an instance, stopping billing and tearing it down. Returns the instance with its updated status. Idempotent: releasing an already-released instance is a no-op.

Path parameters

sessionIdstring · uuidrequired

Session UUID

instanceIdstring · uuidrequired

Instance UUID

Header parameters

X-Organization-Idstring

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Returns

A build/automation machine allocated to a session.

idstring · uuidrequired

The instance's own id

statusstringrequired

Lifecycle: provisioning -> ready, then released, or failed if provisioning could not complete

osstringrequired

Instance operating system. Only macos is supported today.

imagestringrequired

Server-assigned base image the instance booted from

machineobjectrequired

The compute backing an instance.

Show child attributes

archstringrequired

CPU architecture. Only arm64 is supported today.

cpuCoresintegerrequired

memoryMbintegerrequired

diskMbintegerrequired

createdAtstring · date-timerequired

When the instance was allocated (billing start)

readyAtstring · date-timenullable

When the instance finished provisioning; null while provisioning

releasedAtstring · date-timenullable

When the instance was released (billing end); null while active

Request

curl https://api.mobilenexthq.com/api/v1/sessions/{sessionId}/instances/{instanceId}/release \
  -X POST \
  -H 'Authorization: Bearer mob_...'

Response

Release accepted; teardown proceeds asynchronously

{
  "id": "string",
  "status": "provisioning",
  "os": "macos",
  "image": "macos-15-xcode-16",
  "machine": {
    "arch": "arm64",
    "cpuCores": 8,
    "memoryMb": 16384,
    "diskMb": 262144
  },
  "createdAt": "2026-01-01T00:00:00Z",
  "readyAt": "2026-01-01T00:00:00Z",
  "releasedAt": "2026-01-01T00:00:00Z"
}