Esc

↑↓ move↵ openIndex · Pagefind
Automations

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.

Live11 endpoints10 actions

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
Create an event rulecurl
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}})" }
      ]
    }
  }'
A schedule that scans recordsjson
{
  "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, observation
    overdue (open and past due) or date_offset (due date = today + days; negative days = after the date)
  • insurance_policy
    date_offset on the expiration date (company admins)
  • daily_log
    missing: each project with no completed daily log for the day
  • budget_line
    threshold: 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}}.

Dry runcurl
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.

  • notify
    In-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_task
    A project task with title, description, assignees and a due date N days out.
  • create_draft_rfi
    A draft RFI (subject, question, assignees). A person reviews and sends it.
  • create_draft_change_order
    Change event triggers: a draft potential change order on the project's first prime contract or a contract you name.
  • request_coi_renewal
    Insurance policy triggers: open (or reopen) the policy's renewal follow-up, owned by a company admin.
  • assign
    Task, RFI, observation or punch item triggers: set the assignee.
  • set_field
    due_date or priority on a task, RFI, observation or punch item. Status is never settable.
  • add_comment
    Comment on the task or punch item.
  • start_approval
    Change 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.
  • webhook
    Queue a signed automation.action delivery to one of your webhooks (it must subscribe to automation.action). Same signing, retries and history as other deliveries.
webhook action deliveryhttp
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 carry actor.automation_id). It never triggers the same rule again, and chains of rules stop at depth 3.
  • Rate limits. max_runs_per_hour per 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.

Ask the OS

Reading this page

Ask anything about this page. Answers use what you're reading as context.

Suggested

    AI · may be imperfect · sample data where shown

    Open file