Work API

Ask once: Era plans it, splits it across workers that run in parallel, and brings back finished work to use or publish.

Module code work · 23 actions · 5 data models · 18 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: work (everything), work:read (read only) or work:<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

work.add_step

Add a step to a plan — "Şunu da ekle": one more step for a worker; it starts as soon as what it waits for is done.

Needs work:write · changes data

• Canonical address: POST /api/v1/actions/work.add_step

Input

Preconditions

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

Events it publishes: work.step_changed

What it writes: work_step (insert) — Adds the step, queued; work_job (update) — Reopens the plan and notes what was said

curl -X POST https://app.getera.io/api/v1/work_jobs/WORK_JOB_ID/actions/add_step \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"Step","worker":"Worker"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "work.step_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.workJobs.addStep("WORK_JOB_ID", {
  title: "Step",
  worker: "Worker"
})

era work_jobs add_step WORK_JOB_ID \
  --title "Step" \
  --worker "Worker"

{
  "name": "era__work__add_step",
  "arguments": {
    "jobId": "WORK_JOB_ID",
    "title": "Step",
    "worker": "Worker"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold work:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, unknown_worker, unknown_executor, unknown_credential, too_many_steps, bad_steps, bad_dependency, duplicate_step · 429 slow down

work.answer_need

Answer a step that waits for you — Approve a risky step (it runs once) or decline it (it is skipped).

Needs work:write · changes data

• Canonical address: POST /api/v1/actions/work.answer_need

Input

Preconditions

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

Events it publishes: work.step_changed, work.job_finished, work.needs_you

What it writes: work_step (update) — Queues or skips the step; work_job (update) — Updates the plan’s status

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

{
  "ok": true,
  "result": "…",
  "events": [
    "work.step_changed",
    "work.job_finished",
    "work.needs_you"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.workSteps.answerNeed("WORK_STEP_ID", {
  decision: "approve"
})

era work_steps answer_need WORK_STEP_ID \
  --decision "approve"

{
  "name": "era__work__answer_need",
  "arguments": {
    "id": "WORK_STEP_ID",
    "decision": "approve"
  }
}

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

work.approve_plan

Approve a plan — The go-ahead: the workers start on every step that waits for nothing.

Needs work:write · changes data

• Canonical address: POST /api/v1/actions/work.approve_plan

Input

Preconditions

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

Events it publishes: work.plan_approved

What it writes: work_job (update) — Marks the plan approved and running

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

{
  "ok": true,
  "result": "…",
  "events": [
    "work.plan_approved"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.workJobs.approvePlan("WORK_JOB_ID")

era work_jobs approve_plan WORK_JOB_ID

{
  "name": "era__work__approve_plan",
  "arguments": {
    "id": "WORK_JOB_ID"
  }
}

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

work.assign_job

Give a plan to someone — Gives a plan to a person or back to Era, and says who sees it: the whole workspace or only the people on it.

Needs work:write · changes data

• Canonical address: POST /api/v1/actions/work.assign_job

Input

Preconditions

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

Events it publishes: work.job_assigned

What it writes: work_job (update) — Writes who answers for the plan and who sees it

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

{
  "ok": true,
  "result": "…",
  "events": [
    "work.job_assigned"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.workJobs.assignJob("WORK_JOB_ID", {
  assigneeUserId: "APP_USER_ID"
})

era work_jobs assign_job WORK_JOB_ID \
  --assignee-user-id "APP_USER_ID"

{
  "name": "era__work__assign_job",
  "arguments": {
    "id": "WORK_JOB_ID",
    "assigneeUserId": "APP_USER_ID"
  }
}

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

work.change_step

Change a step — "Bunu değiştir": rewrites a step that has not started yet.

Needs work:write · changes data

• Canonical address: POST /api/v1/actions/work.change_step

Input

Preconditions

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

Events it publishes: work.step_changed

What it writes: work_step (update) — Rewrites the step; work_job (update) — Notes what was said

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

{
  "ok": true,
  "result": "…",
  "events": [
    "work.step_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.workSteps.changeStep("WORK_STEP_ID", {
  title: "Step"
})

era work_steps change_step WORK_STEP_ID \
  --title "Step"

{
  "name": "era__work__change_step",
  "arguments": {
    "id": "WORK_STEP_ID",
    "title": "Step"
  }
}

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

work.message_step

Tell a working agent something — Sends a message to an agent while it works on your computer ("also do this", "wait, do it like that"); it takes it into account at its next step.

Needs work:write · reaches outside (sends, publishes or charges)

• Canonical address: POST /api/v1/actions/work.message_step

Input

Preconditions

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

Events it publishes: work.step_changed

What it writes: work_job (update) — Adds the message to the plan’s steering; work_step (update) — Shows the message as the step’s activity

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

{
  "ok": true,
  "result": "…",
  "events": [
    "work.step_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.workSteps.messageStep("WORK_STEP_ID", {
  text: "Message"
})

era work_steps message_step WORK_STEP_ID \
  --text "Message"

{
  "name": "era__work__message_step",
  "arguments": {
    "id": "WORK_STEP_ID",
    "text": "Message"
  }
}

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

work.propose_skill

Offer what Era learned — "Era learned a new skill from this job — keep it?": the procedure that worked, waiting for the author. Machine-only.

Needs work:handle · changes data

• Canonical address: POST /api/v1/actions/work.propose_skill

Input

Preconditions

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

Events it publishes: work.skill_proposed

What it writes: work_job (update) — Writes the offer on the plan

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

work.record_fork

Record a borrowed computer — The computer worker reports a copy made, running, given back or failed, and its running time. Machine-only.

Needs work:handle · changes data

• Canonical address: POST /api/v1/actions/work.record_fork

Input

Preconditions

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

Events it publishes: work.fork_changed

What it writes: work_computer_fork (update) — Writes the copy’s state and time

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

work.record_shop_order

Record an order Era placed — The shopping step’s report: what was ordered, the total, the card’s last four digits, the order number and — later — where it is. Never a card number. Machine-only.

Needs work:handle · changes data

• Canonical address: POST /api/v1/actions/work.record_shop_order

Input

Preconditions

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

Events it publishes: work.order_placed, work.order_updated

What it writes: shop_order (update) — Writes the order, or its tracking

Errors: 401 no or expired credential · 403 the credential does not hold work:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 bad_store, bad_order, card_number_refused, order_not_found · 429 slow down

work.record_step

Record a step’s progress — The engine’s report: taken, progress, what it is doing, what it needs, its result. Derives the plan’s status. Machine-only.

Needs work:handle · changes data

• Canonical address: POST /api/v1/actions/work.record_step

Input

Preconditions

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

Events it publishes: work.step_changed, work.needs_you, work.job_finished, work.held

What it writes: work_step (update) — Writes the step’s progress, checkpoint and result; work_job (update) — Holds the plan at its time limit and derives its status from its steps

Errors: 401 no or expired credential · 403 the credential does not hold work:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 step_not_found, bad_status, bad_transition, bad_result, bad_checkpoint · 429 slow down

work.release_fork

Give a borrowed computer back — The step is done with its copy; the computer worker deletes it.

Needs work:write · changes data

• Canonical address: POST /api/v1/actions/work.release_fork

Input

Preconditions

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

Events it publishes: work.fork_requested

What it writes: work_computer_fork (update) — Marks it to be deleted

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

{
  "ok": true,
  "result": "…",
  "events": [
    "work.fork_requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.workComputerForks.releaseFork("WORK_COMPUTER_FORK_ID")

era work_computer_forks release_fork WORK_COMPUTER_FORK_ID

{
  "name": "era__work__release_fork",
  "arguments": {
    "id": "WORK_COMPUTER_FORK_ID"
  }
}

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

work.replan_step

Re-plan a step’s missing input — A step that found none of the input it needs (no rows to export or import) gets one step that produces it, and waits for it. Machine-only.

Needs work:handle · changes data

• Canonical address: POST /api/v1/actions/work.replan_step

Input

Preconditions

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

Events it publishes: work.step_changed, work.needs_you, work.job_finished

What it writes: work_step (insert) — Adds the step that produces the missing input; work_step (update) — The consumer waits for it and goes back in line; work_job (update) — Notes the re-plan and derives the plan’s status

Errors: 401 no or expired credential · 403 the credential does not hold work:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 step_not_found, not_running, already_replanned, unknown_worker, unknown_executor, unknown_credential, too_many_steps, bad_steps · 429 slow down

work.request_fork

Borrow a copy of my cloud computer — One forked copy of your own signed-in cloud computer for one step, so parallel workers each get their own machine.

Needs work:write · changes data

• Canonical address: POST /api/v1/actions/work.request_fork

Input

Preconditions

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

Events it publishes: work.fork_requested

What it writes: work_computer_fork (insert) — Asks the computer worker for a copy

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

{
  "ok": true,
  "result": "…",
  "events": [
    "work.fork_requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.workComputerForks.requestFork({
  stepId: "WORK_STEP_ID"
})

era work_computer_forks request_fork \
  --step-id "WORK_STEP_ID"

{
  "name": "era__work__request_fork",
  "arguments": {
    "stepId": "WORK_STEP_ID"
  }
}

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

work.requeue_step

Put a step back in line — A step whose process went away goes back in line; the next taker resumes from its checkpoint. Machine-only.

Needs work:handle · changes data

• Canonical address: POST /api/v1/actions/work.requeue_step

Input

Preconditions

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

Events it publishes: work.step_changed, work.needs_you, work.job_finished

What it writes: work_step (update) — Queues the step, keeping its checkpoint; work_job (update) — Derives the plan’s status

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

work.resume_job

Resume a plan — Puts a stopped or failed plan’s unfinished steps back in line.

Needs work:write · changes data

• Canonical address: POST /api/v1/actions/work.resume_job

Input

Preconditions

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

Events it publishes: work.job_resumed

What it writes: work_step (update) — Queues the stopped and failed steps again; work_job (update) — Marks the plan running

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

{
  "ok": true,
  "result": "…",
  "events": [
    "work.job_resumed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.workJobs.resumeJob("WORK_JOB_ID")

era work_jobs resume_job WORK_JOB_ID

{
  "name": "era__work__resume_job",
  "arguments": {
    "id": "WORK_JOB_ID"
  }
}

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

work.retry_step

Try a step again — Puts a failed, stopped or skipped step back in line.

Needs work:write · changes data

• Canonical address: POST /api/v1/actions/work.retry_step

Input

Preconditions

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

Events it publishes: work.step_changed

What it writes: work_step (update) — Queues the step again; work_job (update) — Marks the plan running

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

{
  "ok": true,
  "result": "…",
  "events": [
    "work.step_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.workSteps.retryStep("WORK_STEP_ID")

era work_steps retry_step WORK_STEP_ID

{
  "name": "era__work__retry_step",
  "arguments": {
    "id": "WORK_STEP_ID"
  }
}

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

work.review_skill

Decide what Era keeps — Keep it (the workspace’s Eras may use it), keep it private (only yours), correct it, or forget it.

Needs work:write · changes data

• Canonical address: POST /api/v1/actions/work.review_skill

Input

Preconditions

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

Events it publishes: work.skill_reviewed

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

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

{
  "ok": true,
  "result": "…",
  "events": [
    "work.skill_reviewed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.workJobs.reviewSkill("WORK_JOB_ID", {
  decision: "keep"
})

era work_jobs review_skill WORK_JOB_ID \
  --decision "keep"

{
  "name": "era__work__review_skill",
  "arguments": {
    "id": "WORK_JOB_ID",
    "decision": "keep"
  }
}

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

work.set_limits

Change a plan’s time limit — How many minutes a plan may run. A plan held at its time limit goes on from where it stopped.

Needs work:write · changes data

• Canonical address: POST /api/v1/actions/work.set_limits

Input

Preconditions

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

Events it publishes: work.limits_changed, work.needs_you, work.job_finished

What it writes: work_job (update) — Writes the time limit; lifts the hold it caused

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

{
  "ok": true,
  "result": "…",
  "events": [
    "work.limits_changed",
    "work.needs_you",
    "work.job_finished"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.workJobs.setLimits("WORK_JOB_ID", {
  maxMinutes: 1
})

era work_jobs set_limits WORK_JOB_ID \
  --max-minutes 1

{
  "name": "era__work__set_limits",
  "arguments": {
    "id": "WORK_JOB_ID",
    "maxMinutes": 1
  }
}

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

work.set_shop_rule

Set when Era buys without asking — Purchases up to this amount at this store (or every store) go through without the confirmation card. Empty or 0 = ask every time, which is the default.

Needs work:write · changes data

• Canonical address: POST /api/v1/actions/work.set_shop_rule

Input

Preconditions

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

Events it publishes: work.shop_rule_changed

What it writes: shop_rule (update) — Writes or clears the person’s limit for that store

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

{
  "ok": true,
  "result": "…",
  "events": [
    "work.shop_rule_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.shopRules.setShopRule({
  store: "Store"
})

era shop_rules set_shop_rule \
  --store "Store"

{
  "name": "era__work__set_shop_rule",
  "arguments": {
    "store": "Store"
  }
}

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

work.start_job

Start a plan — Era’s plan for one ask: numbered steps, each for a worker (dev, research, growth, marketing, creative, data, business, computer), run in parallel where nothing waits.

Needs work:write · changes data

• Canonical address: POST /api/v1/actions/work.start_job

Input

Preconditions

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

Events it publishes: work.job_started

What it writes: work_job (insert) — Writes the plan, running or waiting for approval; work_step (insert) — Writes its steps, queued

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

{
  "ok": true,
  "result": "…",
  "events": [
    "work.job_started"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.workJobs.startJob({
  title: "Name",
  steps: {}
})

era work_jobs start_job --data '{"title":"Name","steps":{}}'

{
  "name": "era__work__start_job",
  "arguments": {
    "title": "Name",
    "steps": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold work:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 bad_limits, bad_deliverable, empty_title, no_steps, too_many_steps, bad_steps, unknown_worker, unknown_executor, unknown_credential, bad_dependency, duplicate_step · 429 slow down

work.stop_job

Stop a plan — "Dur": every step that has not finished stops; what is done stays done.

Needs work:write · changes data

• Canonical address: POST /api/v1/actions/work.stop_job

Input

Preconditions

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

Events it publishes: work.job_stopped

What it writes: work_step (update) — Stops every unfinished step; work_job (update) — Marks the plan stopped and notes it

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

{
  "ok": true,
  "result": "…",
  "events": [
    "work.job_stopped"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.workJobs.stopJob("WORK_JOB_ID", {
  reason: "Why"
})

era work_jobs stop_job WORK_JOB_ID \
  --reason "Why"

{
  "name": "era__work__stop_job",
  "arguments": {
    "id": "WORK_JOB_ID",
    "reason": "Why"
  }
}

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

work.supervise_step

Supervise a running step — The work sweep’s ladder: nudge a quiet step, interrupt and send it again (twice at most), hand it to you when it stays stuck, remind you once about an unanswered approval. Machine-only.

Needs work:handle · changes data

• Canonical address: POST /api/v1/actions/work.supervise_step

Input

Preconditions

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

Events it publishes: work.step_changed, work.needs_you, work.job_finished

What it writes: work_step (update) — Writes the ladder’s state; queues a restarted step (keeping its checkpoint) or hands a stuck one to you; work_job (update) — Derives the plan’s status

Errors: 401 no or expired credential · 403 the credential does not hold work:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 step_not_found, bad_supervision, not_running, recoveries_used, not_waiting, already_reminded · 429 slow down

work.use_result

Use a result — Records that a result card was used or published (the card’s own action runs as you).

Needs work:write · changes data

• Canonical address: POST /api/v1/actions/work.use_result

Input

Preconditions

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

Events it publishes: work.result_used

What it writes: work_step (update) — Marks the card used or live

curl -X POST https://app.getera.io/api/v1/work_steps/WORK_STEP_ID/actions/use_result \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"card":1,"kind":"use"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "work.result_used"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.workSteps.useResult("WORK_STEP_ID", {
  card: 1,
  kind: "use"
})

era work_steps use_result WORK_STEP_ID \
  --card 1 \
  --kind "use"

{
  "name": "era__work__use_result",
  "arguments": {
    "stepId": "WORK_STEP_ID",
    "card": 1,
    "kind": "use"
  }
}

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

Data models

ShopOrder

Table shop_order · Resource shop_orders

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

Primary key: id

Checks:

• CHECK (((address_label IS NULL) OR (length(address_label) <= 300)))
• CHECK (((card_last4 IS NULL) OR (card_last4 ~ '^[0-9]{4}$'::text)))
• CHECK (((courier IS NULL) OR (length(courier) <= 200)))
• CHECK ((currency ~ '^[A-Z]{3}$'::text))
• CHECK (((delivery_fee_minor IS NULL) OR (delivery_fee_minor >= 0)))
• CHECK (((eta IS NULL) OR (length(eta) <= 200)))
• CHECK ((jsonb_typeof(items) = 'array'::text))
• CHECK (((order_no IS NULL) OR (length(order_no) <= 120)))
• CHECK ((length(request) <= 1000))
• CHECK ((store ~ '^[a-z_]{2,40}$'::text))
• CHECK (((total_minor IS NULL) OR (total_minor >= 0)))
• CHECK (((track_url IS NULL) OR (length(track_url) <= 2000)))

ShopRule

Table shop_rule · Resource shop_rules

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

Primary key: id

Unique: workspace_id, user_id, store

Checks:

• CHECK (((ask_above_minor > 0) AND (ask_above_minor <= 10000000)))
• CHECK ((currency ~ '^[A-Z]{3}$'::text))
• CHECK ((store ~ '^(\*\|[a-z_]{2,40})$'::text))

WorkComputerFork

Table work_computer_fork · Resource work_computer_forks

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

Primary key: id

Checks:

• CHECK (((device_id IS NULL) OR (length(device_id) <= 200)))
• CHECK (((error IS NULL) OR (length(error) <= 500)))
• CHECK (((external_id IS NULL) OR (length(external_id) <= 200)))
• CHECK ((seconds_used >= 0))

WorkJob

Table work_job · Resource work_jobs

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

Primary key: id

Checks:

• CHECK ((length(goal) <= 8000))
• CHECK (((hold IS NULL) OR ((jsonb_typeof(hold) = 'object'::text) AND (hold ? 'kind'::text))))
• CHECK (((learned IS NULL) OR ((jsonb_typeof(learned) = 'object'::text) AND (learned ? 'status'::text))))
• CHECK (((max_minutes IS NULL) OR ((max_minutes >= 1) AND (max_minutes <= 10080))))
• CHECK (((next_step IS NULL) OR (length(next_step) <= 300)))
• CHECK ((jsonb_typeof(scope_ctx) = 'object'::text))
• CHECK ((jsonb_typeof(steering) = 'array'::text))
• CHECK (((summary IS NULL) OR (length(summary) <= 4000)))
• CHECK (((length(btrim(title)) >= 1) AND (length(btrim(title)) <= 200)))

WorkStep

Table work_step · Resource work_steps

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

Primary key: id

Checks:

• CHECK (((activity IS NULL) OR (length(activity) <= 300)))
• CHECK (((attempts >= 0) AND (attempts <= 1000)))
• CHECK (((checkpoint IS NULL) OR (jsonb_typeof(checkpoint) = 'object'::text)))
• CHECK (((error IS NULL) OR (length(error) <= 1000)))
• CHECK (((executor_ref IS NULL) OR (length(executor_ref) <= 200)))
• CHECK ((length(instruction) <= 8000))
• CHECK (((need IS NULL) OR (jsonb_typeof(need) = 'object'::text)))
• CHECK ((("position" >= 1) AND ("position" <= 50)))
• CHECK (((progress >= 0) AND (progress <= 100)))
• CHECK ((jsonb_typeof(result) = 'object'::text))
• CHECK (((jsonb_typeof(run) = 'object'::text) AND (run ? 'kind'::text)))
• CHECK (((runtime IS NULL) OR (length(runtime) <= 300)))
• CHECK (((supervision IS NULL) OR (jsonb_typeof(supervision) = 'object'::text)))
• CHECK (((length(btrim(title)) >= 1) AND (length(btrim(title)) <= 200)))

Events

Workflows and webhooks react to these events.