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

# Migrate V3 write requests

> Update V3 REST, MCP, and SDK write callers to send one explicit request operation.

As each tool moves to its explicit V3 request contract, update every REST, MCP,
and SDK caller before deploying it. V3 does not accept a request that infers an
operation from its fields or mixes fields from different operations. The
generated OpenAPI and SDK types contain the exact fields for each branch.

The table describes the launch target. A tool changes only when its own slice
merges, so `tools/list` remains the source of truth for the active account.
If a caller needs to correct a rejected request, follow the
[V3 error-handling guide](https://docs.apostra.com/v3/errors.md).

| Tool | Required field | Values | Example |
| - | - | - | - |
| `save_ask` | `kind` | `create`, `update` | `{ "kind": "create", "type": "support", "title": "Need help", "detail": "Describe the issue." }` |
| `save_lesson` | `action` | `propose`, `approve`, `retire` | `{ "action": "propose", "lesson": { "scope": { "kind": "all_briefs" }, "kind": "tone", "payload": { "kind": "tone", "style": "direct" }, "sellerWords": "Use concise package names.", "provenance": { "sessionId": "SESSION_ID" } } }` |
| `generate_variants` | `scope`; `variantAction` | `scope`: `campaign` or `advertiser`; `variantAction`: `generate` starts a generation, `feedback` refines a named parent variant | `{ "scope": "campaign", "variantAction": "generate", "campaignId": "CAMPAIGN_ID", "sessionId": "SESSION_ID", "actionKey": "ACTION_KEY" }` |

## Billing writes

`save_billing` has no `operation` field. It takes `terms`, `paymentTerms`, a
card removal (`paymentMethod`), or a pay now (`payNow`), each sent alone, and a
call sends at least one:
`{ "terms": { "accepted": true, "acceptedVersion": "VERSION" } }` or
`{ "paymentTerms": "net_60" }`. The `idempotencyKey` is optional for
`paymentTerms` and required for `paymentMethod` and `payNow`, and is accepted
only with those three. A `paymentTerms`, `paymentMethod` or `payNow` call
returns `approval_required`, and an administrator approves it on Apostra. Request and
confirm payment authority with `request_payment_authority` and
`confirm_payment_authority`, and read its status with `get` and
`kind: "billing"`. A request returns `approval_required` until an administrator
approves the card setup on the Apostra site; see [Set up a card payment
method](https://docs.apostra.com/v3/tool-reference.md#set-up-a-card-payment-method). The HTTP API, the SDKs and the MCP server accept only this
shape: a call that sends `operation` or `paymentAuthority` is refused with a
validation error.

## `save_agent` takes no operation

`save_agent` no longer has an `operation` field. Its fields say what it does:

* A Seller account sends `agentId`, `productMode` and `reason` to confirm or
  correct a Sales Agent's product mode.
* An Agents account sends no `agentId` to register a Sales or Creative Agent
  (`kind`, `displayName`, `idempotencyKey`), or an owned `agentId` with
  `displayName`, `certificationRequested` or both to update it.
* A buyer agent is created with `save_buyer_agent`, not `save_agent`.

A call that still sends the old `operation` values (`seller_save`,
`developer_create` or `developer_update`) is refused with a validation error.
Send the fields above instead. The HTTP API and the SDKs have only ever taken
the new shape.

## `save_buyer_agent` takes no operation

`save_buyer_agent` has no `operation` field and no `lifecycle` object. Without
`id` it creates a buyer agent (`displayName`). With `id` it carries exactly one
change: `displayName` to rename, `access` to replace advertiser grants,
`lifecycleState` with `expectedLifecycleState` to resume, suspend or retire, or
`credentialHandoff`. A call that still sends the old `operation` values
(`create`, `update_display_name`, `update_access`, `lifecycle` or
`credential_handoff`) or a `lifecycle.action` is refused with a validation
error.

## `save_material` takes no action

`save_material` no longer has an `action` field. Its fields say what it does, and
a call declares one change:

* No `materialId` creates a Material (`clientRequestId`, `source`).
* A `materialId` with `source`, `expectedRevision` and `clientRequestId` adds a
  source revision; with `metadata` or `labels` and `expectedRevision` it edits the
  Material.
* `isArchived: true` archives a Material and `isArchived: false` restores it.
* `candidateDecisions` (`candidateId`, `sourceRevision`, `decision`) records
  decisions on extracted candidates. Accepting a destination-owned candidate whose
  typed save already ran records its receipt, which `reconcile_candidate` did.
* `unitReusable` (`unitId`, `reusable`) marks slides, pages, or sheets reusable.
* `reprocess` (`sourceRevision`), with `clientRequestId`, asks for a new
  rendition.
* `commitPreview` (`sourceRevision`, `previewToken`) applies a previewed rate
  card or avails sheet. The Material's `documentType` picks which.

An MCP call that still sends one of the old `action` values (`create`,
`replace_source`, `update_metadata`, `reprocess`, `decide_candidate`,
`reconcile_candidate`, `mark_reusable`, `archive`, `restore`,
`preview_rate_card`, `commit_rate_card`, `preview_avails_sheet` or
`commit_avails_sheet`) is refused with a validation error. Send the fields above
instead.

The rate-card and avails-sheet previews are now reads: call `get` with
`kind: "material"` and the `rate_card_preview` or `avails_sheet_preview`
include, then send its `previewToken` in `commitPreview`.

The source and candidate shapes are also closed:

* A structure node's `provenance` takes a list of `{ "key", "value" }` entries
  in place of a map: send `"provenance": [{ "key": "parser", "value": "pdfium" }]`
  instead of `"provenance": { "parser": "pdfium" }`.
* A rendition's `completeness` takes an object with any of `text`, `structure`,
  `tables`, `visuals` and `styles`, each `complete`, `degraded`, `unsupported`
  or `failed`.
* A `correct` decision takes `correction.correctedContent` (`title`,
  `summary`) only. `correction.proposedMutation` is no longer published. To
  change what a typed proposal would do, call its own tool: confirm it with
  exactly the proposed arguments, or call the tool without `materialCandidate`
  and `reject` the candidate.

`get` returns provenance and completeness as stored. An MCP call that still
sends the old shapes keeps working until the next ChatGPT re-approval; it is
deprecated.

The enabled-seller beta **Delete from Apostra** workflow is the exception: its
MCP calls use `preview_permanent_delete`, `delete_permanently`, and
`undo_permanent_delete` action values. It is a destructive connected-Library
workflow, not a general Material write. See [Delete from Apostra](https://docs.apostra.com/v3/delete-from-apostra.md)
for the exact inputs, direct-administrator requirement, and 30-day Undo window.

## `save_rfp` takes no action, and turn writes use `save_rfp_turn`

`save_rfp` no longer has an `action` field. It keeps what belongs to the RFP
itself, and its fields say which:

* With no `rfpId`, it creates an RFP: `clientRequestId`, `origin`, `purpose`,
  `request`.
* With `rfpId` and `parentTurnId`, it revises the RFP with a new `request`.
* With `rfpId` and `endorsed`, it endorses the response (`endorsed: true`, with
  optional `endorsementCommentary`) or removes the endorsement
  (`endorsed: false`). This replaces `endorse` and `unendorse`.
* With `rfpId` and `responseMaterialId`, it attaches an uploaded or
  historical-proposal response. This replaces `attach_response`.

What happens to one turn is a separate tool, `save_rfp_turn`. It takes `rfpId`,
`turnId`, `clientRequestId` and exactly one of `released: true`,
`representation`, `cancelRepresentationId`, `feedback` (with optional typed
`grade`, `ledBy` and `commentary`) or `outcome`. These replace `release_turn`,
`request_representation`, `cancel_representation`, `record_feedback` and
`record_outcome`. Feedback and outcome are append-only events, and a
`representation` starts rendering work.

An MCP call to `save_rfp` that still sends an `action` is refused with a
validation error; send the fields above instead. The HTTP API and the SDKs have
always taken the new shape only.

The facts you name yourself are entries, and the flight is AdCP's date range.
`origin.details`, `feedback` and `outcome.details` take a list of
`{ "key", "value" }` entries in place of an open object, where `value` is text,
a number or `true`/`false`: send `"feedback": [{ "key": "note", "value": "..." }]`
instead of `"feedback": { "note": "..." }`. `request.flight` takes `start` and
`end` (`YYYY-MM-DD`) instead of `startDate` and `endDate`. `request.dimensions`,
`request.constraints` and `strategy` publish only their declared keys, and the
legacy Quick preset (`origin.preset` with `kind: "legacy"`) is no longer
published. `get` returns the same entries and the same flight form. An MCP call
that still sends the old open shapes keeps working until the next ChatGPT
re-approval; it is deprecated.

## `save_wholesale_product` types `inventory`

`inventory` was an open object. It is now the sales agent's own shape:
`execution` (`adapter`, `selectors`, `format_bindings`) and
`publisher_properties`, each field listed and closed. The two settings that
depend on the ad server, a selector's `options` and a format binding's
`adapter_config`, take a list of `{ "key", "value" }` entries in place of an
object: send `"options": [{ "key": "include_descendants", "value": true }]`
instead of `"options": { "include_descendants": true }`. `publisher_properties`
entries are AdCP publisher selectors, so each carries a `selection_type`.
`get` still returns `inventory` as stored. An MCP call that still sends the open
object keeps working until the next ChatGPT re-approval; it is deprecated. The
HTTP API and the SDKs take the new shape only.

## `save_creative_session` takes no operation

`save_creative_session` no longer has an `operation` or a `scope` field. The
owner is the id you send, exactly one of `campaignId` or `advertiserId`, and
the fields say what the request saves:

* `draft` (with an `idempotencyKey`, and optionally `engine`) saves a new
  session from a brief.
* `selectedVariantId` or `approvedVariantId`, with the session's `sessionId` and
  the `expectedRevision` you last read, selects or approves an output.
* `finalization` (`approvedVariantId`, `approvedSessionRevision`, and optionally
  `name` and `message`) finalises the approved output.

A request makes one change: send exactly one of `draft`, `selectedVariantId`,
`approvedVariantId` or `finalization`. A request that sends more than one, or a
field that belongs to a different change, is refused with an error naming the
fields and saves nothing. To select and then approve an output, make two
requests. The tool never generates; `generate_variants` does.

Saving an approved output to the advertiser Library moved to `save_creative`.
Send `advertiserId`, `campaignId` when a campaign owns the session (a session
that belongs to an advertiser Library takes `advertiserId` alone),
`idempotencyKey`, and `fromCreativeSessionOutput` with `sessionId`, `variantId`,
`sessionRevision` and `outputHash`. The response has `action: "promoted"`.

An MCP call that still sends the old `operation` values (`save_draft`,
`select_output`, `approve_output`, `finalize_approved_output` or
`promote_approved_output`) or `scope` is refused with a validation error and
saves nothing. Send the new shape instead. The HTTP API and the SDKs have only
ever taken the new shape.

## `manage_organization` is gone

The `manage_organization` task no longer exists, and it had eleven `action`
values. Organization administrators now use the same tools as everyone else, and
`search({ "kind": "account" })` lists the child accounts:

| What `manage_organization` did | What to call now |
| - | - |
| `inspect_organization` | The Organization account's `get_status`, which reports the child account counts, the Agents account and its next step, and the accounts it uses |
| `inspect_account` | `get({ "kind": "account", "id": "ACCOUNT_ID", "include": ["lifecycle", "capacity"] })` |
| `request_create_account` | `save_account` with no `id`: `{ "accountType": "buyer", "name": "Name", "reason": "Why it is needed", "idempotencyKey": "UUID" }` |
| `request_rename_account` | `save_account` with `id`, the new `name`, a `reason` and an `idempotencyKey` |
| `request_account_lifecycle` | `save_account` with `id`, `isArchived` (`true` archives, `false` restores), a `reason` and an `idempotencyKey` |
| `review_create_account`, `review_rename_account`, `review_account_lifecycle` | The same `save_account` call with `dryRun: true` and no `idempotencyKey` |
| `check_request_outcome` | Repeat the `save_account` call with the same `idempotencyKey` |
| `review_demo_storefront`, `request_demo_storefront` | `save_account` with `accountType: "seller"`, `demoStorefront: true`, a `name`, a `reason` and `organizationId`; `dryRun: true` previews. Platform operators only |

`save_account` returns an `approval_required` link for a create, rename, archive
or restore, exactly as `manage_organization` did. The model never approves: an
administrator of the organization does, on the website. `organizationId` replaces
`parentId`: send it to act in an organization you are not connected to, or omit
it to act in the organization account you are in. There is no `orgRef`; the
server reads it. The V3 HTTP API and the SDKs have no operation
named `manage_organization`; it was only ever an MCP task.

## Discriminated write values

`save_rfp` budgets carry `kind: "zero_decimal"`, `"two_decimal"`, or
`"three_decimal"`, matching the currency's minor-unit precision. Its Quick
presets carry `kind: "typed"` or `"legacy"` and wrap their value in `value`.
`save_creative` `sourceAssets` entries carry `kind: "asset_ref"` or
`"asset_id"`. `save_media_buy` demographic ages carry `kind: "minimum"`,
`"maximum"`, or `"range"`.

These are request-side V3 discriminators. Buyer-side writes do not change the
payloads sellers receive or what sellers see; Apostra strips these fields before
sending seller protocol payloads. Use the generated OpenAPI and SDK types for
the complete branch fields.

## Seller lessons

`save_lesson` is available to every seller storefront. A seller operator may propose a lesson. Approving or retiring
one requires a directly authenticated seller account admin; impersonated
sessions cannot do either. `pricing_posture` and `decline_behaviour` lessons
can be proposed, but cannot be approved.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.