> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clawb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Enterprise policy sync API

> Apply desired-state policy specs through a CI/CD-friendly sync endpoint.

Use this endpoint to treat policy configuration as code.

## POST `/v1/policies/sync`

Canonical policy sync endpoint.

## POST `/v1/sync`

Alias endpoint with the same behavior and response contract as `/v1/policies/sync`.

### Auth

Dashboard user session auth (not workspace API key).

### Idempotency

You can set `Idempotency-Key` header to make repeated CI retries safe.

<CodeGroup>
  ```http HTTP theme={null}
  Idempotency-Key: deploy-2026-02-21-001
  ```
</CodeGroup>

<CodeGroup>
  ```bash curl theme={null}
  curl -sS -X POST https://api.clawb.ai/api/v1/policies/sync \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: deploy-2026-02-21-001" \
    -b "<dashboard-session-cookie>" \
    -d '{"dry_run":true,"spec":{"reusable_policy_blocks":{},"agent_groups":[],"bindings":[],"global_guardrails":{}}}'
  ```

  ```python Python SDK theme={null}
  from clawb_agent_sdk import ClawbClient

  client = ClawbClient(base_url="https://api.clawb.ai/api")

  sync_out = client.post(
      "/v1/policies/sync",
      headers={"Cookie": "<dashboard-session-cookie>"},
      json={
          "dry_run": True,
          "spec": {
              "reusable_policy_blocks": {},
              "agent_groups": [],
              "bindings": [],
              "global_guardrails": {},
          },
      },
  )
  print(sync_out)
  ```
</CodeGroup>

### Response patterns

Dry run:

<CodeGroup>
  ```json JSON theme={null}
  {
    "ok": true,
    "dry_run": true,
    "policy_id": "pol_enterprise_sync",
    "current_policy_hash": "...",
    "desired_policy_hash": "...",
    "diff": {"changed": true}
  }
  ```
</CodeGroup>

Conflict:

<CodeGroup>
  ```json JSON theme={null}
  {
    "error": "sync_conflict",
    "current_policy_hash": "..."
  }
  ```
</CodeGroup>

### Junior developer workflow

1. Run `dry_run=true` first in CI.
2. Validate `diff` output.
3. Apply with `dry_run=false` and idempotency key.
4. Fail the pipeline on `sync_conflict` and rebase policy source.

## What gets synchronized

In addition to policy upserts, the sync process materializes group-to-policy bindings and group memberships from the submitted spec.