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

# Seller RFP Lifecycle

> Create, compose, inspect, revise, and evaluate seller RFP responses through the authenticated v3 MCP API.

The v3 seller RFP workflow turns one request into an immutable, auditable
request-and-response turn. It works through `/mcp/v3`; no Apostra page is
required. The authenticated account must be a Seller Account.

An **RFP** is the seller's durable commercial opportunity or exercise. An
**RFP turn** is one immutable request and its response. The response is the
seller proposal artifact inside that turn; clients do not save a second
seller-side Proposal object.

## Before creating an RFP

Response composition uses the Seller Account's own active Storefront products.
At least one product must have all of these catalog facts:

* a name, and a `delivery_type` of `guaranteed` or `non_guaranteed` on the
  product itself, which is where AdCP carries it (a pricing option has no
  delivery type of its own, so one that carries it is ignored);
* at least one channel, including a requested channel when the RFP specifies
  one, with a canonical format whose kind can execute in that channel. For a
  managed source that supplies no channel, the catalog infers a channel only
  when that canonical format maps to exactly one composer-compatible channel.
  Ambiguous formats, including common video and audio formats, stay
  unclassified; set `channels` explicitly with `save_wholesale_product`.
  A non-empty seller-authored channel list always takes precedence;
* an explicit positive fixed or floor price with pricing-option ID, an AdCP
  `pricing_model`, and ISO currency; and
* at least one canonical URL-free creative format (`format_kind` plus `params`).

Missing product, price, or format facts are never replaced with an empty
offer. When no complete priced product exists, the turn finishes as
`needs_clarification` and identifies the missing catalog facts instead. When a
complete product exists but cannot execute the buyer's declared channel or
format, the turn finishes `ready` with a bounded `counter_pitch`: the decision
keeps the literal request separate from the substitute and lists every gap.

`pricingStatus` on a wholesale-product read is the source's coverage result,
not a guarantee that the response includes a quoteable option. Read
`composerCompleteness.missing` beside it to see the request-independent channel,
format, or priced-option fact that must be repaired. A particular RFP still
requires an option in its requested currency.
Composition scans at most 1,000 products and applies declared field,
collection, and artifact-size limits. Request prose may contain tabs and line
breaks. Unicode bidirectional controls, C1 controls, and unsafe C0 controls are
rejected in prose. Leading/trailing Unicode whitespace (including TAB/LF/CR) is
trimmed from structural identifiers and field names; the trimmed value must
contain a visible character and no C0/C1 controls, bidi controls, or
line/paragraph separators. A larger catalog or response also ends in explicit clarification;
Apostra never returns a partial proposal as `ready`.

The deterministic planner treats a channel label and a usable execution as
separate facts. For example, a product labelled `video` does not satisfy a
video request when its selected format options contain only `image`; it needs
`video_hosted` or `video_vast`. Explicit format kinds, sent as AdCP's
`format_kinds` in `request.dimensions` or `request.constraints`, are matched against the
same format kind that makes the declared channel executable, so unrelated
formats on one product cannot be combined into a false match. New typed
requests use `origin.channels`, `origin.preset.channels`, or
`request.dimensions.channels`. Bounded legacy `origin.preset.channel` and
`request.dimensions.channel` values remain accepted and normalized for
compatibility; `origin.channel` is not part of the public `save_rfp` input
schema. These structured declarations populate `decision.requested.channels`.
A channel mentioned in brief prose does not add or override buyer intent. Only structured
`dimensions.productCount` or `constraints.productCount` and
`dimensions.planRoles` or `constraints.planRoles` populate certified buyer
cardinality and roles; prose such as “one-line” or “anchor store” is not
published as authored plan intent. The planner does not certify buyer-authored
strategic roles from channel and format compatibility. It records structured
`planRoles` as requested intent. When the seller is otherwise responding with
a proposal, those roles add a `requested_role_evidence_unavailable` limitation
and yield a `counter_pitch`, even when the catalog otherwise supports the
request; an explicit seller pass remains a pass. Supported execution roles and
rationales are separate seller-derived facts. Measurement intent is certified
only from `request.constraints.measurementRequirements`, never inferred from
the brief. Declared
`reporting_capabilities.available_metrics`
can verify a supported measurement; missing or incomplete reporting evidence
remains an explicit limitation. If the catalog cannot support the literal count, the response also
names that limitation and clearly labels the supported product mix as a
substitute.

`request.dimensions` and `request.constraints` use one spelling for each field.
`format_kinds` is AdCP's own name for the requested format kinds, and every
other field is ours and camelCase: `productCount`, `planRoles`,
`measurementRequirements`, `requiredInputs`, `requiredCreativeInputs` and
`creativeInputs`. A retired spelling (`formatKinds`, `product_count`,
`plan_roles`, `measurement_requirements`, `required_inputs`,
`required_creative_inputs`, `creative_inputs`, and `strategy.pass_reason`) is
refused, and the refusal names the spelling to send. The planner reads each
field from `dimensions` and `constraints`, so a product count declared in both
must match. Conflicting counts are treated as invalid cardinality intent and
produce clarification rather than silently choosing one.

The channel-to-format compatibility vocabulary is closed and deterministic:

| Channel | Compatible canonical `format_kind` values |
| - | - |
| `display` | `image`, `html5`, `display_tag`, `image_carousel`, `native_in_feed`, `sponsored_placement`, `responsive_creative`, `custom` |
| `olv` | `video_hosted`, `video_vast`, `custom` |
| `social` | `image`, `image_carousel`, `video_hosted`, `native_in_feed`, `custom` |
| `search` | `sponsored_placement`, `responsive_creative`, `custom` |
| `ctv` | `image`, `native_in_feed`, `sponsored_placement`, `video_hosted`, `video_vast`, `custom` |
| `linear_tv` | `sponsored_placement`, `video_hosted`, `video_vast`, `custom` |
| `radio` | `audio_hosted`, `audio_daast`, `sponsored_placement`, `custom` |
| `streaming_audio` | `audio_hosted`, `audio_daast`, `sponsored_placement`, `custom` |
| `podcast` | `audio_hosted`, `audio_daast`, `sponsored_placement`, `custom` |
| `dooh` | `image`, `video_hosted`, `video_vast`, `sponsored_placement`, `custom` |
| `ooh` | `image`, `custom` |
| `print` | `image`, `custom` |
| `cinema` | `video_hosted`, `video_vast`, `custom` |
| `email` | `image`, `html5`, `responsive_creative`, `custom` |
| `gaming` | `image`, `html5`, `video_hosted`, `native_in_feed`, `sponsored_placement`, `custom` |
| `retail_media` | `sponsored_placement`, `native_in_feed`, `image`, `video_hosted`, `custom` |
| `influencer` | `image`, `image_carousel`, `video_hosted`, `native_in_feed`, `custom` |
| `affiliate` | `sponsored_placement`, `native_in_feed`, `custom` |
| `product_placement` | `sponsored_placement`, `custom` |
| `sponsored_intelligence` | `agent_placement`, `sponsored_placement`, `custom` |

Supported structured measurement requirements and their accepted catalog
metrics are:

| Requirement | Accepted `available_metrics` values |
| - | - |
| `brand_lift` | `brand_lift` |
| `closed_loop_attribution` | `units_sold`, `incremental_sales_lift`, `new_to_brand_units`, `foot_traffic` |
| `sales_attribution` | `units_sold`, `incremental_sales_lift`, `conversion_value`, `roas`, `new_to_brand_units` |

When multiple measurement requirements are supplied, every distinct requirement
is preserved and verified independently; no requirement subsumes another.

A ready semantic document exposes this result at `decision`: `disposition` is
`pitch` or `counter_pitch`; `requested` records channels, format kinds, product
count, and buyer-authored roles; `supported.roles` binds each verified execution
role to a product and readable rationale without claiming that catalog-derived
roles are buyer-authored; and `limitations` lists the exact
gaps. Commercial allocations also carry that `role` and `rationale`. A
single-product allocation explains why the only supported product receives
100%, rather than presenting an unexplained default split. Missing budget or
request-required flight, audience, or creative inputs produces a bounded
counter or clarification, never an apparently complete approval request.
When the buyer requests an exact demographic age range that the seller's
catalog cannot execute, the decision is likewise a `counter_pitch`: it keeps
the available proposal, names that age targeting was not applied, and lists
the exact supported ranges (or states that none are declared).
When age is stated only in audience prose, the planner reads it in any
language. If that reader is unavailable in a deployed environment, the turn
still composes and tells both parties that audience age constraints were not
verified or applied. Send one closed range in `dimensions.age` to apply age
targeting. A local or test environment without reader credentials remains
silent.
The turn's `response`, its `semanticDocument` and `buyerProposalProjection`
name AdCP objects with AdCP's own fields. Our references sit beside them in
camelCase (`productRef`, `priceRef`, `formatRef`). A product carries
`product_id` and `delivery_type`, and its `channels` are AdCP media channels.
Only the product carries the delivery type; a price, allocation or format row
does not repeat it. A price carries `pricing_option_id`, `pricing_model` (an
AdCP pricing model), `currency`, and exactly one of `fixed_price` or
`floor_price`. An allocation carries `allocation_percentage`, and a format
carries `format_option_id`, `format_kind` and `params`. Age ranges in the planning receipt are AdCP
`include_unknown` ranges (ages 0 to 150), and the planner still asks for a
closed range. The planning decision and receipt list requested channels as AdCP
media channels.

Turns composed before the offer took these names were rebuilt under them
automatically; their text and numbers did not change. Each rebuilt document has
a new `documentId` and `documentDigest`, and the timeline has a later `response`
event for it while the earlier event stays as history. A representation (PDF,
PPTX or HTML) rendered from an earlier document was retired, so its download
link no longer works, and a new one was rendered from the rebuilt document.

In `semantic_document_json`, `commercial.pricing.currency` is nullable only for
an explicit product-free pass without a buyer budget; `totalBudget` is omitted
in that case. `buyer_proposal_json` emits no budget guidance when no total is
available. Its published Proposal shape and field set are unchanged: allocation
`productId` contains the source-qualified `wh:` wholesale product identifier and
`pricingOptionId` contains the corresponding round-trippable `whpo:` wholesale
pricing-option identifier. Buyer integrations must preserve both values exactly
when calling `create_media_buy`.

The composer retrieves eligible passages from each Material's current source
revision. It excludes advertiser-confidential material without an authorised
advertiser scope, and it carries each cited passage's Material ID, revision,
and locator into the semantic document. Prices never come from prose.

Those evidence rules also apply when live narrative generation is unavailable.
An explicit pass remains
product-free and uses its validated seller-authored policy reason instead of
repurposing catalog or Material evidence as the seller's decision basis.
If no eligible Material positioning or proof story remains after relevance,
confidentiality, and required provenance checks, the semantic document records
a bounded warning for each missing class instead
of silently implying that seller proof was considered or available. Excluded
evidence and its contents are never named by that warning.

Deterministic proposal copy is localized from `request.constraints.locale`.
`nl-NL` produces Dutch headings, proposal language metadata, commercial
phrases, pass explanations, and next-step prompts; `en-US` and an omitted
locale produce English. Other valid BCP-47 locales currently fall back to
English, and the semantic document reports `en-US` as the language actually
emitted instead of labelling English copy as the requested language. Currency,
unit prices, allocation percentages, and rendered tables use that emitted
locale. Buyer-facing next-step prose and labels describe the concrete decision
needed; the machine-readable CTA target retains its established v3 operation
reference for agents. A representation uses the immutable semantic document's
language; requesting another supported language is rejected because rendering
does not translate the already-composed response. Append a turn with the new
request locale when a translated response is needed. Previously stored
`story-first-v3` responses remain readable: JSON preserves the exact immutable
document and its original locale, while human artifacts render that recipe's
legacy English copy with truthful `en-US` language metadata.

`request.budget` is an exact currency amount, not an arbitrary decimal. Its
`currency` must match the uppercase ISO 4217 contract published by the
`save_rfp` input schema and be supported by its runtime refinement; `amount`
must remain between the schema's published minimum and maximum. Decimal precision follows that currency's minor unit: for
example USD accepts two decimal places, BHD accepts three, and JPY accepts none.
An amount that cannot be represented in whole minor units is rejected before
the RFP is saved. An empty budget object is accepted as an omitted budget for
legacy clients; a non-empty budget must include both amount and currency. Zero
is accepted so an incomplete brief can be recorded, but
composition returns actionable `needs_clarification`; it never consumes worker
retries or emits zero-value allocation lines.

`request.flight` is AdCP's `DateRange`: `{ "start": "2026-09-01", "end":
"2026-09-30" }`, both inclusive `YYYY-MM-DD` calendar dates, and no other keys.
`get` returns a turn's flight in the same form. For a flight an older call
saved as `startDate` and `endDate` (or `start_date` and `end_date`), `get`
returns that pair as `start` and `end` and leaves everything else as it was
stored, including the date text and any other flight facts. Composition asks for any flight fact the
request explicitly marks as required instead of rejecting the turn at save
time.

Until the next ChatGPT re-approval the server still accepts the older open
flight (`startDate`/`endDate`, `start_date`/`end_date`, a partial range, legacy
ISO datetimes) and stores it as sent, but the published schema no longer lists
it, and it is deprecated. Send `start` and `end`.

`request.dimensions`, `request.constraints` and `strategy` publish only their
declared keys, and the schema is closed. A request stored with other keys, and
an older call that sends them, is still saved; send declared keys only.

## Send facts as entries

`origin.details`, `feedback` and `outcome.details` carry facts you choose the
names of. Each is a list of `{ "key", "value" }` entries, and `get` returns the
same entries, so you can read an RFP, change one entry and save it without
losing the rest:

```json theme={null}
{
  "clientRequestId": "turn-outcome-1",
  "rfpId": "rfp_123",
  "turnId": "turn_456",
  "outcome": {
    "result": "won",
    "finality": "final",
    "details": [
      { "key": "bookedBudget", "value": 12000 },
      { "key": "currency", "value": "USD" }
    ]
  }
}
```

* `key` is a name of 1 to 200 characters. Padding is trimmed, and a name may
  not repeat once it is trimmed.
* `value` is text, a number, or `true`/`false`. There is no nested value: send
  one entry per leaf with a dotted name such as `dimensionScores.clarity`. A
  fact an older call stored as a list, an object or null reads back unchanged
  as that entry's value; to change it, send text, a number or `true`/`false`.
* A list holds at most 200 entries. `feedback` needs at least one entry, or a
  typed `grade`, `ledBy` or `commentary`.

Until the next ChatGPT re-approval the server also accepts the older open
object (`"feedback": { "note": "..." }`) and runs it the same way. It is
deprecated and no longer in the published schema.

The legacy `request.constraints.mustInclude` list remains supported for
compatibility. It accepts at most 16 non-empty, control-safe planning-text
items, each up to 160 Unicode code points after trimming.

Structural identifiers and field names use the same trimming rule: leading and
trailing Unicode whitespace (including TAB/LF/CR) is trimmed, then the value
must contain a visible character and no C0/C1 controls, bidi controls, or
line/paragraph separators. Idempotency uses the trimmed identifier, so padded
and unpadded forms identify the same save request.

## Use a Quick RFP preset

Quick identifies the RFP origin; it does not change the request purpose. Its
production cache is used only when `origin.kind: "quick"`, `purpose: "live"`, and a non-empty typed
`origin.preset` are all present. Supported cache dimensions are buyer,
advertiser, category, location, market, channels, objective, advertiser class,
and budget band. Strings and channel collections are bounded by the published
`save_rfp` schema, which takes the preset as `{ "kind": "typed", "value": { ... } }`.
Omitted presets remain accepted; they compose through the established lifecycle
without populating or reading the production cache. The bounded legacy preset
record (`{ "kind": "legacy", ... }`, including `preset.id`) is deprecated and no
longer in the published schema; the server still accepts it until the next
ChatGPT re-approval, and it never uses the cache. Quick draft and evaluation
requests are likewise accepted and bypass caching.

```json theme={null}
{
  "clientRequestId": "quick:retail-us-video:v1",
  "origin": {
    "kind": "quick",
    "presetId": "curated-retail-us-video",
    "preset": {
      "kind": "typed",
      "value": {
        "category": "retail",
        "location": "US",
        "channels": ["video"],
        "objective": "launch",
        "advertiserClass": "brand",
        "budgetBand": "50k_250k"
      }
    }
  },
  "purpose": "live",
  "request": {
    "brief": "Launch a retail video package.",
    "budget": { "kind": "two_decimal", "amount": 125000, "currency": "USD" },
    "flight": { "start": "2026-09-01", "end": "2026-09-30" },
    "dimensions": { "audience": "retail decision makers" },
    "constraints": { "locale": "en-US" }
  },
  "strategy": { "posture": "hold_value" }
}
```

The cache stores a validated reusable selection/story skeleton and the
truth-gated seller narrative produced by the first viable live composition. A
cache hit skips both the full skeleton build and the narrative model call; it
never stores buyer-authored brief prose for reuse.
Every response still rescans and reloads current products, price options,
product eligibility, and availability, then applies exact budget and currency
facts. Audience, flight, constraints, and overrides remain recorded request
context; the current planner checks required-input presence but does not claim
that those values filtered inventory or overlaid catalog facts. A
dependency digest binds the referenced Material revision, the complete set of
current accepted Material positioning and case-study candidates, Playbook and
acceptance-policy content, catalog and pricing versions
and content, response recipe, model inputs, response-validation contract, and
renderer contract. A changed dependency replaces the entry for that preset
rather than serving stale facts.

The terminal publication transaction takes a Seller Account customer-scoped
dependency fence, re-reads the authoritative catalog, policy, Playbook,
Product Marketing, and Material snapshot, and publishes the semantic document,
receipts, and any cache update atomically. Dependency writers take the
exclusive side of the same customer fence; unrelated Seller Accounts do not
share a platform-wide lock. If the snapshot changed during composition, the
attempt publishes neither a ready response nor a cache entry and retries from
current facts.

Cache hits do not change buyer-facing response shape, representation, or
provenance. Certified plan intent is pre-release: its decision and role fields
are not yet available to Seller Accounts. The `seller-rfp-plan-intent` flag
remains disabled until the follow-up trigger-enforcement migration ships, so
new turns retain the legacy response contract. The pre-release capability adds
no entitlement, package, or billing meter.

Read `receipt.cacheMode` on `get({"kind":"rfp_turn"})`:

* `miss_full_compose` created or replaced the skeleton;
* `hit_hydrated` reused a truth-gated narrative for the same request and
  deterministic decision basis;
* `hit_customized` reused only source-authenticated catalog or Material claims
  whose composite references and decision basis still match; and
* `bypassed` composed normally and names the reason, such as a non-Quick origin,
  any non-live purpose, a legacy or omitted preset, the 500-key Seller Account
  cache limit, or another request currently populating that Seller Account's
  cache.

For cache hits, `cachedSkeletonDigest` identifies the loaded shared skeleton
and `currentSkeletonDigest` identifies the request-specific overlay. The
buyer's requested product count is `null` when no cardinality was authored;
seller-selected plan size remains separate.

Decision claims carry evidence for the source that actually established each
claim. A seller-authored pass reason cites its `strategy.passReason` request
locator. Missing-input limitations cite the exact request path. Catalog,
format, role, and measurement limitations cite the current catalog revision;
the renderer never presents a generic policy or catalog citation for a reason
that source did not produce.

An explicit seller `pass` does not require a viable product, currency, or
`strategy.passReason`. Every explicit pass records
`explicit_strategy_posture` as immutable provenance. For an enrolled Seller
Account, a supplied reason produces the v2 pass document and is recorded as its
seller-authored policy basis; an explicit pass without a reason—or any explicit
pass composed while the exposure flag is off or unavailable—retains the
deployed v1 compatibility document. A planner-driven catalog-gap pass is a v2
decision without seller-posture provenance. Catalog or request gaps remain
separate rendered limitations.

`presetId` labels a preset as curated; normalized dimensions and the resolved
response locale determine its cache key, so cached English narrative can never
be selected for a Dutch response. Dutch platform narrative is deterministic
and does not populate `cachedNarrative`. Unnamed combinations populate lazily from real demand. Apostra
retains at most 500 normalized preset keys per Seller Account and does not
prebuild their Cartesian product.

The same turn receipt includes bounded composition evidence at
`receipt.composer`:

* `schemaVersion` is `rfp-composer-execution-v3`;
* `mode` is `model`, `cache`, or `fallback`;
* `outcome` is `composed` for a live model result, `cache_hit` for reuse, or a
  bounded fallback category. Dutch responses use `localized_deterministic` and
  do not invoke or reuse a narrative model;
* `provider` and `model` identify the live composer only when `mode` is
  `model`; both are `null` for cache and fallback.
* `attempted` says whether a model invocation was attempted for this turn;
  `attemptProvider` and `attemptModel` identify that invocation when the
  provider reported a bounded identity. A rejected or ungrounded paid result
  therefore remains `mode: "fallback"` without being mislabeled as a no-call
  fallback.
* `deadlineMs` is the model budget granted to this turn: up to 90 seconds, always
  bounded by the remaining 120-second composition attempt. A `deadline`
  outcome means the model did not answer inside that budget and the turn fell
  back to the deterministic response.
* `groundingDetail`, when present for an `ungrounded` fallback, is a bounded,
  counts-only diagnosis of the model claims, citation-grounding and entailment
  drops, and their closed reason histogram. It makes a rejected pitch
  diagnosable from the turn receipt without exposing model prose or buyer data.
* `entailmentFailure`, when present, records the bounded verifier failure kind
  and whether a required endorsed response received the one permitted retry
  after a transient `model_error`.
  A recovered proposal retains this receipt evidence; if that retry also
  failed, `retryKind` records its bounded failure kind. `retrySkipped:
  "no_time"` records the distinct case where a retryable fault had no compose
  time left for another verifier call. It never includes model prose or buyer
  data.

`receipt.modelVersion` continues to identify the content's model lineage. On a
cache hit it can name the model that produced the cached narrative without
claiming that a model ran for the current turn; use `receipt.composer.mode` to
distinguish those cases.

## Create and poll a turn

Call `save_rfp` with no `rfpId`: a call without one creates an RFP.
`clientRequestId` is the idempotency key: retrying the exact request returns the
same RFP and turn, while reusing the key with a changed payload returns an
idempotency conflict. A save that returns `SERVICE_UNAVAILABLE` saved nothing:
send the exact request again with the same `clientRequestId`.

```json theme={null}
{
  "clientRequestId": "rfp:autumn-video:v1",
  "origin": {
    "kind": "manual",
    "buyer": "Northwind Media",
    "advertiser": "Contoso",
    "channels": ["video"]
  },
  "purpose": "draft",
  "request": {
    "brief": "Reach high-intent retail audiences with premium video.",
    "budget": { "amount": 125000, "currency": "USD" },
    "constraints": { "mustInclude": ["brand_safe"] }
  },
  "strategy": { "posture": "hold_value" }
}
```

The save returns immediately with `rfpId`, `turnId`, `responseState`, and a
safe `get` call. Poll the exact turn:

```json theme={null}
{ "kind": "rfp_turn", "id": "TURN_ID" }
```

The observable lifecycle is:

`queued → processing → ready | passed | needs_clarification | failed`

* `ready` contains an immutable `proposal-semantic-document-v1` response with
  products, prices, budget allocations, canonical formats, seller claims and
  their source citations, visual reuse decisions, and composition receipts.
* `passed` is a deliberate, evaluated decision not to propose, not an absent
  response. For an enrolled Seller Account, a pass with `strategy.passReason`
  or a planner-driven catalog-gap pass contains an immutable
  `seller-rfp-pass-v2` response. An explicit reasonless pass, or any
  unenrolled explicit pass even when it has a reason, can contain
  `seller-rfp-pass-v1`. Both remain readable. The response includes
  a product-free semantic document with what the seller heard, the grounded
  reason or posture-only compatibility basis for passing, and the condition for
  a useful new turn. Catalog and request gaps appear as separate, rendered
  decision limitations. An explicit
  `strategy.posture: "pass"` records `explicit_strategy_posture` as immutable
  decision provenance on both the response and turn; it never invents a
  catalog incompatibility or emits offer lines and terms disguised as a pass.
* `needs_clarification` also contains an immutable semantic document. It
  contains no proposed products or budget allocations and lists the questions
  and catalog facts that must be resolved. Correct the product catalog or
  request, then append a new turn.
* `failed` contains a stable reason and safe retry guidance. Do not treat it as
  a successful response or keep polling it as though it were processing.

Each composition attempt is lease- and generation-fenced. A reclaimed or late
worker cannot overwrite the artifact committed by the current attempt.

## Read why a recorded response could not answer the brief

Proposal Pass shows a **Why this response** section when the immutable turn
retains an explanation. It describes the recorded decision, rather than making
a new claim about the seller or the current catalogue.

The explanation can say that the request needed more detail or approval, that
the seller declined under a recorded policy, that the recorded selection found
no available fit, or that a run or source failed. It can also say that a
complete recorded catalogue did not declare the requested channel or format.
That last result is limited to the recorded catalogue and request. It does not
prove that the seller has no broader capability. A request can also be outside
the seller's recorded offering, which records the decision for this turn rather
than a general market claim.

Some turns cannot support a stronger answer. Historical, unknown, truncated,
or malformed receipts, and incomplete catalogue evidence, are labelled
incomplete. Proposal Pass does not turn those records into an absence claim or
an offer of a substitute. A partial explanation may still show a confirmed
request limitation beside an incomplete catalogue limitation.

When a complete, authoritative receipt identifies one exact product with only
a price configuration gap, Proposal Pass can show **Open source diagnostics**.
This action is available only to the authenticated seller for that exact turn
and recorded source. It opens the existing source diagnostics Page for that
source; it does not open another source, grant broader account access, or retry
the response. The Page checks the seller, turn, and source again before it
opens. If the host cannot open it, Proposal Pass keeps the recorded explanation
visible and lets the seller retry the same action.

## Continue the lifecycle

Two tools change an RFP. `save_rfp` keeps what belongs to the RFP itself, and
`save_rfp_turn` changes one existing turn. Neither takes an `action` field: the
fields you send say what the call does, and a field that belongs to another kind
of call is rejected rather than ignored.

`save_rfp` does one of these, chosen by its fields:

| To | Send | Effect |
| - | - | - |
| Create an RFP | no `rfpId`; `clientRequestId`, `origin`, `purpose`, `request`; optional `strategy`, `requiredEndorsedPairId`, `requiredLibraryUnitIds` | Creates the RFP and first turn, then queues composition |
| Revise an RFP | `rfpId`, `parentTurnId`, `clientRequestId`, `request`; optional `strategy`, `requiredEndorsedPairId`, `requiredLibraryUnitIds` | Adds an immutable revision turn and queues composition |
| Endorse the response | `rfpId`, `clientRequestId`, `endorsed: true`; optional `endorsementCommentary` | Endorses the paired response and stores its non-text response shape |
| Remove the endorsement | `rfpId`, `clientRequestId`, `endorsed: false` | Removes the endorsement and stored response shape |
| Attach a response | `rfpId`, `responseMaterialId`, `clientRequestId` | Attaches an uploaded or historical-proposal Material response when no composed response is paired |

`save_rfp_turn` takes `rfpId`, `turnId` and `clientRequestId`, the identifiers
a `get` of the turn returns, and exactly one of these. A call that sends two,
or none, is rejected:

| To | Send | Effect |
| - | - | - |
| Release the turn | `released: true` | Marks an eligible live response for delivery |
| Request a proposal file | `representation` | Requests an idempotent representation of the immutable response |
| Cancel a proposal file | `cancelRepresentationId` | Cancels a queued or processing render without changing the source document |
| Add feedback | `feedback` and/or typed `grade`, `ledBy`, `commentary` | Appends bounded feedback without rewriting the response |
| Record the outcome | non-empty `outcome` | Appends the observed commercial result and finality |

Feedback and outcome are append-only events, and a representation starts
rendering work. They record or start something; they do not declare a state to
converge to. Each is idempotent by `clientRequestId`.

`requiredLibraryUnitIds` may be sent when you create or revise an RFP: one to
eight exact `{ materialId, unitId, renditionRevision }` identities from
reusable, price-free Library units currently offered to the authenticated
seller. This is a seller requirement, not a strategy hint or a citation: every
listed unit is placed verbatim in the response, including when deterministic
composition is used. A unit that is not currently eligible is rejected before
the turn is queued. The receipt records each selected Library unit and whether
it was `seller_required` or `model_selected`.

For an evaluation turn, a revision also snapshots the most recent saved
`feedback.note` from its exact parent. The child uses that note only as bounded
writing guidance: it may change wording, emphasis, or the order of supported
products, but it cannot add or change products, prices, sources, or claims.
The buyer-authored `request` remains unchanged, the note is never a citable
fact, and feedback saved after the revision cannot change the child. Live RFP
turns do not inherit feedback this way.

`outcome.result` remains a nonempty free-form string so existing
integrations can preserve their source vocabulary. Aggregate reporting uses the
documented closed taxonomy in [RFP performance](https://docs.apostra.com/v3/rfp-performance.md);
an unknown recorded value is retained but makes classified commercial metrics
unavailable with `unknown_outcome`.

The certified `seller_proposal_v1` profile supports
`seller_response_json`, `buyer_proposal_json`, `semantic_document_json`,
`html`, `pdf`, and `pptx`. Each file is generated from the turn's immutable
document and preserves the same products, prices, budget allocations, seller
claims, and source citations. Layout differs by format. HTML declares its
language, title, heading order, table headers, image alternative text, and
tested color contrast. PDF is paginated and embeds a deterministic subset of
the certified Noto Sans font for its supported Latin, Greek, and Cyrillic
glyphs. A PDF request containing a glyph outside that font, including CJK,
right-to-left scripts, or emoji, fails explicitly instead of replacing the
character. PPTX text remains editable; long text is continued across slides
according to the fixed text-box height. Unsupported profiles, formats, glyphs,
or layout sizes fail explicitly; they are never substituted or truncated.

### Inbound AdCP proposals

When a buyer calls AdCP 3.2 `request_proposals` against a seller, Apostra
records the request as one turn on one inbound seller RFP, and the proposals it
returned are that turn's answer.

* **One RFP per buyer opportunity.** The RFP is the buyer's AdCP
  `opportunity.opportunity_id` at your storefront: one planning cycle for one
  buyer account (the advertiser the buyer's credential is bound to, or the
  buyer when it is bound to none), with sandbox and live requests kept apart.
  Each
  `request_proposals` call in that opportunity adds a turn to the same RFP. A
  new turn doesn't change the RFP's state; [the buyer's opportunity
  decides it](https://docs.apostra.com/v3/rfp-lifecycle.md#inbound-rfp-state). A request that names no opportunity is
  its own RFP with one turn. Sending a recorded request again (the same
  `idempotency_key`) adds nothing.
* **One document per turn.** The turn's semantic document holds every proposal
  of the round: one table of every product, price and allocation, then each
  proposal with its products. It is bound to the exact canonical products,
  prices, pricing options, currencies, and allocations the proposals returned.
* **Size.** A document holds up to 128 products. Proposals are added in the
  order the buyer received them; from the first one that would not fit, the
  rest are left out, and so is any proposal in a different currency from the
  first. The document says how many were left out. The buyer still receives
  every proposal.
* **Proposals Apostra cannot document.** A proposal is left out of the
  document and counted with the ones left out, and your RFP still lists it,
  when any of these is true:

  * its products lack what a document needs (channels, an executable format,
    one positive price);
  * its explicit allocations are invalid or add up to more than 100%;
  * it is larger than one RFP turn or one document holds.

  A request none of whose proposals can be documented is not recorded. The
  AdCP answer is unchanged.

An omitted allocation remains omitted and renders as “Not specified”; Apostra
does not calculate a split. The renderer reads saved bindings; it does not
re-query the catalogue or regenerate commercial values. The seller Session
therefore shows the same immutable document whose default buyer-delivery HTML
representation is queued, with one request and one answer for each buyer
request. The RFP read lists the proposals recorded on its turns in
`links.buyerProposalIds`, including those left out of a document. A proposal
Apostra did not record, as described above, is not listed, although the buyer
received it. A media buy the buyer makes from a listed proposal joins the
RFP's Session, with one exception. The buy does not say which answer it came
from, so it joins no Session when the same proposal id was also answered to
another of the buyer's accounts, in sandbox as well as live, or on another RFP
when either is for a named opportunity. The delivery link is part of the same record; it does not
create a second proposal record.

When the buyer sent the round from a sandbox advertiser, Apostra marks the RFP
as sandbox. The mark is read-only and recorded once, when the RFP is created.
The RFP's `purpose` stays `live`, so you can still release a turn and answer the
buyer. RFPs created before the mark was recorded are not marked.

#### Inbound RFP state

The buyer owns the opportunity, so you can't close it. An inbound RFP's `state`
is the buyer's opportunity status: `open` until the buyer ends it, then
`closed`. It is never `released`. Quick, uploaded, imported and manual RFPs have
no buyer opportunity, and you still set their state yourself.

The buyer closes the RFP when:

* it makes a media buy from one of the RFP's proposals, or a `create_media_buy`
  call sends `opportunity.status: closed`; the opportunity closes as
  `accepted_with_seller`, the only closure AdCP allows on that call. A buy
  still waiting for your approval does not close it. The RFP closes once you
  approve the buy and it is forwarded, and a buy you decline never closes it.
  The buyer's own `opportunity.status: closed` on the call closes it either way.
  Apostra does not serve
  `accept_proposal` yet, and a `request_proposals` proposal is a draft, so a
  buyer finalizes it with a `get_products` refine and then buys it with
  `create_media_buy` and its `proposal_id`; a buy made that way closes the RFP.
  Otherwise the buyer closes it by its planning horizon or an explicit status;
* the last day of its `opportunity.planning_horizon` passes. The read treats the
  RFP as closed from then on, with no delay for a job to run. With no planning
  horizon, the RFP stays open until the buyer closes it.

The RFP reads closed from the media buy itself, so a buy that was forwarded
always shows it closed, however the rest of the call went. A buy the
source rejected, one that never reached the source, and one Apostra ended after a
fault (a task the source never answered, a create that timed out) close
nothing. A cancel the source made itself still counts.

A `request_proposals` call that sends `opportunity.status: open` reopens it,
whatever its answer was (`rejected` included). No other call reopens it: a
`create_media_buy` that sends `open` does nothing. A request without `status`
adds its turn and leaves the state as it is, as AdCP requires, with one
exception that follows from the planning horizon: a horizon it names replaces
the old one, so a new horizon in the future lifts a closure the old horizon
caused, and the RFP reads open again. A closure from a buyer signal, a media
buy or an explicit `closed`, is left as it is, and a media buy made before the
buyer reopened the RFP no longer closes it. A reopening that names no new
planning horizon is no longer closed by the old one.

Your marks are notes on the RFP, not a state change. Releasing a turn still
records it as sent (`releasedTurn`), and an outcome is still recorded
(`outcomeSummary`), but neither moves `state`. You can still record won or lost,
preliminary or final: that is your account of the deal, not the buyer's
planning cycle. For RFP performance, every inbound turn counts as delivered when
Apostra records it, because the buyer has already received its proposals.

`search` filters by `state` as before. On an inbound RFP, `open` and `closed`
mean the buyer's status, and `released` never matches one. The RFP's Session is
active until the buyer ends the opportunity, and the Sessions list labels the
RFP "sent" once you release a turn.

`get({"kind":"rfp","id":"RFP_ID"})` of an inbound RFP that named an opportunity
also returns `opportunity`, the buyer's AdCP opportunity as it last arrived:

| Field | Meaning |
| - | - |
| `opportunity_id` | The buyer's id for the planning cycle |
| `status` | `open` or `closed`, as the buyer last stated it or as a media buy closed it; absent until the buyer has stated one |
| `close_reason` | AdCP's reason, present when `status` is `closed` |
| `planning_horizon` | The buyer's `start` and `end` dates, inclusive |
| `response_deadline` | When the buyer needs a response |
| `closed_at` | When the buyer closed it, or when the planning horizon ended. Absent while the RFP is open |

`opportunity` is read-only and isn't a filter. It is absent on every other RFP,
and on an inbound RFP whose request named no opportunity.

#### Retrieving a buyer proposal document

For every proposal in a recorded buyer-delivery document, the AdCP proposal
response includes it in response-level `ext.apostra.proposal_documents`, keyed
by `proposal_id`. Every proposal of one request links to that request's
document:

```json theme={null}
{
  "ext": {
    "apostra": {
      "proposal_documents": {
        "proposal_123": {
          "fetch_url": "https://seller.example/seller/acme/proposal-documents/proposal_123?turn=turn_0123456789abcdef01234567",
          "format": "html"
        }
      }
    }
  }
}
```

`fetch_url` is a stable authenticated endpoint, not a public download URL. Its
`turn` names the RFP turn whose document it serves, so a link keeps returning
that document even when the same proposal id is later answered to another of
your accounts. Call the URL as given: without its `turn`, it finds no
document. A link issued before links named their turn has none, and still
returns the newest document of the one proposal its RFP holds. A buyer agent
calls it with the same buyer credentials used for
the proposal. It returns the standard API response envelope:

```json theme={null}
{
  "data": {
    "download_url": "https://storage.example/signed-document",
    "expires_at": "2026-10-19T12:05:00.000Z"
  },
  "error": null
}
```

`download_url` is a short-lived, private object-store URL for the immutable
HTML file. Apostra verifies the seller, buyer customer, buyer principal, and
proposal before minting it.
Requests for another buyer's or seller's proposal return `404`. The field is
absent when no document exists. A document may still be rendering when its
field first appears; in that case the authenticated fetch also returns `404`,
and the buyer agent should retry later.

Set `representation.audience` to `seller_preview` only for a preview you
review yourself. Seller previews include the seller-only **Shaped by**
provenance line when the agent followed an endorsed pair. The default,
`buyer_delivery`, is the required audience for any file you send to a buyer
and never includes that provenance. `buyer_proposal_json` is always clamped to
`buyer_delivery`.

Representation states are `queued`, `processing`, `ready`, `failed`, and
`canceled`. Temporary render failures retry automatically. A canceled or
superseded attempt cannot replace a newer file. A `ready` representation
returns its checksum, commercial digest, validation receipt, expiry, and a
short-lived download URL authorized for the current Seller Account. The URL is
limited to the exact stored file version, expires no later than the artifact's
retention expiry, and does not make the file public. An artifact at or past its
retention expiry receives no download URL. Signing also requires more than
three minutes of retention to remain, so private-storage validation cannot
consume the URL's usable lifetime.

### Rendering continues after the request returns

Creating a turn or requesting a representation records durable work before the
API responds. The composition and rendering workers continue that queued work
after the request that started it has completed. Poll the exact turn or
representation for its current state rather than treating a completed request
as a completed file.

This does not make rendering unbounded or irreversible. You can explicitly
cancel a `queued` or `processing` representation, and terminal `failed` or
`canceled` states remain visible for diagnosis. A later worker attempt cannot
replace a newer attempt for the same representation.

Newly rendered files return a `proposal-representation-validation-v2` receipt.
It binds `rfpId`, `turnId`, `representationId`, and the originating
`clientRequestId` alongside the document, commercial, artifact, format, and
render-option digests. Use those correlation fields to match a file to the
exact `save_rfp_turn` call that requested it. Historical
`proposal-representation-validation-v1` receipts remain readable as immutable
legacy evidence, but they do not contain the four request-correlation fields
and must not be treated as a v2 receipt with stripped fields. A
representation request and a feedback call both echo `clientRequestId` in their
fresh and idempotent-replay responses. When an equivalent representation is
reused, the request also returns
`originatingClientRequestId`; it identifies the original request whose
immutable validation receipt is returned, while `clientRequestId` identifies
the current call.

The receipt's existing `options` record includes `audience`. This remains v2:
render options are an extensible record, and a historical receipt without an
audience is interpreted fail-closed as `buyer_delivery`.

A visual is included only when its reuse rights, confidentiality, advertiser
restrictions, expiry, file type, checksum, and allowed `proposal` use all
permit it. The response lists every omitted or unavailable visual and the
fallback used.

Requests that exceed a certified limit fail explicitly; they are never
returned as partial files.

| Limit | Maximum |
| - | -: |
| Semantic document | 512 KB |
| Rendered file | 10 MB |
| Sections | 16 |
| Story blocks | 320 |
| Visual references | 32 |
| One input visual | 5 MB |
| All input visuals | 20 MB |

## Proposal Pass, the portable turn workbench

Proposal Pass is the portable MCP App a seller opens to work one RFP turn —
in Apostra, Claude, ChatGPT, or another conforming MCP Apps host. It is a thin
client of the same `save_rfp`, `save_rfp_turn` and `get` contract documented above: it introduces
no calculation, no hidden lifecycle step, and no capability the API itself
does not already offer.

Open it from a v3 Seller Account with the exact immutable pair returned by
`save_rfp` or `get`:

```json theme={null}
{
  "rfpId": "rfp_01...",
  "turnId": "turn_01..."
}
```

Call `open_proposal_pass` with that object. The launch result contains only
those ids; after the fixed Proposal Pass resource opens, its app-only tools
load the private turn. A missing turn, a turn belonging to another RFP or
Seller Account, or an unauthorized account returns `NOT_FOUND` or
`WRONG_ACCOUNT` without opening the Page. The legacy v2 Storefront form,
`open_proposal_pass({"runId": ...})`, is unchanged and is not the v3 contract.

Draft and evaluation turns can be opened deliberately by exact id for review.
That does not promote them into the live Demand Inbox or include them in live
RFP performance metrics; those populations remain live-only.

From an open turn, Proposal Pass can:

* add feedback to the turn;
* revise it with an evaluation rerun that snapshots the latest saved note as
  non-citable writing guidance, opening a new immutable turn without changing
  the buyer brief — the parent turn is never edited in place;
* request a proposal file for `seller_response_json`, `html`, `pdf`, or
  `pptx` as either a seller preview or buyer delivery, and watch it move
  through `queued → processing → ready | failed`; and
* cancel a proposal file while it is still `queued`.

For an evaluation, **Save coaching and run test again** performs the first two
actions in sequence, opens the child turn, and hydrates its exact parent for the
before-and-after comparison. If feedback saves but the rerun cannot start, the
page keeps the correction and offers a safe retry with the same idempotency
keys, including after the widget reloads, so it does not create duplicate
feedback or child turns.

Releasing a turn and recording its outcome are deliberately not available from
Proposal Pass. Both are consequential, human-facing commitments the widget
does not yet have a reviewed confirmation flow for; use `save_rfp_turn`
directly for those two.

Feedback and representations render in the same bounded pages the exact-turn
read returns (see [Search and audit](https://docs.apostra.com/v3/rfp-lifecycle.md#search-and-audit) below): the widget
shows the default page and a "Show more" control follows `feedback.next`/
`representations.next` for the rest, so a turn with more than one page of
either never hides feedback or representations past the default page.

Preview and buyer-delivery download read the representation's short-lived signed URL fresh
at the moment of the request, hand it directly to the host's own
link-opening capability to open in a new browser tab, and hold it nowhere
else: the URL is never written into the widget's saved state, never
rendered, never logged, and never visible to the model driving the
conversation the seller is in. Every other format downloads the same way.
An expired or not-yet-ready representation offers no open action. Because
a proposal-file request is idempotent per format-and-audience tuple for a
given turn, a representation that has already been requested cannot be re-requested to force a
fresh attempt — a failed, canceled, or expired representation stays in
that terminal state.

## Search and audit

Use `search({"kind":"rfp"})` for opportunities and
`search({"kind":"rfp_turn"})` for immutable turns. RFP filters include state,
origin, purpose, buyer, advertiser, category, market, channel, posture,
Playbook version, cache mode, and outcome. Turn filters add RFP ID, response and
evaluation state, recipe/model/judge version, and feedback status.

A sandbox RFP and its turns carry `sandbox: true` on `search` and `get`. The
field is absent on any other RFP, never `false`. It is not an input or a filter
on these reads, so every list keeps showing sandbox RFPs, labelled. The
RFP's Session in the Sessions page carries the same `sandbox: true`, and
Proposal Pass shows a **Sandbox** label on a sandbox turn. To leave
them out of aggregate figures, see [RFP performance](https://docs.apostra.com/v3/rfp-performance.md#sandbox-rfps).

### Find past RFPs by brief

> [!NOTE]
>
> Searching RFPs by brief text and the `outcome` projection are in beta for
> Seller Accounts on the beta profile. For a Seller Account outside the beta, a
> `search({"kind":"rfp"})` call that sends `query` or `include: ["outcome"]`
> is refused with `FEATURE_NOT_ENABLED`. A plain RFP search without them works
> as before for every seller.

Send `query` with `kind: "rfp"` to find past RFPs whose brief matches some
text, for example the brief of a new request:

```json theme={null}
{
  "kind": "rfp",
  "query": "sports video or ctv",
  "include": ["outcome"]
}
```

* **What it matches.** The brief of each RFP's latest turn. Matching is
  full-text, word by word, with no stemming and no synonyms. By default every
  word must appear. Write `or` between words to match any of them, put a phrase
  in double quotes to match it exactly, and put `-` before a word to leave out
  briefs that contain it. The query can be up to 512 characters.
* **Order.** The best match comes first, using the same full-text ranking as
  Library evidence matches. RFPs that rank equally are newest first. Without
  `query`, results stay newest first, as before.
* **Filters and paging.** Every RFP filter above still applies. `total` counts
  the RFPs that match both the query and the filters. Pass `nextCursor` back
  with the same `query` to get the next page; a cursor from another query, or
  from a search without one, is refused. Every page matches and ranks each RFP
  by its brief as of the first page, so a turn added while you page does not
  move an RFP between pages or add it to a later one. Search again without a
  cursor to see the newest briefs.

Add `include: ["outcome"]` to put each RFP's response and result on its row,
as `outcome`. It holds exactly these four fields:

| Field | Meaning |
| - | - |
| `responseState` | The latest turn's response state, such as `ready`, `passed`, or `failed`; `null` when the RFP has no turn |
| `selectedPosture` | The response posture the latest turn chose; `null` when none was recorded |
| `result` | The same value as `commercial.outcomeResult` on `get`: `won`, `lost`, `accepted`, or `pending`, or `null` when no recognized outcome is counted |
| `finality` | The same value as `commercial.outcomeFinality` on `get`: `preliminary`, `final`, or `mixed`, or `null` when `result` is `null` |

`result` follows the rules for `commercial` below: a draft, an evaluation, or
an imported RFP reports `result: null`, whatever result was recorded.

**Past RFPs read for one buyer.** When your agent answers one buyer's
request, the past RFPs it reads will be limited to RFPs that buyer's
own Apostra account sent. Another buyer's RFP never comes back in any form. An
RFP with no buyer account, such as one you entered by hand, uploaded, or
imported, is never shown to an agent answering a buyer either, because it
cannot be shown to belong to that buyer. Your own searches as the seller are
not limited this way.

### Read one RFP or turn

Use `get({"kind":"rfp","id":"RFP_ID"})` for the opportunity summary,
latest and released turns, bounded turn history, outcome summary, and links.
Use `get({"kind":"rfp_turn","id":"TURN_ID"})` for the exact request,
response, receipts, diagnostics, feedback, outcome, and representation status.

Both reads also return `commercial`, the server's reading of the recorded
outcome, so a client never has to interpret the free-form `outcome` itself:

| Field | Meaning |
| - | - |
| `lifecycle` | `closed_won` or `closed_lost` when a recognized outcome decides the RFP; otherwise `awaiting_advertiser_decision` (response ready), `no_offer_returned` (passed), `response_unavailable` (failed, or the RFP is closed), or `response_not_recorded` (queued, processing, or needs clarification). An inbound RFP reads from its response alone, because the buyer closing their opportunity says nothing about your response |
| `outcomeResult` | `won`, `lost`, `accepted`, or `pending`, using the same taxonomy as [RFP performance](https://docs.apostra.com/v3/rfp-performance.md); `null` when no recognized outcome is counted |
| `outcomeFinality` | `preliminary`, `final`, or `mixed`; `null` when `outcomeResult` is `null` |
| `wonValue` | `{ amount, currency }` from the outcome's `bookedBudget` (or the `bookedBudget` entry in `details`, with its `currency` entry), only when the result is `won` and the outcome recorded both an amount and an ISO 4217 currency; otherwise `null` |

Outcomes count only for live demand that is not imported. A draft, an
evaluation, or an imported RFP reports `outcomeResult: null` and
`wonValue: null`, whatever result was recorded. `accepted` is not a win. On
`get` for an RFP, `commercial` reads its most recent outcome across turns; on
`get` for a turn, it reads that turn's most recent outcome.

Search results are summaries; they do not repeat the complete request or
response. Feedback bodies and representation statuses remain on the authorized
exact-turn read in bounded pages. Follow `feedback.next` and
`representations.next` until they are `null`. Feedback continuations carry
`feedbackOffset`; representation pages carry an opaque `representationCursor`.
Pass the supplied argument back to `get` rather than synthesizing one. The
representation cursor pins a snapshot, so rows appended while paging do not
produce skips or duplicates.


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