Skip to main content
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.

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. 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 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: 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.