AUautify
Sessions

Create a session

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.

post/api/sessions

Request

Request body

titlestring required

Session title.

autoGenerateTitleboolean

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.

promptstring required

Test instructions for the AI agent.

projectIdstring 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.

startUrlstring uri

Starting URL for desktop sessions.

caseIdstring uuid

Link this session to an existing test case.

tagsstring[]

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.

interactiveModeboolean

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.

hostnameOverrideIdsstring[]

IDs of hostname overrides to apply for this session. Overrides are resolved against the workspace's configured hostname overrides; unknown IDs are ignored.

deviceArnstring

Encrypted device token from GET /api/devices. Required for mobile sessions unless userDeviceId is set (local devices never use a Device Farm token).

deviceNamestring

Human-readable device name (mobile only).

uploadArnstring

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).

appNamestring

Display name of the app used in test instructions (mobile only).

bundleIdstring

App bundle identifier (mobile only).

userDeviceIdstring 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.

Example request

{
  "title": "Login flow smoke test",
  "prompt": "Go to https://example.com, click Login, enter test@example.com / password123, and verify the dashboard loads.",
  "tags": [
    "git:sha:3f2c1e9a7b6d5c4e3f2a1b0c9d8e7f6a5b4c3d2e",
    "genesis:pr:1234"
  ]
}

Response

Session created and queued.

successboolean required
sessionIdstring uuid required
warningsstring[]

Advisory only, set when userDeviceId names a device that is offline or busy; the session is queued regardless.

Example response

{
  "success": true
}

Changes

No recorded changes to this operation across all 1 revision of this API.