---
title: "Push code-declared action shapes (the SDK's door.sync)"
method: POST
path: "/v1/agent-door/actions/sync"
tags: ["platform-sync"]
---

# Push code-declared action shapes (the SDK's door.sync)

`POST /v1/agent-door/actions/sync`

## Request

- Base URL: `https://api.bubblio.dev`
- URL: `https://api.bubblio.dev/v1/agent-door/actions/sync`
- Auth: HTTP bearer

SHAPES ONLY, never capability: synced actions always arrive with policy `off`, and
`suggestedPolicy`/`approvalSuggestion` are displayed next to the dashboard control,
never applied — which is exactly why API-key auth is allowed here. Idempotent;
actions no longer declared are ORPHANED (flagged, never deleted); destructive-
looking NAMES sync anyway with the suggestion dropped and a warning returned
(machine callers must not 400 on a heuristic). Declaring `connectPath` sets the
phone-connect page; `payments` sets the rails profile (PUBLISHABLE key only —
sk_/rk_ values are refused by name); omitting either clears it.

## Request body

- object
  - `callbackUrl` string, uri, required: https (http for localhost only).
  - `connectPath` string: Path on the platform site, resolved against callbackUrl.
  - `payments` object
    - `rails` string[]
    - `stripePublishableKey` string: pk_… only.
  - `actions` object[], required
    - `name` string, required
    - `description` string, required
    - `parameters` object, required: JSON Schema (object/properties/required).
    - `suggestedPolicy` 'off' | 'keyed' | 'any'
    - `approvalSuggestion` 'auto' | 'mandate' | 'always'
    - `price` object
      - `amount_cents` integer
      - `currency` 'usd'
    - `timeoutSeconds` integer

## Response `200`

The sync result.

- object
  - `synced` integer
  - `orphaned` integer
  - `unchanged` integer
  - `pendingDecision` integer
  - `warnings` string[]

## Other responses

- `400`: One calm sentence naming the malformed field.

---

[API](https://skmtc.dev/bubblio/apis/bubblio-agent-door-api.md) · [All operations](https://skmtc.dev/bubblio/apis/bubblio-agent-door-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bubblio/apis/bubblio-agent-door-api/revisions/d858aff9c01d?raw)