Start a task

POST

/tasks/{id}/start

• Production

Constraints not expressible in JSON Schema, enforced at runtime:

• Agent IDs must be unique within each agent list.
• Credential IDs must be unique within a task’s ordered AI-account list.

May require, depending on the request: tasks.start, tasks.write

Payload shapes are not yet fully described. The endpoint, authentication and permissions are accurate; unconstrained JSON marks the shapes still awaiting extraction.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string

Resource ULID.

Header Parameters

x-uai-org

string

Org scope: me or an org slug. Absent means the caller’s active/personal org. It selects the workspace used for permission checks and for most resource filters; operation-specific access rules still apply.

Request Body ^required

object

hostId

string

>= 1 characters

mode

string

Allowed values: open secretary

secretaryAgentId

Any of:

string

string

>= 1 characters /^[A-Za-z0-9_-]+$/

null

null

astronaut

object

kind

required

string

>= 1 characters /^[a-z0-9][a-z0-9_-]*$/

model

string

>= 1 characters

effort

string

>= 1 characters

permissions

Array<string>

<= 64 items

accountId

string

>= 1 characters <= 128 characters /^[A-Za-z0-9_.:-]+$/

name

string

>= 1 characters <= 120 characters

projects

Array<object>

<= 32 items

object

projectId

required

string

>= 1 characters

position

required

integer

globalContext

Any of:

string

string

<= 50000 characters

null

null

agents

Array

Any of:

object

object

id

required

string

>= 1 characters /^[A-Za-z0-9_-]+$/

personaId

required

string

>= 1 characters

overrides

object

label

string

>= 1 characters

kind

string

>= 1 characters /^[a-z0-9][a-z0-9_-]*$/

model

Any of:

string

string

>= 1 characters

null

null

effort

Any of:

string

string

>= 1 characters

null

null

defaultPrompt

string

initialPrompt

string

teamSkillIds

Array<string>

accountId

string

>= 1 characters <= 128 characters /^[A-Za-z0-9_.:-]+$/

object

object

id

required

string

>= 1 characters /^[A-Za-z0-9_-]+$/

label

required

string

>= 1 characters

kind

required

string

>= 1 characters /^[a-z0-9][a-z0-9_-]*$/

model

string

>= 1 characters

effort

string

>= 1 characters

defaultPrompt

string

permissions

Array<string>

uaiProvider

string

Allowed values: anthropic openai

accountId

string

>= 1 characters <= 128 characters /^[A-Za-z0-9_.:-]+$/

accountBinding

string

Allowed values: required preferred

sourcePersonaId

string

>= 1 characters

teamSkillIds

Array<string>

initialPrompt

string

skills

Array<object>

object

name

required

string

>= 1 characters

type

required

string

>= 1 characters

value

required

string

builtIn

string

source

string | null

subpath

string | null

role

string

<= 64 characters

avatar

A PXLBOT string or a legacy avatar. Avatars reserved for the Astronaut (house bot pxlbot:901:…, or a house colour such as midnight) are refused with 422 AVATAR_RESERVED

string

builtIn

Set by Moondeck on the built-in Astronaut only; a request that sends it is refused with 422 BUILT_IN_AGENT

string

tokenGeneration

Set by Moondeck when the agent joins a task; its task token must carry the same value. Any value a client sends is replaced, and a draft stores none

string

>= 1 characters <= 64 characters

aiAccounts

Any of:

object

object

lane

required

string

Allowed values: subscriptions_then_credits subscriptions_only credits_only

accounts

Array<string>

<= 100 items

null

null

approvedConnectionIds

Array<string>

<= 50 items

sharedFiles

string

Allowed values: off ro rw

browserTesting

boolean

Responses

202

Successful response. Payload shape not yet described.

400

BAD_JSON — the body is not valid JSON, or INVALID_REQUEST — the decoded body does not match the route’s request schema.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

401

UNAUTHORIZED — missing or invalid token, or an org-scoped API key (only user-scoped keys are accepted).

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

402

PLAN_LIMIT — the workspace’s plan does not include API access. Every API-key call can return this; session-token calls never do.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

403

FORBIDDEN (lacking the required permission) or SCOPE_REQUIRED (no workspace, or a membership change in progress).

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

404

SCOPE_REQUIRED — the x-uai-org scope names a workspace that does not exist, or one the caller is not a member of. The two are deliberately indistinguishable: a 403 would confirm the workspace exists.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

422

Among the refusals of the agents a client sends: BUILT_IN_AGENT — an agent carries the built-in marker, which only Moondeck sets; AVATAR_RESERVED — an agent wears an avatar reserved for the built-in Astronaut: house bot pxlbot:901:…, or a house background colour such as midnight.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

503

SCOPE_REQUIRED — membership reconciliation required, or membership verification unavailable.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any