Zum Inhalt
HALOWERK

Audiowerk

ad slot auction

Four actions on one endpoint. create opens a slot with its position, length, reserve price and closing time, and returns an admin token that only the opener holds. bid places a sealed bid, checked against the reserve, the slot length and the publisher's excluded categories before it is accepted — a rejected bid is recorded with its reason rather than silently dropped, so a bidder can see why it never competed. close settles the auction and needs the admin token: the highest valid bid wins.

POST https://audio.halowerk.com/ad-slot-auction

Eingaben

Felder des veröffentlichten Eingabeschemas
FeldTypPflichtBeschreibung
actionstringJacreate opens a slot, bid places a sealed bid, close settles it, status reads it.
auction_idstringNeinRequired for bid, close and status.
admin_tokenstringNeinRequired for close. Returned once by create.
publisherstringNeinName of the publisher offering the slot. create only.
slot_labelstringNeinWhat is being sold, for example "episode 41, mid-roll 2". create only.
positionstringNeinWhere the slot sits in the content. create only.
slot_secondsintegerNeinLength of the slot. create only.
reserve_usdcnumberNeinPrice below which the slot is not sold. create only.
expected_listenersintegerNeinReach the publisher claims. Recorded as a claim, not verified. create only.
excluded_categoriesarrayNeinAdvertiser categories the publisher refuses. create only.
closes_at_unixintegerNeinClosing time in Unix seconds. create only. At most 30 days out.
bidderstringNeinWho is bidding. bid only.
amount_usdcnumberNeinSealed bid amount. bid only.
categorystringNeinAdvertiser category, checked against the exclusions. bid only.
creative_secondsintegerNeinLength of the advertisement, checked against the slot. bid only.
Vollständiges Eingabeschema anzeigen
{
  "type": "object",
  "required": [
    "action"
  ],
  "additionalProperties": false,
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "create",
        "bid",
        "close",
        "status"
      ],
      "description": "create opens a slot, bid places a sealed bid, close settles it, status reads it."
    },
    "auction_id": {
      "type": "string",
      "maxLength": 64,
      "description": "Required for bid, close and status."
    },
    "admin_token": {
      "type": "string",
      "maxLength": 128,
      "description": "Required for close. Returned once by create."
    },
    "publisher": {
      "type": "string",
      "maxLength": 120,
      "description": "Name of the publisher offering the slot. create only."
    },
    "slot_label": {
      "type": "string",
      "maxLength": 200,
      "description": "What is being sold, for example \"episode 41, mid-roll 2\". create only."
    },
    "position": {
      "type": "string",
      "enum": [
        "pre_roll",
        "mid_roll",
        "post_roll"
      ],
      "description": "Where the slot sits in the content. create only."
    },
    "slot_seconds": {
      "type": "integer",
      "minimum": 5,
      "maximum": 180,
      "description": "Length of the slot. create only."
    },
    "reserve_usdc": {
      "type": "number",
      "minimum": 0,
      "maximum": 100000,
      "description": "Price below which the slot is not sold. create only."
    },
    "expected_listeners": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100000000,
      "description": "Reach the publisher claims. Recorded as a claim, not verified. create only."
    },
    "excluded_categories": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string",
        "maxLength": 40
      },
      "description": "Advertiser categories the publisher refuses. create only."
    },
    "closes_at_unix": {
      "type": "integer",
      "minimum": 0,
      "description": "Closing time in Unix seconds. create only. At most 30 days out."
    },
    "bidder": {
      "type": "string",
      "maxLength": 120,
      "description": "Who is bidding. bid only."
    },
    "amount_usdc": {
      "type": "number",
      "minimum": 0,
      "maximum": 100000,
      "description": "Sealed bid amount. bid only."
    },
    "category": {
      "type": "string",
      "maxLength": 40,
      "description": "Advertiser category, checked against the exclusions. bid only."
    },
    "creative_seconds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 180,
      "description": "Length of the advertisement, checked against the slot. bid only."
    }
  }
}

Originalschema öffnen

Veröffentlichtes Eingabebeispiel

{
  "action": "create",
  "publisher": "HALOWERK example publisher",
  "slot_label": "episode 1, mid-roll 1",
  "position": "mid_roll",
  "slot_seconds": 30,
  "reserve_usdc": 5,
  "closes_at_unix": 1794718155
}

Ergebnis & Dokumentation

Maschinenlesbare Dokumentation dieses Hubs

Quelle dieser Seite: der veröffentlichte HALOWERK-Katalog. Stand: 2026-11-01, 15:19 UTC.

Weitere Endpunkte dieses Hubs

Alle Endpunkte dieses Hubs →