DiscoBeat Channel API

Manage your channel's publishers and ad recommendations programmatically — list and update publishers, configure category exclusions at the channel and per-publisher level, and read channel details. Authenticate with your management API key; everything is scoped to your channel.

Base URL & authentication

All endpoints are relative to your environment's base URL:

Environment	Base URL
Production	https://api.disconetwork.com
Staging	https://api.disconetwork-staging.com

All requests require a secret API key in the x-api-key header. Your Disco CS agent provisions a key for each environment. You can view, rotate, and revoke your keys under Developers → API keys in Channel Management.

Secret key vs. publishable key

The publishable key is safe to embed in client-side code and grants read-only access. The secret key allows writes and must be kept private — never expose it in client-side code.

Keys are environment-specific

Your staging key works only against the staging base URL, and your production key only against production. Sending a staging key to production (or vice versa) returns a 401 with "API key environment does not match service environment."

curl -H "x-api-key: your-secret-api-key" \
  https://api.disconetwork.com/discobeat/channel/details/

An invalid, expired, or missing key returns 401:

{"detail": "Invalid or expired API key."}

Errors & validation

The API uses standard HTTP status codes.

Validation errors — 400 (field-level messages):

{"subcategory_ids": ["At least one subcategory must belong to the selected primary category."]}

Conflict errors — 409:

{"error": "A create request for this brand and domain already exists."}

Not found errors — 404:

{"error": "Publisher not found."}

Endpoint reference

Ad recommendation management

Method	Path	Description
GET	/discobeat/adconfig/categories/	List all subcategories, grouped by parent category
PUT	/discobeat/channel/exclusions/	Update channel-wide exclusions
PUT	/discobeat/publishers/{id}/exclusions/	Update publisher-specific exclusions

Channel & publisher management

Method	Path	Description
GET	/discobeat/channel/details/	Get channel name and global exclusions
GET	/discobeat/publishers/list/	List all publishers, paginated and searchable
GET	/discobeat/publishers/details/{id}/	Get details for a single publisher
POST	/discobeat/publishers/add/	Submit a request to add publisher(s)
DELETE	/discobeat/publishers/{id}/remove/	Remove a publisher from your channel

---

List categories

GET /discobeat/adconfig/categories/

Returns all categories with their subcategories, grouped by parent. Use it to populate selectors when submitting publisher create requests or managing exclusions. Categories and subcategories are sorted alphabetically.

Response: 200

{
  "categories": [
    {
      "remote_id": "c9a1e2b3-4d5f-6789-abcd-ef0123456789",
      "name": "Fashion",
      "subcategories": [
        {"remote_id": "d4e5f6a7-8901-4235-bcde-f67890000001", "name": "Women's Apparel"},
        {"remote_id": "e5f6a7b8-9012-4356-cdef-a78901000002", "name": "Men's Apparel"},
        {"remote_id": "f6a7b8c9-0123-4567-defa-b89012000003", "name": "Footwear"}
      ]
    },
    {
      "remote_id": "a7b8c9d0-1234-4678-efab-c90123000004",
      "name": "Home & Garden",
      "subcategories": [
        {"remote_id": "b8c9d0e1-2345-4789-fabc-d01234000005", "name": "Furniture"},
        {"remote_id": "c9d0e1f2-3456-4890-abcd-e12345000006", "name": "Kitchen"}
      ]
    }
  ]
}

curl -H "x-api-key: your-management-api-key" \
  https://api.disconetwork.com/discobeat/adconfig/categories/

Update channel exclusions

PUT /discobeat/channel/exclusions/

Set subcategory exclusions that apply to all publishers under your channel. This replaces the current exclusion list entirely — send [] to clear all.

Field	Type	Required	Details
subcategory_ids	string[]	✓	Subcategory remote_ids to exclude. Send [] to clear.

Request body

{"subcategory_ids": ["d4e5f6a7-8901-2345-bcde-f67890123456", "e5f6a7b8-9012-3456-cdef-a78901234567"]}

Response: 200

{"ok": true}

curl -X PUT \
  -H "x-api-key: your-management-api-key" \
  -H "Content-Type: application/json" \
  -d '{"subcategory_ids": ["d4e5f6a7-8901-2345-bcde-f67890123456"]}' \
  https://api.disconetwork.com/discobeat/channel/exclusions/

Update publisher exclusions

PUT /discobeat/publishers/{publisher_remote_id}/exclusions/

Set additional subcategory exclusions for a specific publisher. These apply at runtime on top of the publisher's own exclusions and your channel-level exclusions. Send [] to clear.

Field	Type	Required	Details
subcategory_ids	string[]	✓	Full set of subcategory remote_ids to exclude for this publisher

Response: 200

{"ok": true}

Errors: 404 — no publisher with that ID found for your channel.

curl -X PUT \
  -H "x-api-key: your-management-api-key" \
  -H "Content-Type: application/json" \
  -d '{"subcategory_ids": ["d4e5f6a7-8901-2345-bcde-f67890123456"]}' \
  https://api.disconetwork.com/discobeat/publishers/f47ac10b-58cc-4372-a567-0e02b2c3d479/exclusions/

Channel details

GET /discobeat/channel/details/

Returns your channel name and channel-level exclusions. The exclusions.subcategories.channel array contains subcategory IDs excluded across all your publishers.

Response: 200

{
  "channel": {
    "name": "Acme",
    "exclusions": {
      "subcategories": {"channel": ["d4e5f6a7-8901-2345-bcde-f67890123456"]}
    }
  }
}

Publisher list

GET /discobeat/publishers/list/

Returns a paginated list of all publishers and pending requests, sorted newest first.

Query param	Type	Details
page	integer	Page number. Default: 1
page_size	integer	Results per page. Max: 200. Default: 50
q	string	Filter by name; words are split and matched independently (OR)

Response: 200

{
  "count": 47,
  "next": "https://api.disconetwork.com/discobeat/publishers/list/?page=2",
  "previous": null,
  "publishers": [
    {
      "pending_publisher_id": null,
      "publisher_remote_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "brand_name": "Allbirds",
      "primary_category": "Fashion",
      "status": "APPROVED",
      "created_at": "2026-03-10T09:15:00Z",
      "exclusions": {"subcategories": {"external": ["d4e5f6a7-8901-4235-bcde-f67890000001"], "publisher": ["e5f6a7b8-9012-4356-cdef-a78901000002"]}}
    },
    {
      "pending_publisher_id": "b2c3d4e5-f678-9012-3456-789012345678",
      "publisher_remote_id": null,
      "brand_name": "New Brand Co",
      "primary_category": "Home & Garden",
      "status": "PENDING",
      "created_at": "2026-04-14T12:00:00Z",
      "exclusions": {"subcategories": {"external": [], "publisher": []}}
    }
  ]
}

Status values: PENDING · NEEDS_INFO · APPROVED · REJECTED

Key fields:

• pending_publisher_id — present for pending requests; use as the path parameter for the detail endpoint until approved.
• publisher_remote_id — the publisher's ad-serving UUID; null for pending requests. Use for the remove and exclusions endpoints once approved.
• exclusions.subcategories.external — set by the publisher, read-only from your perspective; may change without notice.
• exclusions.subcategories.publisher — set by your channel for this specific publisher via the publisher-exclusions endpoint.

curl -H "x-api-key: your-management-api-key" \
  "https://api.disconetwork.com/discobeat/publishers/list/?page=1&page_size=50"

Publisher detail

GET /discobeat/publishers/details/{id}/

Returns the full record for a single publisher or pending request. Pass the remote_id (approved) or pending_publisher_id (pending) from the list.

Response: 200 (approved publisher)

{
  "publisher": {
    "pending_publisher_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "publisher_remote_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "api_key": "disco_pk_live_...",
    "brand_name": "Allbirds",
    "primary_category": "Fashion",
    "status": "APPROVED",
    "created_at": "2026-03-10T09:15:00Z",
    "exclusions": {"subcategories": {"external": ["d4e5f6a7-8901-4235-bcde-f67890000001"], "publisher": ["e5f6a7b8-9012-4356-cdef-a78901000002"]}}
  }
}

Errors: 404 — no publisher or pending request with that ID found for your channel.

curl -H "x-api-key: your-management-api-key" \
  https://api.disconetwork.com/discobeat/publishers/details/f47ac10b-58cc-4372-a567-0e02b2c3d479/

Add publishers

POST /discobeat/publishers/add/

Submit one or more create requests for new publishers (max 50 per call). Each request triggers a matching process against existing publishers; staff review and approve matches. Each item reports its result independently — duplicates are flagged but don't fail the batch.

Field	Type	Required	Details
items	array	✓	List of publisher entries (max 50)
items[].brand_name	string	✓	Brand name of the publisher
items[].domain	string	✓	Brand's website domain
items[].primary_category_id	string	✓	Primary category remote_id
items[].subcategory_ids	string[]	✓	Subcategory remote_ids; at least one must belong to the primary category

Request body

{
  "items": [
    {
      "brand_name": "Allbirds",
      "domain": "allbirds.com",
      "primary_category_id": "c9a1e2b3-4d5f-6789-abcd-ef0123456789",
      "subcategory_ids": ["d4e5f6a7-8901-2345-bcde-f67890123456", "e5f6a7b8-9012-3456-cdef-a78901234567"]
    },
    {
      "brand_name": "Casper",
      "domain": "casper.com",
      "primary_category_id": "a7b8c9d0-1234-5678-efab-c90123456789",
      "subcategory_ids": ["b8c9d0e1-2345-6789-fabc-d01234567890"]
    }
  ]
}

Response: 201

{
  "results": [
    {
      "brand_name": "Allbirds",
      "domain": "allbirds.com",
      "status": "created",
      "create_request": {
        "pending_publisher_id": "b2c3d4e5-f678-9012-3456-789012345678",
        "status": "PENDING",
        "brand_name": "Allbirds",
        "domain": "allbirds.com",
        "primary_category": {"remote_id": "c9a1e2b3-4d5f-4789-abcd-ef0123456789", "name": "Fashion"},
        "subcategory_ids": ["d4e5f6a7-8901-4235-bcde-f67890000001", "e5f6a7b8-9012-4356-cdef-a78901000002"],
        "staff_notes": "",
        "created_at": "2026-04-14T12:00:00Z",
        "updated_at": "2026-04-14T12:00:00Z"
      }
    },
    {
      "brand_name": "Casper",
      "domain": "casper.com",
      "status": "duplicate",
      "error": "A create request for this brand and domain already exists."
    }
  ]
}

Errors: 400 — missing required fields, invalid category/subcategory IDs, empty subcategory list, or items empty / exceeding 50 entries.

curl -X POST \
  -H "x-api-key: your-management-api-key" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"brand_name": "Allbirds", "domain": "allbirds.com", "primary_category_id": "c9a1e2b3-4d5f-4789-abcd-ef0123456789", "subcategory_ids": ["d4e5f6a7-8901-4235-bcde-f67890000001"]}]}' \
  https://api.disconetwork.com/discobeat/publishers/add/

Remove publisher

DELETE /discobeat/publishers/{publisher_remote_id}/remove/

Remove an approved publisher from your channel. Returns 204 No Content on success.

Errors: 404 — no publisher with that ID found for your channel.

curl -X DELETE \
  -H "x-api-key: your-management-api-key" \
  https://api.disconetwork.com/discobeat/publishers/f47ac10b-58cc-4372-a567-0e02b2c3d479/remove/

Related

• DiscoBeat Reporting API — read-only channel + per-publisher analytics.