---
title: "Apply a chart"
method: POST
path: "/v1/org/apply"
tags: ["Organization"]
---

# Apply a chart

`POST /v1/org/apply`

## Request

- Base URL: `https://api.1claw.co`
- URL: `https://api.1claw.co/v1/org/apply`
- Auth: HTTP bearer

Create what the chart describes. Human users only.

**Apply calls the same handlers the HTTP routes call.** Creating a vault
runs five gates before anything is written — the delegation scope, a name
check, control-plane consensus, a creation rate limit and the tier quota
— and creating an agent runs its own. A reconciler that wrote through the
repositories would skip all of them and would look, in review, exactly
like one that did not.

So if your org has consensus configured on `vault.create`, applying a
chart queues an approval exactly as a dashboard click would. That resource
comes back as `awaiting_approval` rather than failing the whole chart.

Resource kinds, in the order apply walks them: `vault`, `agent`,
`policy` (one per path pattern, named `vault:agent:path`), `connector`
(`agent/binding_name`; `authorization_url` on the result when a person
still has to sign in) and `binding` (`agent/name`, from
`spec.agents[].bindings` — declared in full with `binding_type`, `config`,
`guardrails.allowed_hosts` and an optional `credential: {vault_ref, path}`
pointing into a chart vault). A dependent resource whose vault or agent
was queued for approval this run is `skipped` with "waiting on …" and is
created by the next apply.

Per-resource results: `created`, `patched`, `unchanged`, `skipped`,
`refused`, `awaiting_approval`, `failed`. `needs_attention` is true when
the chart is not fully applied — something is waiting on a person, whether
an approval, an OAuth sign-in, or a resource that drifted and was left
alone.

Save `applied_state` to `.1claw/apply-state.json`. It records what apply
set, which is what lets the next run tell drift from a first apply.

Apply creates, and patches an agent's `description`/`system_prompt` in
place through the same `update_agent` gate a dashboard edit takes. Policy
permissions, binding config and guardrails, connector presets and vault
fields are create-only: a difference is `refused` with the endpoint that
owns the change. It does not delete or prune. An apply that silently
deletes is an apply nobody runs twice.

## Request body

- object
  - `chart` object, required: A chart document — `apiVersion`, `kind`, `metadata`, `spec`.
  - `applied_state` object

## Response `200`

What happened to each resource

- object
  - `chart_name` string
  - `resources` object[]
    - `kind` string
    - `name` string
    - `result` 'created' | 'patched' | 'unchanged' | 'skipped' | 'refused' | 'awaiting_approval' | 'failed'
    - `id` string, uuid
    - `detail` string
    - `authorization_url` string: Connectors only — where a person signs in to finish the install.
  - `warnings` string[]
  - `applied_state` object: Save to `.1claw/apply-state.json`.
  - `needs_attention` boolean: The chart is not fully applied — something is waiting on a person.

## Other responses

- `400`: Invalid request
- `403`: Insufficient permissions

---

[API](https://skmtc.dev/1claw/apis/1claw-api.md) · [All operations](https://skmtc.dev/1claw/apis/1claw-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1claw/apis/1claw-api/revisions/ae109b496830?raw)