Automations
- GET
/rest/v1.0/companies/{company_id}/automationsList automations - POST
/rest/v1.0/companies/{company_id}/automationsCreate an automation - GET
/rest/v1.0/companies/{company_id}/automations/{id}Show an automation - PATCH
/rest/v1.0/companies/{company_id}/automations/{id}Update an automation - DELETE
/rest/v1.0/companies/{company_id}/automations/{id}Delete an automation - GET
/rest/v1.0/companies/{company_id}/automations/{id}/runsList an automation's runs - POST
/rest/v1.0/companies/{company_id}/automations/{id}/testDry-run an automation with a sample - GET
/rest/v1.0/companies/{company_id}/automations/{id}/versionsList an automation's versions - GET
/rest/v1.0/companies/{company_id}/automations/catalogAutomation builder catalog - GET
/rest/v1.0/companies/{company_id}/automations/runsList automation runs - GET
/rest/v1.0/companies/{company_id}/automations/runs/{run_id}Show an automation run
/rest/v1.0/companies/{company_id}/automationsList automations
Parameters
- filters[project_id]stringqueryRules of one project
- filters[include_company]stringqueryWith filters[project_id]: also company-wide rules
- filters[enabled]stringquerytrue or false
- searchstringqueryName contains
- pageintegerquery
- per_pageintegerquery
- company_idstringpathrequired
Response · 200 · object[]
- idintegerrequired
- namestringrequired
- descriptionstring | null
- enabledbooleanrequired
- projectobject | null
- project.idinteger
- project.namestring | null
- scopestringrequiredOne of: company, project.
- triggerobjectrequired
- trigger_summarystring
- conditionsobjectrequired
- actionsobject[]required
- versionintegerrequired
- ownerobjectrequiredActions run with this person's permissions; the last person to save the rule.
- owner.idinteger
- owner.namestring | null
- template_keystring | null
- max_runs_per_hourinteger
- next_run_atstring (date-time) | null
- last_run_atstring (date-time) | null
- last_run_statusstring | null
- consecutive_failuresinteger
- paused_reasonstring | null
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Unauthorized403Forbidden404Not 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"/rest/v1.0/companies/{company_id}/automationsCreate an automation
Parameters
- Idempotency-KeystringheaderOptional. 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_idstringpathrequired
Request body
- automationobjectrequired
- automation.namestringrequired
- automation.descriptionstring | null
- automation.project_idinteger | nullnull = every project in the company (company admins only).
- automation.enabledbooleanDefaults to false on create.
- automation.triggerobjectrequiredevent: { 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.kindstringrequiredOne of: event, schedule.
- automation.trigger.event_typestring
- automation.trigger.frequencystringOne of: daily, weekdays, weekly.
- automation.trigger.timestringHH:MM, 24-hour
- automation.trigger.weekdayinteger
- automation.trigger.timezonestringIANA time zone
- automation.trigger.scanobject | null
- automation.trigger.scan.sourcestringOne of: rfi, submittal, punch_item, task, observation, insurance_policy, daily_log, budget_line.
- automation.trigger.scan.matchstringOne of: overdue, date_offset, missing, threshold.
- automation.trigger.scan.daysinteger
- automation.trigger.scan.percentnumber
- automation.conditionsobjectConditions: match all (AND) or any (OR); rules may nest groups up to 3 deep, at most 25 conditions.
- automation.conditions.matchstringOne of: all, any.
- automation.conditions.rulesobject[]
- automation.conditions.rules[].fieldstringevent.*, data.*, project.*, resource.* or custom_fields.<definition id>; see GET …/automations/catalog trigger_fields.
- automation.conditions.rules[].operatorstringOne of: eq, neq, gt, gte, lt, lte, in, not_in, contains, not_contains, is_empty, is_not_empty, includes_user.
- automation.conditions.rules[].valueany | nullString, number, boolean, null or a list. Dates accept YYYY-MM-DD, today, today+N, today-N.
- automation.conditions.rules[].matchstring
- automation.conditions.rules[].rulesobject[]
- automation.actionsobject[]required
- automation.actions[].typestringrequired
- automation.actions[].channelsstring[]requiredOne of: in_app, email.
- automation.actions[].recipientsobjectrequiredWho to notify or assign. Everyone resolves to active people in the company; each must be able to open the record.
- automation.actions[].recipients.usersinteger[]
- automation.actions[].recipients.rolesstring[]Project team roles, e.g. Project Manager, Superintendent.
- automation.actions[].recipients.assigneesboolean
- automation.actions[].recipients.creatorboolean
- automation.actions[].recipients.managerboolean
- automation.actions[].recipients.distribution_groupsinteger[]
- automation.actions[].recipients.rule_ownerboolean
- automation.actions[].recipients.company_adminsboolean
- automation.actions[].subjectstringrequired
- automation.actions[].bodystring
- automation.max_runs_per_hourinteger
- automation.template_keystring | null
Response · 201 · object
- idintegerrequired
- namestringrequired
- descriptionstring | null
- enabledbooleanrequired
- projectobject | null
- project.idinteger
- project.namestring | null
- scopestringrequiredOne of: company, project.
- triggerobjectrequired
- trigger_summarystring
- conditionsobjectrequired
- actionsobject[]required
- versionintegerrequired
- ownerobjectrequiredActions run with this person's permissions; the last person to save the rule.
- owner.idinteger
- owner.namestring | null
- template_keystring | null
- max_runs_per_hourinteger
- next_run_atstring (date-time) | null
- last_run_atstring (date-time) | null
- last_run_statusstring | null
- consecutive_failuresinteger
- paused_reasonstring | null
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Unauthorized403Forbidden404Not found422Validation 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"
}
]
}
}'/rest/v1.0/companies/{company_id}/automations/{id}Show an automation
Parameters
- company_idstringpathrequired
- idstringpathrequired
Response · 200 · object
- idintegerrequired
- namestringrequired
- descriptionstring | null
- enabledbooleanrequired
- projectobject | null
- project.idinteger
- project.namestring | null
- scopestringrequiredOne of: company, project.
- triggerobjectrequired
- trigger_summarystring
- conditionsobjectrequired
- actionsobject[]required
- versionintegerrequired
- ownerobjectrequiredActions run with this person's permissions; the last person to save the rule.
- owner.idinteger
- owner.namestring | null
- template_keystring | null
- max_runs_per_hourinteger
- next_run_atstring (date-time) | null
- last_run_atstring (date-time) | null
- last_run_statusstring | null
- consecutive_failuresinteger
- paused_reasonstring | null
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Unauthorized404Not 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"/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.
Parameters
- Idempotency-KeystringheaderOptional. 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_idstringpathrequired
- idstringpathrequired
Request body
- automationobjectrequired
- automation.namestring
- automation.descriptionstring | null
- automation.project_idinteger | nullnull = every project in the company (company admins only).
- automation.enabledbooleanDefaults to false on create.
- automation.triggerobjectevent: { 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.kindstringrequiredOne of: event, schedule.
- automation.trigger.event_typestring
- automation.trigger.frequencystringOne of: daily, weekdays, weekly.
- automation.trigger.timestringHH:MM, 24-hour
- automation.trigger.weekdayinteger
- automation.trigger.timezonestringIANA time zone
- automation.trigger.scanobject | null
- automation.trigger.scan.sourcestringOne of: rfi, submittal, punch_item, task, observation, insurance_policy, daily_log, budget_line.
- automation.trigger.scan.matchstringOne of: overdue, date_offset, missing, threshold.
- automation.trigger.scan.daysinteger
- automation.trigger.scan.percentnumber
- automation.conditionsobjectConditions: match all (AND) or any (OR); rules may nest groups up to 3 deep, at most 25 conditions.
- automation.conditions.matchstringOne of: all, any.
- automation.conditions.rulesobject[]
- automation.conditions.rules[].fieldstringevent.*, data.*, project.*, resource.* or custom_fields.<definition id>; see GET …/automations/catalog trigger_fields.
- automation.conditions.rules[].operatorstringOne of: eq, neq, gt, gte, lt, lte, in, not_in, contains, not_contains, is_empty, is_not_empty, includes_user.
- automation.conditions.rules[].valueany | nullString, number, boolean, null or a list. Dates accept YYYY-MM-DD, today, today+N, today-N.
- automation.conditions.rules[].matchstring
- automation.conditions.rules[].rulesobject[]
- automation.actionsobject[]
- automation.actions[].typestringrequired
- automation.actions[].channelsstring[]requiredOne of: in_app, email.
- automation.actions[].recipientsobjectrequiredWho to notify or assign. Everyone resolves to active people in the company; each must be able to open the record.
- automation.actions[].recipients.usersinteger[]
- automation.actions[].recipients.rolesstring[]Project team roles, e.g. Project Manager, Superintendent.
- automation.actions[].recipients.assigneesboolean
- automation.actions[].recipients.creatorboolean
- automation.actions[].recipients.managerboolean
- automation.actions[].recipients.distribution_groupsinteger[]
- automation.actions[].recipients.rule_ownerboolean
- automation.actions[].recipients.company_adminsboolean
- automation.actions[].subjectstringrequired
- automation.actions[].bodystring
- automation.max_runs_per_hourinteger
- automation.template_keystring | null
Response · 200 · object
- idintegerrequired
- namestringrequired
- descriptionstring | null
- enabledbooleanrequired
- projectobject | null
- project.idinteger
- project.namestring | null
- scopestringrequiredOne of: company, project.
- triggerobjectrequired
- trigger_summarystring
- conditionsobjectrequired
- actionsobject[]required
- versionintegerrequired
- ownerobjectrequiredActions run with this person's permissions; the last person to save the rule.
- owner.idinteger
- owner.namestring | null
- template_keystring | null
- max_runs_per_hourinteger
- next_run_atstring (date-time) | null
- last_run_atstring (date-time) | null
- last_run_statusstring | null
- consecutive_failuresinteger
- paused_reasonstring | null
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
401Unauthorized403Forbidden404Not found422Validation 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": {}
}'/rest/v1.0/companies/{company_id}/automations/{id}Delete an automation
Parameters
- Idempotency-KeystringheaderOptional. 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_idstringpathrequired
- idstringpathrequired
Response · 204
No response body.
Errors
401Unauthorized403Forbidden404Not 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)"/rest/v1.0/companies/{company_id}/automations/{id}/runsList an automation's runs
Parameters
- filters[status]stringqueryRun status
- pageintegerquery
- per_pageintegerquery
- company_idstringpathrequired
- idstringpathrequired
Response · 200 · object[]
- idstring (uuid)required
- automation_idintegerrequired
- automation_namestring | null
- automation_versioninteger
- statusstringrequiredOne of: queued, running, succeeded, partial, failed, skipped, dry_run.
- dry_runbooleanrequired
- trigger_keystring
- project_idinteger | null
- eventobject | null
- event.idstring | null
- event.typestring | null
- resourceobject | null
- resource.typestring
- resource.idstring | null
- depthintegerAutomation chain depth; runs stop at 3.
- conditions_matchedboolean | null
- condition_traceobject | null
- outcomesobject[]required
- outcomes[].indexinteger
- outcomes[].typestring
- outcomes[].statusstringOne of: started, succeeded, failed, retrying, uncertain, skipped, preview.
- outcomes[].detailstring | null
- outcomes[].errorstring | null
- outcomes[].recordobject | null
- errorstring | null
- attemptsinteger
- inputobject
- created_atstring (date-time)required
- started_atstring (date-time) | null
- finished_atstring (date-time) | null
Errors
400Bad request401Unauthorized404Not 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"/rest/v1.0/companies/{company_id}/automations/{id}/testDry-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.
Parameters
- Idempotency-KeystringheaderOptional. 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_idstringpathrequired
- idstringpathrequired
Request body
- testobject
- test.event_idstring (uuid)
- test.project_idinteger
- test.resource_idinteger | string
- test.dataobject
Response · 200 · object
- run_idstring
- matchedbooleanrequired
- skipped_reasonstring | null
- traceobject | null
- actionsobject[]required
- actions[].indexinteger
- actions[].typestring
- actions[].previewstring
- contextobject | null
Errors
401Unauthorized403Forbidden404Not found422Validation 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": {}
}'/rest/v1.0/companies/{company_id}/automations/{id}/versionsList an automation's versions
Parameters
- company_idstringpathrequired
- idstringpathrequired
Response · 200 · object[]
- versioninteger
- created_atstring (date-time)
- created_byobject
- snapshotobject
Errors
401Unauthorized404Not 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"/rest/v1.0/companies/{company_id}/automations/catalogAutomation builder catalog
Triggers, the fields each trigger exposes (trigger_fields keyed event:<type>, scan:<source> or schedule), operators, actions with availability, templates and pickers.
Parameters
- project_idintegerqueryInclude this project's distribution groups
- company_idstringpathrequired
Response · 200 · object
No documented fields.
Errors
401Unauthorized403Forbidden404Not 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"/rest/v1.0/companies/{company_id}/automations/runsList automation runs
Parameters
- filters[status]stringqueryqueued, running, succeeded, partial, failed, skipped or dry_run
- filters[project_id]stringqueryRuns for one project
- pageintegerquery
- per_pageintegerquery
- company_idstringpathrequired
Response · 200 · object[]
- idstring (uuid)required
- automation_idintegerrequired
- automation_namestring | null
- automation_versioninteger
- statusstringrequiredOne of: queued, running, succeeded, partial, failed, skipped, dry_run.
- dry_runbooleanrequired
- trigger_keystring
- project_idinteger | null
- eventobject | null
- event.idstring | null
- event.typestring | null
- resourceobject | null
- resource.typestring
- resource.idstring | null
- depthintegerAutomation chain depth; runs stop at 3.
- conditions_matchedboolean | null
- condition_traceobject | null
- outcomesobject[]required
- outcomes[].indexinteger
- outcomes[].typestring
- outcomes[].statusstringOne of: started, succeeded, failed, retrying, uncertain, skipped, preview.
- outcomes[].detailstring | null
- outcomes[].errorstring | null
- outcomes[].recordobject | null
- errorstring | null
- attemptsinteger
- inputobject
- created_atstring (date-time)required
- started_atstring (date-time) | null
- finished_atstring (date-time) | null
Errors
400Bad request401Unauthorized403Forbidden404Not 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"/rest/v1.0/companies/{company_id}/automations/runs/{run_id}Show an automation run
Parameters
- company_idstringpathrequired
- run_idstringpathrequired
Response · 200 · object
- idstring (uuid)required
- automation_idintegerrequired
- automation_namestring | null
- automation_versioninteger
- statusstringrequiredOne of: queued, running, succeeded, partial, failed, skipped, dry_run.
- dry_runbooleanrequired
- trigger_keystring
- project_idinteger | null
- eventobject | null
- event.idstring | null
- event.typestring | null
- resourceobject | null
- resource.typestring
- resource.idstring | null
- depthintegerAutomation chain depth; runs stop at 3.
- conditions_matchedboolean | null
- condition_traceobject | null
- outcomesobject[]required
- outcomes[].indexinteger
- outcomes[].typestring
- outcomes[].statusstringOne of: started, succeeded, failed, retrying, uncertain, skipped, preview.
- outcomes[].detailstring | null
- outcomes[].errorstring | null
- outcomes[].recordobject | null
- errorstring | null
- attemptsinteger
- inputobject
- created_atstring (date-time)required
- started_atstring (date-time) | null
- finished_atstring (date-time) | null
Errors
401Unauthorized404Not 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"