Skip to content
Artbucket

Make an automation

POST
/api/v1/automations
curl --request POST \
  --url http://localhost:3000/api/v1/automations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "trigger": "brand.released", "brand": "example", "days": 1, "actions": [ "example" ], "times": 1, "kind": "stale", "action": "email", "format": "json", "emails": [ "hello@example.com" ], "url": "https://example.com", "enabled": true }'

Brand.released fires when a brand (brand, or any) is released; asset.expiring once per approved asset, days before its last day of use, and again for a new date. governance fires on each entry of the project’s audit log and each asset decision (asset.approved, asset.rejected, asset.archived…) that actions names, exact or by prefix (share.*), every one when empty; never on entries outside a project or a private asset’s. check.refused fires once per asset and window when the use check refused it times times within days (7 unless said). fix.opened fires once for each new thing Fixes lists, of kind (stale or gap, or both), first seen since the automation was made. review.waiting fires once for each proposal in review days or more. email sends to emails; webhook POSTs to url the run’s payload (format json), a Slack incoming webhook’s message (slack) or a Teams workflow’s Adaptive Card (teams), signed as Artbucket-Signature: t={unix seconds},v1={hex HMAC-SHA256 of "{t}.{body}"} with secret, which is in this answer only. A delivery that fails is tried again 5 minutes, then an hour later: 3 attempts in all.

Scope: write.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required
string
>= 1 characters <= 80 characters
trigger
required

Brand.released: a brand’s guidelines are released. asset.expiring: an asset’s license ends within days days. governance: an entry of the audit log, or an asset decision (asset.approved, asset.rejected, asset.archived…), named in actions. check.refused: an asset refused by the use check times times within days days. fix.opened: something new in Fixes, of kind. review.waiting: a proposal in review for days days

string
Allowed values: brand.released asset.expiring governance check.refused fix.opened review.waiting
brand
Any of:
string
>= 1 characters <= 64 characters
days

Asset.expiring: how many days before its last day of use; 0 is the day itself. check.refused: the window counted, 7 when left out. review.waiting: how long a proposal waits

integer
<= 365
actions

Governance: the actions it fires on, exact (grant.set) or by prefix (share.*); empty or left out: every one

Array<string>
<= 50 items
times

Check.refused: refusals of one asset within days before it fires; 1 when left out

integer
>= 1 <= 1000
kind
Any of:
string
Allowed values: stale gap
action
required

Email: to emails. webhook: a signed POST to url

string
Allowed values: email webhook
format

Webhook: json (the run, signed), slack (a Slack incoming webhook’s message) or teams (a Teams workflow’s Adaptive Card); json when left out

string
Allowed values: json slack teams
emails

Email: who it goes to

Array<string>
<= 20 items
url

Webhook: where it is posted. Kept sealed, never shown again: the answer gives its host

string format: uri
<= 2000 characters
enabled

Off: nothing fires, and what waits to be retried waits. On when left out

boolean

Responses

Section titled “Responses”

201

Section titled “201”

Created, with the webhook’s secret

Media typeapplication/json
object
data
required
object
id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
name
required
string
trigger
required
string
Allowed values: brand.released asset.expiring governance check.refused fix.opened review.waiting
brand
required

Brand.released: the brand it is for, by slug; null: any

string | null
days
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
actions
required

Governance: the actions it fires on; empty: every one

Array<string>
times
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
kind
required
Any of:
string
Allowed values: stale gap
action
required
string
Allowed values: email webhook
format
required
string
Allowed values: json slack teams
emails
required
Array<string>
host
required

Webhook: the URL’s host; the URL itself is never shown

string | null
enabled
required
boolean
last
required
Any of:
object
status
required
string
Allowed values: pending delivered failed
at
required
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
createdBy
required
string
createdAt
required
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
updatedAt
required
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
secret

Webhook: what each POST is signed with (Artbucket-Signature). Given once, when made

string
Example
{
  "data": {
    "trigger": "brand.released",
    "kind": "stale",
    "action": "email",
    "format": "json",
    "last": {
      "status": "pending"
    }
  }
}

default

Section titled “default”

An error

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
detail
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": "example"
  }
}