---
title: "Create a session"
method: POST
path: "/api/sessions"
tags: ["Sessions"]
---

# Create a session

`POST /api/sessions`

## Request

- Base URL: `https://aximo.autify.com`
- URL: `https://aximo.autify.com/api/sessions`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/autify/apis/aximo-api/docs/api/sessions/post.ts> (a function with typed inputs; its response is checked against the schema)

Triggers a new AI test session and returns its ID. The session is queued immediately
and will begin executing as soon as a worker is available.

Poll `GET /api/sessions/{sessionId}` until `status` reaches a terminal value:
`succeeded`, `failed`, `terminated`, `error`, or `archived`.

## Request body

- object
  - `title` string, required: Session title.
  - `autoGenerateTitle` boolean: Replace `title` with one generated when the run finishes; ignored for a session linked to a case. `title` is still required as the initial name.
  - `prompt` string, required: Test instructions for the AI agent.
  - `projectId` string, uuid, required: ID of the workspace to run the session under.
  - `platform` 'desktop' | 'android' | 'ios'
  - `model` 'haiku' | 'sonnet' | 'kimi' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.5' | 'auto': Model to use for this session. Call `GET /api/models` for the values your organization can run — anything else is rejected with `400`, and the error carries the usable list in `availableModels`. When omitted, the `defaultModel` from that endpoint applies.
  - `startUrl` string, uri: Starting URL for desktop sessions.
  - `caseId` string, uuid: Link this session to an existing test case.
  - `tags` string[]: Caller-supplied labels, for example the commit and pull request a run was testing. At most 10, each 1-64 characters after trimming; duplicates are collapsed. A request exceeding a bound is refused with 400, never truncated. Tags are returned exactly as stored and are visible to everyone in your organization, so never put secrets in them.
  - `interactiveMode` boolean: Run the session in interactive mode: when the instructions are too vague to complete without guessing, the agent pauses and asks a clarifying question (answered from the session view in the dashboard) instead of proceeding.
  - `hostnameOverrideIds` string[]: IDs of hostname overrides to apply for this session. Overrides are resolved against the workspace's configured hostname overrides; unknown IDs are ignored.
  - `deviceArn` string: Encrypted device token from `GET /api/devices`. Required for mobile sessions unless `userDeviceId` is set (local devices never use a Device Farm token).
  - `deviceName` string: Human-readable device name (mobile only).
  - `uploadArn` string: Encrypted upload token from `GET /api/uploads/{id}`. Required for mobile sessions with own app.
  - `uploadType` 'own_app' | 'existing' | 'sample': App source type (mobile only).
  - `appName` string: Display name of the app used in test instructions (mobile only).
  - `bundleId` string: App bundle identifier (mobile only).
  - `userDeviceId` string, uuid: Run the session on a registered local device (BYOD) instead of AWS Device Farm — a desktop machine or a locally connected phone registered via `POST /api/devices/register`. Cannot be combined with `deviceArn`/`deviceName`. Requires the BYOD feature to be enabled for your organization.
  - `apps` object[]: Up to 3 apps to install for a mobile session. Takes precedence over the single-app fields (`uploadArn`/`uploadType`/`appName`/`bundleId`); the first entry is the primary app.
    - `uploadArn` string, required: Encrypted upload token from `GET /api/uploads/{id}`.
    - `uploadType` 'own_app' | 'existing' | 'sample', required
    - `appName` string, nullable, required
    - `bundleId` string

## Response `201`

Session created and queued.

- object
  - `success` boolean, required
  - `sessionId` string, uuid, required
  - `warnings` string[]: Advisory only, set when `userDeviceId` names a device that is offline or busy; the session is queued regardless.

## Other responses

- `400`: Invalid request body — including a `model` this organization cannot run (the response then carries `availableModels`), combining `userDeviceId` with `deviceArn`/`deviceName`, a local device whose platform does not match the session platform, a local-device app reference (`uploadArn`/`apps`) supplied without a `bundleId` to launch it, an undecryptable `deviceArn`/`uploadArn`/`apps[].uploadArn` token (`details.path` names the slot), or a non-http(s) `startUrl`.
- `401`: Missing or invalid API key.
- `403`: Forbidden — the organization is out of credits (`details.reason` is `insufficient_credits`), `userDeviceId` used while BYOD is not enabled for the organization, or the API key is not organization-scoped, or its owner is banned or no longer a member of the organization.
- `404`: Project, upload, or user device not found.
- `429`: Rate limit exceeded — e.g. the daily session limit was reached for the organization, or too many API requests were sent in a short window (retry after the number of seconds in the `Retry-After` header).
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/autify/apis/aximo-api.md) - [All operations](https://skmtc.dev/autify/apis/aximo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/autify/apis/aximo-api/revisions/590722011284?raw)