Quickstart

On Levain you don't put one agent in front of one team — you provision a workspace per customer and run agents inside it over the API. This walks that path end to end: provision a workspace, put an agent in it, watch a run finish there. Embedded Agents explains the model behind the calls.

1. Get an org API keyCopy Anchor Link

One org key reaches every workspace in your org; each request picks its workspace with the X-Workspace-Id header. Create a key in the dashboard under Organization settings → API Keys, or via POST /api/v1/org/api-keys — either way the value is shown once.

export LEVAIN_ORG_KEY="sk_live_..."

Provisioning workspaces requires the Enterprise plan; see Plans & Billing. Not there yet? See the note below — the run calls are the same.

2. Provision your first customerCopy Anchor Link

WS_ID=$(curl -s -X POST https://api.levainlabs.com/api/v1/org/workspaces \
  -H "Authorization: Bearer $LEVAIN_ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Tools"}' | jq -r .id)

That's a whole workspace: isolated agents, credentials, runs, and usage, behind a boundary no other customer can cross. It starts empty and headless — nobody signs in to it; your backend acts on it through the API. Store the id against the customer in your own database. Workspaces per Customer covers lifecycle from here.

3. Give it an agentCopy Anchor Link

Author the agent once, at the org level. Build and test it in your primary workspace — describe it in plain language in the dashboard, or author it from your own Claude session (Build from Claude) — then snapshot it into the org registry. Grab $PRIMARY_WS_ID and $AGENT_ID from the agent's detail page in the dashboard and export them:

export PRIMARY_WS_ID="..."
export AGENT_ID="..."

New agents start in draft; promote snapshots the active version, so activate the agent in the dashboard first (see Agent lifecycle).

Pick a slug for the org registry entry promote creates — it's independent of $AGENT_ID, which stays the workspace-level agent's own id — and export it:

export REGISTRY_SLUG="support-triage"

curl -X POST https://api.levainlabs.com/api/v1/org/agents/$REGISTRY_SLUG/promote \
  -H "Authorization: Bearer $LEVAIN_ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "'$PRIMARY_WS_ID'",
    "agent_id": "'$AGENT_ID'"
  }'

Then adopt it into the customer's workspace:

curl -X POST https://api.levainlabs.com/api/v1/managed-agents/$REGISTRY_SLUG/adopt \
  -H "Authorization: Bearer $LEVAIN_ORG_KEY" \
  -H "X-Workspace-Id: $WS_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

Adopted agents follow the registry's active version, so promoting a new version rolls it out to every adopting workspace — Fleet Agents covers the registry.

4. Run it in the customer's workspaceCopy Anchor Link

Runs are asynchronous — post the input, get a run ID back immediately, then poll for progress:

RUN_ID=$(curl -s -X POST https://api.levainlabs.com/api/v1/agents/$REGISTRY_SLUG/runs \
  -H "Authorization: Bearer $LEVAIN_ORG_KEY" \
  -H "X-Workspace-Id: $WS_ID" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Triage the tickets that arrived overnight."}' | jq -r .id)

5. Watch it workCopy Anchor Link

Poll the run to see state transitions, token spend, and cost accumulating in real time:

curl https://api.levainlabs.com/api/v1/runs/$RUN_ID \
  -H "Authorization: Bearer $LEVAIN_ORG_KEY" \
  -H "X-Workspace-Id: $WS_ID"

Or fetch structured log events (the same view as the Logs tab in the dashboard):

curl https://api.levainlabs.com/api/v1/runs/$RUN_ID/log/events \
  -H "Authorization: Bearer $LEVAIN_ORG_KEY" \
  -H "X-Workspace-Id: $WS_ID"

That run executed in the customer's workspace: its own sandbox, its own credentials, billed to its own usage line. Every customer after this one is the same three calls — provision, adopt, run.

Not on Enterprise yet?Copy Anchor Link

Step 2 and the promote call in step 3 need Enterprise — provisioning and promoting are gated by plan, not the run calls. Everything else works in the workspace your team signs in to: create a workspace key under Settings → API Keys — it's scoped to that workspace, unlike the org key from step 1, so export it separately:

export LEVAIN_API_KEY="sk_live_..."

build your agent directly in that workspace instead of promoting it from the org registry (skip promote and adopt). New agents start in draft, so activate it first (see Agent lifecycle) — then run it with steps 4–5's commands, substituting $LEVAIN_API_KEY for $LEVAIN_ORG_KEY, dropping the X-Workspace-Id header and $WS_ID wherever they appear, and setting $AGENT_SLUG to the slug you gave the agent when you created it:

export AGENT_SLUG="support-triage"

RUN_ID=$(curl -s -X POST https://api.levainlabs.com/api/v1/agents/$AGENT_SLUG/runs \
  -H "Authorization: Bearer $LEVAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Triage the tickets that arrived overnight."}' | jq -r .id)

curl https://api.levainlabs.com/api/v1/runs/$RUN_ID \
  -H "Authorization: Bearer $LEVAIN_API_KEY"

curl https://api.levainlabs.com/api/v1/runs/$RUN_ID/log/events \
  -H "Authorization: Bearer $LEVAIN_API_KEY"

Building your own agent needs the Team plan; see Plans & Billing.

Next stepsCopy Anchor Link

• Embedded Agents — the org / workspace / agent model these calls act on.
• Hand off credentials so customer agents can reach customer data.
• Receive webhooks when runs finish, and meter usage per customer.
• Build from Claude — author agents in your own Claude session, with review threads and a verified publish.
• Browse the Organization API reference.