Content Signals Public APIs

This document covers the contentSignals targeting fields introduced in the Public Deal API (create and update).

Create Deal — POST /api/deals

{
  "name": "My Deal",
  "dspId": "DSP_ACCOUNT_ID",
  "dealType": "PREFERRED_DEAL",
  "dealCategory": "STANDARD_DEAL",
  "startDate": "01/01/2026 00:00:00",
  "endDate": "31/12/2026 23:59:59",
  "isActive": false,
  "dealFloor": 2.5,
  "dealBid": 3.0,
  "dealCeil": 10.0,
  "dealFloorType": "HARD",
  "dealFloorTolerance": "0",
  "regionOfOrigin": "US",
  "seats": [],
  "targeting": [
    {
      "contentSignals": {
        "genreTargeting": {
          "genres": ["Drama", "Comedy"],
          "isIncl": true
        },
        "languageTargeting": {
          "languages": ["en", "fr"],
          "isIncl": true
        },
        "ratingTargeting": {
          "ratings": ["PG", "PG-13"],
          "isIncl": true
        },
        "iabCategoryTargeting": {
          "categories": ["IAB2-1", "IAB9-1"],
          "isIncl": true
        },
        "productionQualityTargeting": {
          "values": [1, 2],
          "isIncl": true
        },
        "fullEpisodePlayer": true
      }
    }
  ]
}

Update Deal — PUT /api/deals

Only id is required; all other fields are optional. To clear a targeting dimension, set its sub-field to null.

{
  "id": 12345,
  "name": "My Deal Updated",
  "isActive": true,
  "targeting": [
    {
      "contentSignals": {
        "genreTargeting": {
          "genres": ["Action"],
          "isIncl": false
        },
        "languageTargeting": {
          "languages": ["en"],
          "isIncl": true
        },
        "ratingTargeting": null,
        "iabCategoryTargeting": {
          "categories": ["IAB2-1"],
          "isIncl": true
        },
        "productionQualityTargeting": {
          "values": [1],
          "isIncl": true
        },
        "fullEpisodePlayer": false
      }
    }
  ]
}

Content Signal Fields Reference

Validation Rules

• Genres — accept canonical names or free text; no write-time validation. Use GET /api/metadata/content-genres to discover valid canonical values.
• Languages — validated at write time against the meta_language table; must be valid ISO 639-1 codes (e.g. "en", "fr", "hi").
• Ratings — accept canonical names or free text; no write-time validation. Use GET /api/metadata/content-ratings to discover valid canonical values.
• IAB Categories — accept raw strings; no write-time validation (externally versioned taxonomy).
• Production Quality — validated to integers in range 0–3.
• Full Episode Player — boolean; no validation beyond type check.

Setting any sub-field to null clears that targeting dimension. All contentSignals sub-fields are optional and independent of each other.

Metadata Endpoints

Use these endpoints to discover valid canonical values before constructing a targeting payload.

GET /api/metadata/content-genres

Returns non-deprecated content genres. Supports optional ?search=<term> for case-insensitive name filtering.

Response

{
  "data": [
    { "id": 1, "name": "Drama", "aliases": ["drama"] },
    { "id": 2, "name": "Comedy", "aliases": ["comedy", "com"] }
  ]
}

GET /api/metadata/content-ratings

Returns all non-deprecated content ratings ordered by name.

Response

{
  "data": [
    { "id": 1, "name": "PG", "description": "Parental Guidance Suggested", "aliases": ["pg"] },
    { "id": 2, "name": "PG-13", "description": "Parents Strongly Cautioned", "aliases": ["pg13"] }
  ]