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,productModeandreasonto confirm or correct a Sales Agent’s product mode. - An Agents account sends no
agentIdto register a Sales or Creative Agent (kind,displayName,idempotencyKey), or an ownedagentIdwithdisplayName,certificationRequestedor both to update it. - A buyer agent is created with
save_buyer_agent, notsave_agent.
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
materialIdcreates a Material (clientRequestId,source). - A
materialIdwithsource,expectedRevisionandclientRequestIdadds a source revision; withmetadataorlabelsandexpectedRevisionit edits the Material. isArchived: truearchives a Material andisArchived: falserestores it.candidateDecisions(candidateId,sourceRevision,decision) records decisions on extracted candidates. Accepting a destination-owned candidate whose typed save already ran records its receipt, whichreconcile_candidatedid.unitReusable(unitId,reusable) marks slides, pages, or sheets reusable.reprocess(sourceRevision), withclientRequestId, asks for a new rendition.commitPreview(sourceRevision,previewToken) applies a previewed rate card or avails sheet. The Material’sdocumentTypepicks which.
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
provenancetakes 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
completenesstakes an object with any oftext,structure,tables,visualsandstyles, eachcomplete,degraded,unsupportedorfailed. - A
correctdecision takescorrection.correctedContent(title,summary) only.correction.proposedMutationis 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 withoutmaterialCandidateandrejectthe 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
rfpIdandparentTurnId, it revises the RFP with a newrequest. - With
rfpIdandendorsed, it endorses the response (endorsed: true, with optionalendorsementCommentary) or removes the endorsement (endorsed: false). This replacesendorseandunendorse. - With
rfpIdandresponseMaterialId, it attaches an uploaded or historical-proposal response. This replacesattach_response.
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 anidempotencyKey, and optionallyengine) saves a new session from a brief.selectedVariantIdorapprovedVariantId, with the session’ssessionIdand theexpectedRevisionyou last read, selects or approves an output.finalization(approvedVariantId,approvedSessionRevision, and optionallynameandmessage) finalises the approved output.
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.