37 operations. Call each with POST https://app.chirply.io/api/v1/actions/<name> and a bearer token; the response is { "data": { "action", "summary", "result" } }. A read badge means the operation changes nothing; write requires the credential’s write scope.
Approve a proposed action
ai_employees.approvewriteconfirmadmin only
Authorize (or refuse) an action an AI employee proposed and stopped on, then let it carry on. Approving RUNS the action for real — it is one the employee flagged as irreversible, outward-facing, or costly, so it may send messages to real people, spend the organization's money, or destroy data. Refusing tells the employee no and it continues without it. Either way the employee resumes and its follow-up reply is returned.
Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.
Parameters
Field
Type
Required
Description
approval_id
string (uuid)
required
The pending approval to resolve, from ai_employees.list_approvals.
approve
boolean
optional
true runs the action; false declines it and the employee moves on. Default: true
Over MCP the same operation is the tool ai_employees_approve at https://app.chirply.io/api/mcp, same bearer token, same input.
Give an employee work
ai_employees.askwrite
Hand a task or message to an AI employee and get its reply. The employee acts for real within its granted areas — reading and writing actual account records — and its turn consumes the organization's own OpenRouter credits immediately. Anything risky it wants to do (sending real messages, spending money, deleting) is NEVER run off its own decision: those come back in `pending` and appear in ai_employees.list_approvals for a second, deliberate ai_employees.approve call. Continues an existing conversation when you pass thread_id, otherwise starts one. A paused employee refuses new work.
Parameters
Field
Type
Required
Description
employee_id
string (uuid)
required
Which employee to task, from ai_employees.list.
message
string
required
The task or message, in plain language, as you'd brief a coworker.
thread_id
string (uuid)
optional
Continue this conversation with the employee. Omit to start a new one.
image_asset_ids
array of (string (uuid))
optional
Up to 4 uploaded image IDs from this account's media library (PNG, JPEG, WebP or GIF, maximum 6 MB each). The employee reads their visible contents using the account's metered vision model; this consumes AI credits in addition to the reply. Upload with assets.upload first.
Over MCP the same operation is the tool ai_employees_ask at https://app.chirply.io/api/mcp, same bearer token, same input.
Today's AI spend
ai_employees.budgetread
Reports how many tokens an AI employee has used since midnight UTC against its daily token budget, and whether that budget is currently stopping it from taking work. An employee with no budget set has no ceiling. This is the number that decides whether the next scheduled run happens, so it is worth checking when a duty has gone quiet.
Over MCP the same operation is the tool ai_employees_budget at https://app.chirply.io/api/mcp, same bearer token, same input.
Cancel report delivery
ai_employees.cancel_duty_deliverywriteadmin only
Cancels a report delivery waiting for its run, queued for sending, or failed before provider submission. Keeps its saved report and history; does not stop the AI run. Cannot recall a sent message or stop a provider submission already in progress. Cancelling spends no credits.
Parameters
Field
Type
Required
Description
delivery_id
string (uuid)
required
Delivery to cancel, from ai_employees.list_duty_deliveries.
Over MCP the same operation is the tool ai_employees_cancel_duty_delivery at https://app.chirply.io/api/mcp, same bearer token, same input.
Add a standing duty
ai_employees.create_dutywriteconfirmadmin only
Puts an AI employee on a schedule: from now on it runs the brief you give here, on its own, with nobody watching. EVERY run consumes the organization's own OpenRouter credits, and a duty set to run every 15 minutes runs ~96 times a day — the cost is recurring, not one-off. The employee acts for real within the areas it was hired with; anything risky (sending messages, spending money, deleting) still stops as a proposal in the approvals inbox rather than happening unattended. The configured report destination is standing permission for that report delivery, including billable email/SMS when selected. Other risky actions still need approval. The run acts under the authority of the employee's supervisor, and stops working entirely if that person leaves the account.
Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.
Parameters
Field
Type
Required
Description
employee_id
string (uuid)
required
Which employee takes on the duty, from ai_employees.list.
name
string
required
Short name for the job, as it appears on the duty list, e.g. 'Work new leads'.
task
string
required
The brief handed to the employee on EVERY run, in plain language, as you'd brief a colleague. Each run starts a fresh conversation, so write it to stand alone rather than referring to a previous run.
When to run: 'interval' = every N minutes; 'daily' = a local clock time; 'weekly' = selected weekdays at that time; 'monthly' = day_of_month at that time (shorter months use their last day); 'once' = a future run_at instant, then pauses; 'event' = a matching team-chat event. Each run spends AI credits. Execution follows the scheduler tick, so a chosen time is not a second-exact guarantee. Report delivery has its own timing fields.
interval_minutes
integer
optional
For cadence 'interval': how many minutes between runs. Minimum 5 (the scheduler ticks every 5 minutes, and a tighter loop only burns the workspace's own AI credits faster). 60 = hourly, 1440 = daily.
at_minute
integer
optional
For cadence 'daily', 'weekly' or 'monthly': local run time as minutes past midnight in timezone. 540 = 9:00am, 1020 = 5:00pm.
weekday
integer
optional
For cadence 'weekly': which day, 0 = Sunday through 6 = Saturday, in `timezone`.
weekdays
integer[] (or null)
optional
For cadence 'weekly': selected days (0 Sunday through 6 Saturday), e.g. [1,2,3,4,5] for weekdays. Overrides legacy weekday; null restores that single-day field.
day_of_month
integer (or null)
optional
For cadence 'monthly': calendar day 1–31. A shorter month runs on its final day. Pass null to clear when changing cadence.
run_at
string (date-time) (or null)
optional
For cadence 'once': a future ISO datetime including Z or UTC offset. Runs once, then pauses. Pass null to clear when changing cadence.
timezone
string
optional
IANA timezone for calendar schedules, e.g. 'America/New_York'. Defaults to UTC. Interval runs use elapsed minutes; once uses the explicit offset in run_at.
delivery_kind
"none" | "chat" | "email" | "sms"
optional
Where completed reports go. Choosing email or SMS grants standing permission to send this duty's reports to report_to_contact_id using the account's configured provider; provider charges and recipient consent policies apply. Other employee actions still require their normal approvals. Omitted on create: chat if report_to_channel_id is set, otherwise none.
report_to_contact_id
string (uuid) (or null)
optional
Existing account contact receiving this duty's email or SMS reports, from contacts.list. Its relevant email or phone and consent must be valid. Null clears the recipient; required for email/SMS.
delivery_mode
"immediate" | "daily"
optional
Deliver each completed report immediately, or queue it until the next daily delivery_at_minute in delivery_timezone. This does not change when the AI runs and does not merge separate reports into a digest.
delivery_at_minute
integer (or null)
optional
For daily delivery: local report time in minutes past midnight (540 = 09:00). Applies to completed reports at the next occurrence, independently of the run schedule.
delivery_timezone
string (or null)
optional
IANA timezone for report delivery, e.g. America/Chicago. Defaults to the run timezone when omitted on create.
event_type
"chat_message" | "chat_everyone"
optional
For cadence 'event': what sets the duty off. 'chat_message' = any message a person posts in the watched channel; 'chat_everyone' = only a message that addresses the whole room (@all / @everyone / @channel / @here). The employee's own posts never set it off.
event_channel_id
string (uuid)
optional
For cadence 'event': the team-chat channel being watched, from team_chat.list_channels. A burst of messages produces ONE run, not one per message — the employee reads what it missed when it runs.
event_keywords
string[]
optional
For cadence 'event': wake words. When set, the duty runs only if a new message contains one of these words or phrases (case-insensitive, whole words); every other message is skipped without calling a model or spending AI credits. An empty array wakes for every message.
event_senders
"everyone" | "github_linked"
optional
For cadence 'event': who the duty responds to. 'github_linked' runs only for messages from people with a GitHub username on their profile or linked in this account; everyone else's messages are skipped without calling a model or spending AI credits. 'everyone' (the default) responds to anyone.
status
"active" | "paused"
optional
Start it running ('active', the default) or set it up switched off ('paused').
report_to_channel_id
string (uuid)
optional
Destination for delivery_kind chat, from team_chat.list_channels. Naming it grants standing permission to post completed reports as the employee. Internal chat has no provider send charge. Email/SMS instead use report_to_contact_id; all results remain in Activity.
Over MCP the same operation is the tool ai_employees_create_duty at https://app.chirply.io/api/mcp, same bearer token, same input.
Delete an AI employee
ai_employees.deletewriteconfirmadmin only
Permanently delete an AI employee. Its conversations, run history, and pending approvals go with it, and this cannot be undone. Anything it already did to the account stays done. To stop one temporarily, pause it with ai_employees.update instead.
Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.
Over MCP the same operation is the tool ai_employees_delete at https://app.chirply.io/api/mcp, same bearer token, same input.
Delete a standing duty
ai_employees.delete_dutywriteconfirmadmin only
Permanently removes a standing duty. The employee stops running it. Past runs stay in the activity log, but the duty itself and its schedule are gone and cannot be recovered — pause it instead if you might want it back.
Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.
Parameters
Field
Type
Required
Description
duty_id
string (uuid)
required
Which duty to delete, from ai_employees.list_duties.
Over MCP the same operation is the tool ai_employees_delete_duty at https://app.chirply.io/api/mcp, same bearer token, same input.
Open an AI employee
ai_employees.getread
Fetch one AI employee: its persona, standing instructions, its own reference knowledge, permission grants, status, its most recent runs (what it has actually done), and how many of its proposed actions are still waiting for approval.
Over MCP the same operation is the tool ai_employees_get at https://app.chirply.io/api/mcp, same bearer token, same input.
Review inbox run
ai_employees.get_inbox_runread
Read one employee inbox job's recorded run and all approval proposals in its conversation, including older jobs outside the recent activity page. Returns an explicit error if the job is missing or belongs elsewhere. Does not approve actions or send email.
Parameters
Field
Type
Required
Description
employee_id
string (uuid)
required
Existing AI employee ID in the active workspace.
run_id
string (uuid)
required
Run ID returned by ai_employees.inbox_activity for this employee.
Over MCP the same operation is the tool ai_employees_get_inbox_run at https://app.chirply.io/api/mcp, same bearer token, same input.
Hire an AI employee
ai_employees.hirewriteconfirmadmin only
Create a new AI employee: a persistent, named AI coworker that acts inside this account with the permissions you grant it. Once hired and given work, it operates real records — and in areas granted at the 'propose' level it can queue actions that, when approved, send real messages to real people, spend the organization's money, or delete data. Its work runs on the organization's own OpenRouter key and is billed to it; set `daily_token_budget` to cap what it may spend in a day.
Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.
Parameters
Field
Type
Required
Description
name
string
required
The employee's name, e.g. 'Sam'.
title
string
optional
Job title shown on the roster, e.g. 'SDR' or 'Support rep'.
avatar_emoji
string
optional
An emoji used as this employee's face on the roster and in its chat header, e.g. '🤖'. Cosmetic only — it changes nothing about what the employee can do. Defaults to 🤖.
persona
string
optional
Who the employee is — tone, personality, background. Shapes how it writes and speaks.
instructions
string
optional
Standing duties and rules it must follow on every task, in plain language.
knowledge
string
optional
Reference information only this employee may rely on — background it answers from, in every room it works in: its own console, team chat, and its scheduled duties. This is FACTS, not orders (use `instructions` for what it must do) and not the account-wide Knowledge Brain (`brain_mode`), which every employee and every customer-facing agent shares. Plain sentences or a list; it is injected into the prompt verbatim.
grants
map of string → "view" | "work" | "propose"
optional
Feature areas the employee may touch, as { domain: level } — e.g. { "contacts": "work", "communications": "propose" }. Valid domains come from ai_employees.list_grantable_areas; unknown domains are refused. Areas left out are off limits entirely. Default: {}
model
string
optional
OpenRouter model id to run it on, e.g. 'anthropic/claude-sonnet-4.5'. Must be a real vendor/model id — it is sent to OpenRouter verbatim on every turn. Omit for the account default.
brain_mode
"all" | "topics" | "none"
optional
Brain access: all topics, selected topics from brain_topic_ids, or none. Selected topics are enforced when preparing employee context.
brain_topic_ids
array of (string (uuid))
optional
Selected Brain topic IDs in this account. Used when brain_mode is topics; an empty selection gives no Brain content.
autonomous_chat
boolean
optional
Standing permission to send internal team-chat messages as the employee in joined rooms, within its grants and the operator's access. Not permission for SMS, email, deletion or purchases. Default false.
daily_token_budget
integer
optional
The most thinking this employee may do in one day, in tokens, on the organization's OWN OpenRouter credits. Once the day's usage reaches it the employee stops taking work — chat, tasks and scheduled duties alike — until midnight UTC, which is what stops a duty running up a bill overnight. Omit for no ceiling. Read the spend against it with ai_employees.budget.
answers_everyone
boolean
optional
Whether this employee also answers '@all' (and @everyone/@channel/@here) in the team-chat rooms it sits in. Default false: a room-wide call is normally aimed at the people in it, and every AI in the room answering costs a turn each. Being named directly always reaches the employee regardless of this.
start_paused
boolean
optional
Create the employee paused instead of active, so it can be reviewed and started deliberately later. A paused employee takes no turns and runs no duties; resume it with ai_employees.update once you are satisfied with its permissions. Default: false
Over MCP the same operation is the tool ai_employees_hire at https://app.chirply.io/api/mcp, same bearer token, same input.
Inbox activity
ai_employees.inbox_activityread
Read durable Gmail jobs for one employee, including originating account and sender, subject, reasoning summary, errors, run links and whether manager approval is pending. Reads existing activity only; does not retry jobs or send email.
Parameters
Field
Type
Required
Description
employee_id
string (uuid)
required
Existing AI employee ID in the active workspace.
limit
integer
optional
Maximum recent inbox jobs to return, from one to one hundred. Default: 30
Over MCP the same operation is the tool ai_employees_inbox_activity at https://app.chirply.io/api/mcp, same bearer token, same input.
AI employees
ai_employees.listread
List the account's AI employees — its named, persistent AI coworkers — with each one's status (active or paused) and a plain-language summary of which feature areas it may touch and at what level.
Over MCP the same operation is the tool ai_employees_list at https://app.chirply.io/api/mcp, same bearer token, same input.
Approvals inbox
ai_employees.list_approvalsread
List the actions AI employees have proposed and stopped on — the risky ones (sending real messages, spending money, deleting data) that never run without a deliberate authorization. Each entry names the employee, the capability it wants to run, and the exact arguments. Pending ones are resolved with ai_employees.approve, which IS manager-only.
Over MCP the same operation is the tool ai_employees_list_approvals at https://app.chirply.io/api/mcp, same bearer token, same input.
Choose Brain topics
ai_employees.list_brain_topicsreadadmin only
List this account's Brain topic names and descriptions for employee knowledge selection. Reads metadata only; does not expose item bodies or spend credits.
Over MCP the same operation is the tool ai_employees_list_brain_topics at https://app.chirply.io/api/mcp, same bearer token, same input.
Standing duties
ai_employees.list_dutiesread
Lists the standing duties an AI employee runs on a schedule — what each one is briefed to do, how often it runs, when it next runs, and whether it has been failing. A duty runs unattended and spends the organization's own OpenRouter credits every time it fires, so this is the list of what the account is paying for on a timer.
Parameters
Field
Type
Required
Description
employee_id
string (uuid)
optional
Only this employee's duties. Omit for every duty in the account.
Over MCP the same operation is the tool ai_employees_list_duties at https://app.chirply.io/api/mcp, same bearer token, same input.
Report deliveries
ai_employees.list_duty_deliveriesreadadmin only
Lists saved report delivery states, scheduled send times and errors for this account's standing duties. No messages are sent and no AI credits are spent. 'needs_review' means a provider submission may have happened; do not resend blindly.
Parameters
Field
Type
Required
Description
employee_id
string (uuid)
optional
Limit to this employee, from ai_employees.list.
duty_id
string (uuid)
optional
Limit to this duty, from ai_employees.list_duties.
limit
integer
optional
Maximum deliveries to return, newest first. Defaults to 30.
Over MCP the same operation is the tool ai_employees_list_duty_deliveries at https://app.chirply.io/api/mcp, same bearer token, same input.
Grantable areas
ai_employees.list_grantable_areasread
List the feature areas an AI employee can be granted access to, with a plain-language label, every action the area contains (machine name, title, whether it reads or writes, and whether it is risky), and whether the area belongs to a paid app. Areas marked `licensed: false` are apps this account has not installed — granting one is refused, so install it from the App Marketplace first. Use these domain names to build a valid `grants` object for ai_employees.hire or ai_employees.update. Read-only.
Over MCP the same operation is the tool ai_employees_list_grantable_areas at https://app.chirply.io/api/mcp, same bearer token, same input.
Employee inboxes
ai_employees.list_inboxesread
Read an existing AI employee's Gmail assignments, shared account connection status, and exact actions permitted by both employee grants and caller access. Does not read message bodies, connect accounts or activate inbox work.
Over MCP the same operation is the tool ai_employees_list_inboxes at https://app.chirply.io/api/mcp, same bearer token, same input.
Employee activity
ai_employees.list_runsread
The AI employees' activity feed: every run — a task handed to an employee and what came of it — newest first, with its status (running, waiting on an approval, completed, failed), a one-line summary, and how many actions it took. Optionally filter to one employee.
Over MCP the same operation is the tool ai_employees_list_runs at https://app.chirply.io/api/mcp, same bearer token, same input.
Pause account
ai_employees.pause_inboxwriteadmin only
Pause one employee Gmail assignment to stop new jobs and block further tools or approvals for its existing jobs. Retains configuration, mail and activity. An action already accepted by an external provider cannot be recalled by pausing.
Parameters
Field
Type
Required
Description
employee_id
string (uuid)
required
Existing AI employee ID in the active workspace.
inbox_id
string (uuid)
required
Assignment ID returned by ai_employees.list_inboxes for this employee.
Over MCP the same operation is the tool ai_employees_pause_inbox at https://app.chirply.io/api/mcp, same bearer token, same input.
Retry report delivery
ai_employees.retry_duty_deliverywriteconfirmadmin only
Queues a failed report for another delivery attempt only when it is known no provider submission occurred. Sending an email or SMS uses the account's provider and may incur its normal charges; recipient consent and current permissions are checked again. Does not rerun the AI. A sent, in-progress or uncertain delivery cannot be retried here, preventing duplicate messages and charges.
Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.
Parameters
Field
Type
Required
Description
delivery_id
string (uuid)
required
A failed delivery with retry_safe true, from ai_employees.list_duty_deliveries.
Over MCP the same operation is the tool ai_employees_retry_duty_delivery at https://app.chirply.io/api/mcp, same bearer token, same input.
Run a duty now
ai_employees.run_dutywriteconfirmadmin only
Runs a standing duty immediately instead of waiting for its next scheduled time, and returns what the employee did. This is a real run: it acts on real account records and spends the organization's own OpenRouter credits now. It does not change the schedule — the next scheduled run still happens as planned. Anything risky the employee wants to do comes back as a proposal in ai_employees.list_approvals rather than being carried out. A paused duty can be run this way; a paused employee refuses.
Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.
Parameters
Field
Type
Required
Description
duty_id
string (uuid)
required
Which duty to run right now, from ai_employees.list_duties.
Over MCP the same operation is the tool ai_employees_run_duty at https://app.chirply.io/api/mcp, same bearer token, same input.
Save inbox assignments
ai_employees.save_inboxeswriteconfirmadmin only
Configure selected connected Gmail accounts for an existing employee. Active assignments process future eligible mail using the account's OpenRouter credits, within existing employee grants; all writes and replies require manager approval. Paused saves configuration, and older messages are never enrolled. Does not activate a paused employee or send email itself.
Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.
Parameters
Field
Type
Required
Description
employee_id
string (uuid)
required
Existing AI employee ID in the active workspace.
connection_ids
array of (string (uuid))
required
One to twenty connected Gmail account IDs already shared with this workspace. Saves these accounts atomically and preserves other assignments.
instructions
string
required
Standing instructions for handling new messages on the selected accounts. Email bodies remain untrusted data and cannot override these instructions or permissions.
allowed_capabilities
string[]
required
Exact capability names from ai_employees.list_inboxes actions. Limited to the employee's existing grants; every write requires human approval.
status
"active" | "paused"
optional
Paused saves configuration. Active handles future eligible mail using the workspace's OpenRouter credits while the employee is active; never imports older mail or activates a paused employee. Default: "paused"
approval_policy
"always"
optional
Every write, including Gmail replies and CRM changes, is proposed for manager approval. Automatic sending is not enabled. Default: "always"
Over MCP the same operation is the tool ai_employees_save_inboxes at https://app.chirply.io/api/mcp, same bearer token, same input.
Pause or resume every AI employee
ai_employees.set_all_statuswriteconfirmadmin only
Pause, or put back to work, EVERY AI employee in the account in one call — the roster's own “Pause all” button. Pausing stops all of them taking new work and stops their standing duties running on schedule; nothing is deleted and every configuration, conversation and run log is kept, so resuming puts them back exactly as they were. Resuming starts scheduled duties again, which can send real messages and spend the account's own OpenRouter credits. Employees already in the requested state are left alone, and the reply counts only the ones that actually changed. To change one employee, use ai_employees.update.
Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.
Parameters
Field
Type
Required
Description
status
"active" | "paused"
required
What to set every employee to: 'paused' stops them all taking new work and halts their scheduled duties; 'active' puts them all back on the clock and lets those duties run again.
Over MCP the same operation is the tool ai_employees_set_all_status at https://app.chirply.io/api/mcp, same bearer token, same input.
Pause or resume a duty
ai_employees.set_duty_statuswriteadmin only
Switches a standing duty off ('paused') or back on ('active'). Pausing is the stop button: it takes effect before the next run, costs nothing, and keeps the duty and its history intact. Resuming re-arms the schedule from now — it does not replay runs missed while it was off. Resuming also clears the failure counter, so a duty that auto-paused itself after repeated failures starts fresh.
Parameters
Field
Type
Required
Description
duty_id
string (uuid)
required
Which duty, from ai_employees.list_duties.
status
"active" | "paused"
required
'paused' stops it before the next run; 'active' puts it back on the clock.
Over MCP the same operation is the tool ai_employees_set_duty_status at https://app.chirply.io/api/mcp, same bearer token, same input.
Edit an AI employee
ai_employees.updatewriteadmin only
Update an AI employee's name, title, face emoji, persona, standing instructions, its own reference knowledge, permission grants, model, knowledge-base access, daily token budget, or status. Omitted fields are left alone; a supplied `grants` object REPLACES the previous grants entirely. Setting status to 'paused' stops it taking new work without losing its configuration or history; 'active' puts it back to work. Raising or removing `daily_token_budget` raises what the account can spend on this employee's OpenRouter usage in a day.
Parameters
Field
Type
Required
Description
id
string (uuid)
required
The employee to edit.
name
string
optional
New name.
title
string (or null)
optional
New job title. null clears it.
avatar_emoji
string (or null)
optional
New face emoji, e.g. '🤖'. null clears it back to the default. Cosmetic only.
persona
string (or null)
optional
New persona. null clears it.
instructions
string (or null)
optional
New standing duties. null clears them.
knowledge
string (or null)
optional
New reference information for this one employee — background it answers from in every room it works in: its own console, team chat, and its scheduled duties. FACTS, not orders (use `instructions` for what it must do) and not the account-wide Knowledge Brain (`brain_mode`), which every employee and every customer-facing agent shares. REPLACES the stored text entirely, so send the whole thing rather than the part you are adding; read the current value with ai_employees.get first. null clears it.
grants
map of string → "view" | "work" | "propose"
optional
Feature areas the employee may touch, as { domain: level } — e.g. { "contacts": "work", "communications": "propose" }. Valid domains come from ai_employees.list_grantable_areas; unknown domains are refused. Areas left out are off limits entirely.
model
string (or null)
optional
New OpenRouter model id, in vendor/model form. null reverts to the account default.
brain_mode
"all" | "topics" | "none"
optional
Brain access: all topics, selected topics from brain_topic_ids, or none. Selected topics are enforced when preparing employee context.
brain_topic_ids
array of (string (uuid))
optional
Replace the selected Brain topic IDs. Every topic must belong to this account. Empty means no selected content.
autonomous_chat
boolean
optional
Allow internal team-chat messages without per-message approval in rooms the employee has joined. Employee grants and operator access still apply. Email, SMS and other actions retain their own approval rules.
daily_token_budget
integer (or null)
optional
New daily token ceiling, spent on the organization's own OpenRouter credits; the employee stops taking work once the day's usage reaches it and resumes at midnight UTC. null removes the ceiling entirely. This is the number ai_employees.budget reports against, so it is what to change when a duty has gone quiet because the budget ran out.
answers_everyone
boolean
optional
Whether this employee also answers '@all' (and @everyone/@channel/@here) in the team-chat rooms it sits in. Default false: a room-wide call is normally aimed at the people in it, and every AI in the room answering costs a turn each. Being named directly always reaches the employee regardless of this.
status
"active" | "paused"
optional
'active' = working; 'paused' = keeps its configuration and history but refuses new work.
Over MCP the same operation is the tool ai_employees_update at https://app.chirply.io/api/mcp, same bearer token, same input.
Edit a standing duty
ai_employees.update_dutywriteconfirmadmin only
Changes a standing duty's brief, schedule or report destination. Saving an email/SMS recipient authorizes future report sends with normal provider charges and consent checks. Tightening the schedule increases how often the account's own OpenRouter credits are spent — every run costs, so 'every hour' to 'every 5 minutes' is a twelvefold increase in spend, not a preference. To simply stop or restart a duty, use ai_employees.set_duty_status instead.
Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.
Parameters
Field
Type
Required
Description
duty_id
string (uuid)
required
Which duty to change, from ai_employees.list_duties.
When to run: 'interval' = every N minutes; 'daily' = a local clock time; 'weekly' = selected weekdays at that time; 'monthly' = day_of_month at that time (shorter months use their last day); 'once' = a future run_at instant, then pauses; 'event' = a matching team-chat event. Each run spends AI credits. Execution follows the scheduler tick, so a chosen time is not a second-exact guarantee. Report delivery has its own timing fields.
interval_minutes
integer
optional
For cadence 'interval': how many minutes between runs. Minimum 5 (the scheduler ticks every 5 minutes, and a tighter loop only burns the workspace's own AI credits faster). 60 = hourly, 1440 = daily.
at_minute
integer
optional
For cadence 'daily', 'weekly' or 'monthly': local run time as minutes past midnight in timezone. 540 = 9:00am, 1020 = 5:00pm.
weekday
integer
optional
For cadence 'weekly': which day, 0 = Sunday through 6 = Saturday, in `timezone`.
weekdays
integer[] (or null)
optional
For cadence 'weekly': selected days (0 Sunday through 6 Saturday), e.g. [1,2,3,4,5] for weekdays. Overrides legacy weekday; null restores that single-day field.
day_of_month
integer (or null)
optional
For cadence 'monthly': calendar day 1–31. A shorter month runs on its final day. Pass null to clear when changing cadence.
run_at
string (date-time) (or null)
optional
For cadence 'once': a future ISO datetime including Z or UTC offset. Runs once, then pauses. Pass null to clear when changing cadence.
timezone
string
optional
IANA timezone for calendar schedules, e.g. 'America/New_York'. Defaults to UTC. Interval runs use elapsed minutes; once uses the explicit offset in run_at.
delivery_kind
"none" | "chat" | "email" | "sms"
optional
Where completed reports go. Choosing email or SMS grants standing permission to send this duty's reports to report_to_contact_id using the account's configured provider; provider charges and recipient consent policies apply. Other employee actions still require their normal approvals. Omitted on create: chat if report_to_channel_id is set, otherwise none.
report_to_contact_id
string (uuid) (or null)
optional
Existing account contact receiving this duty's email or SMS reports, from contacts.list. Its relevant email or phone and consent must be valid. Null clears the recipient; required for email/SMS.
delivery_mode
"immediate" | "daily"
optional
Deliver each completed report immediately, or queue it until the next daily delivery_at_minute in delivery_timezone. This does not change when the AI runs and does not merge separate reports into a digest.
delivery_at_minute
integer (or null)
optional
For daily delivery: local report time in minutes past midnight (540 = 09:00). Applies to completed reports at the next occurrence, independently of the run schedule.
delivery_timezone
string (or null)
optional
IANA timezone for report delivery, e.g. America/Chicago. Defaults to the run timezone when omitted on create.
event_type
"chat_message" | "chat_everyone"
optional
For cadence 'event': what sets the duty off. 'chat_message' = any message a person posts in the watched channel; 'chat_everyone' = only a message that addresses the whole room (@all / @everyone / @channel / @here). The employee's own posts never set it off.
event_channel_id
string (uuid)
optional
For cadence 'event': the team-chat channel being watched, from team_chat.list_channels. A burst of messages produces ONE run, not one per message — the employee reads what it missed when it runs.
event_keywords
string[]
optional
For cadence 'event': wake words. When set, the duty runs only if a new message contains one of these words or phrases (case-insensitive, whole words); every other message is skipped without calling a model or spending AI credits. An empty array wakes for every message.
event_senders
"everyone" | "github_linked"
optional
For cadence 'event': who the duty responds to. 'github_linked' runs only for messages from people with a GitHub username on their profile or linked in this account; everyone else's messages are skipped without calling a model or spending AI credits. 'everyone' (the default) responds to anyone.
report_to_channel_id
string (uuid) (or null)
optional
Change which team-chat channel this duty reports into, as the employee. Pass null to stop it announcing anywhere — the duty keeps running and its answers stay on the employee's run log.
Over MCP the same operation is the tool ai_employees_update_duty at https://app.chirply.io/api/mcp, same bearer token, same input.
Connect hosting provider
ai_runners.authorizewriteadmin only
Open account-bound provider authorization and return to this employee’s Infrastructure tab. When Cloudflare OAuth is unavailable, returns the scoped API token instructions. Connecting does not create paid resources.
Parameters
Field
Type
Required
Description
employee_id
string (uuid)
required
The AI employee to configure in this account.
provider
"cloudflare" | "digitalocean"
required
Cloudflare Containers or DigitalOcean App Platform in your connected account.
Over MCP the same operation is the tool ai_runners_authorize at https://app.chirply.io/api/mcp, same bearer token, same input.
Hosting connections
ai_runners.connect_optionsreadadmin only
Read this account’s Cloudflare and DigitalOcean hosting connections and available Cloudflare accounts. Provider credentials stay private. Does not create paid resources.
Over MCP the same operation is the tool ai_runners_connect_options at https://app.chirply.io/api/mcp, same bearer token, same input.
Save hosting connection
ai_runners.connect_tokenwriteconfirmadmin only
Verify and securely save a scoped provider API token for this account’s dedicated employee hosting connection. Replaces that hosting credential while preserving other provider integrations. Does not create paid resources. Use the secure Infrastructure form or a private API/MCP client, never a chat message.
Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.
Parameters
Field
Type
Required
Description
employee_id
string (uuid)
required
The AI employee to configure in this account.
provider
"cloudflare" | "digitalocean"
required
Cloudflare Containers or DigitalOcean App Platform in your connected account.
api_token
string
required
Private provider API token with the hosting permissions listed by Connect hosting provider.
Over MCP the same operation is the tool ai_runners_connect_token at https://app.chirply.io/api/mcp, same bearer token, same input.
Download setup
ai_runners.create_setupwriteconfirmadmin only
Create a one-use, one-hour installer for this employee on Cloudflare Containers or DigitalOcean App Platform. The returned installer contains a pairing secret; keep it private. Downloading is free. Running it creates two paid containers in the customer's provider account. Model usage is billed separately by the account's OpenRouter connection. Hosting switches only after a healthy runner is explicitly enabled.
Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.
Parameters
Field
Type
Required
Description
employee_id
string (uuid)
required
The AI employee to configure in this account.
provider
"cloudflare" | "digitalocean"
required
Cloudflare Containers or DigitalOcean App Platform in the customer's own account.
Over MCP the same operation is the tool ai_runners_create_setup at https://app.chirply.io/api/mcp, same bearer token, same input.
Deploy employee hosting
ai_runners.deploywriteconfirmadmin only
Create two paid employee runners on your connected Cloudflare or DigitalOcean account. Provider hosting charges start as resources are created; model usage is billed separately. Saves deployment progress and automatically routes new jobs to this host after a healthy heartbeat. Repeated calls reuse the current deployment. No local installer is required.
Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.
Parameters
Field
Type
Required
Description
employee_id
string (uuid)
required
The AI employee to configure in this account.
provider
"cloudflare" | "digitalocean"
required
Cloudflare Containers or DigitalOcean App Platform in your connected account.
account_id
string
optional
Cloudflare account ID selected from Hosting connections. Required when multiple accounts are available; omit for DigitalOcean.
Over MCP the same operation is the tool ai_runners_deploy at https://app.chirply.io/api/mcp, same bearer token, same input.
Remove employee hosting
ai_runners.remove_hostingwriteconfirmadmin only
Return new work to managed hosting, wait for existing runner jobs, then permanently delete the provider resources created by this employee’s saved deployment. Provider charges continue until deletion completes. Unrelated resources and legacy manual installations are not deleted.
Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.
Over MCP the same operation is the tool ai_runners_remove_hosting at https://app.chirply.io/api/mcp, same bearer token, same input.
Retry deployment
ai_runners.retrywriteconfirmadmin only
Resume the employee’s failed deployment or resource removal after checking the saved provider resources. Deployment can create paid resources; an existing installation is reused. Removal continues stopping its provider charges.
Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.
Over MCP the same operation is the tool ai_runners_retry at https://app.chirply.io/api/mcp, same bearer token, same input.
Disconnect runner
ai_runners.revokewriteconfirmadmin only
Revoke the customer runner's employee-scoped credential and return new jobs to managed hosting. In-flight unconfirmed actions require review. Does not delete Cloudflare or DigitalOcean resources or stop their charges; remove those in the provider account.
Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.
Over MCP the same operation is the tool ai_runners_revoke at https://app.chirply.io/api/mcp, same bearer token, same input.
Use this infrastructure
ai_runners.set_hostingwriteconfirmadmin only
Route new employee jobs to a connected customer runner, or return new jobs to Chirply-managed hosting. Existing leased work finishes on its current host. This does not delete paid provider resources; stop those in the provider account to stop their hosting charges.
Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.
Parameters
Field
Type
Required
Description
employee_id
string (uuid)
required
The AI employee to configure in this account.
customer_owned
boolean
required
True requires a recent runner heartbeat; false routes new work to managed hosting.
Chirply