{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/arcmira/main/json-schema/arcmira-channel-sponsors-response-schema.json",
  "title": "ChannelSponsorsResponse",
  "x-generated": "2026-10-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/arcmira-v1-openapi.json#/components/schemas/ChannelSponsorsResponse",
  "type": "object",
  "properties": {
    "channel": {
      "type": "object",
      "properties": {
        "id": {
          "type": [
            "string",
            "null"
          ],
          "description": "Public entity id (\"ent_{n}\") of the channel. Null when the channel has media in the index but no entity record yet."
        },
        "youtube_channel_id": {
          "type": "string",
          "description": "YouTube channel id as supplied in the request path."
        },
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Channel name. Null when no entity record exists."
        },
        "page": {
          "type": [
            "string",
            "null"
          ],
          "description": "The channel's page on arcmira.com, absolute. Null when no channel is known."
        }
      },
      "required": [
        "id",
        "youtube_channel_id",
        "name",
        "page"
      ]
    },
    "sponsors": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ChannelSponsor"
      },
      "description": "Recurring sponsors ordered by ad read count (descending)."
    },
    "meta": {
      "type": "object",
      "properties": {
        "min_ad_reads": {
          "type": "integer",
          "description": "The min_ad_reads threshold applied (default 3)."
        },
        "count": {
          "type": "integer",
          "description": "Number of sponsors returned."
        },
        "total": {
          "type": "integer",
          "description": "Sponsors in the rollup at the applied threshold. Greater than count only when the plan gate cut the list to the free slice."
        }
      },
      "required": [
        "min_ad_reads",
        "count",
        "total"
      ]
    },
    "access": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "invalid_request_error",
            "authentication_error",
            "permission_error",
            "quota_exceeded",
            "rate_limit_error",
            "not_found",
            "conflict_error",
            "server_error"
          ],
          "description": "The error class. It fixes the HTTP status: invalid_request_error 400, authentication_error 401, quota_exceeded 402, permission_error 403, not_found 404, conflict_error 409, rate_limit_error 429, server_error 500. Switch on it for retry and gate handling."
        },
        "code": {
          "type": "string",
          "description": "The specific condition, stable and snake_case; doc_url anchors on it. x-arcmira-codes on this schema lists every code with its type, gate and meaning. The list is open: new codes may appear inside an existing type, so switch on type and gate first."
        },
        "reason": {
          "type": "string",
          "enum": [
            "no_credential",
            "invalid",
            "revoked"
          ],
          "description": "Only on invalid_api_key. no_credential: nothing was sent. invalid: a credential was sent and is unknown or malformed. revoked: the key exists and is no longer usable."
        },
        "message": {
          "type": "string",
          "description": "One plain line. Names the fix or the unlock."
        },
        "param": {
          "type": "string",
          "description": "The query or body parameter the gate refused, when one did."
        },
        "gate": {
          "type": "string",
          "enum": [
            "rows",
            "key",
            "plan",
            "freshness",
            "exposure_law",
            "rate",
            "pagination"
          ],
          "description": "Which boundary refused. Present on every gate error; switch on it without parsing the message."
        },
        "resource": {
          "$ref": "#/$defs/ErrorResource"
        },
        "unlock": {
          "type": "object",
          "properties": {
            "tier": {
              "type": "string",
              "description": "The plan that lifts the gate."
            },
            "url": {
              "type": "string",
              "description": "Absolute upgrade or sign-up URL carrying its ?src= attribution. Use it verbatim."
            },
            "offer": {
              "type": "null",
              "description": "Reserved for the agent-discount offer. Always null today."
            },
            "action": {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "description": "What the call does. send_signup_code sends a verification code to an address for an account key."
                },
                "method": {
                  "type": "string",
                  "description": "HTTP method to use."
                },
                "url": {
                  "type": "string",
                  "description": "Absolute endpoint carrying its ?src= attribution. Call it verbatim."
                }
              },
              "required": [
                "kind",
                "method",
                "url"
              ],
              "description": "The request that lifts the gate with no human, present when the caller can fix this itself. A key gate carries the signup send here; a plan or quota gate has no action and its url is a page a person opens."
            }
          },
          "required": [
            "tier",
            "url",
            "offer"
          ],
          "description": "How to lift the gate. Present when the gate has an unlock."
        },
        "retry_after_seconds": {
          "type": "integer",
          "description": "Present on rate gates. Mirrors the Retry-After header."
        },
        "details": {
          "type": "object",
          "properties": {
            "quote": {
              "$ref": "#/$defs/RefusedQuote"
            },
            "existing_id": {
              "type": "string",
              "description": "On tracker_already_exists, the existing tracker id. Reuse it instead of creating another tracker."
            },
            "limit": {
              "type": "integer",
              "description": "On tracker_limit, the trackers the plan holds."
            },
            "count": {
              "type": "integer",
              "description": "On tracker_limit, the trackers the account holds now."
            }
          },
          "description": "Machine data the refusal carries for you to act on. Present only on the codes that name a field here."
        },
        "doc_url": {
          "type": "string"
        },
        "request_id": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "message",
        "doc_url",
        "request_id"
      ],
      "description": "The gate that reduced this response. Present only when something was withheld; carries the same code, gate, and unlock an outright refusal would."
    }
  },
  "required": [
    "channel",
    "sponsors",
    "meta"
  ],
  "$defs": {
    "ChannelSponsor": {
      "type": "object",
      "properties": {
        "entity": {
          "allOf": [
            {
              "$ref": "#/$defs/EntityRef"
            },
            {
              "description": "The sponsoring entity."
            }
          ]
        },
        "ad_reads": {
          "type": "integer",
          "description": "Number of ad_read recommendation rows for this sponsor on the channel."
        },
        "videos": {
          "type": "integer",
          "description": "Number of distinct videos containing those ad reads."
        },
        "first_seen": {
          "type": [
            "string",
            "null"
          ],
          "description": "Publish timestamp of the earliest video with an ad read. Null when unknown."
        },
        "last_seen": {
          "type": [
            "string",
            "null"
          ],
          "description": "Publish timestamp of the most recent video with an ad read. Null when unknown."
        },
        "sponsor_status": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "status": {
              "type": "string",
              "description": "Curated sponsorship status from the known-advertisers dataset. Values: active (currently sponsoring), lapsed (no recent ad reads), ended (relationship known to have ended), uncertain (signal too weak to classify)."
            },
            "ad_count": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Curated ad count from the known-advertisers dataset."
            },
            "first_ad_date": {
              "type": [
                "string",
                "null"
              ],
              "description": "Curated first-ad date. Null when not recorded."
            },
            "last_ad_date": {
              "type": [
                "string",
                "null"
              ],
              "description": "Curated last-ad date. Null when not recorded."
            }
          },
          "required": [
            "status",
            "ad_count",
            "first_ad_date",
            "last_ad_date"
          ],
          "description": "Curated known-advertiser record for this sponsor/channel pair. Null unless the pair exists in the curated dataset."
        }
      },
      "required": [
        "entity",
        "ad_reads",
        "videos",
        "first_seen",
        "last_seen",
        "sponsor_status"
      ]
    },
    "EntityRef": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Public entity id in the form \"ent_{n}\"."
        },
        "name": {
          "type": "string",
          "description": "Canonical entity name."
        },
        "type": {
          "type": "string",
          "description": "Entity type. Values: person (an individual), organization (a company or institution; legacy rows may read company or brand), product (a product or service), topic (a subject or theme), channel (a media source such as a YouTube channel), unknown (type was never classified)."
        },
        "slug": {
          "type": [
            "string",
            "null"
          ],
          "description": "URL slug, the site's canonical id for every type but channel. Null when never slugged."
        },
        "page": {
          "type": [
            "string",
            "null"
          ],
          "description": "The entity's page on arcmira.com, absolute. Link the name to it when you write the entity into an answer. Null for a type the site has no page for."
        }
      },
      "required": [
        "id",
        "name",
        "type",
        "slug",
        "page"
      ]
    },
    "ErrorResource": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "media_rows"
              ]
            },
            "beyond_row": {
              "type": "integer"
            }
          },
          "required": [
            "kind",
            "beyond_row"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "fresh_media"
              ]
            },
            "window_days": {
              "type": "integer"
            },
            "cutoff": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "kind",
            "window_days",
            "cutoff"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "sidebar_rows"
              ]
            },
            "section": {
              "type": "string",
              "enum": [
                "topics",
                "entities"
              ]
            },
            "beyond_row": {
              "type": "integer"
            }
          },
          "required": [
            "kind",
            "section",
            "beyond_row"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "counts"
              ]
            }
          },
          "required": [
            "kind"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "chart"
              ]
            }
          },
          "required": [
            "kind"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "pagination"
              ]
            },
            "param": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "offset",
                "cursor",
                null
              ]
            }
          },
          "required": [
            "kind",
            "param"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "premium_transcript"
              ]
            }
          },
          "required": [
            "kind"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "filter"
              ]
            },
            "param": {
              "type": "string"
            }
          },
          "required": [
            "kind",
            "param"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "commercial"
              ]
            },
            "what": {
              "type": "string",
              "enum": [
                "sponsors",
                "recommendations",
                "mention_details",
                "community_review",
                "paid_split"
              ]
            }
          },
          "required": [
            "kind",
            "what"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "feature"
              ]
            },
            "feature": {
              "type": "string",
              "enum": [
                "api",
                "export"
              ]
            }
          },
          "required": [
            "kind",
            "feature"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "rows"
              ]
            },
            "requested": {
              "type": [
                "integer",
                "null"
              ]
            },
            "remaining": {
              "type": [
                "integer",
                "null"
              ]
            }
          },
          "required": [
            "kind",
            "requested",
            "remaining"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "key"
              ]
            },
            "scope": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "read",
                "monitors:write",
                "trackers:write",
                "recommendations:read",
                null
              ]
            }
          },
          "required": [
            "kind",
            "scope"
          ]
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "requests"
              ]
            }
          },
          "required": [
            "kind"
          ]
        }
      ],
      "description": "The value the boundary withheld, not the reason it refused. kind is a closed vocabulary and the fields beside it are fixed per kind; see https://arcmira.com/docs/errors#resource-kinds."
    },
    "RefusedQuote": {
      "allOf": [
        {
          "$ref": "#/$defs/TranscriptQuote"
        },
        {
          "type": "object",
          "properties": {
            "charge": {
              "type": "object",
              "properties": {
                "unit": {
                  "type": "string",
                  "enum": [
                    "rows",
                    "credits"
                  ]
                },
                "amount": {
                  "type": "number"
                },
                "from": {
                  "type": "string",
                  "enum": [
                    "included",
                    "on_demand",
                    "mixed"
                  ],
                  "description": "Where the charge would come from at the current balance."
                }
              },
              "required": [
                "unit",
                "amount",
                "from"
              ],
              "description": "What the purchase would charge at the current balance. Absent when no current price could be read."
            },
            "max_on_demand_cents": {
              "type": "integer",
              "description": "The on-demand money, in whole cents, this purchase needs beyond included credits at the current balance."
            }
          }
        }
      ],
      "description": "The refused price, on a priced refusal: quota_exceeded, spend_limit_exceeded and paid_plan_required."
    },
    "TranscriptQuote": {
      "type": "object",
      "properties": {
        "quarters": {
          "type": "integer",
          "description": "Number of 15-minute blocks in the video, ceiling'd, minimum 1."
        },
        "rows": {
          "type": "integer",
          "description": "Total unlock cost in rows: 75 rows per 15-minute block."
        }
      },
      "required": [
        "quarters",
        "rows"
      ]
    }
  }
}