Trigger an environment image build

curl -X POST https://api.ara.so/v3/organizations/orgId/environment/builds \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "contents": "base: ubuntu:22.04\nenv:\n  - NODE_ENV=production\ninitialize:\n  - apt-get update && apt-get install -y curl\nsession_start:\n  - echo '\''Session started'\''\nknowledge:\n  - ara: version 3.0\nclone:\n  - git clone"
}'

{
  "id": "b7f3a9d2-4c1e-4f3a-9a2e-8c9d7f1a2b3c",
  "repo_full_name": "octocat/hello-world",
  "recipe_set_hash": "3a7bd3e2360a3f1b9c8d4e5f6a7b8c9d",
  "status": "pending",
  "trigger": "manual",
  "image_ref": "ara-image-20240601-123456",
  "error_class": "",
  "started_at": "2024-06-01T12:35:00Z",
  "completed_at": "",
  "created_at": "2024-06-01T12:34:50Z",
  "updated_at": "2024-06-01T12:34:50Z"
}

Builds the current Recipe set into an Image. Dedups on the recipe-set hash. Returns a null build when no Image is needed (runs on Tier-0 + the Session Start Script layer).

_{Scope: blueprints:write}

Authentication

AuthorizationBearer

Your ara_ API key from Settings > Ara API. Keys are capability-scoped: run, plugins:read, secrets:read, secrets:write, sessions:read, knowledge:read, repos:read, repos:write, reviews:read, reviews:write, analytics:read, org:read, org:write, attachments:read, attachments:write, plugins:write, guardrails:read, guardrails:write.

Path parameters

orgIdstringRequired

Organization id or slug. Resolve it with GET /v3/self.

Request

This endpoint expects an object.

contentsstringRequired

The environment spec YAML. base, env, and initialize are the Recipe (they build into the Image); session_start, knowledge, and clone sit alongside it and never trigger a build.

repo_namestringOptional

Provider-native repo path for a repo-tier recipe; GitHub uses owner/repo, GitLab may include nested groups. Omit for the org tier.

providerenumOptional

Source-control provider for repo_name. Defaults to GitHub first, then GitLab if no GitHub repository matches.

Response

The build (or null when skipped).

idstringOptional

repo_full_namestring or nullOptional

recipe_set_hashstringOptional

statusenumOptional

triggerstring or nullOptional

image_refstring or nullOptional

error_classstring or nullOptional

started_atstring or nullOptional

completed_atstring or nullOptional

created_atstringOptional

updated_atstringOptional

Errors

400

Bad Request Error