Skip to main content
PUT
Record demand-inbox ledger annotations

Authorizations

Authorization
string
header
required

API key or access token

Path Parameters

runId
integer
required

Surrogate id of the chef compose run this ledger row wraps.

Required range: 0 < x <= 9007199254740991
Example:

42

Body

application/json

Records the seller-authored ledger annotations (grade, buyer feedback, led-by attribution) on one demand-inbox row.

grade
enum<string> | null

Seller's letter grade (A–F) for the proposal. Null clears it.

Available options:
A,
B,
C,
D,
F
feedback
string | null

Buyer feedback captured against the proposal. Null clears it.

Maximum string length: 2000
ledBy
enum<string>

Who led the response: the agent, or a human who took it over. Omit to leave the run's current attribution.

Available options:
agent,
human

Response

Record demand-inbox ledger annotations

id
string
required
brief
string | null
required

The brief text the agent answered (label for the row).

buyer
string | null
required

Legacy ambiguous buyer label retained for compatibility. New readers must use commercialIdentity instead.

commercialIdentity
object
required

Advertiser = BrandRef × Operator (AI-5080), projected from the persisted brief request first and the compose-run identity snapshot only as a historical fallback. CRM evidence and seller-native mappings are deliberately not joined into this identity.

responseKind
enum<string>
required

What the persisted seller response actually proves: 'proposal' requires a non-empty proposal_id; products without that evidence are a product_offer, never a Proposal.

Available options:
product_offer,
proposal,
no_offer,
unavailable
commercialLifecycle
enum<string>
required

The most specific commercial lifecycle supported by the persisted response and attributed outcome. This supplements result so an undecided exchange is never presented as an ambiguous Pending state.

Available options:
closed_won,
closed_lost,
awaiting_advertiser_decision,
awaiting_seller_approval,
forwarding_failed,
no_offer_returned,
response_not_recorded,
response_unavailable
budgetRange
object | null
required

The buyer's stated budget range, exactly as sent in the brief's filters.budget_range and captured in the brief artifact. Null when the buyer did not state one.

receivedAt
string
required
respondedAt
string | null
required

When the agent answered. Null while the brief is unanswered.

responseTimeMs
number | null
required

Persisted compose duration in milliseconds. Null when duration was not recorded; never derived as zero from equal timestamps.

Required range: x >= 0
ledBy
enum<string> | null
required
Available options:
agent,
human
feedback
string | null
required
result
enum<string>
required

Commercial result derived from this run’s own attributed outcome: closed_won (booked/delivered), closed_lost (rejected), else pending. A booking attributed to a later refine pass is not rolled up here (see the win-rate scope note).

Available options:
closed_won,
closed_lost,
pending
grade
enum<string> | null
required
Available options:
A,
B,
C,
D,
F
wonValue
object | null
required

Money attributed to this run's won outcome: delivered spend when reporting exists, else the booked media-buy budget. Null unless the outcome persisted both an amount and its currency.

provenance
string | null
required

How this brief reached the ledger: 'live' = an AdCP get_products call from a buyer agent, 'uploaded' = a seller-uploaded RFP/brief confirmed in chat (AI-4728). Reflects this run's own intake origin (AI-5025), falling back to the linked brief artifact's source column only for historical runs recorded before that origin was captured. Null when neither is available (e.g. a practice pitch or a historical pre-capture run). Uploaded briefs never masquerade as live buyer demand.

briefArtifactId
string | null
required

Canonical brief artifact id (AI-4693) for the build-3 drill-in. Null = artifact unavailable (historical pre-capture run).

proposalArtifactId
string | null
required

Historical storage-table name for the latest canonical seller-response artifact. Its presence does not prove a Proposal; responseKind is authoritative and 'proposal' requires proposal_id evidence.

artifactAvailable
boolean
required

False when the brief artifact was not captured; readers must say "artifact unavailable" rather than reconstruct it.