Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Core Tools

Automations

11 endpoints11 implementedAll modules →
  1. GET /rest/v1.0/companies/{company_id}/automationsList automations
  2. POST /rest/v1.0/companies/{company_id}/automationsCreate an automation
  3. GET /rest/v1.0/companies/{company_id}/automations/{id}Show an automation
  4. PATCH /rest/v1.0/companies/{company_id}/automations/{id}Update an automation
  5. DELETE /rest/v1.0/companies/{company_id}/automations/{id}Delete an automation
  6. GET /rest/v1.0/companies/{company_id}/automations/{id}/runsList an automation's runs
  7. POST /rest/v1.0/companies/{company_id}/automations/{id}/testDry-run an automation with a sample
  8. GET /rest/v1.0/companies/{company_id}/automations/{id}/versionsList an automation's versions
  9. GET /rest/v1.0/companies/{company_id}/automations/catalogAutomation builder catalog
  10. GET /rest/v1.0/companies/{company_id}/automations/runsList automation runs
  11. GET /rest/v1.0/companies/{company_id}/automations/runs/{run_id}Show an automation run
GET /rest/v1.0/companies/{company_id}/automations

List automations

v1.0Implemented

Parameters

  • filters[project_id]
    stringquery
    Rules of one project
  • filters[include_company]
    stringquery
    With filters[project_id]: also company-wide rules
  • filters[enabled]
    stringquery
    true or false
  • search
    stringquery
    Name contains
  • page
    integerquery
  • per_page
    integerquery
  • company_id
    stringpathrequired

Response · 200 · object[]

  • id
    integerrequired
  • name
    stringrequired
  • description
    string | null
  • enabled
    booleanrequired
  • project
    object | null
  • project.id
    integer
  • project.name
    string | null
  • scope
    stringrequired
    One of: company, project.
  • trigger
    objectrequired
  • trigger_summary
    string
  • conditions
    objectrequired
  • actions
    object[]required
  • version
    integerrequired
  • owner
    objectrequired
    Actions run with this person's permissions; the last person to save the rule.
  • owner.id
    integer
  • owner.name
    string | null
  • template_key
    string | null
  • max_runs_per_hour
    integer
  • next_run_at
    string (date-time) | null
  • last_run_at
    string (date-time) | null
  • last_run_status
    string | null
  • consecutive_failures
    integer
  • paused_reason
    string | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 401Unauthorized
  • 403Forbidden
  • 404Not found

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/automations" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/automations

Create an automation

v1.0Implemented

Parameters

  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
  • company_id
    stringpathrequired

Request body

  • automation
    objectrequired
  • automation.name
    stringrequired
  • automation.description
    string | null
  • automation.project_id
    integer | null
    null = every project in the company (company admins only).
  • automation.enabled
    boolean
    Defaults to false on create.
  • automation.trigger
    objectrequired
    event: { kind, event_type } (any project record event in the webhooks catalog). schedule: { kind, frequency, time, weekday?, timezone, scan? }; scan runs once per matching record per day.
  • automation.trigger.kind
    stringrequired
    One of: event, schedule.
  • automation.trigger.event_type
    string
  • automation.trigger.frequency
    string
    One of: daily, weekdays, weekly.
  • automation.trigger.time
    string
    HH:MM, 24-hour
  • automation.trigger.weekday
    integer
  • automation.trigger.timezone
    string
    IANA time zone
  • automation.trigger.scan
    object | null
  • automation.trigger.scan.source
    string
    One of: rfi, submittal, punch_item, task, observation, insurance_policy, daily_log, budget_line.
  • automation.trigger.scan.match
    string
    One of: overdue, date_offset, missing, threshold.
  • automation.trigger.scan.days
    integer
  • automation.trigger.scan.percent
    number
  • automation.conditions
    object
    Conditions: match all (AND) or any (OR); rules may nest groups up to 3 deep, at most 25 conditions.
  • automation.conditions.match
    string
    One of: all, any.
  • automation.conditions.rules
    object[]
  • automation.conditions.rules[].field
    string
    event.*, data.*, project.*, resource.* or custom_fields.<definition id>; see GET …/automations/catalog trigger_fields.
  • automation.conditions.rules[].operator
    string
    One of: eq, neq, gt, gte, lt, lte, in, not_in, contains, not_contains, is_empty, is_not_empty, includes_user.
  • automation.conditions.rules[].value
    any | null
    String, number, boolean, null or a list. Dates accept YYYY-MM-DD, today, today+N, today-N.
  • automation.conditions.rules[].match
    string
  • automation.conditions.rules[].rules
    object[]
  • automation.actions
    object[]required
  • automation.actions[].type
    stringrequired
  • automation.actions[].channels
    string[]required
    One of: in_app, email.
  • automation.actions[].recipients
    objectrequired
    Who to notify or assign. Everyone resolves to active people in the company; each must be able to open the record.
  • automation.actions[].recipients.users
    integer[]
  • automation.actions[].recipients.roles
    string[]
    Project team roles, e.g. Project Manager, Superintendent.
  • automation.actions[].recipients.assignees
    boolean
  • automation.actions[].recipients.creator
    boolean
  • automation.actions[].recipients.manager
    boolean
  • automation.actions[].recipients.distribution_groups
    integer[]
  • automation.actions[].recipients.rule_owner
    boolean
  • automation.actions[].recipients.company_admins
    boolean
  • automation.actions[].subject
    stringrequired
  • automation.actions[].body
    string
  • automation.max_runs_per_hour
    integer
  • automation.template_key
    string | null

Response · 201 · object

  • id
    integerrequired
  • name
    stringrequired
  • description
    string | null
  • enabled
    booleanrequired
  • project
    object | null
  • project.id
    integer
  • project.name
    string | null
  • scope
    stringrequired
    One of: company, project.
  • trigger
    objectrequired
  • trigger_summary
    string
  • conditions
    objectrequired
  • actions
    object[]required
  • version
    integerrequired
  • owner
    objectrequired
    Actions run with this person's permissions; the last person to save the rule.
  • owner.id
    integer
  • owner.name
    string | null
  • template_key
    string | null
  • max_runs_per_hour
    integer
  • next_run_at
    string (date-time) | null
  • last_run_at
    string (date-time) | null
  • last_run_status
    string | null
  • consecutive_failures
    integer
  • paused_reason
    string | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 401Unauthorized
  • 403Forbidden
  • 404Not found
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/automations" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "automation": {
    "name": "string",
    "trigger": {
      "kind": "event"
    },
    "actions": [
      {
        "type": "string",
        "channels": "in_app",
        "recipients": {},
        "subject": "string"
      }
    ]
  }
}'
GET /rest/v1.0/companies/{company_id}/automations/{id}

Show an automation

v1.0Implemented

Parameters

  • company_id
    stringpathrequired
  • id
    stringpathrequired

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • description
    string | null
  • enabled
    booleanrequired
  • project
    object | null
  • project.id
    integer
  • project.name
    string | null
  • scope
    stringrequired
    One of: company, project.
  • trigger
    objectrequired
  • trigger_summary
    string
  • conditions
    objectrequired
  • actions
    object[]required
  • version
    integerrequired
  • owner
    objectrequired
    Actions run with this person's permissions; the last person to save the rule.
  • owner.id
    integer
  • owner.name
    string | null
  • template_key
    string | null
  • max_runs_per_hour
    integer
  • next_run_at
    string (date-time) | null
  • last_run_at
    string (date-time) | null
  • last_run_status
    string | null
  • consecutive_failures
    integer
  • paused_reason
    string | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 401Unauthorized
  • 404Not found

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/automations/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PATCH /rest/v1.0/companies/{company_id}/automations/{id}

Update an automation

Partial update. Saving makes the caller the owner; a changed definition creates a new version.

v1.0Implemented

Parameters

  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
  • company_id
    stringpathrequired
  • id
    stringpathrequired

Request body

  • automation
    objectrequired
  • automation.name
    string
  • automation.description
    string | null
  • automation.project_id
    integer | null
    null = every project in the company (company admins only).
  • automation.enabled
    boolean
    Defaults to false on create.
  • automation.trigger
    object
    event: { kind, event_type } (any project record event in the webhooks catalog). schedule: { kind, frequency, time, weekday?, timezone, scan? }; scan runs once per matching record per day.
  • automation.trigger.kind
    stringrequired
    One of: event, schedule.
  • automation.trigger.event_type
    string
  • automation.trigger.frequency
    string
    One of: daily, weekdays, weekly.
  • automation.trigger.time
    string
    HH:MM, 24-hour
  • automation.trigger.weekday
    integer
  • automation.trigger.timezone
    string
    IANA time zone
  • automation.trigger.scan
    object | null
  • automation.trigger.scan.source
    string
    One of: rfi, submittal, punch_item, task, observation, insurance_policy, daily_log, budget_line.
  • automation.trigger.scan.match
    string
    One of: overdue, date_offset, missing, threshold.
  • automation.trigger.scan.days
    integer
  • automation.trigger.scan.percent
    number
  • automation.conditions
    object
    Conditions: match all (AND) or any (OR); rules may nest groups up to 3 deep, at most 25 conditions.
  • automation.conditions.match
    string
    One of: all, any.
  • automation.conditions.rules
    object[]
  • automation.conditions.rules[].field
    string
    event.*, data.*, project.*, resource.* or custom_fields.<definition id>; see GET …/automations/catalog trigger_fields.
  • automation.conditions.rules[].operator
    string
    One of: eq, neq, gt, gte, lt, lte, in, not_in, contains, not_contains, is_empty, is_not_empty, includes_user.
  • automation.conditions.rules[].value
    any | null
    String, number, boolean, null or a list. Dates accept YYYY-MM-DD, today, today+N, today-N.
  • automation.conditions.rules[].match
    string
  • automation.conditions.rules[].rules
    object[]
  • automation.actions
    object[]
  • automation.actions[].type
    stringrequired
  • automation.actions[].channels
    string[]required
    One of: in_app, email.
  • automation.actions[].recipients
    objectrequired
    Who to notify or assign. Everyone resolves to active people in the company; each must be able to open the record.
  • automation.actions[].recipients.users
    integer[]
  • automation.actions[].recipients.roles
    string[]
    Project team roles, e.g. Project Manager, Superintendent.
  • automation.actions[].recipients.assignees
    boolean
  • automation.actions[].recipients.creator
    boolean
  • automation.actions[].recipients.manager
    boolean
  • automation.actions[].recipients.distribution_groups
    integer[]
  • automation.actions[].recipients.rule_owner
    boolean
  • automation.actions[].recipients.company_admins
    boolean
  • automation.actions[].subject
    stringrequired
  • automation.actions[].body
    string
  • automation.max_runs_per_hour
    integer
  • automation.template_key
    string | null

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • description
    string | null
  • enabled
    booleanrequired
  • project
    object | null
  • project.id
    integer
  • project.name
    string | null
  • scope
    stringrequired
    One of: company, project.
  • trigger
    objectrequired
  • trigger_summary
    string
  • conditions
    objectrequired
  • actions
    object[]required
  • version
    integerrequired
  • owner
    objectrequired
    Actions run with this person's permissions; the last person to save the rule.
  • owner.id
    integer
  • owner.name
    string | null
  • template_key
    string | null
  • max_runs_per_hour
    integer
  • next_run_at
    string (date-time) | null
  • last_run_at
    string (date-time) | null
  • last_run_status
    string | null
  • consecutive_failures
    integer
  • paused_reason
    string | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 401Unauthorized
  • 403Forbidden
  • 404Not found
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/automations/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "automation": {}
}'
DELETE /rest/v1.0/companies/{company_id}/automations/{id}

Delete an automation

v1.0Implemented

Parameters

  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
  • company_id
    stringpathrequired
  • id
    stringpathrequired

Response · 204

No response body.

Errors

  • 401Unauthorized
  • 403Forbidden
  • 404Not found

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/automations/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/companies/{company_id}/automations/{id}/runs

List an automation's runs

v1.0Implemented

Parameters

  • filters[status]
    stringquery
    Run status
  • page
    integerquery
  • per_page
    integerquery
  • company_id
    stringpathrequired
  • id
    stringpathrequired

Response · 200 · object[]

  • id
    string (uuid)required
  • automation_id
    integerrequired
  • automation_name
    string | null
  • automation_version
    integer
  • status
    stringrequired
    One of: queued, running, succeeded, partial, failed, skipped, dry_run.
  • dry_run
    booleanrequired
  • trigger_key
    string
  • project_id
    integer | null
  • event
    object | null
  • event.id
    string | null
  • event.type
    string | null
  • resource
    object | null
  • resource.type
    string
  • resource.id
    string | null
  • depth
    integer
    Automation chain depth; runs stop at 3.
  • conditions_matched
    boolean | null
  • condition_trace
    object | null
  • outcomes
    object[]required
  • outcomes[].index
    integer
  • outcomes[].type
    string
  • outcomes[].status
    string
    One of: started, succeeded, failed, retrying, uncertain, skipped, preview.
  • outcomes[].detail
    string | null
  • outcomes[].error
    string | null
  • outcomes[].record
    object | null
  • error
    string | null
  • attempts
    integer
  • input
    object
  • created_at
    string (date-time)required
  • started_at
    string (date-time) | null
  • finished_at
    string (date-time) | null

Errors

  • 400Bad request
  • 401Unauthorized
  • 404Not found

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/automations/1/runs" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/automations/{id}/test

Dry-run an automation with a sample

Evaluates the conditions and previews each action without side effects. Without a sample, uses the latest matching event (event rules) or the first record the schedule would pick today.

v1.0Implemented

Parameters

  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
  • company_id
    stringpathrequired
  • id
    stringpathrequired

Request body

  • test
    object
  • test.event_id
    string (uuid)
  • test.project_id
    integer
  • test.resource_id
    integer | string
  • test.data
    object

Response · 200 · object

  • run_id
    string
  • matched
    booleanrequired
  • skipped_reason
    string | null
  • trace
    object | null
  • actions
    object[]required
  • actions[].index
    integer
  • actions[].type
    string
  • actions[].preview
    string
  • context
    object | null

Errors

  • 401Unauthorized
  • 403Forbidden
  • 404Not found
  • 422Validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/automations/1/test" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "test": {}
}'
GET /rest/v1.0/companies/{company_id}/automations/{id}/versions

List an automation's versions

v1.0Implemented

Parameters

  • company_id
    stringpathrequired
  • id
    stringpathrequired

Response · 200 · object[]

  • version
    integer
  • created_at
    string (date-time)
  • created_by
    object
  • snapshot
    object

Errors

  • 401Unauthorized
  • 404Not found

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/automations/1/versions" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/companies/{company_id}/automations/catalog

Automation builder catalog

Triggers, the fields each trigger exposes (trigger_fields keyed event:<type>, scan:<source> or schedule), operators, actions with availability, templates and pickers.

v1.0Implemented

Parameters

  • project_id
    integerquery
    Include this project's distribution groups
  • company_id
    stringpathrequired

Response · 200 · object

No documented fields.

Errors

  • 401Unauthorized
  • 403Forbidden
  • 404Not found

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/automations/catalog" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/companies/{company_id}/automations/runs

List automation runs

v1.0Implemented

Parameters

  • filters[status]
    stringquery
    queued, running, succeeded, partial, failed, skipped or dry_run
  • filters[project_id]
    stringquery
    Runs for one project
  • page
    integerquery
  • per_page
    integerquery
  • company_id
    stringpathrequired

Response · 200 · object[]

  • id
    string (uuid)required
  • automation_id
    integerrequired
  • automation_name
    string | null
  • automation_version
    integer
  • status
    stringrequired
    One of: queued, running, succeeded, partial, failed, skipped, dry_run.
  • dry_run
    booleanrequired
  • trigger_key
    string
  • project_id
    integer | null
  • event
    object | null
  • event.id
    string | null
  • event.type
    string | null
  • resource
    object | null
  • resource.type
    string
  • resource.id
    string | null
  • depth
    integer
    Automation chain depth; runs stop at 3.
  • conditions_matched
    boolean | null
  • condition_trace
    object | null
  • outcomes
    object[]required
  • outcomes[].index
    integer
  • outcomes[].type
    string
  • outcomes[].status
    string
    One of: started, succeeded, failed, retrying, uncertain, skipped, preview.
  • outcomes[].detail
    string | null
  • outcomes[].error
    string | null
  • outcomes[].record
    object | null
  • error
    string | null
  • attempts
    integer
  • input
    object
  • created_at
    string (date-time)required
  • started_at
    string (date-time) | null
  • finished_at
    string (date-time) | null

Errors

  • 400Bad request
  • 401Unauthorized
  • 403Forbidden
  • 404Not found

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/automations/runs" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/companies/{company_id}/automations/runs/{run_id}

Show an automation run

v1.0Implemented

Parameters

  • company_id
    stringpathrequired
  • run_id
    stringpathrequired

Response · 200 · object

  • id
    string (uuid)required
  • automation_id
    integerrequired
  • automation_name
    string | null
  • automation_version
    integer
  • status
    stringrequired
    One of: queued, running, succeeded, partial, failed, skipped, dry_run.
  • dry_run
    booleanrequired
  • trigger_key
    string
  • project_id
    integer | null
  • event
    object | null
  • event.id
    string | null
  • event.type
    string | null
  • resource
    object | null
  • resource.type
    string
  • resource.id
    string | null
  • depth
    integer
    Automation chain depth; runs stop at 3.
  • conditions_matched
    boolean | null
  • condition_trace
    object | null
  • outcomes
    object[]required
  • outcomes[].index
    integer
  • outcomes[].type
    string
  • outcomes[].status
    string
    One of: started, succeeded, failed, retrying, uncertain, skipped, preview.
  • outcomes[].detail
    string | null
  • outcomes[].error
    string | null
  • outcomes[].record
    object | null
  • error
    string | null
  • attempts
    integer
  • input
    object
  • created_at
    string (date-time)required
  • started_at
    string (date-time) | null
  • finished_at
    string (date-time) | null

Errors

  • 401Unauthorized
  • 404Not found

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/automations/runs/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

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