---
title: "Plan controlled action adapter handoff"
method: POST
path: "/official-adapter-invocation-plan"
---

# Plan controlled action adapter handoff

`POST /official-adapter-invocation-plan`

## Request

- Base URL: `https://api.gravityads.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gravityads.dev/official-adapter-invocation-plan`
- Auth: HTTP bearer

Builds an adapter invocation plan for an approved controlled action. Persist=false keeps planning separate from execution.

## Request body

- object
  - `action_id` string, required
  - `operator_id` string
  - `adapter` 'auto' | 'google_ads_api' | 'meta_official_mcp' | 'microsoft_ads_rest_api' | 'noop': Optional adapter hint. When omitted or auto, the server derives the adapter from the persisted controlled-action platform.
  - `execute_mode` 'dry_run' | 'live': Hosted live execution must hand off to the action worker; request-time adapter dispatch is not allowed in hosted SaaS.
  - `adapter_context` object
  - `persist` boolean

## Response `200`

Invocation plan

- object
  - `schema_version` string
  - `status` string
  - `summary` object
  - `authority_flags` object
    - `platform_write_allowed` boolean
  - `request` object
    - `action_id` string
    - `adapter` string
    - `execute_mode` 'dry_run' | 'live'
    - `persist` boolean

---

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