The agent document

spinrun.agent/v1: identity, where it lives, what it is, what it may touch, and how it is invoked. Every top-level section is required. The server fills in id, slug, status and updated_at; a document you create must omit id and updated_at.

Agent fields

Field	Type	Required	Description
kind	"spinrun.agent/v1"	Yes	Document discriminator.
id	string	No	Server id. Omit when creating.
slug	string	No	URL slug. Cannot change after creation.
status	"draft" | "active" | "archived"	No	Read-only lifecycle status.
updated_at	string	No	Version stamp. Required on replace; travels as If-Match too.
name	string	Yes	Display name.
description	string | null	Yes	What the agent does.
icon	string | null	Yes	Icon preset.
space	object	Yes	Where the agent lives.
folder	string | null	Yes	Folder path within the space.
instructions	string	Yes	The system instructions.
model	string	Yes	Model id, e.g. spinrun default or a named model.
max_steps	integer	Yes	Maximum tool steps per run.
reasoning_effort	"low" | "medium" | "high" | null	No	Absent = the model default.
tools	object	Yes	What the agent may touch.
skills	string[]	Yes	Marketplace skill slugs.
workspace_skills	string[]	Yes	Workspace skill names.
workflows	string[]	Yes	Workflow slugs the agent may run.
schedule	object	Yes	When the agent runs on its own.
email	object	Yes	The email channel.
whatsapp	object	Yes	The WhatsApp channel.
triggers	object[]	Yes	Event triggers, at most 20.
eval_criteria	string | null	Yes	How a run is judged.

space

Field	Type	Required	Description
team	string | null	Yes	Team slug, or null for the workspace space.

tools

Field	Type	Required	Description
apps	string[]	Yes	App slugs the agent may use.
connections	"all" | string[]	Yes	"all" or explicit connection addresses.
disabled_tools	string[]	Yes	Tool slugs to hide.
approval	"destructive" | "write"	Yes	Which tool calls need human approval.

schedule

Field	Type	Required	Description
enabled	boolean	No	Whether the schedule fires.
cron	string	No	Cron expression for the schedule.
timezone	string	No	IANA timezone for the cron.
prompt	string	No	Prompt the scheduled run starts with.

email

Field	Type	Required	Description
enabled	boolean	No	Whether the email channel is on.
allowed_senders	string[]	No	Senders the agent answers.
allowed_recipients	string[]	No	Recipients the agent may mail.
from_name	string	No	Display name on outbound mail.
locale	string	No	Locale for email rendering.

whatsapp

Field	Type	Required	Description
enabled	boolean	No	Whether WhatsApp is on.

triggers[] ("webhook")

Field	Type	Required	Description
id	string	No	Server-assigned trigger id. Omit when creating.
kind	"webhook"	Yes	Trigger kind.
name	string	Yes	Trigger name.
prompt	string | null	No	Prompt the triggered run starts with.
enabled	boolean	No	Whether the trigger fires.
secret_prefix	string | null	No	Read-only display prefix of the webhook secret.

triggers[] ("poll")

Field	Type	Required	Description
id	string	No	Server-assigned trigger id. Omit when creating.
kind	"poll"	Yes	Trigger kind.
name	string	Yes	Trigger name.
prompt	string | null	No	Prompt the triggered run starts with.
enabled	boolean	No	Whether the trigger fires.
tool	string	Yes	Read-only tool slug the poll watches with.
args	object	No	Arguments for the detector tool.
cron	string	Yes	How often the detector runs.
timezone	string	Yes	IANA timezone for the cron.

triggers[] ("app_event")

Field	Type	Required	Description
id	string	No	Server-assigned trigger id. Omit when creating.
kind	"app_event"	Yes	Trigger kind.
name	string	Yes	Trigger name.
prompt	string | null	No	Prompt the triggered run starts with.
enabled	boolean	No	Whether the trigger fires.
app	string	Yes	App slug the event belongs to.
event	string	Yes	Event slug within the app.
connection	string	Yes	Connection address, e.g. github__main.
config	object	No	Trigger configuration.

Full JSON Schema: /schemas/agent-v1.json.

Related

• Workflow document
• Concurrency