GET /api/v1/buyer/context
Prepare evidence and next actions for an MCP media buyer
Read-only, tenant-scoped guidance for briefing, creative direction, campaign review and launch assistance. References existing canonical tools and the existing human approval flow; performs no provider calls or commercial actions.
Authenticated and advertiser scoped. Cross-tenant resource access returns 404. Product/channel entitlements also apply.
Request
HTTP
GET /api/v1/buyer/contextUse the configured API origin. Private requests require a verified Bearer credential; an agent mutation can additionally require exact approval headers. Authentication guide →
| Parameter | Location | Required | Description |
|---|---|---|---|
workflow | query | Yes | |
campaignId | query | Conditional / optional | |
planId | query | Conditional / optional | |
personaId | query | Conditional / optional | |
creativeId | query | Conditional / optional |
Parameter schemas
JSON Schema
[
{
"name": "workflow",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"brief_to_plan",
"creative_direction",
"campaign_review",
"launch_assistance"
]
},
"style": "form",
"explode": true
},
{
"name": "campaignId",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"style": "form",
"explode": true
},
{
"name": "planId",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"style": "form",
"explode": true
},
{
"name": "personaId",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"style": "form",
"explode": true
},
{
"name": "creativeId",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"style": "form",
"explode": true
}
]Responses
Reference schemas resolve through the downloadable OpenAPI components. The specification marks unmodeled success payloads; an unrestricted payload is not a promise that arbitrary fields exist.
400Invalid request or unsupported fields
Response contract
{
"description": "Invalid request or unsupported fields",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}401Missing or invalid authentication
Response contract
{
"description": "Missing or invalid authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}403Permission or product scope refused
Response contract
{
"description": "Permission or product scope refused",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}404Route or tenant-scoped resource not found
Response contract
{
"description": "Route or tenant-scoped resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}409State, revision, approval, funding or idempotency conflict
Response contract
{
"description": "State, revision, approval, funding or idempotency conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}422Supplier configuration, capability or upstream refusal
Response contract
{
"description": "Supplier configuration, capability or upstream refusal",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}429Rate limit reached; wait before retrying
Response contract
{
"description": "Rate limit reached; wait before retrying",
"headers": {
"x-ratelimit-limit": {
"description": "Maximum requests permitted in the current rate-limit window.",
"schema": {
"type": "integer"
}
},
"x-ratelimit-remaining": {
"description": "Requests remaining in the current window.",
"schema": {
"type": "integer"
}
},
"x-ratelimit-reset": {
"description": "Seconds until the current rate-limit window resets.",
"schema": {
"type": "integer"
}
},
"retry-after": {
"description": "Minimum seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}500Internal error; inspect state before retrying a mutation
Response contract
{
"description": "Internal error; inspect state before retrying a mutation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}503Dependency or authentication verifier unavailable
Response contract
{
"description": "Dependency or authentication verifier unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}2XXSuccessful response.
Response contract
{
"description": "Successful response.",
"headers": {
"x-ratelimit-limit": {
"description": "Maximum requests permitted in the current rate-limit window.",
"schema": {
"type": "integer"
}
},
"x-ratelimit-remaining": {
"description": "Requests remaining in the current window.",
"schema": {
"type": "integer"
}
},
"x-ratelimit-reset": {
"description": "Seconds until the current rate-limit window resets.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"buyerContext": {
"type": "object",
"properties": {
"workflow": {
"type": "string",
"enum": [
"brief_to_plan",
"creative_direction",
"campaign_review",
"launch_assistance"
]
},
"selected": {
"type": "object",
"properties": {
"campaign": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"planId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"name": {
"type": "string"
},
"status": {
"type": "string"
},
"startDate": {
"type": "string"
},
"endDate": {
"type": "string"
},
"lines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"lineItemId": {
"type": "string"
},
"channel": {
"type": "string",
"enum": [
"ctv",
"audio",
"tv",
"cinema",
"dooh",
"search",
"social"
]
},
"adapterKey": {
"type": "string"
},
"status": {
"type": "string"
},
"executionMode": {
"type": "string"
},
"budget": {
"type": "object",
"properties": {
"amountMinor": {
"type": "integer"
},
"currency": {
"type": "string",
"enum": [
"GBP",
"USD",
"EUR"
]
}
},
"required": [
"amountMinor",
"currency"
],
"additionalProperties": true
}
},
"required": [
"id",
"lineItemId",
"channel",
"adapterKey",
"status",
"executionMode",
"budget"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"planId",
"name",
"status",
"startDate",
"endDate",
"lines"
],
"additionalProperties": false
},
"plan": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"personaId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 128
},
{
"type": "null"
}
]
},
"status": {
"type": "string"
},
"staleReason": {
"type": [
"string",
"null"
]
},
"planKind": {
"type": "string"
},
"executionMode": {
"type": "string"
},
"budget": {
"type": "object",
"properties": {
"amountMinor": {
"type": "integer"
},
"currency": {
"type": "string",
"enum": [
"GBP",
"USD",
"EUR"
]
}
},
"required": [
"amountMinor",
"currency"
],
"additionalProperties": true
},
"goal": {
"type": "string"
},
"startDate": {
"type": "string"
},
"endDate": {
"type": "string"
},
"channels": {
"type": "array",
"items": {
"type": "string",
"enum": [
"ctv",
"audio",
"tv",
"cinema",
"dooh",
"search",
"social"
]
}
},
"lines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"channel": {
"type": "string",
"enum": [
"ctv",
"audio",
"tv",
"cinema",
"dooh",
"search",
"social"
]
},
"adapterKey": {
"type": "string"
},
"budget": {
"type": "object",
"properties": {
"amountMinor": {
"type": "integer"
},
"currency": {
"type": "string",
"enum": [
"GBP",
"USD",
"EUR"
]
}
},
"required": [
"amountMinor",
"currency"
],
"additionalProperties": true
}
},
"required": [
"id",
"channel",
"adapterKey",
"budget"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"personaId",
"status",
"staleReason",
"planKind",
"executionMode",
"budget",
"goal",
"startDate",
"endDate",
"channels",
"lines"
],
"additionalProperties": false
},
"persona": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"version": {
"type": "integer"
},
"name": {
"type": "string"
},
"nlDescription": {
"type": "string"
},
"compiled": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"channel": {
"type": "string",
"enum": [
"ctv",
"audio",
"tv",
"cinema",
"dooh",
"search",
"social"
]
},
"spec": {
"anyOf": [
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"const": "ctv"
},
"euidAudienceIds": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"marketplaceSegmentIds": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"geoCities": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"frequencyCapPerWeek": {
"type": "integer",
"minimum": 1
},
"dealIds": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"ageMin": {
"type": "integer",
"minimum": 16
},
"ageMax": {
"type": "integer",
"maximum": 99
},
"gender": {
"type": "string",
"enum": [
"any",
"male",
"female"
],
"default": "any"
}
},
"required": [
"channel"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"const": "audio"
},
"showAllowlist": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"publisherSegments": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"geoCities": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"dayparts": {
"type": "array",
"items": {
"type": "string",
"enum": [
"breakfast",
"commute-am",
"daytime",
"commute-pm",
"evening"
]
},
"default": []
},
"pmpDealSpecs": {
"type": "array",
"items": {
"type": "string"
},
"default": []
}
},
"required": [
"channel"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"const": "tv"
},
"adsmartAttributes": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"postcodeDistricts": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"universalAdsAudience": {
"type": "string",
"enum": [
"custom-csv",
"pixel-lookalike",
"none"
],
"default": "none"
},
"tvRegions": {
"type": "array",
"items": {
"type": "string"
},
"default": []
}
},
"required": [
"channel"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"const": "cinema"
},
"agpPacks": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"venueIds": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"filmGenres": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"weeks": {
"type": "integer",
"minimum": 1,
"default": 2
}
},
"required": [
"channel"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"const": "dooh"
},
"audienceSegmentIds": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"venueTypes": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"geoPolygonRefs": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"dayparts": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"screenRankings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"screenId": {
"type": "string"
},
"overIndex": {
"type": "number"
}
},
"required": [
"screenId",
"overIndex"
],
"additionalProperties": true
},
"default": []
}
},
"required": [
"channel"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"const": "search"
},
"seedKeywords": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"maxItems": 20,
"default": []
},
"negativeKeywords": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"maxItems": 50,
"default": []
},
"geoCities": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"language": {
"type": "string",
"default": "en"
},
"matchTypes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"exact",
"phrase",
"broad"
]
},
"minItems": 1,
"default": [
"exact",
"phrase"
]
},
"network": {
"type": "string",
"enum": [
"search-only",
"search-partners"
],
"default": "search-only"
}
},
"required": [
"channel"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"const": "social"
},
"interestTerms": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"maxItems": 50,
"default": []
},
"geoCities": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"ageMin": {
"type": "integer",
"minimum": 16,
"maximum": 99
},
"ageMax": {
"type": "integer",
"minimum": 16,
"maximum": 99
},
"gender": {
"type": "string",
"enum": [
"any",
"male",
"female"
],
"default": "any"
},
"placements": {
"type": "array",
"items": {
"type": "string",
"enum": [
"feed",
"stories",
"reels",
"search",
"video"
]
},
"default": [
"feed",
"stories",
"reels"
]
},
"optimizationGoal": {
"type": "string",
"enum": [
"unset",
"reach",
"traffic",
"conversions"
],
"default": "unset"
}
},
"required": [
"channel"
],
"additionalProperties": true
}
]
},
"fidelity": {
"type": "object",
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"grade": {
"type": "string",
"enum": [
"person",
"household",
"content",
"venue",
"geo-cohort"
]
},
"rationale": {
"type": "string"
}
},
"required": [
"score",
"grade",
"rationale"
],
"additionalProperties": true
},
"lawfulBasisManifest": {
"type": "array",
"items": {
"type": "object",
"properties": {
"element": {
"type": "string"
},
"basis": {
"type": "string",
"enum": [
"consent-chained",
"legitimate-interest",
"outside-scope"
]
},
"source": {
"type": "string"
},
"note": {
"type": "string"
}
},
"required": [
"element",
"basis",
"source"
],
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"coverage": {
"type": "object",
"properties": {
"requested": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": [
"country",
"city",
"postcode",
"tv-region",
"age",
"gender",
"income",
"industry",
"seniority",
"company-size",
"interest",
"intent",
"audience-exclusion",
"search-negative",
"unresolved"
]
},
"value": {
"type": "string"
}
},
"required": [
"field",
"value"
],
"additionalProperties": true
}
},
"supported": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": [
"country",
"city",
"postcode",
"tv-region",
"age",
"gender",
"income",
"industry",
"seniority",
"company-size",
"interest",
"intent",
"audience-exclusion",
"search-negative",
"unresolved"
]
},
"value": {
"type": "string"
},
"representation": {
"type": "string"
},
"evidence": {
"type": "string",
"enum": [
"semantic",
"modeled",
"provider-catalogue"
]
},
"sourceIds": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"field",
"value",
"representation",
"evidence",
"sourceIds"
],
"additionalProperties": true
}
},
"unsupported": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": [
"country",
"city",
"postcode",
"tv-region",
"age",
"gender",
"income",
"industry",
"seniority",
"company-size",
"interest",
"intent",
"audience-exclusion",
"search-negative",
"unresolved"
]
},
"value": {
"type": "string"
},
"reason": {
"type": "string"
}
},
"required": [
"field",
"value",
"reason"
],
"additionalProperties": true
}
},
"requiresProviderValidation": {
"type": "boolean"
}
},
"required": [
"requested",
"supported",
"unsupported",
"requiresProviderValidation"
],
"additionalProperties": true
}
},
"required": [
"channel",
"spec",
"fidelity",
"lawfulBasisManifest"
],
"additionalProperties": true
}
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"version",
"name",
"nlDescription",
"compiled"
],
"additionalProperties": false
},
"creative": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"revision": {
"type": "integer"
},
"name": {
"type": "string"
},
"channel": {
"type": "string",
"enum": [
"ctv",
"audio",
"tv",
"cinema",
"dooh",
"search",
"social"
]
},
"format": {
"type": "string"
},
"copyText": {
"type": "string"
},
"hasVerifiedAssetBytes": {
"type": "boolean"
},
"hasPrecheck": {
"type": "boolean"
}
},
"required": [
"id",
"revision",
"name",
"channel",
"format",
"copyText",
"hasVerifiedAssetBytes",
"hasPrecheck"
],
"additionalProperties": false
}
},
"additionalProperties": false
},
"instructions": {
"type": "array",
"items": {
"type": "string"
}
},
"evidenceRequests": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"minLength": 1
},
"arguments": {
"type": "object",
"additionalProperties": {}
},
"reason": {
"type": "string",
"minLength": 1
}
},
"required": [
"tool",
"arguments",
"reason"
],
"additionalProperties": false
}
},
"nextActions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"minLength": 1
},
"arguments": {
"type": "object",
"additionalProperties": {}
},
"reason": {
"type": "string",
"minLength": 1
},
"requiresInputs": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"tool",
"arguments",
"reason",
"requiresInputs"
],
"additionalProperties": false
}
},
"missingInputs": {
"type": "array",
"items": {
"type": "string"
}
},
"approvalPolicy": {
"type": "object",
"properties": {
"execution": {
"type": "string",
"const": "existing-agent-approval-flow"
},
"humanApprovalRequired": {
"type": "boolean",
"const": true
},
"instructions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"execution",
"humanApprovalRequired",
"instructions"
],
"additionalProperties": false
}
},
"required": [
"workflow",
"selected",
"instructions",
"evidenceRequests",
"nextActions",
"missingInputs",
"approvalPolicy"
],
"additionalProperties": false
}
},
"required": [
"buyerContext"
],
"additionalProperties": false
}
}
}
}Operation constraints
Machine-readable metadata
{
"x-response-schema-completeness": "modeled",
"x-rate-limit": {
"requests": 300,
"windowMilliseconds": 60000,
"key": "request IP",
"headers": [
"x-ratelimit-limit",
"x-ratelimit-remaining",
"x-ratelimit-reset"
]
},
"x-idempotency": {
"policy": "not-generalized",
"note": "There is no universal Idempotency-Key middleware. Only the documented endpoint mechanisms protect retries."
}
}Complete operation
OpenAPI
{
"operationId": "get_api_v1_buyer_context",
"summary": "Prepare evidence and next actions for an MCP media buyer",
"description": "Read-only, tenant-scoped guidance for briefing, creative direction, campaign review and launch assistance. References existing canonical tools and the existing human approval flow; performs no provider calls or commercial actions.\n\nAuthenticated and advertiser scoped. Cross-tenant resource access returns 404. Product/channel entitlements also apply.",
"tags": [
"Buyer"
],
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "workflow",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"brief_to_plan",
"creative_direction",
"campaign_review",
"launch_assistance"
]
},
"style": "form",
"explode": true
},
{
"name": "campaignId",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"style": "form",
"explode": true
},
{
"name": "planId",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"style": "form",
"explode": true
},
{
"name": "personaId",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"style": "form",
"explode": true
},
{
"name": "creativeId",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"style": "form",
"explode": true
}
],
"responses": {
"400": {
"description": "Invalid request or unsupported fields",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing or invalid authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Permission or product scope refused",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Route or tenant-scoped resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "State, revision, approval, funding or idempotency conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Supplier configuration, capability or upstream refusal",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limit reached; wait before retrying",
"headers": {
"x-ratelimit-limit": {
"description": "Maximum requests permitted in the current rate-limit window.",
"schema": {
"type": "integer"
}
},
"x-ratelimit-remaining": {
"description": "Requests remaining in the current window.",
"schema": {
"type": "integer"
}
},
"x-ratelimit-reset": {
"description": "Seconds until the current rate-limit window resets.",
"schema": {
"type": "integer"
}
},
"retry-after": {
"description": "Minimum seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal error; inspect state before retrying a mutation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Dependency or authentication verifier unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"2XX": {
"description": "Successful response.",
"headers": {
"x-ratelimit-limit": {
"description": "Maximum requests permitted in the current rate-limit window.",
"schema": {
"type": "integer"
}
},
"x-ratelimit-remaining": {
"description": "Requests remaining in the current window.",
"schema": {
"type": "integer"
}
},
"x-ratelimit-reset": {
"description": "Seconds until the current rate-limit window resets.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"buyerContext": {
"type": "object",
"properties": {
"workflow": {
"type": "string",
"enum": [
"brief_to_plan",
"creative_direction",
"campaign_review",
"launch_assistance"
]
},
"selected": {
"type": "object",
"properties": {
"campaign": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"planId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"name": {
"type": "string"
},
"status": {
"type": "string"
},
"startDate": {
"type": "string"
},
"endDate": {
"type": "string"
},
"lines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"lineItemId": {
"type": "string"
},
"channel": {
"type": "string",
"enum": [
"ctv",
"audio",
"tv",
"cinema",
"dooh",
"search",
"social"
]
},
"adapterKey": {
"type": "string"
},
"status": {
"type": "string"
},
"executionMode": {
"type": "string"
},
"budget": {
"type": "object",
"properties": {
"amountMinor": {
"type": "integer"
},
"currency": {
"type": "string",
"enum": [
"GBP",
"USD",
"EUR"
]
}
},
"required": [
"amountMinor",
"currency"
],
"additionalProperties": true
}
},
"required": [
"id",
"lineItemId",
"channel",
"adapterKey",
"status",
"executionMode",
"budget"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"planId",
"name",
"status",
"startDate",
"endDate",
"lines"
],
"additionalProperties": false
},
"plan": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"personaId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 128
},
{
"type": "null"
}
]
},
"status": {
"type": "string"
},
"staleReason": {
"type": [
"string",
"null"
]
},
"planKind": {
"type": "string"
},
"executionMode": {
"type": "string"
},
"budget": {
"type": "object",
"properties": {
"amountMinor": {
"type": "integer"
},
"currency": {
"type": "string",
"enum": [
"GBP",
"USD",
"EUR"
]
}
},
"required": [
"amountMinor",
"currency"
],
"additionalProperties": true
},
"goal": {
"type": "string"
},
"startDate": {
"type": "string"
},
"endDate": {
"type": "string"
},
"channels": {
"type": "array",
"items": {
"type": "string",
"enum": [
"ctv",
"audio",
"tv",
"cinema",
"dooh",
"search",
"social"
]
}
},
"lines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"channel": {
"type": "string",
"enum": [
"ctv",
"audio",
"tv",
"cinema",
"dooh",
"search",
"social"
]
},
"adapterKey": {
"type": "string"
},
"budget": {
"type": "object",
"properties": {
"amountMinor": {
"type": "integer"
},
"currency": {
"type": "string",
"enum": [
"GBP",
"USD",
"EUR"
]
}
},
"required": [
"amountMinor",
"currency"
],
"additionalProperties": true
}
},
"required": [
"id",
"channel",
"adapterKey",
"budget"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"personaId",
"status",
"staleReason",
"planKind",
"executionMode",
"budget",
"goal",
"startDate",
"endDate",
"channels",
"lines"
],
"additionalProperties": false
},
"persona": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"version": {
"type": "integer"
},
"name": {
"type": "string"
},
"nlDescription": {
"type": "string"
},
"compiled": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"channel": {
"type": "string",
"enum": [
"ctv",
"audio",
"tv",
"cinema",
"dooh",
"search",
"social"
]
},
"spec": {
"anyOf": [
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"const": "ctv"
},
"euidAudienceIds": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"marketplaceSegmentIds": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"geoCities": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"frequencyCapPerWeek": {
"type": "integer",
"minimum": 1
},
"dealIds": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"ageMin": {
"type": "integer",
"minimum": 16
},
"ageMax": {
"type": "integer",
"maximum": 99
},
"gender": {
"type": "string",
"enum": [
"any",
"male",
"female"
],
"default": "any"
}
},
"required": [
"channel"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"const": "audio"
},
"showAllowlist": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"publisherSegments": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"geoCities": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"dayparts": {
"type": "array",
"items": {
"type": "string",
"enum": [
"breakfast",
"commute-am",
"daytime",
"commute-pm",
"evening"
]
},
"default": []
},
"pmpDealSpecs": {
"type": "array",
"items": {
"type": "string"
},
"default": []
}
},
"required": [
"channel"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"const": "tv"
},
"adsmartAttributes": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"postcodeDistricts": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"universalAdsAudience": {
"type": "string",
"enum": [
"custom-csv",
"pixel-lookalike",
"none"
],
"default": "none"
},
"tvRegions": {
"type": "array",
"items": {
"type": "string"
},
"default": []
}
},
"required": [
"channel"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"const": "cinema"
},
"agpPacks": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"venueIds": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"filmGenres": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"weeks": {
"type": "integer",
"minimum": 1,
"default": 2
}
},
"required": [
"channel"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"const": "dooh"
},
"audienceSegmentIds": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"venueTypes": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"geoPolygonRefs": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"dayparts": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"screenRankings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"screenId": {
"type": "string"
},
"overIndex": {
"type": "number"
}
},
"required": [
"screenId",
"overIndex"
],
"additionalProperties": true
},
"default": []
}
},
"required": [
"channel"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"const": "search"
},
"seedKeywords": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"maxItems": 20,
"default": []
},
"negativeKeywords": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"maxItems": 50,
"default": []
},
"geoCities": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"language": {
"type": "string",
"default": "en"
},
"matchTypes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"exact",
"phrase",
"broad"
]
},
"minItems": 1,
"default": [
"exact",
"phrase"
]
},
"network": {
"type": "string",
"enum": [
"search-only",
"search-partners"
],
"default": "search-only"
}
},
"required": [
"channel"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"const": "social"
},
"interestTerms": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"maxItems": 50,
"default": []
},
"geoCities": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"ageMin": {
"type": "integer",
"minimum": 16,
"maximum": 99
},
"ageMax": {
"type": "integer",
"minimum": 16,
"maximum": 99
},
"gender": {
"type": "string",
"enum": [
"any",
"male",
"female"
],
"default": "any"
},
"placements": {
"type": "array",
"items": {
"type": "string",
"enum": [
"feed",
"stories",
"reels",
"search",
"video"
]
},
"default": [
"feed",
"stories",
"reels"
]
},
"optimizationGoal": {
"type": "string",
"enum": [
"unset",
"reach",
"traffic",
"conversions"
],
"default": "unset"
}
},
"required": [
"channel"
],
"additionalProperties": true
}
]
},
"fidelity": {
"type": "object",
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"grade": {
"type": "string",
"enum": [
"person",
"household",
"content",
"venue",
"geo-cohort"
]
},
"rationale": {
"type": "string"
}
},
"required": [
"score",
"grade",
"rationale"
],
"additionalProperties": true
},
"lawfulBasisManifest": {
"type": "array",
"items": {
"type": "object",
"properties": {
"element": {
"type": "string"
},
"basis": {
"type": "string",
"enum": [
"consent-chained",
"legitimate-interest",
"outside-scope"
]
},
"source": {
"type": "string"
},
"note": {
"type": "string"
}
},
"required": [
"element",
"basis",
"source"
],
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"coverage": {
"type": "object",
"properties": {
"requested": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": [
"country",
"city",
"postcode",
"tv-region",
"age",
"gender",
"income",
"industry",
"seniority",
"company-size",
"interest",
"intent",
"audience-exclusion",
"search-negative",
"unresolved"
]
},
"value": {
"type": "string"
}
},
"required": [
"field",
"value"
],
"additionalProperties": true
}
},
"supported": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": [
"country",
"city",
"postcode",
"tv-region",
"age",
"gender",
"income",
"industry",
"seniority",
"company-size",
"interest",
"intent",
"audience-exclusion",
"search-negative",
"unresolved"
]
},
"value": {
"type": "string"
},
"representation": {
"type": "string"
},
"evidence": {
"type": "string",
"enum": [
"semantic",
"modeled",
"provider-catalogue"
]
},
"sourceIds": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"field",
"value",
"representation",
"evidence",
"sourceIds"
],
"additionalProperties": true
}
},
"unsupported": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": [
"country",
"city",
"postcode",
"tv-region",
"age",
"gender",
"income",
"industry",
"seniority",
"company-size",
"interest",
"intent",
"audience-exclusion",
"search-negative",
"unresolved"
]
},
"value": {
"type": "string"
},
"reason": {
"type": "string"
}
},
"required": [
"field",
"value",
"reason"
],
"additionalProperties": true
}
},
"requiresProviderValidation": {
"type": "boolean"
}
},
"required": [
"requested",
"supported",
"unsupported",
"requiresProviderValidation"
],
"additionalProperties": true
}
},
"required": [
"channel",
"spec",
"fidelity",
"lawfulBasisManifest"
],
"additionalProperties": true
}
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"version",
"name",
"nlDescription",
"compiled"
],
"additionalProperties": false
},
"creative": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"revision": {
"type": "integer"
},
"name": {
"type": "string"
},
"channel": {
"type": "string",
"enum": [
"ctv",
"audio",
"tv",
"cinema",
"dooh",
"search",
"social"
]
},
"format": {
"type": "string"
},
"copyText": {
"type": "string"
},
"hasVerifiedAssetBytes": {
"type": "boolean"
},
"hasPrecheck": {
"type": "boolean"
}
},
"required": [
"id",
"revision",
"name",
"channel",
"format",
"copyText",
"hasVerifiedAssetBytes",
"hasPrecheck"
],
"additionalProperties": false
}
},
"additionalProperties": false
},
"instructions": {
"type": "array",
"items": {
"type": "string"
}
},
"evidenceRequests": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"minLength": 1
},
"arguments": {
"type": "object",
"additionalProperties": {}
},
"reason": {
"type": "string",
"minLength": 1
}
},
"required": [
"tool",
"arguments",
"reason"
],
"additionalProperties": false
}
},
"nextActions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"minLength": 1
},
"arguments": {
"type": "object",
"additionalProperties": {}
},
"reason": {
"type": "string",
"minLength": 1
},
"requiresInputs": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"tool",
"arguments",
"reason",
"requiresInputs"
],
"additionalProperties": false
}
},
"missingInputs": {
"type": "array",
"items": {
"type": "string"
}
},
"approvalPolicy": {
"type": "object",
"properties": {
"execution": {
"type": "string",
"const": "existing-agent-approval-flow"
},
"humanApprovalRequired": {
"type": "boolean",
"const": true
},
"instructions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"execution",
"humanApprovalRequired",
"instructions"
],
"additionalProperties": false
}
},
"required": [
"workflow",
"selected",
"instructions",
"evidenceRequests",
"nextActions",
"missingInputs",
"approvalPolicy"
],
"additionalProperties": false
}
},
"required": [
"buyerContext"
],
"additionalProperties": false
}
}
}
}
},
"x-response-schema-completeness": "modeled",
"x-rate-limit": {
"requests": 300,
"windowMilliseconds": 60000,
"key": "request IP",
"headers": [
"x-ratelimit-limit",
"x-ratelimit-remaining",
"x-ratelimit-reset"
]
},
"x-idempotency": {
"policy": "not-generalized",
"note": "There is no universal Idempotency-Key middleware. Only the documented endpoint mechanisms protect retries."
}
}