stable · api · 0.1.0

Create an advertising Ad Decision

POST /api/v1/advertising/ad-decisions

Capability Domain: Advertising Sponsorship

Authentication

projectCredential (advertising:serve)

Scope: advertising:serve

Parameters and request body

X-Correlation-ID — header, optional
X-Correlation-ID schema
```
{
    "type": "string",
    "format": "uuid"
}
```

Request schema

application/json

application/json request schema

{
    "type": "object",
    "additionalProperties": false,
    "required": [
        "placement_code",
        "frequency_token"
    ],
    "properties": {
        "placement_code": {
            "type": "string",
            "maxLength": 120
        },
        "image_preset_id": {
            "type": [
                "string",
                "null"
            ],
            "format": "uuid"
        },
        "targeting": {
            "type": "object",
            "additionalProperties": {
                "type": "string"
            }
        },
        "frequency_token": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
        }
    }
}

application/json request example

{
    "placement_code": "article-sidebar",
    "image_preset_id": "8a000000-0000-4000-8000-000000000101",
    "targeting": {
        "section": "technology"
    },
    "frequency_token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Responses and errors

Status	Description
`200`	Signed paid or House Ad Decision, or null for no-fill
`401`	Invalid or revoked Project Credential
`403`	Project Credential lacks the required scope
`422`	The Placement or Targeting Context is invalid

200 schema

200 response schema

{
    "type": "object",
    "required": [
        "data"
    ],
    "properties": {
        "data": {
            "oneOf": [
                {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                        "id",
                        "inventory_type",
                        "selection_version",
                        "expires_at",
                        "creative",
                        "tracking"
                    ],
                    "properties": {
                        "id": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "inventory_type": {
                            "type": "string",
                            "enum": [
                                "paid",
                                "house"
                            ]
                        },
                        "selection_version": {
                            "type": "string"
                        },
                        "expires_at": {
                            "type": "string",
                            "format": "date-time"
                        },
                        "creative": {
                            "type": "object",
                            "required": [
                                "format",
                                "image_preset_id",
                                "asset_url",
                                "content"
                            ],
                            "properties": {
                                "format": {
                                    "type": "string",
                                    "enum": [
                                        "image",
                                        "native"
                                    ]
                                },
                                "image_preset_id": {
                                    "type": [
                                        "string",
                                        "null"
                                    ],
                                    "format": "uuid"
                                },
                                "asset_url": {
                                    "type": [
                                        "string",
                                        "null"
                                    ]
                                },
                                "content": {
                                    "type": "object",
                                    "additionalProperties": {
                                        "type": "string"
                                    }
                                }
                            }
                        },
                        "tracking": {
                            "type": "object",
                            "required": [
                                "token",
                                "impression_url",
                                "click_url"
                            ],
                            "properties": {
                                "token": {
                                    "type": "string"
                                },
                                "impression_url": {
                                    "type": "string",
                                    "format": "uri"
                                },
                                "click_url": {
                                    "type": "string",
                                    "format": "uri"
                                }
                            }
                        }
                    }
                },
                {
                    "type": "null"
                }
            ]
        }
    }
}

401 schema

401 response schema

{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "code",
                "message",
                "retryable",
                "correlation_id",
                "details"
            ],
            "properties": {
                "code": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "retryable": {
                    "type": "boolean"
                },
                "correlation_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "details": {
                    "type": "object"
                }
            }
        }
    }
}

403 schema

403 response schema

{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "code",
                "message",
                "retryable",
                "correlation_id",
                "details"
            ],
            "properties": {
                "code": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "retryable": {
                    "type": "boolean"
                },
                "correlation_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "details": {
                    "type": "object"
                }
            }
        }
    }
}

200 example

200 response example

{
    "data": null
}

Idempotency

Each request creates a short-lived signed decision; reuse the returned interaction URLs instead of replaying the request.