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}

Authentification

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.

Paramètres de chemin

orgIdstringRequis

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

Requête

This endpoint expects an object.

contentsstringRequis

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_namestringOptionnel

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

providerenumOptionnel

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

Réponse

The build (or null when skipped).

idstringOptionnel

repo_full_namestring or nullOptionnel

recipe_set_hashstringOptionnel

statusenumOptionnel

triggerstring or nullOptionnel

image_refstring or nullOptionnel

error_classstring or nullOptionnel

started_atstring or nullOptionnel

completed_atstring or nullOptionnel

created_atstringOptionnel

updated_atstringOptionnel

Erreurs

400

Bad Request Error