Create or update the environment recipe

curl -X PUT https://api.ara.so/v3/organizations/orgId/environment/recipe \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "contents": "base:\n  image: python:3.10-slim\n  packages:\n    - git\n    - curl\nenv:\n  variables:\n    ENV: production\ninitialize:\n  commands:\n    - pip install -r requirements.txt\nsession_start:\n  commands:\n    - ./"
}'

{
  "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
  "tier": "org",
  "repo_full_name": "",
  "contents": "base:\n  image: python:3.10-slim\n  packages:\n    - git\n    - curl\nenv:\n  variables:\n    ENV: production\ninitialize:\n  commands:\n    - pip install -r requirements.txt\nsession_start:\n  commands:\n    - ./",
  "source": "org",
  "updated_by": "jane.doe@example.com",
  "created_at": "2024-06-01T12:00:00Z",
  "updated_at": "2024-06-10T15:30:00Z"
}

Validates the recipe YAML and stores it. repo_name selects the tier. Changes apply at the next session start.

_{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 stored recipe.

idstring

tierenum

repo_full_namestring or null

contentsstring

sourcestring

updated_bystring or null

created_atstring

updated_atstring

Errors

400

Bad Request Error

403

Forbidden Error