Add or update a task's agents
POST /tasks/{id}/agents
Constraints not expressible in JSON Schema, enforced at runtime:
- Agent IDs must be unique within each agent list.
Requires: tasks.agents.manage
Payload shapes are not yet fully described. The endpoint, authentication and permissions are accurate; unconstrained JSON marks the shapes still awaiting extraction.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Resource ULID.
Header Parameters
Section titled “Header Parameters ”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
Section titled “Request Body required ”object
object
object
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
Set by Moondeck on the built-in Astronaut only; a request that sends it is refused with 422 BUILT_IN_AGENT
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
Responses
Section titled “ Responses ”Successful response. Payload shape not yet described.
BAD_JSON — the body is not valid JSON, or INVALID_REQUEST — the decoded body does not match the route’s request schema.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
UNAUTHORIZED — missing or invalid token, or an org-scoped API key (only user-scoped keys are accepted).
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
PLAN_LIMIT — the workspace’s plan does not include API access. Every API-key call can return this; session-token calls never do.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
FORBIDDEN (lacking the required permission) or SCOPE_REQUIRED (no workspace, or a membership change in progress).
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
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
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
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
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
SCOPE_REQUIRED — membership reconciliation required, or membership verification unavailable.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan