{"openapi":"3.0.3","info":{"title":"Campaign Planner Resources","version":"2.0.0","description":"Buzz API v2"},"paths":{"/forecasting/keys":{"get":{"operationId":"forecasting_keys_retrieve","description":"Returns all targeting keys available for pre-sales forecasting, along with their key type and support level. Use this endpoint to discover which targeting dimensions can be used when running a forecast. Results are filtered to the latest supported forecasting model version.","summary":"List available forecasting targeting keys","parameters":[{"in":"query","name":"key_type","schema":{"type":"string"},"description":"Filter by key type. Valid values: targeting_key, line_item_field."},{"in":"query","name":"support","schema":{"type":"string"},"description":"Filter by support level. Valid values: all, some."},{"in":"query","name":"targeting_key","schema":{"type":"string"},"description":"Filter by exact targeting key name (e.g. geo)."},{"in":"query","name":"targeting_key__contains","schema":{"type":"string"},"description":"Filter keys where name contains this value (case-insensitive, e.g. exchange)."}],"tags":["Campaign Planner"],"security":[{"nestSessionAuth":[]},{"nestBasicAuth":[]}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForecastingKeysEnvelope"}}},"description":"List of available forecasting keys with their type and support level, filtered to the latest supported version."},"401":{"description":"Authentication credentials are missing or invalid."},"403":{"description":"Permission denied."}}}},"/forecasting/run":{"post":{"operationId":"forecasting_run_create","description":"Executes a forecast using the specified targeting modules, time range, and line item type. Returns daily predicted impression values with confidence bounds. Rate limited to 10 requests per minute per account. Use GET /forecasting/keys and GET /forecasting/values to discover valid targeting options before calling this endpoint.","summary":"Run a pre-sales forecast","tags":["Campaign Planner"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForecastRun"},"examples":{"GeoTargeting":{"value":{"start_time":"2025-07-01T00:00:00Z","end_time":"2025-07-14T00:00:00Z","non_targeting_keys":{"line_item_type":"banner"},"targeting_modules":{"geo":{"ALL":{"country":[{"value":"US","comparator":"is"}]}}}},"summary":"Geo targeting (country)","description":"Forecast impressions for US traffic."},"EnvironmentTargeting":{"value":{"start_time":"2025-07-01T00:00:00Z","end_time":"2025-07-14T00:00:00Z","non_targeting_keys":{"line_item_type":"banner"},"targeting_modules":{"environment_targeting":{"ALL":{"environment_type":[{"value":"site","comparator":"is"}]}}}},"summary":"Environment targeting","description":"Forecast for site (web) environment."},"ExchangeInventorySource":{"value":{"start_time":"2025-07-01T00:00:00Z","end_time":"2025-07-14T00:00:00Z","non_targeting_keys":{"line_item_type":"banner"},"targeting_modules":{"inventory_source":{"ALL":{"inventory_source":[{"value":"Google Ad Manager","comparator":"is"}]}}}},"summary":"Exchange / inventory source targeting","description":"Forecast for a specific inventory source."},"PlatformDeviceType":{"value":{"start_time":"2025-07-01T00:00:00Z","end_time":"2025-07-14T00:00:00Z","non_targeting_keys":{"line_item_type":"banner"},"targeting_modules":{"platform_targeting":{"ALL":{"device_type":[{"value":"mobile","comparator":"is"}]}}}},"summary":"Platform / device type targeting","description":"Forecast for mobile device type."},"AppSiteTargeting":{"value":{"start_time":"2025-07-01T00:00:00Z","end_time":"2025-07-14T00:00:00Z","non_targeting_keys":{"line_item_type":"banner"},"targeting_modules":{"app_site_targeting":{"ALL":{"app_bundle":[{"value":"com.example.app","comparator":"is"}]}}}},"summary":"App/site targeting","description":"Forecast for a specific app bundle."},"SegmentTargeting":{"value":{"start_time":"2025-07-01T00:00:00Z","end_time":"2025-07-14T00:00:00Z","non_targeting_keys":{"line_item_type":"banner"},"targeting_modules":{"segment":{"ALL":{"segment_id":[{"value":"12345","comparator":"is"}]}}}},"summary":"User / segment targeting","description":"Forecast using a first-party segment."},"DealIdTargeting":{"value":{"start_time":"2025-07-01T00:00:00Z","end_time":"2025-07-14T00:00:00Z","non_targeting_keys":{"line_item_type":"banner"},"targeting_modules":{"deal_targeting":{"ALL":{"deal_id":[{"value":"DEAL-ABC-123","comparator":"is"},{"value":"DEAL-DEF-456","comparator":"is"}]}}}},"summary":"Deal ID targeting","description":"Forecast for PMP deal inventory."},"CombinedTargeting":{"value":{"start_time":"2025-07-01T00:00:00Z","end_time":"2025-07-31T00:00:00Z","non_targeting_keys":{"line_item_type":"video"},"targeting_modules":{"geo":{"ALL":{"country":[{"value":"US","comparator":"is"},{"value":"CA","comparator":"is"}]}},"environment_targeting":{"ALL":{"environment_type":[{"value":"app","comparator":"is"}]}},"platform_targeting":{"ALL":{"device_type":[{"value":"ctv","comparator":"is"}]}},"inventory_source":{"ALL":{"inventory_source":[{"value":"Google Ad Manager","comparator":"is"}]}}}},"summary":"Combined multi-module targeting","description":"Forecast combining geo, environment, platform, and exchange targeting."}}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/ForecastRun"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ForecastRun"}}},"required":true},"security":[{"nestSessionAuth":[]},{"nestBasicAuth":[]}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForecastRunEnvelope"}}},"description":"Forecast completed successfully."},"400":{"description":"Request validation failed. Possible causes: invalid targeting module, invalid line_item_type, start_time in the past, start_time after end_time, invalid deal IDs, or upstream forecast service error."},"401":{"description":"Authentication credentials are missing or invalid."},"403":{"description":"Permission denied."},"429":{"description":"Rate limit exceeded. Default limit is 10 requests per minute per account."},"504":{"description":"The upstream forecast service did not respond within 60 seconds. Please try again later."}}}},"/forecasting/values":{"get":{"operationId":"forecasting_values_retrieve","description":"Returns the available targeting values for a specified forecasting key. The targeting_key query parameter is required. Use GET /forecasting/keys first to discover valid key names. Results are paginated.","summary":"List values for a forecasting targeting key","parameters":[{"in":"query","name":"page","schema":{"type":"integer"},"description":"Page number for paginated results."},{"in":"query","name":"page_size","schema":{"type":"integer"},"description":"Number of results per page. Defaults to 50, maximum 10000."},{"in":"query","name":"targeting_key","schema":{"type":"string"},"description":"The targeting key to retrieve values for (e.g. geo). Must be a valid key returned by GET /forecasting/keys.","required":true},{"in":"query","name":"targeting_values__contains","schema":{"type":"string"},"description":"Filter values containing this string (case-insensitive, e.g. US)."}],"tags":["Campaign Planner"],"security":[{"nestSessionAuth":[]},{"nestBasicAuth":[]}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForecastingValuesEnvelope"}}},"description":"Paginated list of targeting values for the specified key."},"400":{"description":"The targeting_key parameter is missing or not available for forecasting."},"401":{"description":"Authentication credentials are missing or invalid."},"403":{"description":"Permission denied."}}}}},"components":{"schemas":{"Errors":{"type":"object","properties":{"errors":{"type":"object","additionalProperties":{},"description":"Field-level validation errors, keyed by field name."},"non_field_errors":{"type":"array","items":{"type":"string"},"description":"Validation errors not tied to a specific field."}},"required":["errors","non_field_errors"]},"ForecastRun":{"type":"object","properties":{"start_time":{"type":"string","format":"date-time","description":"The start time for the forecasting run."},"end_time":{"type":"string","format":"date-time","description":"The end time for the forecasting run."},"non_targeting_keys":{"$ref":"#/components/schemas/NonTargetingKeys"},"targeting_modules":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TargetingModule"},"description":"Refer to the [targeting guide](https://dash.readme.com/project/beeswax/v2.0/docs/how-to-use-targeting-in-campaign-planner) for more information on constructing the modules object"}},"required":["end_time","non_targeting_keys","start_time","targeting_modules"]},"ForecastRunBeewarePredictedValue":{"type":"object","properties":{"start_time":{"type":"string","format":"date-time","description":"Start of the interval."},"end_time":{"type":"string","format":"date-time","description":"End of the interval."},"prediction":{"type":"integer","description":"Central forecast value for the interval."},"upper_bound":{"type":"integer","description":"Upper confidence bound."},"lower_bound":{"type":"integer","description":"Lower confidence bound."}},"required":["end_time","lower_bound","prediction","start_time","upper_bound"]},"ForecastRunEnvelope":{"type":"object","properties":{"result":{"allOf":[{"$ref":"#/components/schemas/ForecastRunResponseSchema"}],"description":"Forecast result data."},"errors":{"allOf":[{"$ref":"#/components/schemas/Errors"}],"description":"Validation errors, if any."},"warnings":{"allOf":[{"$ref":"#/components/schemas/Warnings"}],"description":"Warnings, if any."}},"required":["errors","result","warnings"]},"ForecastRunResponseSchema":{"type":"object","properties":{"support_set_id":{"type":"string","description":"Identifier for the support (dimension) set used for this forecast."},"predicted_values_daily":{"type":"array","items":{"$ref":"#/components/schemas/ForecastRunBeewarePredictedValue"},"description":"Predicted impression values for each day in the requested date range, each with a central prediction and upper/lower confidence bounds."},"predicted_values_weekly":{"type":"array","items":{"$ref":"#/components/schemas/ForecastRunBeewarePredictedValue"},"description":"Predicted impression values aggregated by calendar week, each with a central prediction and upper/lower confidence bounds."}},"required":["predicted_values_daily","predicted_values_weekly","support_set_id"]},"ForecastingKeyMetadata":{"type":"object","properties":{"key_type":{"type":"string","description":"Type of forecasting key. One of: targeting_key, line_item_field."},"support":{"type":"string","description":"Support level for this forecasting key. One of: all, some."}},"required":["key_type","support"]},"ForecastingKeysEnvelope":{"type":"object","properties":{"result":{"allOf":[{"$ref":"#/components/schemas/ForecastingKeysResponse"}],"description":"Forecasting keys and version information."},"errors":{"allOf":[{"$ref":"#/components/schemas/Errors"}],"description":"Validation errors, if any."},"warnings":{"allOf":[{"$ref":"#/components/schemas/Warnings"}],"description":"Warnings, if any."}},"required":["errors","result","warnings"]},"ForecastingKeysResponse":{"type":"object","properties":{"keys":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ForecastingKeyMetadata"},"description":"Available forecasting keys, keyed by targeting key name. Each entry contains key_type and support."},"supported_version_id":{"type":"string","description":"Identifier for the forecasting model version these keys belong to."}},"required":["keys","supported_version_id"]},"ForecastingValue":{"type":"object","properties":{"key":{"type":"string","description":"Unique identifier for the targeting value."},"name":{"type":"string","description":"Display name of the targeting value."},"alternative_id":{"type":"string","description":"Alternative identifier for the targeting value."}},"required":["alternative_id","key","name"]},"ForecastingValuesEnvelope":{"type":"object","properties":{"count":{"type":"integer","description":"Total number of matching targeting values."},"next":{"type":"string","nullable":true,"description":"URL for the next page of results, or null if this is the last page."},"previous":{"type":"string","nullable":true,"description":"URL for the previous page of results, or null if this is the first page."},"result":{"type":"array","items":{"$ref":"#/components/schemas/ForecastingValue"},"description":"List of matching targeting values for the requested key."},"targeting_key":{"type":"string","description":"The targeting key name these values belong to."},"supported_version_id":{"type":"string","description":"Identifier for the forecasting model version these values belong to."},"errors":{"allOf":[{"$ref":"#/components/schemas/Errors"}],"description":"Validation errors, if any."},"warnings":{"allOf":[{"$ref":"#/components/schemas/Warnings"}],"description":"Warnings, if any."}},"required":["count","errors","next","previous","result","supported_version_id","targeting_key","warnings"]},"LineItemTypeEnum":{"enum":["BANNER","VIDEO","NATIVE","AUDIO"],"type":"string","description":"* `BANNER` - BANNER\n* `VIDEO` - VIDEO\n* `NATIVE` - NATIVE\n* `AUDIO` - AUDIO"},"NonTargetingKeys":{"type":"object","properties":{"line_item_type":{"allOf":[{"$ref":"#/components/schemas/LineItemTypeEnum"}],"description":"The line item type for the forecast. Valid values: BANNER, VIDEO, NATIVE, AUDIO.\n\n* `BANNER` - BANNER\n* `VIDEO` - VIDEO\n* `NATIVE` - NATIVE\n* `AUDIO` - AUDIO"}},"required":["line_item_type"]},"TargetingModule":{"type":"object","description":"Serializer for validating targeting modules in forecast requests.\nIncludes deal_id validation using the same logic as DealRefListViewSet.","properties":{"all":{"type":"object","additionalProperties":{}},"any":{"type":"object","additionalProperties":{}},"none":{"type":"object","additionalProperties":{}}}},"Warnings":{"type":"object","properties":{"warnings":{"type":"object","additionalProperties":{},"description":"Field-level warnings, keyed by field name."},"non_field_warnings":{"type":"array","items":{"type":"string"},"description":"Warnings not tied to a specific field."}},"required":["non_field_warnings","warnings"]}},"securitySchemes":{"nestBasicAuth":{"type":"http","scheme":"basic","description":"Form-based Basic Authentication"},"nestSessionAuth":{"type":"http","scheme":"basic","description":"Form-based Basic Authentication"}}},"x-explorer-enabled":false,"x-samples-languages":["curl","node","ruby","javascript","python","php","java"],"servers":[{"url":"https://{buzz_key}.api.beeswax.com/rest/v2","variables":{"buzz_key":{"default":"stingersbx","description":"Unique customer ID assigned by the Beeswax"}}}]}