Skip to main content
POST
Create a task

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string

Makes retrying the create safe. A retry with the same key and the same request returns the record the first call created, with status 200, instead of creating another. Reusing a key with a different request returns 422. Keys are scoped to the project and do not expire. The Kernel SDKs send a key automatically and reuse it when they retry.

Required string length: 1 - 255

Body

application/json

Request body for creating a task.

description
string
required

What the task is meant to accomplish, at most 4 KB.

Required string length: 1 - 4096
Example:

"Book a hotel room for two nights"

metadata
object

Caller-defined string key-value pairs for grouping and filtering tasks, such as a user or thread ID. At most 20 keys; keys are 1-64 characters, values at most 256 characters, and keys and values together at most 4 KB.

Example:
session_ids
string[]

IDs of browsers to link to the task. Each must belong to the request's project; deleted browsers can be linked.

Maximum array length: 100
Minimum string length: 1
started_at
string<date-time>

When work on the task started. Defaults to the time the task is created. Must be no more than 5 minutes in the future or 30 days in the past.

target_website
string

Hostname of the website the task targets, without a scheme or path.

Required string length: 1 - 253
Example:

"booking.com"

Response

Task previously created with the same Idempotency-Key and request

A goal an agent works toward. Reports are submitted against a task, and browsers can be linked to it. Tasks are immutable apart from added browser links.

created_at
string<date-time>
required

When the task was created

description
string
required

What the task is meant to accomplish

id
string
required

Unique identifier for the task

metadata
object
required

Caller-defined string key-value pairs for grouping and filtering tasks, such as a user or thread ID. At most 20 keys; keys are 1-64 characters, values at most 256 characters, and keys and values together at most 4 KB.

Example:
session_ids
string[]
required

IDs of browsers linked to the task, oldest link first. Linked browsers may since have been deleted.

started_at
string<date-time>
required

When work on the task started

target_website
string | null

Hostname of the website the task targets