Workflows API

Automations that react to what happens, or run on a schedule, and do the work for you.

Module code workflows · 10 actions · 3 data models · 10 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: workflows (everything), workflows:read (read only) or workflows:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

workflows.cancel_wait

Cancel a waiting workflow run — Stops a canvas execution that is waiting; the blocks that already ran stay done.

Needs workflows:write · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/workflows.cancel_wait

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: workflows.wait_cancelled

What it writes: canvas_wait (update) — Marks the wait for cancelling

curl -X POST https://app.getera.io/api/v1/canvas_waits/CANVAS_WAIT_ID/actions/cancel_wait \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "workflows.wait_cancelled"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.canvasWaits.cancelWait("CANVAS_WAIT_ID")

era canvas_waits cancel_wait CANVAS_WAIT_ID

{
  "name": "era__workflows__cancel_wait",
  "arguments": {
    "waitId": "CANVAS_WAIT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold workflows:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, already_finished · 429 slow down

workflows.decide_wait

Approve or reject a waiting workflow — Answers an Era approval. Completing its task on the Tasks screen does the same.

Needs workflows:write · changes data

• Canonical address: POST /api/v1/actions/workflows.decide_wait

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: workflows.wait_decided

What it writes: canvas_wait (update) — Records the decision

curl -X POST https://app.getera.io/api/v1/canvas_waits/CANVAS_WAIT_ID/actions/decide_wait \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"approve":true}'

{
  "ok": true,
  "result": "…",
  "events": [
    "workflows.wait_decided"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.canvasWaits.decideWait("CANVAS_WAIT_ID", {
  approve: true
})

era canvas_waits decide_wait CANVAS_WAIT_ID \
  --approve true

{
  "name": "era__workflows__decide_wait",
  "arguments": {
    "waitId": "CANVAS_WAIT_ID",
    "approve": true
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold workflows:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, not_waiting_for_approval · 429 slow down

workflows.draft

Draft a workflow — Checks a whole workflow — trigger, conditions and steps — and draws it as a canvas for a person to review and deploy.

Needs workflows:manage · changes data

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: workflows.drafted

curl -X POST https://app.getera.io/api/v1/actions/workflows.draft \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "workflows.drafted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("workflows.draft", {
  name: "Name"
})

era workflows draft \
  --name "Name"

{
  "name": "era__workflows__draft",
  "arguments": {
    "name": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold workflows:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 empty_name, unknown_event, bad_trigger, bad_schedule, bad_condition, bad_step, unknown_action · 429 slow down

workflows.install_template

Start a workflow from a template — Fills a template in for you and draws it as a canvas, ready to review and deploy.

Needs workflows:manage · changes data

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: workflows.template_used

curl -X POST https://app.getera.io/api/v1/actions/workflows.install_template \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"code":"Template"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "workflows.template_used"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("workflows.install_template", {
  code: "Template"
})

era workflows install_template \
  --code "Template"

{
  "name": "era__workflows__install_template",
  "arguments": {
    "code": "Template"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold workflows:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 unknown_template, template_needs_module · 429 slow down

workflows.note_undo

Record an undo of a workflow run — Records which Era actions of a run were undone through their declared inverse, and which refused.

Needs workflows:write · changes data

• Canonical address: POST /api/v1/actions/workflows.note_undo

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: workflows.run_undone

What it writes: canvas_run_note (upsert) — Records the undo

curl -X POST https://app.getera.io/api/v1/canvas_run_notes/actions/note_undo \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"canvasId":"Canvas workflow","executionId":"Canvas execution","status":"done","steps":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "workflows.run_undone"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.canvasRunNotes.noteUndo({
  canvasId: "Canvas workflow",
  executionId: "Canvas execution",
  status: "done",
  steps: {}
})

era canvas_run_notes note_undo --data '{"canvasId":"Canvas workflow","executionId":"Canvas execution","status":"done","steps":{}}'

{
  "name": "era__workflows__note_undo",
  "arguments": {
    "canvasId": "Canvas workflow",
    "executionId": "Canvas execution",
    "status": "done",
    "steps": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold workflows:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 bad_canvas, already_undone · 429 slow down

workflows.park_canvas

Park a workflow run at a wait — Machine-only: the Era wait / approval block parks the canvas execution until its time, its answer or its expiry.

Needs workflows:write · changes data

• Canonical address: POST /api/v1/actions/workflows.park_canvas

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: workflows.canvas_parked

What it writes: canvas_wait (upsert) — Records the parked execution

Errors: 401 no or expired credential · 403 the credential does not hold workflows:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 bad_canvas, bad_wait · 429 slow down

workflows.record_step_key

Remember a step’s idempotency key — Machine-only: an Era block with an idempotency key succeeded, so it does not run again for that key.

Needs workflows:write · changes data

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: workflows.step_key_recorded

What it writes: canvas_step_key (insert) — Remembers the key

Errors: 401 no or expired credential · 403 the credential does not hold workflows:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 bad_canvas, already_done · 429 slow down

workflows.report_run_failed

Report a failed workflow run — Machine-only: turns a failed canvas execution into the workflows.run_failed event for its owner, once.

Needs workflows:read · changes data

• Canonical address: POST /api/v1/actions/workflows.report_run_failed

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: workflows.run_failed

What it writes: canvas_run_note (upsert) — Marks the failure reported

Errors: 401 no or expired credential · 403 the credential does not hold workflows:read · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 bad_canvas, already_reported · 429 slow down

workflows.subscribe_canvas

Start a workflow on a module event — The canvas starts by itself when the event happens — called when a canvas with an Era event trigger is deployed.

Needs workflows:manage · changes data

• Canonical address: POST /api/v1/actions/workflows.subscribe_canvas

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: workflows.canvas_subscribed

What it writes: canvas_trigger (upsert) — Creates or updates the canvas subscription

curl -X POST https://app.getera.io/api/v1/canvas_triggers/actions/subscribe_canvas \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"canvasId":"Canvas workflow","eventPattern":"When this happens"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "workflows.canvas_subscribed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.canvasTriggers.subscribeCanvas({
  canvasId: "Canvas workflow",
  eventPattern: "When this happens"
})

era canvas_triggers subscribe_canvas \
  --canvas-id "Canvas workflow" \
  --event-pattern "When this happens"

{
  "name": "era__workflows__subscribe_canvas",
  "arguments": {
    "canvasId": "Canvas workflow",
    "eventPattern": "When this happens"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold workflows:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 bad_canvas, unknown_event, bad_trigger · 429 slow down

workflows.unsubscribe_canvas

Stop a workflow listening to events — Removes the canvas subscription; the canvas no longer starts on module events.

Needs workflows:manage · removes or cannot be undone

• Canonical address: POST /api/v1/actions/workflows.unsubscribe_canvas

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: workflows.canvas_unsubscribed

What it writes: canvas_trigger (delete) — Removes the subscription

curl -X POST https://app.getera.io/api/v1/canvas_triggers/actions/unsubscribe_canvas \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"canvasId":"Canvas workflow"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "workflows.canvas_unsubscribed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.canvasTriggers.unsubscribeCanvas({
  canvasId: "Canvas workflow"
})

era canvas_triggers unsubscribe_canvas \
  --canvas-id "Canvas workflow"

{
  "name": "era__workflows__unsubscribe_canvas",
  "arguments": {
    "canvasId": "Canvas workflow"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold workflows:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_subscribed · 429 slow down

Data models

CanvasRunNote

Table canvas_run_note · Resource canvas_run_notes

• GET /api/v1/canvas_run_notes
• GET /api/v1/canvas_run_notes/{id}

Primary key: id

Checks:

• CHECK (((undo_status IS NULL) OR (undo_status = ANY (ARRAY['done'::text, 'partial'::text]))))

CanvasTrigger

Table canvas_trigger · Resource canvas_triggers

• GET /api/v1/canvas_triggers
• GET /api/v1/canvas_triggers/{id}

Primary key: id

Checks:

• CHECK ((canvas_id ~ '^[A-Za-z0-9_-]{1,128}$'::text))
• CHECK (((event_pattern = '*'::text) OR (event_pattern ~ '^[a-z][a-z0-9_]*\.([a-z][a-z0-9_]*\|\*)$'::text)))

CanvasWait

Table canvas_wait · Resource canvas_waits

• GET /api/v1/canvas_waits
• GET /api/v1/canvas_waits/{id}

Primary key: id

Checks:

• CHECK ((canvas_id ~ '^[A-Za-z0-9_-]{1,128}$'::text))
• CHECK (((decision IS NULL) OR (decision = ANY (ARRAY['approved'::text, 'rejected'::text]))))

Events

Workflows and webhooks react to these events.