POST /api/v1/buyer/sessions/{id}/turns
Claim one idempotent buyer turn
Claims one active reasoning turn using an expected revision and request UUID. Exact retries return the original turn and must never execute it again. A stale or competing request fails closed.
Authenticated and advertiser scoped. Cross-tenant resource access returns 404. Product/channel entitlements also apply.
The request schema is generated from the runtime Zod input validator. Cross-field refinements and state-dependent constraints are additionally enforced by the API.
Request
HTTP
POST /api/v1/buyer/sessions/{id}/turnsUse 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 |
|---|---|---|---|
id | path | Yes |
Parameter schemas
JSON Schema
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
]Request body contract
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"requestId": {
"type": "string",
"format": "uuid"
},
"expectedRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 16000
}
},
"required": [
"requestId",
"expectedRevision",
"message"
],
"additionalProperties": false
}
}
}
}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": {
"session": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"workflow": {
"type": "string",
"enum": [
"brief_to_plan",
"creative_direction",
"campaign_review",
"launch_assistance"
]
},
"context": {
"type": "object",
"properties": {
"campaignId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"planId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"personaId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"creativeId": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"additionalProperties": false
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"activeTurnId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"running",
"idle"
]
},
"messages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"role": {
"type": "string",
"enum": [
"user",
"assistant"
]
},
"message": {
"type": "string"
},
"requestId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"role",
"message",
"requestId"
],
"additionalProperties": false
},
"maxItems": 40
},
"history": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"maxItems": 128
},
"productScope": {
"type": "object",
"properties": {
"product": {
"type": "string",
"enum": [
"adbuymcp",
"doohmcp",
"ctvmcp"
]
},
"channels": {
"type": "array",
"items": {
"type": "string",
"enum": [
"ctv",
"audio",
"tv",
"cinema",
"dooh",
"search",
"social"
]
},
"minItems": 1,
"maxItems": 7
}
},
"required": [
"product",
"channels"
],
"additionalProperties": false
},
"references": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"persona",
"plan",
"campaign",
"creative",
"asset",
"mission",
"run"
]
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"kind",
"id"
],
"additionalProperties": false
},
"maxItems": 32
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"workflow",
"context",
"revision",
"activeTurnId",
"status",
"messages",
"history",
"productScope",
"references",
"createdAt",
"updatedAt"
],
"additionalProperties": false
},
"turn": {
"type": "object",
"properties": {
"sessionId": {
"type": "string",
"format": "uuid"
},
"requestId": {
"type": "string",
"format": "uuid"
},
"inputRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"status": {
"type": "string",
"enum": [
"running",
"completed",
"failed",
"cancelled"
]
},
"message": {
"type": "string"
},
"responseMessage": {
"type": [
"string",
"null"
]
},
"toolCalls": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,119}$"
},
"status": {
"type": "string",
"enum": [
"completed",
"failed"
]
}
},
"required": [
"tool",
"status"
],
"additionalProperties": false
},
"maxItems": 64
},
"references": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"persona",
"plan",
"campaign",
"creative",
"asset",
"mission",
"run"
]
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"kind",
"id"
],
"additionalProperties": false
},
"maxItems": 32
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"sessionId",
"requestId",
"inputRevision",
"revision",
"status",
"message",
"responseMessage",
"toolCalls",
"references",
"createdAt",
"updatedAt"
],
"additionalProperties": false
},
"replay": {
"type": "boolean"
}
},
"required": [
"session",
"turn",
"replay"
],
"additionalProperties": true
}
}
}
}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": "post_api_v1_buyer_sessions_id_turns",
"summary": "Claim one idempotent buyer turn",
"description": "Claims one active reasoning turn using an expected revision and request UUID. Exact retries return the original turn and must never execute it again. A stale or competing request fails closed.\n\nAuthenticated and advertiser scoped. Cross-tenant resource access returns 404. Product/channel entitlements also apply.\n\nThe request schema is generated from the runtime Zod input validator. Cross-field refinements and state-dependent constraints are additionally enforced by the API.",
"tags": [
"Buyer"
],
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"requestId": {
"type": "string",
"format": "uuid"
},
"expectedRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 16000
}
},
"required": [
"requestId",
"expectedRevision",
"message"
],
"additionalProperties": false
}
}
}
},
"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": {
"session": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"workflow": {
"type": "string",
"enum": [
"brief_to_plan",
"creative_direction",
"campaign_review",
"launch_assistance"
]
},
"context": {
"type": "object",
"properties": {
"campaignId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"planId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"personaId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"creativeId": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"additionalProperties": false
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"activeTurnId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"running",
"idle"
]
},
"messages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"role": {
"type": "string",
"enum": [
"user",
"assistant"
]
},
"message": {
"type": "string"
},
"requestId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"role",
"message",
"requestId"
],
"additionalProperties": false
},
"maxItems": 40
},
"history": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"maxItems": 128
},
"productScope": {
"type": "object",
"properties": {
"product": {
"type": "string",
"enum": [
"adbuymcp",
"doohmcp",
"ctvmcp"
]
},
"channels": {
"type": "array",
"items": {
"type": "string",
"enum": [
"ctv",
"audio",
"tv",
"cinema",
"dooh",
"search",
"social"
]
},
"minItems": 1,
"maxItems": 7
}
},
"required": [
"product",
"channels"
],
"additionalProperties": false
},
"references": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"persona",
"plan",
"campaign",
"creative",
"asset",
"mission",
"run"
]
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"kind",
"id"
],
"additionalProperties": false
},
"maxItems": 32
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"workflow",
"context",
"revision",
"activeTurnId",
"status",
"messages",
"history",
"productScope",
"references",
"createdAt",
"updatedAt"
],
"additionalProperties": false
},
"turn": {
"type": "object",
"properties": {
"sessionId": {
"type": "string",
"format": "uuid"
},
"requestId": {
"type": "string",
"format": "uuid"
},
"inputRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0
},
"status": {
"type": "string",
"enum": [
"running",
"completed",
"failed",
"cancelled"
]
},
"message": {
"type": "string"
},
"responseMessage": {
"type": [
"string",
"null"
]
},
"toolCalls": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,119}$"
},
"status": {
"type": "string",
"enum": [
"completed",
"failed"
]
}
},
"required": [
"tool",
"status"
],
"additionalProperties": false
},
"maxItems": 64
},
"references": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"persona",
"plan",
"campaign",
"creative",
"asset",
"mission",
"run"
]
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"kind",
"id"
],
"additionalProperties": false
},
"maxItems": 32
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"sessionId",
"requestId",
"inputRevision",
"revision",
"status",
"message",
"responseMessage",
"toolCalls",
"references",
"createdAt",
"updatedAt"
],
"additionalProperties": false
},
"replay": {
"type": "boolean"
}
},
"required": [
"session",
"turn",
"replay"
],
"additionalProperties": true
}
}
}
}
},
"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."
}
}