When this happens, do that.
Rules run on any project record event in the webhook catalog or on a schedule, check conditions, then run a small set of safe actions with the rule owner's permissions. The same rules are built in the app under Company Admin → Automations and each project's Automations tool.
Rules
A rule has a trigger, optional conditions and up to 10 actions, wrapped in automation. project_id: null makes it company-wide (company admins only); a project rule needs Admin on that project's Automations tool. If the token is scoped it needs automations:read or automations:write. Creating, changing, deleting and testing rules are admin-class writes, so agent credentials can read rules and runs but never change them.
Saving a rule makes the caller its owner. Every action runs as the owner, through the same services and permission checks as the app, so a rule can never do more than its owner could do by hand. If the owner loses the right to manage automations there, the next run fails and the rule is paused.
- GET
/companies/{company_id}/automationsList rules (filters[project_id], filters[include_company], filters[enabled], search) - POST
/companies/{company_id}/automationsCreate a rule (off unless enabled: true) - GET
/companies/{company_id}/automations/{id}Show one - PATCH
/companies/{company_id}/automations/{id}Change it; the caller becomes the owner, a new version is saved - DELETE
/companies/{company_id}/automations/{id}Delete it; queued runs are skipped - POST
/companies/{company_id}/automations/{id}/testDry run with a sample: conditions trace and action previews, no side effects - GET
/companies/{company_id}/automations/{id}/runsRun history for one rule - GET
/companies/{company_id}/automations/{id}/versionsSaved versions - GET
/companies/{company_id}/automations/runsRun history across rules (filters[status], filters[project_id]) - GET
/companies/{company_id}/automations/runs/{run_id}One run: input, condition trace, each action outcome - GET
/companies/{company_id}/automations/catalogTriggers, fields per trigger, operators, actions, templates, pickers
curl -X POST https://app.os.construction/rest/v1.0/companies/{company_id}/automations \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"automation": {
"name": "Change order approved",
"project_id": null,
"enabled": true,
"trigger": { "kind": "event", "event_type": "change_order.approved" },
"conditions": { "match": "all", "rules": [
{ "field": "resource.amount", "operator": "gte", "value": 25000 }
] },
"actions": [
{ "type": "notify", "channels": ["in_app", "email"],
"recipients": { "roles": ["Project Executive", "Accounting"], "creator": true },
"subject": "Change order {{data.number}} approved on {{project.name}}",
"body": "{{data.title}} ({{resource.amount}})" }
]
}
}'{
"automation": {
"name": "Overdue RFI escalation",
"project_id": 7,
"enabled": true,
"trigger": { "kind": "schedule", "frequency": "weekdays", "time": "08:00",
"timezone": "America/Chicago", "scan": { "source": "rfi", "match": "overdue" } },
"conditions": { "match": "all", "rules": [
{ "field": "resource.days_overdue", "operator": "gte", "value": 3 }
] },
"actions": [
{ "type": "notify", "channels": ["in_app"], "recipients": { "assignees": true, "manager": true },
"subject": "{{resource.label}} is {{resource.days_overdue}} days overdue" },
{ "type": "create_task", "title": "Chase RFI {{resource.number}}", "assignees": { "roles": ["Project Manager"] }, "due_in_days": 1 }
]
}
}Triggers and conditions
{ "kind": "event", "event_type": "rfi.answered" } runs once per event. { "kind": "schedule", "frequency": "daily" | "weekdays" | "weekly", "time": "HH:MM", "weekday": 0-6, "timezone": "IANA" } runs once per period, or with scan once per matching record per day:
- rfi, submittal, punch_item, task, observationoverdue (open and past due) or date_offset (due date = today + days; negative days = after the date)
- insurance_policydate_offset on the expiration date (company admins)
- daily_logmissing: each project with no completed daily log for the day
- budget_linethreshold: committed + direct + pending costs at or over percent of the revised budget
Conditions are { "match": "all" | "any", "rules": [...] } with nested groups up to 3 deep and at most 25 conditions. Each condition is { field, operator, value }. Fields are data.* (the event payload), resource.* (the record, read as the owner: status, due date, days overdue, assignees, amounts), project.*, event.* and custom_fields.<definition id>. GET …/automations/catalog lists the fields for every trigger. Operators: eq, neq, gt, gte, lt, lte, in, not_in, contains, not_contains, is_empty, is_not_empty, includes_user. Date values accept today, today+7, today-3. Text in actions can use the same paths as {{placeholders}}, plus {{link}} and {{today}}.
curl -X POST https://app.os.construction/rest/v1.0/companies/{company_id}/automations/{id}/test \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "test": { "project_id": 7, "resource_id": 212 } }'
{
"run_id": "5c0d…",
"matched": true,
"skipped_reason": null,
"actions": [ { "index": 0, "type": "notify", "preview": "Notify 3 people (in-app + email): \"Change order 14 approved on Harbor View\"" } ],
"trace": { "match": "all", "result": true, "rules": [ { "field": "resource.amount", "operator": "gte", "value": 25000, "actual": "31250.00", "result": true } ] }
}Actions
Actions create, draft, assign, comment and notify. None approves, certifies, executes, posts, pays, deletes or sends anything outside your company.
- notifyIn-app notification and/or email to users, project team roles, the record's assignees, creator or manager, distribution groups, the owner or company admins. Only active people in the company, and only those who can open the record.
- create_taskA project task with title, description, assignees and a due date N days out.
- create_draft_rfiA draft RFI (subject, question, assignees). A person reviews and sends it.
- create_draft_change_orderChange event triggers: a draft potential change order on the project's first prime contract or a contract you name.
- request_coi_renewalInsurance policy triggers: open (or reopen) the policy's renewal follow-up, owned by a company admin.
- assignTask, RFI, observation or punch item triggers: set the assignee.
- set_fielddue_date or priority on a task, RFI, observation or punch item. Status is never settable.
- add_commentComment on the task or punch item.
- start_approvalChange order, payment application or submittal triggers: start the matching approval workflow as the owner (the approvals module picks the policy, or uses policy_id). If a run is already pending it is returned, so a retry never starts a second one. Approvers still decide.
- webhookQueue a signed automation.action delivery to one of your webhooks (it must subscribe to automation.action). Same signing, retries and history as other deliveries.
POST /os HTTP/1.1
X-OS-Event: automation.action
X-OS-Signature: sha256=…
{
"id": "…", "event": "automation.action", "company_id": 1, "created_at": "2026-11-21T14:03:10.000Z",
"data": {
"automation_id": 9, "automation_name": "Change order approved", "run_id": "…", "action_index": 1, "project_id": 7,
"trigger_event": { "id": "…", "type": "change_order.approved", "data": { "number": "14", "status": "approved" } },
"resource": { "type": "change_order", "id": 88 }
}
}Runs, retries and safety limits
- Once per event. A run is unique per rule and event (or per rule, record and day for schedules). Events reach rules from the same outbox as webhooks, in the transaction that dispatches them.
- No loops. A change an automation makes is recorded with actor type
automation, the owner's id and the rule id (webhook envelopes carryactor.automation_id). It never triggers the same rule again, and chains of rules stop at depth 3. - Rate limits.
max_runs_per_hourper rule (default 60, up to 500) and 2,000 runs an hour per company. Runs over a limit are logged as skipped. - Retries. Transient failures retry with exponential backoff, 5 attempts. Actions that finished are not repeated; an action whose result is unknown after a crash is marked uncertain rather than repeated, unless it is safe to repeat (webhook, renewal follow-up, assign, set field).
- Errors surface. Each run stores its input, the condition trace and every action's outcome. The owner is notified when a rule starts failing, and a rule pauses after 25 failed runs in a row.