Build API

Turn an idea into a real app: ERA composes it from its own building blocks, or your coding tools change your repository and ERA opens the pull request with a preview.

Module code build · 10 actions · 2 data models · 6 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: build (everything), build:read (read only) or build:<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

build.archive_project

Archive a project — Takes it off the Projects list. Its site, repository and pull requests are not touched.

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

• Canonical address: POST /api/v1/actions/build.archive_project

Input

Preconditions

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

What it writes: build_project (update) — → archived

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

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

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.buildProjects.archiveProject("BUILD_PROJECT_ID")

era build_projects archive_project BUILD_PROJECT_ID

{
  "name": "era__build__archive_project",
  "arguments": {
    "id": "BUILD_PROJECT_ID"
  }
}

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

build.cancel_run

Stop a build — Stops it; the coding tool on the computer is stopped too. Nothing is committed.

Needs build:write · removes or cannot be undone

• Canonical address: POST /api/v1/actions/build.cancel_run

Input

Preconditions

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

What it writes: build_run (update) — → cancelled; build_project (update) — Back to ready or draft

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

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

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.buildRuns.cancelRun("BUILD_RUN_ID")

era build_runs cancel_run BUILD_RUN_ID

{
  "name": "era__build__cancel_run",
  "arguments": {
    "id": "BUILD_RUN_ID"
  }
}

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

build.complete_run

Finish a build — Records what was built: the pull request and its files, or the composed app and where it is live. Machine-only.

Needs build:handle · changes data

• Canonical address: POST /api/v1/actions/build.complete_run

Input

Preconditions

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

Events it publishes: build.run_succeeded

What it writes: build_run (update) — → succeeded, with its result; build_project (update) — → ready, with its preview / live address

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

build.create_project

Start a project — An app ERA composes from its own building blocks, or a code repository ERA works on with your coding tools.

Needs build:write · changes data

• Canonical address: POST /api/v1/actions/build.create_project

Input

Preconditions

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

Events it publishes: build.project_created

What it writes: build_project (insert) — Writes the project

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

{
  "ok": true,
  "result": "…",
  "events": [
    "build.project_created"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.buildProjects.createProject({
  kind: "app",
  name: "Name"
})

era build_projects create_project \
  --kind "app" \
  --name "Name"

{
  "name": "era__build__create_project",
  "arguments": {
    "kind": "app",
    "name": "Name"
  }
}

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

build.fail_run

Mark a build failed — Records why it stopped and at which step. Machine-only.

Needs build:handle · changes data

• Canonical address: POST /api/v1/actions/build.fail_run

Input

Preconditions

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

Events it publishes: build.run_failed

What it writes: build_run (update) — → failed; build_project (update) — → failed, unless an earlier build left it ready

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

build.record_preview

Record a preview — The pull request’s preview deployment appeared (Vercel, Netlify, Cloudflare Pages…). Machine-only.

Needs build:handle · changes data

• Canonical address: POST /api/v1/actions/build.record_preview

Input

Preconditions

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

Events it publishes: build.preview_ready

What it writes: build_run (update) — Sets the preview; build_project (update) — Sets the project’s latest preview

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

build.record_progress

Record build progress — Moves a build to its next step (getting the repo ready, writing, opening the pull request). Machine-only.

Needs build:handle · changes data

• Canonical address: POST /api/v1/actions/build.record_progress

Input

Preconditions

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

What it writes: build_run (update) — Status, step and where it runs

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

build.record_publish

Record that an app went live — The person approved the draft and its site was published (site.publish, as them). Machine-only: it records the live address.

Needs build:handle · reaches outside (sends, publishes or charges)

• Canonical address: POST /api/v1/actions/build.record_publish

Input

Preconditions

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

Events it publishes: build.app_published

What it writes: build_project (update) — → live, with its address; build_run (update) — The last app run’s "live" step done

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

build.request_run

Build or change something — For an app project: ERA composes the app from its building blocks (modules, workflows, Eras, a site) and shows it as a draft to publish — or puts it live when you say "publish it". With a linked repository, your coding tool (Claude Code, Codex, Antigravity, Copilot, Cursor … any the Harness Manager runs) changes the code on your computer and ERA opens a pull request with a preview; "mobile" asks Expo for an iPhone / Android build.

Needs build:write · changes data

• Canonical address: POST /api/v1/actions/build.request_run

Input

Preconditions

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

Events it publishes: build.run_requested

What it writes: build_run (insert) — Queues the run with its steps; build_project (update) — → building

curl -X POST https://app.getera.io/api/v1/build_projects/BUILD_PROJECT_ID/actions/request_run \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"prompt":"What to build or change"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "build.run_requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.buildProjects.requestRun("BUILD_PROJECT_ID", {
  prompt: "What to build or change"
})

era build_projects request_run BUILD_PROJECT_ID \
  --prompt "What to build or change"

{
  "name": "era__build__request_run",
  "arguments": {
    "projectId": "BUILD_PROJECT_ID",
    "prompt": "What to build or change"
  }
}

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

build.update_project

Change a project — Rename it, describe it, connect its repository (an app’s custom code too), pick the coding tool and computer, or set the Expo project for phone builds.

Needs build:write · changes data

• Canonical address: POST /api/v1/actions/build.update_project

Input

Preconditions

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

What it writes: build_project (update) — Changes the project

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

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

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.buildProjects.updateProject("BUILD_PROJECT_ID", {
  name: "Name"
})

era build_projects update_project BUILD_PROJECT_ID \
  --name "Name"

{
  "name": "era__build__update_project",
  "arguments": {
    "id": "BUILD_PROJECT_ID",
    "name": "Name"
  }
}

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

Data models

BuildProject

Table build_project · Resource build_projects

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

Primary key: id

Checks:

• CHECK (((harness IS NULL) OR (harness ~ '^[a-z][a-z0-9_]{1,31}$'::text)))
• CHECK ((length(btrim(name)) > 0))
• CHECK (((repo_provider IS NULL) OR (repo_provider = ANY (ARRAY['github'::text, 'gitlab'::text]))))
• CHECK (((site_state IS NULL) OR (site_state = ANY (ARRAY['draft'::text, 'live'::text]))))

BuildRun

Table build_run · Resource build_runs

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

Primary key: id

Events

Workflows and webhooks react to these events.