OSWorld

GenStudio DesktopEnv execute (`task.json` + desktop episode). Not Harbor `task.toml`. Prefer `/sandbox/osworld/v2`.

GenStudio DesktopEnv execute (task.json + desktop episode). Not Harbor task.toml. Prefer /sandbox/osworld/v2.

Every request needs a credential — see Authentication.

Method	Path	Summary
`GET`	`/sandbox/osworld/api-versions`	Api Versions
`GET`	`/sandbox/osworld/capabilities`	OSWorld execute capabilities
`GET`	`/sandbox/osworld/jobs/{job_id}`	Get OSWorld job status
`GET`	`/sandbox/osworld/jobs/{job_id}/artifacts`	List job artifacts
`GET`	`/sandbox/osworld/jobs/{job_id}/artifacts/archive`	Download job archive
`POST`	`/sandbox/osworld/jobs/{job_id}/cancel`	Cancel OSWorld job
`GET`	`/sandbox/osworld/jobs/{job_id}/events`	SSE job events
`POST`	`/sandbox/osworld/jobs/execute-tasks`	Enqueue OSWorld execute job
`POST`	`/sandbox/osworld/jobs/validate-task`	Enqueue verifier-only OSWorld task preflight
`GET`	`/sandbox/osworld/v1/capabilities`	OSWorld execute capabilities
`GET`	`/sandbox/osworld/v1/jobs/{job_id}`	Get OSWorld job status
`GET`	`/sandbox/osworld/v1/jobs/{job_id}/artifacts`	List job artifacts
`GET`	`/sandbox/osworld/v1/jobs/{job_id}/artifacts/archive`	Download job archive
`POST`	`/sandbox/osworld/v1/jobs/{job_id}/cancel`	Cancel OSWorld job
`GET`	`/sandbox/osworld/v1/jobs/{job_id}/events`	SSE job events
`POST`	`/sandbox/osworld/v1/jobs/execute-tasks`	Enqueue OSWorld execute job
`POST`	`/sandbox/osworld/v1/jobs/validate-task`	Enqueue verifier-only OSWorld task preflight
`GET`	`/sandbox/osworld/v2/capabilities`	OSWorld execute capabilities
`GET`	`/sandbox/osworld/v2/jobs/{job_id}`	Get OSWorld job status
`GET`	`/sandbox/osworld/v2/jobs/{job_id}/artifacts`	List job artifacts
`GET`	`/sandbox/osworld/v2/jobs/{job_id}/artifacts/archive`	Download job archive
`POST`	`/sandbox/osworld/v2/jobs/{job_id}/cancel`	Cancel OSWorld job
`GET`	`/sandbox/osworld/v2/jobs/{job_id}/events`	SSE job events
`POST`	`/sandbox/osworld/v2/jobs/execute-tasks`	Enqueue OSWorld execute job
`POST`	`/sandbox/osworld/v2/jobs/validate-task`	Enqueue verifier-only OSWorld task preflight

Common headers

Accepted on every endpoint on this page.

Name	In	Type	Required	Description
`x-correlation-id`	header	string	no	End-to-end correlation id for this eval run. When set, the gateway and downstream services honor it verbatim in logs, Cloud Trace span attributes, async job payloads, and Langfuse trace.id. When omitted, the gateway generates a ULID and echoes it on the response.

Endpoints

Api Versions

GET /sandbox/osworld/api-versions

Responses

Status	Description	Body
`200`	Successful Response	object

OSWorld execute capabilities

GET /sandbox/osworld/capabilities

Responses

Status	Description	Body
`200`	Successful Response	object

Get OSWorld job status

GET /sandbox/osworld/jobs/{job_id}

Parameters

Name	In	Type	Required	Description
`job_id`	path	string	yes
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Responses

Status	Description	Body
`200`	Successful Response	object
`422`	Validation Error	HTTPValidationError

List job artifacts

GET /sandbox/osworld/jobs/{job_id}/artifacts

Parameters

Name	In	Type	Required	Description
`job_id`	path	string	yes
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Responses

Status	Description	Body
`200`	Successful Response	object
`422`	Validation Error	HTTPValidationError

Download job archive

GET /sandbox/osworld/jobs/{job_id}/artifacts/archive

Parameters

Name	In	Type	Required	Description
`job_id`	path	string	yes
`presigned`	query	boolean	no
`as`	query	string \| null	no	Set to "json" to receive {"url": ...} instead of a 307 redirect. Requires presigned=true.
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Responses

Status	Description	Body
`200`	Successful Response	any
`422`	Validation Error	HTTPValidationError

Cancel OSWorld job

POST /sandbox/osworld/jobs/{job_id}/cancel

Parameters

Name	In	Type	Required	Description
`job_id`	path	string	yes
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Responses

Status	Description	Body
`200`	Successful Response	object
`422`	Validation Error	HTTPValidationError

SSE job events

GET /sandbox/osworld/jobs/{job_id}/events

Parameters

Name	In	Type	Required	Description
`job_id`	path	string	yes
`Last-Event-ID`	header	string \| null	no
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Responses

Status	Description	Body
`200`	Successful Response	any
`422`	Validation Error	HTTPValidationError

Enqueue OSWorld execute job

POST /sandbox/osworld/jobs/execute-tasks

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string \| null	no
`X-Sandbox-Job-Id`	header	string \| null	no
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Request body

application/json, required — OSWorldExecuteTasksRequest

Field	Type	Required	Description
`task_slug`	string	yes
`agents`	OSWorldAgentBody[]	yes
`metadata`	object	no
`labels`	object	no
`engine`	string \| null	no	Ignored — OSWorld service always runs DesktopEnv episodes
`sandbox`	string \| null	no
`image_ref`	string \| null	no

Responses

Status	Description	Body
`202`	Successful Response	object
`422`	Validation Error	HTTPValidationError

Enqueue verifier-only OSWorld task preflight

POST /sandbox/osworld/jobs/validate-task

Runs no agent or LLM. The archive must contain the strict host-only/preflight/manifest.json version-1 manifest with exactly known_correct (expect pass), unchanged (expect fail), and known_incorrect (expect fail). Each case gets a fresh desktop using the same image, normal task setup/readiness, hidden setup, and the existing evaluator. Results have purpose=task_authoring, valid_for_scoring=false, and set valid_for_passk=true only when all expectations match. Setup/import/evaluator/runtime/timeout faults are errored; score mismatches fail validation. Artifacts contain sanitized logs and digests only, never hidden fixture contents.

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string \| null	no
`X-Sandbox-Job-Id`	header	string \| null	no
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Request body

application/json, required — OSWorldValidateTaskRequest

Field	Type	Required	Description
`task_slug`	string	yes	Logical OSWorld task slug
`metadata`	object	no	Must contain task_archive_url for the task-authoring archive
`labels`	object	no
`image_ref`	string \| null	no	Optional immutable desktop image override used for every case

Responses

Status	Description	Body
`202`	Successful Response	object
`422`	Validation Error	HTTPValidationError

OSWorld execute capabilities

GET /sandbox/osworld/v1/capabilities

Responses

Status	Description	Body
`200`	Successful Response	object

Get OSWorld job status

GET /sandbox/osworld/v1/jobs/{job_id}

Parameters

Name	In	Type	Required	Description
`job_id`	path	string	yes
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Responses

Status	Description	Body
`200`	Successful Response	object
`422`	Validation Error	HTTPValidationError

List job artifacts

GET /sandbox/osworld/v1/jobs/{job_id}/artifacts

Parameters

Name	In	Type	Required	Description
`job_id`	path	string	yes
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Responses

Status	Description	Body
`200`	Successful Response	object
`422`	Validation Error	HTTPValidationError

Download job archive

GET /sandbox/osworld/v1/jobs/{job_id}/artifacts/archive

Parameters

Name	In	Type	Required	Description
`job_id`	path	string	yes
`presigned`	query	boolean	no
`as`	query	string \| null	no	Set to "json" to receive {"url": ...} instead of a 307 redirect. Requires presigned=true.
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Responses

Status	Description	Body
`200`	Successful Response	any
`422`	Validation Error	HTTPValidationError

Cancel OSWorld job

POST /sandbox/osworld/v1/jobs/{job_id}/cancel

Parameters

Name	In	Type	Required	Description
`job_id`	path	string	yes
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Responses

Status	Description	Body
`200`	Successful Response	object
`422`	Validation Error	HTTPValidationError

SSE job events

GET /sandbox/osworld/v1/jobs/{job_id}/events

Parameters

Name	In	Type	Required	Description
`job_id`	path	string	yes
`Last-Event-ID`	header	string \| null	no
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Responses

Status	Description	Body
`200`	Successful Response	any
`422`	Validation Error	HTTPValidationError

Enqueue OSWorld execute job

POST /sandbox/osworld/v1/jobs/execute-tasks

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string \| null	no
`X-Sandbox-Job-Id`	header	string \| null	no
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Request body

application/json, required — OSWorldExecuteTasksRequest

Field	Type	Required	Description
`task_slug`	string	yes
`agents`	OSWorldAgentBody[]	yes
`metadata`	object	no
`labels`	object	no
`engine`	string \| null	no	Ignored — OSWorld service always runs DesktopEnv episodes
`sandbox`	string \| null	no
`image_ref`	string \| null	no

Responses

Status	Description	Body
`202`	Successful Response	object
`422`	Validation Error	HTTPValidationError

Enqueue verifier-only OSWorld task preflight

POST /sandbox/osworld/v1/jobs/validate-task

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string \| null	no
`X-Sandbox-Job-Id`	header	string \| null	no
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Request body

application/json, required — OSWorldValidateTaskRequest

Field	Type	Required	Description
`task_slug`	string	yes	Logical OSWorld task slug
`metadata`	object	no	Must contain task_archive_url for the task-authoring archive
`labels`	object	no
`image_ref`	string \| null	no	Optional immutable desktop image override used for every case

Responses

Status	Description	Body
`202`	Successful Response	object
`422`	Validation Error	HTTPValidationError

OSWorld execute capabilities

GET /sandbox/osworld/v2/capabilities

Responses

Status	Description	Body
`200`	Successful Response	object

Get OSWorld job status

GET /sandbox/osworld/v2/jobs/{job_id}

Parameters

Name	In	Type	Required	Description
`job_id`	path	string	yes
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Responses

Status	Description	Body
`200`	Successful Response	object
`422`	Validation Error	HTTPValidationError

List job artifacts

GET /sandbox/osworld/v2/jobs/{job_id}/artifacts

Parameters

Name	In	Type	Required	Description
`job_id`	path	string	yes
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Responses

Status	Description	Body
`200`	Successful Response	object
`422`	Validation Error	HTTPValidationError

Download job archive

GET /sandbox/osworld/v2/jobs/{job_id}/artifacts/archive

Parameters

Name	In	Type	Required	Description
`job_id`	path	string	yes
`presigned`	query	boolean	no
`as`	query	string \| null	no	Set to "json" to receive {"url": ...} instead of a 307 redirect. Requires presigned=true.
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Responses

Status	Description	Body
`200`	Successful Response	any
`422`	Validation Error	HTTPValidationError

Cancel OSWorld job

POST /sandbox/osworld/v2/jobs/{job_id}/cancel

Parameters

Name	In	Type	Required	Description
`job_id`	path	string	yes
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Responses

Status	Description	Body
`200`	Successful Response	object
`422`	Validation Error	HTTPValidationError

SSE job events

GET /sandbox/osworld/v2/jobs/{job_id}/events

Parameters

Name	In	Type	Required	Description
`job_id`	path	string	yes
`Last-Event-ID`	header	string \| null	no
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Responses

Status	Description	Body
`200`	Successful Response	any
`422`	Validation Error	HTTPValidationError

Enqueue OSWorld execute job

POST /sandbox/osworld/v2/jobs/execute-tasks

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string \| null	no
`X-Sandbox-Job-Id`	header	string \| null	no
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Request body

application/json, required — OSWorldExecuteTasksRequest

Field	Type	Required	Description
`task_slug`	string	yes
`agents`	OSWorldAgentBody[]	yes
`metadata`	object	no
`labels`	object	no
`engine`	string \| null	no	Ignored — OSWorld service always runs DesktopEnv episodes
`sandbox`	string \| null	no
`image_ref`	string \| null	no

Responses

Status	Description	Body
`202`	Successful Response	object
`422`	Validation Error	HTTPValidationError

Enqueue verifier-only OSWorld task preflight

POST /sandbox/osworld/v2/jobs/validate-task

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string \| null	no
`X-Sandbox-Job-Id`	header	string \| null	no
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Request body

application/json, required — OSWorldValidateTaskRequest

Field	Type	Required	Description
`task_slug`	string	yes	Logical OSWorld task slug
`metadata`	object	no	Must contain task_archive_url for the task-authoring archive
`labels`	object	no
`image_ref`	string \| null	no	Optional immutable desktop image override used for every case

Responses

Status	Description	Body
`202`	Successful Response	object
`422`	Validation Error	HTTPValidationError

Schemas

The object shapes referenced above.

HTTPValidationError

Field	Type	Required	Description
`detail`	ValidationError[]	no

OSWorldAgentBody

Field	Type	Required	Description
`name`	string	no	Logical agent label Default: "".
`harbor_agent`	string	yes	OSWorld agent id (GenStudio field name kept for compatibility)
`model`	string	yes	provider/model id (e.g. openai/gpt-4o). Required — same egress as Harbor.
`pass_at_k`	integer	no	Default: 1.
`params`	object	no

OSWorldExecuteTasksRequest

Field	Type	Required	Description
`task_slug`	string	yes
`agents`	OSWorldAgentBody[]	yes
`metadata`	object	no
`labels`	object	no
`engine`	string \| null	no	Ignored — OSWorld service always runs DesktopEnv episodes
`sandbox`	string \| null	no
`image_ref`	string \| null	no

OSWorldValidateTaskRequest

Field	Type	Required	Description
`task_slug`	string	yes	Logical OSWorld task slug
`metadata`	object	no	Must contain task_archive_url for the task-authoring archive
`labels`	object	no
`image_ref`	string \| null	no	Optional immutable desktop image override used for every case

ValidationError

Field	Type	Required
`loc`	string \| integer[]	yes
`msg`	string	yes
`type`	string	yes
`input`	any	no
`ctx`	object	no

Machine-readable spec: OpenAPI YAML.

OSWorld

On this page