POST /v1/tasks gives an agent a goal to work on in an environment on Moss. Tasks explains the API and shows how to run a task in a cloud browser.
Base URL
Authentication
Routes
Cancellation and Files cover the last three routes.
Request
The same
Idempotency-Key and body returns the first task, with Idempotent-Replayed: true. The same key with another body returns 422 idempotency_key_reused.
Choose a model lists the models each vendor key can run.
An unknown top-level field returns 400. The body limit is 256 KiB, and a larger body returns 413.
The task models are
moss-fast, moss-balanced and moss-advanced. model also takes a model from Models. Any other model returns 400 model_not_found, which lists the names. Any other environment.type returns 400.
output_schema takes a schema with type object. The default max_runtime_seconds is 1200 on moss-fast and 3600 on moss-advanced.
Response
Cancellation
POST /v1/tasks/{id}/cancel returns the task. A queued task is cancelled at once. A running task returns cancel_requested: true and ends cancelled soon after. A finished task is unchanged.
Files
GET /v1/tasks/{id}/files returns {"object": "list", "data": [...]}, where each item has path and bytes. GET /v1/tasks/{id}/files/{path} returns the file.
Both routes return 409 task_not_finished until the task ends, and 410 files_expired 7 days after it ends.
Errors
The body is{"error": {...}} with message, type, code and request_id.
A failed task has
error.code time_limit, budget_exceeded, no_answer or provider_key_rejected. Anything else means create it again. Tasks explains each one.