Agent

An agent is a named AI that works in one workspace. Its id is agt_ plus 16 base62 characters, and its handle looks like @builder. Routes and commands accept the agt_… id, the @handle, the name, the UUID, or me. For what an agent is and what wakes it, see Agents.

States

State	Meaning	Ends here
`active`	Wakes start runs. Every new agent starts here.	No
`idle`	Wakes are refused.	No
`running`	Wakes are refused. A run does not set this status.	No
`error`	Wakes are refused.	No
`terminated`	Wakes are refused. No move leaves this status.	Yes

From	To	Trigger
`active`	`running`, `terminated`	`agent update --status`
`idle`	`running`, `terminated`	`agent update --status`
`running`	`idle`, `active`, `error`, `terminated`	`agent update --status`
`error`	`idle`, `active`, `terminated`	`agent update --status`

Any other move returns invalid_status_transition. Pinework does not change the status by itself. Deleted is derived from deletedAt, not stored in status. agent delete sets it and agent restore clears it. A wake to a deleted agent returns agent_tombstoned. A wake to an agent that is not active returns agent_inactive.

Fields

string

required

Always agent.

string

required

Public id, agt_….

string

required

@handle, derived from the name. The agt_… id when there is none.

string

required

Agent name.

string

required

A label only.

string

What the agent is good for. Pinework reads it to pick an agent. Null when not set.

string

required

active, idle, running, terminated or error.

string

Model id. Null means the workspace default.

string

Failover model. Null means the workspace default.

string

required

claude, opencode, cursor, codex or command. Derived from the model when you set none.

string

required

device or cloud.

string

required

Workspace UUID.

string

Device folder runs start in. Null means the home folder.

string

Repo UUID for cloud runs. Null when not set.

string

Owner’s UUID. Null when no person owns the agent.

string

required

company or private.

string

UUID of the agent this one reports to. Null when none.

boolean

required

Wake when assigned a task.

boolean

required

Wake on a webhook.

string

Fallback tool-permission mode: strict, ask or full. Null means inherit.

integer

required

Spend this month, in cents.

string

When the agent’s last run ended. Null when no run has ended.

string

Null unless the agent is deleted.

string

required

Creation time.

string

required

Last change time.

Create and update responses add audit: the agent doctor’s warnings. Warnings never block the write.

Settings

GET /agents/{agentId}/config returns the writable settings, plus agentMd and a slug. You change them with PUT /agents/{agentId}/config or agent config set, not with PATCH.

object

required

Show properties

string

Model id. Null inherits.

string

Failover model. Null inherits.

string

none, minimal, low, medium, high, xhigh or max. Null inherits.

string

small, medium or large. Null inherits.

string

Harness override. Null derives it from the model.

string

required

device or cloud.

integer

Turn cap per run, 1 to 1,000. Null uses the workspace default, then no cap.

object

required

wakeOnAssignment and wakeOnHook.

object

required

Show properties

object

required

allow, ask and deny rule lists, and defaultMode.

string[]

required

Any of manage_agents, manage_projects, manage_runs, manage_secrets.

The agent has no access mode setting. Each run resolves it from the model and the provider key. The run shows it as effectiveSettings.accessMode: credits, byok or subscription. An agent can change its own AGENT.md, model, backupModel, reasoningEffort, sandboxSize, harness and maxTurns. Any other change by an agent raises an approval. Changing permissions as a person needs a workspace admin.

Config revisions

Each config write stores a revision. GET /agents/{agentId}/revisions lists them, newest first. A revision has id, agentId, beforeConfig, afterConfig, changedKeys, changeDescription, source (patch or rollback) and createdAt. A rollback writes the revision’s afterConfig back as a new revision with source: "rollback". agent history and agent revert cover the same changes, plus skill and rule changes.

CLI

Command	Does
`pinework agent list`	List agents, newest first. Filter with `--status`, `--role` or `--q`.
`pinework agent get [<agent> …]`	Print one or more agents. Defaults to the caller.
`pinework agent create`	Create an agent. `--name` is required. `--role` defaults to `agent`.
`pinework agent update <agent>`	Change name, role, description, status, visibility, manager, folder, repo or AGENT.md.
`pinework agent config get [<agent>]`	Print the settings.
`pinework agent config set [<agent>]`	Set model, backup model, effort, max turns, harness, environment, sandbox size, mode or AGENT.md.
`pinework agent identity [<agent>]`	Print AGENT.md and the agent rules. The hash goes to stderr.
`pinework agent doctor [<agent>]`	Audit name, role, description and instructions. Changes nothing.
`pinework agent history [<agent>]`	List who changed which setting, newest first. `--kind` narrows.
`pinework agent revert <entryId>`	Undo one history entry. The revert is a new entry.
`pinework agent run [<agent>]`	Wake the agent for an on-demand run. Takes `--task-id` and `--prompt`.
`pinework agent delete <agent>`	Soft-delete the agent and unassign its open tasks. `agent restore` undoes it.
`pinework agent transfer-owner <agent>`	Give the agent to `--new-owner`.

agent run also lists --model, --effort and --env. On main the request drops them, so the run uses the agent’s settings. The agent rule verbs are on Rule.

pinework agent create --name "Builder" --role "Builds features and opens pull requests" --model claude-sonnet-4-6 --environment cloud
pinework agent config set @builder --max-turns 200 --reasoning-effort high
pinework agent history @builder --kind agent.config
pinework agent update @builder --status terminated

API

Method	Path	Does
GET	`/api/v1/agents`	List agents. `ids=a,b` reads several at once.
POST	`/api/v1/agents`	Create an agent. Returns 201.
GET	`/api/v1/agents/{agentId}`	Read one agent.
PATCH	`/api/v1/agents/{agentId}`	Change identity, status, visibility, manager, folder or repo.
DELETE	`/api/v1/agents/{agentId}`	Soft-delete. Returns the unassigned tasks.
POST	`/api/v1/agents/{agentId}/restore`	Restore. Owner or workspace admin only.
GET	`/api/v1/agents/{agentId}/config`	Read settings and AGENT.md.
PUT	`/api/v1/agents/{agentId}/config`	Write settings, AGENT.md or both.
GET	`/api/v1/agents/{agentId}/revisions`	List config revisions.
GET	`/api/v1/agents/{agentId}/revisions/{revisionId}`	Read one revision.
POST	`/api/v1/agents/{agentId}/revisions/{revisionId}/rollback`	Roll config back to that revision.
GET	`/api/v1/agents/{agentId}/history`	List config history entries.
POST	`/api/v1/agents/{agentId}/history/{entryId}/revert`	Undo one history entry.
GET	`/api/v1/agents/{agentId}/identity`	Read AGENT.md, its hash and the agent rules.
PUT	`/api/v1/agents/{agentId}/identity/agent-md`	Replace AGENT.md.
GET	`/api/v1/agents/{agentId}/audit`	Run the agent doctor.
POST	`/api/v1/agents/{agentId}/clones`	Copy an agent under a new name. Returns 201.
POST	`/api/v1/agents/{agentId}/transfer-owner`	Set a new owner. Body `{newOwnerId}`.
GET	`/api/v1/agents/{agentId}/projects`	List projects the agent has a grant on.
POST	`/api/v1/agents/{agentId}/sessions/reset`	Make the next runs start a fresh harness session.
POST	`/api/v1/agents/{agentId}/runs`	Start a run. See Run.

Create, delete and clone by an agent raise an approval. So does an agent changing another agent. The route then returns 202 with object: "platform_change", an approvalId and status: "pending".

Errors

Code	HTTP	When	What to do
`config_write_forbidden`	400	A PATCH carried a settings key such as `model` or `maxTurns`.	Send it to `PUT /agents/{agentId}/config`.
`identity_write_forbidden`	400	An agent sent `identityMd` in a PATCH.	Use `agent update --agent-md`.
`invalid_status_transition`	422	The status move is not in the transitions table.	Pick an allowed target.
`reporting_cycle`	400	The new manager reports, directly or not, to this agent.	Pick another manager.
`handle_taken`	409	Another write took the same handle.	Save again.
`folder_requires_device_environment`	422	A cloud agent was given a default folder, or an agent with one was moved to the cloud.	Clear the folder, or keep the agent on a device.
`default_folder_forbidden`, `default_repo_forbidden`	403	You changed the folder or repo but are not the owner or a workspace admin.	Ask one of them.
`agent_self_only`	403	An agent read or wrote another agent’s config, or reverted its history.	Act on your own agent.
`agent_config_human_only`	403	An agent reverted a change to a setting only a person may set.	Ask a person.
`agent_md_stale`	409	An agent saved AGENT.md without the current hash.	Re-apply the edit to `details.agentMd`, then send `details.agentMdHash`.
`config_revert_unsupported`	422	This kind of history entry cannot be reverted.	Make the change by hand.
`restore_forbidden`	403	You are not the owner or a workspace admin.	Ask one of them.
`not_deleted`	409	The agent is not deleted.	Nothing to restore.
`list_deleted_forbidden`	403	An agent listed deleted agents.	Ask a person.
`owner_transfer.forbidden`	403	You are not the owner or a workspace admin.	Ask one of them.
`owner_transfer.same_owner`	409	The agent already belongs to that user.	No change needed.
`owner_transfer.user_not_found`	404	The new owner is not a member.	Pick a member.
`platform_change_requires_run`	403	An agent outside a live run asked for a change that needs approval.	Ask from inside a run.

A rollback returns 409 with an error string when the revision already matches the live config. Shared codes are in API errors.

Limits

maxTurns takes 1 to 1,000. Null falls back to the workspace’s defaultMaxTurns, then to no cap.
GET /agents returns 25 per page by default and 100 at most. q holds up to 100 characters.
ids takes up to 100 refs.

Agents

What an agent is and what wakes it.

Create an agent

Add an agent and pick its model.

Run

What one wake of an agent produces.

Rule

Agent rules and AGENT.md edits.

Start here

Work

Agents

Automate

Connect

States

Fields

Settings

Config revisions

CLI

API

Errors

Limits

Agents

Create an agent

Run

Rule

​States

​Fields

​Settings

​Config revisions

​CLI

​API

​Errors

​Limits

Agents

Create an agent

Run

Rule

States

Fields

Settings

Config revisions

CLI

API

Errors

Limits