openapi: 3.1.0 info: title: VideoAmp Public API version: '2026-07-31' summary: Audience, planning, measurement and data-collaboration APIs for VideoAmp's cross-platform media measurement platform. description: |- The VideoAmp Public API powers audience building, media planning and optimization, ad and content measurement, inventory and rate cards, data streams, and cross-organization data sharing. **Provenance.** VideoAmp does not publish an anonymous OpenAPI document: `https://docs.videoamp.dev` redirects to Auth0 and the CLI's `--oas` flag fetches the specification from the authenticated API. This document was derived by API Evangelist from the operation table that VideoAmp itself ships inside the official `videoamp` CLI binary (GitHub release `v0.148.32`, api_edition `2026-07-31`) — every path, method, operationId, summary, description and parameter here is reproduced verbatim from that binary's own `--help` output. Request and response body schemas are not exposed on any anonymous surface and have deliberately been left unspecified rather than invented. **Not an official VideoAmp artifact.** See https://docs.videoamp.dev for the authoritative specification. contact: name: VideoAmp Support email: support@videoamp.com url: https://help.videoamp.dev termsOfService: https://videoamp.com/terms-of-use/ servers: - url: https://api.videoamp.dev description: Production. The VideoAmp CLI also references `staging` and `preprod` environments (api.staging.videoamp.dev, api.preprod.videoamp.dev), but neither resolves publicly (DNS NXDOMAIN as of 2026-08-02), so they are not listed as callable servers. security: - videoampOAuth: [] tags: - name: adMeasurements description: adMeasurements operations. - name: audiences description: audiences operations. - name: campaigns description: campaigns operations. - name: consents description: consents operations. - name: content description: content operations. - name: currency-of-record description: currency-of-record operations. - name: dataStreamTypes description: dataStreamTypes operations. - name: dataStreams description: dataStreams operations. - name: inventories description: inventories operations. - name: library description: library operations. - name: me description: me operations. - name: plans description: plans operations. - name: reports description: reports operations. - name: shares description: shares operations. paths: /external/v1/content/episodes: get: operationId: episode_list summary: List Episodes tags: - content description: Retrieve a filtered list of TV episodes with associated metadata. Use this endpoint to discover available episode inventory for content measurement campaigns, build episode selection interfaces, or perform bulk analysis of programming content. Supports filtering by network, program, and currency of record to match specific measurement requirements. parameters: - name: currencyOfRecord in: query required: false schema: type: integer description: Viewershiptype id as a filter. - name: episodeIds in: query required: false schema: type: array items: type: string description: A list of episodes to filter the results to. - name: networkId in: query required: false schema: type: integer description: To filter programs to those that are aired on a given network. - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. The maximum value is 1000; values above 1000 will be coerced to 1000. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: programId in: query required: false schema: type: integer description: To filter episodes to those that belong to a particular series. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: episode_list /external/v1/content/episodes/{episodeId}: get: operationId: episode_get summary: Get Episode tags: - content description: Retrieve detailed metadata for a specific TV episode by ID. Use this endpoint to access episode-specific information needed for content measurement, advertising campaign planning, or media inventory analysis. Essential for workflows that require episode-level granularity in viewership reporting. parameters: - name: episodeId in: path required: true schema: type: string description: The unique identifier of the Episode. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: episode_get /external/v1/content/media-groups: get: operationId: media_group_list summary: List Network MediaGroups tags: - content description: Return a list of network media groups with metadata available to query networks. parameters: - name: name in: query required: false schema: type: array items: type: string description: A search string for matching against the network media group name. - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: media_group_list /external/v1/content/metric-type-compatibility-matrix: get: operationId: content_metric_compatibility_get summary: List Metric and Dimension Types tags: - content description: Return the compatibility matrix of supported metrics and dimensions for content measurement requests. Use this endpoint before creating content metrics to validate your measurement configuration and discover available combinations. Essential for building dynamic UI forms or validating programmatic measurement requests. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: content_metric_compatibility_get /external/v1/content/metrics: post: operationId: content_metric_create summary: Create Metrics tags: - content description: Initiates an asynchronous content metric request that returns a universally unique identifier (uuid). The Get Content Metrics Request endpoint can be polled to obtain the status of the async request and, once complete, the output location in the client's configured S3 bucket. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp content_metric_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: content_metric_create /external/v1/content/metrics/{id}: get: operationId: content_metric_get summary: Get Metrics tags: - content description: Given a valid content metrics uuid, returns the status of the request and, if complete, the s3 location of the output CSV file. parameters: - name: id in: path required: true schema: type: string responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: content_metric_get /external/v1/content/networks: get: operationId: network_list summary: List Networks tags: - content description: Returns a list of networks with metadata available for use. parameters: - name: currencyOfRecord in: query required: false schema: type: integer description: Viewershiptype id as a filter. - name: mediaGroupName in: query required: false schema: type: array items: type: string description: A Media group name to use as filter. - name: name in: query required: false schema: type: array items: type: string description: Search strings for matching against the primary name of the underlying object. This is a case insensitive simple text search using fuzzy matching logic. - name: networkIds in: query required: false schema: type: array items: type: string description: A list of network ids to filter the results to, if its empty return all the networks. - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. The maximum value is 1000; values above 1000 will be coerced to 1000. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: network_list /external/v1/content/networks/{id}: get: operationId: network_get summary: Get Network tags: - content description: Returns the network details provided an id. parameters: - name: id in: path required: true schema: type: string responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: network_get /external/v1/content/programs: get: operationId: program_list summary: List Programs tags: - content description: Returns a list of programs with metadata available for use. parameters: - name: currencyOfRecord in: query required: false schema: type: integer description: Viewershiptype id as a filter. - name: name in: query required: false schema: type: array items: type: string description: A search string for matching against the primary name of the underlying object. This is a case insensitive simple text search using fuzzy matching logic on NAME column. - name: networkId in: query required: false schema: type: integer description: Network to filter to. - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. The maximum value is 1000; values above 1000 will be coerced to 1000. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: programIds in: query required: false schema: type: array items: type: string description: A list of programs to filter against. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: program_list /external/v1/content/programs/{programId}: get: operationId: program_get summary: Get Program tags: - content description: Returns the program details provided an id. parameters: - name: programId in: path required: true schema: type: string responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: program_get /external/v1/currency-of-record: get: operationId: cor_list summary: List Currency of Records tags: - currency-of-record description: |- ### What Retrieves a paginated list of available Currency of Records (CoRs) with filtering and search capabilities. Each CoR represents a specific measurement methodology tied to a broadcast year, defining the panel composition, data collection standards, and measurement currency used for audience guarantees. ### Why Currency of Records are foundational to VideoAmp's measurement system, ensuring consistent methodology across analyses within the same broadcast year. Different broadcast years use different panels, measurement techniques, and data sources, making CoR selection critical for accurate comparisons and contractual guarantees. This endpoint enables discovery of valid CoRs before creating Measurement requests, preventing configuration errors. ### When Call this endpoint when you need to: - Discover available measurement methodologies for your account before creating Measurement requests - Validate CoR values for API requests that require `currency_of_record` parameters - Understand broadcast year boundaries and data availability windows for campaign planning - Filter CoRs by reporting scope (Ad Measurement vs Content Measurement requests) for specific use cases - Check actualized data dates to determine when final broadcast metrics are available ### How Requires bearer token authentication with appropriate scope. Supports optional filtering by `name` (substring search), `currencyOfRecord` IDs (exact match), and `reportingScope` values (case-insensitive exact match). Pagination uses `pageSize` (max 1000, default 50) and opaque `pageToken` for cursor-based navigation. Response includes broadcast year boundaries, CoR IDs, and actualized data dates for both linear and digital mediums. Typical response time under 200ms for unfiltered queries. Related endpoints: - `POST /v2beta/adMeasurements` - Uses `currency_of_record` from this endpoint - `GET /v2beta/adMeasurements/{id}` - Returns Measurement requests using specific CoR methodology parameters: - name: currencyOfRecord in: query required: false schema: type: integer description: Optional filter to retrieve specific Currency of Records by their numeric IDs. Accepts an array of int32 values representing CoR identifiers, with exact match filtering. Common CoR ID values include 23 (broadcast year 2023-24), 25 (2024-25), and 26 (2025-26), though available IDs vary by account permissions and product configuration. This filter uses OR logic, returning CoRs that match any of the provided IDs. Use this parameter when you already know specific CoR IDs from previous API calls or configuration data and want to retrieve their detailed metadata (broadcast year boundaries, actualized dates, reporting scopes). Can be combined with `name` and `reportingScope` filters for more refined queries. Maximum of 100 IDs supported per request. Leave empty or omit to retrieve all CoRs without ID filtering. If an invalid or unauthorized CoR ID is provided, it is silently ignored rather than causing an error, resulting in fewer results than IDs requested. - name: name in: query required: false schema: type: string description: Optional filter for searching CoR names using case-insensitive substring-based matching. Accepts multiple search strings that are matched against the primary name field of each Currency of Record. The substring matching logic uses SQL ILIKE with wildcard patterns, so partial matches are supported (e.g., searching for '24-25' will match 'Currency 2024-25'). Each string in the array is treated as an independent search term with OR logic, meaning results include CoRs matching any of the provided name patterns. Common use case is searching by broadcast year identifiers like '23', '24', '25' to quickly find specific currency years. Leave empty or omit entirely to retrieve all available CoRs without name filtering. - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. Controls the size of the `data` array in the response and impacts both API performance and client memory usage. Accepted values range from 1 to 1000, with values exceeding 1000 automatically coerced down to the maximum. Default is 50 when omitted, which provides good balance for most interactive use cases. Smaller page sizes (10-25) are recommended for UI pagination with progressive loading, while larger sizes (100-1000) are more efficient for batch processing workflows and data exports that need to retrieve all CoRs with minimal API calls. The total number of available results is returned in the `paging.totalResults` field, allowing clients to calculate the number of pages needed. When processing all results, use maximum `pageSize` (1000) combined with `pageToken` navigation to minimize round trips while respecting rate limits. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: reportingScope in: query required: false schema: type: array items: type: string description: Optional filter to retrieve Currency of Records by their reporting scope classification, which determines what types of Measurement requests can use each CoR. Accepts an array of scope strings with case-insensitive exact matching (no partial matches or fuzzy logic). Valid values are 'AD_MEASUREMENT' and 'CONTENT_MEASUREMENT'. Some CoRs support multiple scopes and will be returned if any of their scopes match any filter value provided (OR logic). Use this filter when building scope-specific workflows that require filtering CoRs by their intended measurement use case. For example, Ad Measurement workflows should filter by 'AD_MEASUREMENT' to exclude content-only CoRs. Leave empty or omit to retrieve all CoRs regardless of reporting scope. Invalid scope values are silently ignored rather than causing errors. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: cor_list /v1/audiences: post: operationId: audience_create_v1 summary: Create Audience tags: - audiences description: This endpoint triggers the create audience process. To use the creation endpoint, the current holding company must be onboarded, please contact Videoamp support for more information. To see a full list of response messages please view our [help page](https://help.videoamp.dev/en/articles/9415579-audience-service-error-codes-messages). parameters: - name: validateOnly in: query required: false schema: type: string description: This field validates the required fields and the requesting user's permissions. An audience resource will not be created when this field is set to true. This field is optional and defaults to `false`. (default true) requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp audience_create_v1 --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: audience_create_v1 get: operationId: audience_list_v1 summary: List Audiences tags: - audiences description: This endpoint returns a list of the audiences accessible to the user. The list can be filtered and sorted. To see a full list of response messages please view our [help page](https://help.videoamp.dev/en/articles/9415579-audience-service-error-codes-messages). parameters: - name: audienceIds in: query required: false schema: type: string description: Query param audience_ids returns only matching audiences for given valid audience legacy ids. The values in this field must be valid numeric ids. - name: audienceUuids in: query required: false schema: type: string description: Query param audience_uuids returns only matching audiences for given valid audience uuids. The values in this field must be valid UUIDs. - name: cadences in: query required: false schema: type: string description: 'Query param cadences returns only the audiences with refresh cadence in the provided list. Accepted Values: - `one_time` - `weekly` - `monthly` - `quarterly`' - name: currencyOfRecord in: query required: false schema: type: string description: Query param 'currencyOfRecord' refers to the data and methodologies used for VideoAmp currency guarantees within a given broadcast year. If not provided, 'demo' audiences default to VideoAmp's latest currency of record. 'advance' audiences from all currency of record will be returned. - name: filteredAgencyAdvertiserIds in: query required: false schema: type: string description: Query param filteredAgencyAdvertiserIds returns only the audiences these agency advertisers have access to. - name: filteredAgencyIds in: query required: false schema: type: string description: Query param filteredAgencyIds returns only the audiences these agencies have access to. - name: level in: query required: false schema: type: string description: 'Query param ''level'' filters the audiences by level. This filter only applies to demographic audiences (i.e. ''type=demo'') as advanced audiences are all household level. If unset, the default is to return all audiences. - LEVEL_UNSPECIFIED: Unspecified level - HOUSEHOLD: Household based audience - PERSON: Person based audience' - name: orderBy in: query required: false schema: type: string description: 'Query param ''orderBy'' specifies the order of the results. This field is case sensitive. Accepted Values: - ''desc(createdAt)'' - (Default) - ''asc(createdAt)'' - ''desc(name)'' - ''asc(name)''' - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: query in: query required: false schema: type: string description: Query param 'query' filters the audiences by name, description, id or uuid. This field is case insensitive. - name: status in: query required: false schema: type: string description: 'Query param ''status'' filters the audiences by status. This field is case insensitive. Accepted Values: - ''ready'' - Ready to use - ''failed'' - Failed to create Audience - ''processing'' - Audience is being created - ''draft'' - Audience to be created' - name: type in: query required: false schema: type: string description: 'Query param ''type'' filters the audiences by type. Accepted Values: - ''advanced'' - Returns the combination of ''owned'' and ''shared'' audiences - ''demo'' - Returns VideoAmp''s global demographic audiences - ''shared'' - Returns audiences that are shared to this organization - ''owned'' - Returns only audiences that are created within this organization - ''exposure'' - Returns exposure audiences - ''content'' - Returns content audiences - ''user_provided'' - Returns user provided audiences - ''composite'' - Returns composite audiences If no type filter is specified, all audiences will be returned.' - name: useCases in: query required: false schema: type: string description: 'Query param useCases filters the audiences by use cases. If multiple use cases are provided, the result will contain audiences with at least one of the provided use cases. This field is case insensitive. Accepted Values: - `measurement` - Returns audiences that can be used for ad measurement - `activation` - Returns audiences that can be used for activation - `content` - Returns audiences that can be used for content measurement' - name: year in: query required: false schema: type: string description: 'Query param ''year'' filters the audiences by broadcast year. This filter retrieves demographic audiences with metrics for the given broadcast year. Accepted Values: - ''2020'' - ''2099''' responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: audience_list_v1 /v1/audiences/status: get: operationId: audience_status_list summary: List Statuses tags: - audiences description: This endpoint returns a list of audience creation statuses. The list can be filtered and sorted. To see a full list of response messages please view our [help page](https://help.videoamp.dev/en/articles/9415579-audience-service-error-codes-messages). parameters: - name: orderBy in: query required: false schema: type: string description: 'Query param ''orderBy'' specifies the order of the results. This field is case sensitive. Accepted Values: - ''desc(createdAt)'' - (Default) - ''asc(createdAt)'' - ''desc(name)'' - ''asc(name)''' - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: requestId in: query required: false schema: type: string description: Query param requestIds filters the audiences by request id. This field is synonymous with the Audience's UUID. - name: status in: query required: false schema: type: string description: 'Query param ''status'' filters the audiences by status. This field is case insensitive. Accepted Values: - ''ready'' - Ready to use - ''failed'' - Failed to create Audience - ''processing'' - Audience is being created - ''draft'' - Audience to be created' responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: audience_status_list /v1/audiences/{audienceId}/exports: post: operationId: audience_export_create summary: Create Export tags: - audiences description: |- Creates a new export of the audience to a downstream destination. **Why**: Push audience members to a destination. Each export is owned by the calling organization and runs on a one-time or recurring cadence. **When**: Returns `201` with the created `Export` (`status=QUEUED`). The audience may be in any status — the export materializes once its data is available. Check `audience_export_get` to monitor progress until `status` reaches `READY` or `FAILED`. **Discovering valid export types**: Not every type is valid for every audience. The v2 `Audience` exposes `available_export_types`, listing the types eligible for that audience (based on classification, use cases, ownership, and onboarding). **Call `audience_get` (or `audience_list`) v2 first** and pick `exportType` from that list. Empty for SYSTEM audiences and audiences with no eligible use cases (cannot be exported). **Prerequisites**: - Calling organization onboarded for the chosen `exportType`. Onboarding populates `available_export_types`; contact VideoAmp Support if empty for an expected destination. - For `LIVERAMP`: submit a [HelpDesk Ticket](https://help.videoamp.dev/en/articles/10609936-submit-a-help-desk-ticket) with the audience name and your LiveRamp destination account ID/name — the API call alone does not finalize the sync. **How**: `audienceId` accepts the audience's UUID or legacy integer (no `-` wildcard — a concrete audience is required). Request body is the `Export` object; see its `export` field for per-type required sub-fields and the `exportType`↔`*ExportTypeSpecification` matching rule. **Pre-flight validation**: Set `validate_only=true` to verify request shape and permissions without creating a resource. On success the response is the validated `Export`; errors return `400` with `field_violations`. **Scope**: The created export is owned by the calling organization; `owner.type` must be `ORGANIZATION` (or `HOLDING_COMPANY`) and `owner.id` must be the calling organization's id. parameters: - name: audienceId in: path required: true schema: type: string description: 'Audience identifier the export will be created against. **Accepted formats** (all map to the same audience resource): - UUID (string) — **use this**. Matches ''audience.audienceUUId'' (v1) or ''audience.id'' (v2). - Legacy integer (string-encoded) — backwards compatibility only. Matches ''audience.audienceId'' (v1) or ''audience.legacy_id'' (v2). Use UUID for new integrations. Returns ''404'' if the audience does not exist or is not accessible to the calling organization.' - name: validateOnly in: query required: false schema: type: string description: This field validates the required fields and the requesting user's permissions. An export resource will not be created when this field is set to true. This field is optional and defaults to `false`. (default true) requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp audience_export_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: audience_export_create get: operationId: audience_export_list summary: List Exports tags: - audiences description: |- Returns the paginated list of exports configured for the given audience. **Why**: Discover all delivery destinations and runs for an audience. Use this endpoint to monitor recurring export pipelines, audit which destinations have received the audience, and confirm whether a previous export reached `READY` before triggering downstream activation. **When**: Call after `POST /v1/audiences/{audienceId}/exports` to poll the per-export `status` until it reaches a terminal state (`READY` or `FAILED`). Also use to enumerate existing exports before creating a new one to avoid duplicates. When the specific export id is already known, use `GET /v1/audiences/{audienceId}/exports/{id}` instead of paging through this list. **How**: The `audienceId` path segment accepts a UUID, a legacy integer, or `-` (wildcard for all audiences in the caller's organization). Page with `pageSize` (max `3000`, default `20`) and `pageToken`. Sort with the `sorts` query parameter using `+field` / `-field` syntax. **Filtering by status, exportType, or other attributes is not currently supported** — perform any post-filtering client-side on the returned `results`. **Scope**: Results are automatically scoped to the caller's organization; only exports owned by your organization are returned. There is no parameter to widen this scope. **Status lifecycle**: Each returned `Export.status` advances `QUEUED` → `PROCESSING` → `READY` or `FAILED`. `READY` and `FAILED` are terminal; `QUEUED` and `PROCESSING` are non-terminal and indicate work is ongoing. Do not treat `PROCESSING` as a terminal state. parameters: - name: audienceId in: path required: true schema: type: string description: 'Audience identifier whose exports to list. **Accepted formats** (all map to the same audience resource): - UUID (string) — **use this**. Matches ''audience.audienceUUId'' (v1) or ''audience.id'' (v2). - Legacy integer (string-encoded) — backwards compatibility only. Matches ''audience.audienceId'' (v1) or ''audience.legacy_id'' (v2). Use UUID for new integrations. - ''-'' (single dash) — wildcard. Returns exports across all audiences accessible to the calling organization. Use to enumerate exports without first knowing the audience id. An unknown audience id returns ''200'' with an empty ''results'' array (not ''404''). Malformed values that are neither UUID, integer, nor ''-'' return ''400'' with a ''field_violations'' entry.' - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. Defaults to `20` when omitted. Maximum allowed value is `3000` — values above this return `400` with a `page_size` field violation. Pair with `pageToken` to iterate through large result sets. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: sorts in: query required: false schema: type: string description: 'Sort order for the result list. Specify each sort key as with **no space** between them — e.g., `-created_at`. Whitespace is stripped before parsing, so `+ created_at` and `+created_at` are treated identically. **Field names are case sensitive.** Default when omitted: `-created_at` (newest first). **Sortable fields:** - `created_at` — when the export was created - `audience_id` — audience integer id - `export_type` — destination type (`CUSTOM_S3`, `LIVERAMP`, etc.) - `status` — execution status **Direction prefixes:** - `+` ascending (also the default if no prefix is supplied) - `-` descending **Multiple keys:** repeat the query parameter to compose ordering, e.g. `?sorts=-status&sorts=+created_at`. Keys are applied in the order received. **Note:** unlike v2 endpoints (which use `orderBy=created_at desc` syntax), this endpoint uses prefix notation. Do not mix the two.' responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: audience_export_list /v1/audiences/{audienceId}/exports/{id}: get: operationId: audience_export_get summary: Get Export tags: - audiences description: |- Returns the full details of a single export, identified by its UUID and audience. **Why**: Retrieve the current state of one export — its execution `status`, the destination-specific spec object, and any per-destination metadata populated once the run reaches `READY`. **When**: This is the canonical endpoint for **checking export status**. After `audience_export_create` returns the new export's `id`, check this endpoint to monitor progress until `status` is `READY` or `FAILED` (both terminal). For recurring exports, call this between scheduled runs to inspect the most recent delivery's metadata. Use this over `audience_export_list` when the specific export `id` is already known. **How**: Pass the export `id` (UUID) and `audienceId` (UUID, legacy integer, or `-` wildcard for "any audience accessible based on the caller's organization context"). When `audienceId` is concrete, it must reference the same audience that owns the export — a mismatch returns `404`. **Scope**: Returns only exports created by the calling organization. **Status lifecycle**: `QUEUED` → `PROCESSING` → `READY` or `FAILED`. `READY` and `FAILED` are terminal for one-time exports; recurring exports cycle back to `QUEUED` on each scheduled run. parameters: - name: audienceId in: path required: true schema: type: string description: 'Audience identifier of the export to retrieve. **Accepted formats**: - UUID (string) — **use this**. Matches ''audience.audienceUUId'' (v1) or ''audience.id'' (v2). - Legacy integer (string-encoded) — backwards compatibility only. Matches ''audience.audienceId'' (v1) or ''audience.legacy_id'' (v2). Use UUID for new integrations. - ''-'' (single dash) — wildcard for "any audience in the calling organization". Useful when the export ''id'' is known but the audience is not. The server enforces calling-organization scope regardless of which form you use. When a concrete identifier is supplied, it must reference the same audience that owns the export ''id''; mismatch returns ''404''.' - name: id in: path required: true schema: type: string description: The export's unique identifier (UUID). Obtain from the response of 'audience_export_create' (the 'id' field) or from a previous 'audience_export_list' page. The supplied 'id' must belong to the audience referenced by 'audienceId'. If the export exists but its audience differs, the endpoint returns '404' (the relationship is enforced server-side). Malformed values return '400'. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: audience_export_get /v1/audiences/{id}: get: operationId: audience_get_v1 summary: Get Audience tags: - audiences description: This endpoint returns the requested audience and it's details. To see a full list of response messages please view our [help page](https://help.videoamp.dev/en/articles/9415579-audience-service-error-codes-messages). parameters: - name: id in: path required: true schema: type: string description: The Audience's UUID or id (int64). responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: audience_get_v1 /v1/audiences:batchGet: get: operationId: audience_batch_get summary: Batch Get Audiences tags: - audiences description: This endpoint returns the requested audiences and their details. To see a full list of response messages please view our [help page](https://help.videoamp.dev/en/articles/9415579-audience-service-error-codes-messages). parameters: - name: ids in: query required: true schema: type: array items: type: string description: The UUIDs or legacy integer Ids of the audiences to retrieve. Must be all UUIDs or all legacy integer Ids. A maximum of 100 audiences can be retrieved in a batch. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: audience_batch_get /v1/audiences:lookUpIdTypes: get: operationId: audience_id_types_lookup summary: Look Up Id Types tags: - audiences description: |- Returns all identifier types supported for audience ingestion and export within the authenticated organization. Each entry includes the type name, description, and ingestible/exportable flags. ### Why Organizations are provisioned with a specific set of ID types based on their data partnerships. This is the authoritative reference for valid types in your org — preventing failures from passing unsupported values to audience creation or export. ### When Call this endpoint when you need to: - Populate a UI dropdown for ID type selection - Validate ID type strings client-side before submission - Determine which types support export before triggering an export job **Do NOT use:** Before every audience creation or export — cache the response instead. **Next Steps:** Cache the response. Use `name` as the `type` value in `DataSources` for `POST /v2/audiences` (recommended) or `POST /v1/audiences`. Filter by `ingestible` or `exportable` flags for the relevant operation. ### How No parameters required. Response is scoped to the authenticated organization. This list changes infrequently — cache for session duration. No endpoint-specific rate limits beyond platform defaults. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: audience_id_types_lookup /v1/consents: get: operationId: consent_list summary: List Consents tags: - consents description: |- ### What Returns a paginated list of consent records where recipients have authorized your organization to share resources with them. Each consent contains recipient identity, status, organization names, and optionally the recipient's organizational hierarchy path. ### Why Enables discovery of which recipients have consented to receive shared data from your organization. Essential for pre-share validation (verifying consent exists before creating shares), building consent management dashboards, and searching for specific partner organizations by name or type. ### When - Verify consent exists before calling POST /v1/shares or POST /v2/shares to create new shares - Build partner management UIs displaying all consenting recipients - Search for specific recipients by name using q=recipient_name filters - Filter recipients by organizational type using q=recipient_kind filters Use POST /v1/shares to create shares with consenting recipients. Use GET /v1/shares to view existing shares. ### How Requires valid JWT authentication. Results are automatically filtered to show only consents where your organization is the approved sharer. Use pageSize and pageToken for pagination. Use q parameter to filter by recipient_kind (eq, in) or recipient_name (startswith, endswith, contains). parameters: - name: fetchRecipientAncestorPath in: query required: false schema: type: boolean description: When true, populates the recipient_ancestor_path field in each consent showing the recipient's full position in the organizational hierarchy (e.g., 'Organization > Ad Agency > Advertiser'). Useful for consent dashboards that need to display organizational context. May increase response time for large result sets - omit if hierarchy information is not needed. (default true) - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: q in: query required: false schema: type: array items: type: string description: 'Advanced query filter for attribute-based filtering. Supported attributes: - **recipient_kind**: Filter by recipient type. Operators: eq, in. Values: ORGANIZATION, ADVERTISER, AD_AGENCY, BRAND, SUB_BRAND, PRODUCT. - **recipient_name**: Filter by recipient organization name. Operators: startswith, endswith, contains. Multiple q parameters are AND''d by default. Use OR keyword between conditions for OR logic. Examples: - ?q=recipient_kind eq ADVERTISER - ?q=recipient_kind in ADVERTISER,AD_AGENCY - ?q=recipient_name startswith Acme - ?q=recipient_name contains Media OR recipient_kind eq AD_AGENCY' responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: consent_list /v1/library/conversionDataProviderOptionsSearch: post: operationId: datasource_conversion_provider_search summary: Search Conversion Data Providers tags: - library description: |- Searches for a list of available Conversion Data Providers for a given agency advertiser. The response includes details such as the provider's value and label. Please view our [help page](https://help.videoamp.dev/en/articles/11429353-datasource-options) for more information on how datasource options can be used. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp datasource_conversion_provider_search --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: datasource_conversion_provider_search /v1/library/conversionGroups: post: operationId: conversion_group_create summary: Create Conversion Group tags: - library description: |- Creates a new Conversion Group using the provided details. A valid `data_provider_id` must be specified. The `data_provider_id` can be retrieved using the [`Search Conversion Data Providers`](/#tag/datasource-options-service/POST/v1/library/conversionDataProviderOptionsSearch) endpoint. The response returns the details of the newly created Conversion Group, including its unique identifier, metadata, and associated datasources. Please view our [help page](https://help.videoamp.dev/en/articles/11429351-conversion-groups) for more information on how conversion groups can be used. parameters: - name: validateOnly in: query required: false schema: type: boolean description: Optional. When true, performs all validation without persisting the resource. Returns the resource with defaults applied on success. (default true) requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp conversion_group_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: conversion_group_create get: operationId: conversion_group_list summary: List Conversion Groups tags: - library description: |- ### What Retrieves paginated Conversion Groups configured within your organization. Returns group metadata, datasource configurations, and conversion definitions. ### Why Conversion Groups are required for creating outcomes Measurement reports (ADVANCED_RF_OUTCOMES, TOPLINE_LINEAR_OUTCOMES, ADVANCED_RF_OUTCOMES_SUPPLEMENTAL). Use this endpoint to discover available Conversion Groups before creating attribution analysis reports. ### When - Discover Conversion Groups before creating outcomes Measurement reports - Search groups by advertiser, date range, or data provider - Audit conversion tracking configurations - Bulk fetch specific groups by UUID ### How Filter by `advertiserId`, `startDate`/`endDate`, `search`, `includeDataProviderId`/`excludeDataProviderId`, `currencyOfRecord`, `dataLatency`. Use `ids` for bulk fetch. Use `includeDeleted` for soft-deleted groups. ### Related Endpoints - `GET /v1/library/conversionGroups/{id}` - Retrieve specific group - `POST /v1/library/conversionGroups` - Create new group - `DELETE /v1/library/conversionGroups/{id}` - Delete group - `POST /v2beta/adMeasurements` - Create outcomes report See [help page](https://help.videoamp.dev/en/articles/11429351-conversion-groups) for more information. parameters: - name: agencyAdvertiserId in: query required: false schema: type: string description: '**Deprecated** Optional. Ignored if advertiserId is provided. Supports multiple values via repeated query parameters.' - name: currencyOfRecord in: query required: false schema: type: string description: Filter by currency of record identifier. Must be combined with 'data_latency' filter. Returns groups with matching value or no currency_of_record set. - name: dataLatency in: query required: false schema: type: string description: 'Filter by data latency. Required when using ''currency_of_record'' filter. - DATA_LATENCY_UNSPECIFIED: No selection; Default value. - FINAL: Fully reconciled data with complete accuracy. Available 2-3 weeks after broadcast. **DSGs:** Valid when reporting_scope=AD_MEASUREMENT with KANTAR_COMMINGLE or NATIONAL_LINEAR_AND_BROADCAST_CABLE datasources; or reporting_scope=CONTENT_MEASUREMENT. **CGs:** Required when data_provider_id=linear_tune_in; not valid otherwise. - PRELIMINARY: Fast-processed data, 3-4 days after broadcast, subject to revisions. **DSGs:** Valid when reporting_scope=CONTENT_MEASUREMENT and currency_of_record supports it. **CGs:** Not valid. - NEXT_NEXT_DAY: Near real-time data, ~2 days after broadcast. Volatile. **DSGs:** Valid when reporting_scope=CONTENT_MEASUREMENT and currency_of_record supports it. **CGs:** Not valid.' - name: endDate in: query required: false schema: type: string description: Filter Conversion Groups by their configured date range end. Format YYYY-MM-DD (ISO 8601). When provided, returns groups where 'filter_start_date' is on or before this date, enabling discovery of groups with conversion data coverage overlapping or before this date. Can be used independently or combined with 'start_date' for complete date range filtering. Useful when creating reports for specific campaign periods to ensure returned groups have data coverage for the analysis timeframe. Validation error occurs if date format is invalid. - name: excludeDataProviderId in: query required: false schema: type: array items: type: string description: 'Excludes Conversion Groups configured with the specified data provider IDs. Supports multiple values via repeated query parameters. In addition to individual provider IDs, accepts predefined group keys that represent a set of related providers. Available group keys: streaming_tune_in (paramount_streamlog, nbcu_streamlog, tubi_streamlog). If same provider appears in both include_data_provider_id and this field, exclusion takes precedence. Use conversionDataProviderOptionsSearch endpoint to discover valid individual provider IDs.' - name: ids in: query required: false schema: type: array items: type: string description: Bulk fetch specific Conversion Groups by UUID identifiers. Format is UUID v4 for each ID. Use this for efficient batch retrieval when specific group IDs are known, avoiding filtering through large result sets. Common use case is retrieving multiple groups referenced in existing report configurations or fetching groups from saved preferences. Maximum recommended is 50 IDs per request. A user needs to have access to the IDs included for them to appear in the results. - name: includeDataProviderId in: query required: false schema: type: array items: type: string description: 'Includes only Conversion Groups configured with data provider IDs in the specified list. Supports multiple values via repeated query parameters with OR logic. In addition to individual provider IDs, accepts predefined group keys that represent a set of related providers. Available group keys: streaming_tune_in (paramount_streamlog, nbcu_streamlog, tubi_streamlog). If same provider appears in both this field and exclude_data_provider_id, exclusion takes precedence. Use conversionDataProviderOptionsSearch endpoint to discover valid individual provider IDs.' - name: includeDeleted in: query required: false schema: type: string description: Controls whether soft-deleted Conversion Groups appear in results. Default false returns only active non-deleted groups. Set to true to include deleted groups for auditing or historical reference. Deleted groups retain all configuration data and can be referenced in historical reports but cannot be used for new report creation. Useful for auditing, troubleshooting reports created before group deletion, or recovering configurations. Response includes deleted_at timestamp for each deleted group when true. Hard-deleted groups never appear regardless of this setting. (default true) - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. Defaults to 20 if not specified. Maximum allowed value is 200. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: search in: query required: false schema: type: string description: Free-text search query to filter Conversion Groups by 'display_name' field. Performs case-insensitive partial match against Conversion Group names. When omitted, no name filtering is applied and all groups matching other criteria are returned. When provided, only groups with names containing the search term as substring are included. Useful for quickly finding groups when partial name is known but not full name or ID. Search is not tokenized; entire search string is matched as phrase. Does not search other fields like 'description' or 'advertiser_name'. Combine with other filters like 'advertiserId' for precise results. - name: startDate in: query required: false schema: type: string description: Filter Conversion Groups by their configured date range start. Format YYYY-MM-DD (ISO 8601). When provided, returns groups where 'filter_end_date' is on or after this date, enabling discovery of groups with conversion data coverage overlapping or after this date. Can be used independently or combined with 'end_date' for complete date range filtering. Useful when creating reports for specific campaign periods to ensure returned groups have data coverage for the analysis timeframe. Validation error occurs if date format is invalid. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: conversion_group_list /v1/library/conversionGroups/{conversionGroupId}: delete: operationId: conversion_group_delete summary: Delete Conversion Group tags: - library description: |- Soft deletes a Conversion Group by its unique identifier (UUID). The resource can still be referenced by ID but will not be included in list results unless `include_deleted` is set to true. Please view our [help page](https://help.videoamp.dev/en/articles/11429351-conversion-groups) for more information on how conversion groups can be used. parameters: - name: conversionGroupId in: path required: true schema: type: string responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: conversion_group_delete get: operationId: conversion_group_get summary: Get Conversion Group tags: - library description: 'Retrieves complete details of a specific Conversion Group by UUID. Returns the full resource configuration including datasources with filters, lookback window settings, metadata, and timestamps. The response structure matches the format used when creating or listing Conversion Groups. Use `top_level_only=true` to retrieve metadata without datasource details for reduced response size. Use `include_deleted=true` to retrieve soft-deleted groups by ID. Do NOT use for: listing multiple groups (use GET /v1/library/conversionGroups with query parameters instead); creating new groups (use POST /v1/library/conversionGroups). Next Steps: After retrieval, use the `id` field to reference this group in subsequent API operations; examine `datasources` array to understand filter configuration; cache response client-side if displaying in UI to avoid repeated calls. Typical latency under 100ms; full datasource details (top_level_only=false, default) may add 50-100ms for groups with extensive filter configurations. See [help page](https://help.videoamp.dev/en/articles/11429351-conversion-groups) for more information on Conversion Groups.' parameters: - name: conversionGroupId in: path required: true schema: type: string description: Unique identifier for the Conversion Group in standard UUID v4 format without prefix. Immutable and system-assigned when created via POST /v1/library/conversionGroups. Obtain from list operations, GET responses, or Location header of creation. Fetches complete configuration including datasources, filters, lookback window, and metadata. Required for retrieval. Returns 404 if ID nonexistent or group deleted (unless include_deleted=true). Invalid UUID format returns 400 with field validation error. - name: includeDeleted in: query required: false schema: type: boolean description: Enables retrieval of soft-deleted groups by ID. Default false restricts to active groups; deleted IDs return 404. True allows soft-deleted retrieval for audit trails, historical analysis, restoration. Soft-deleted groups have deleted_at timestamp, excluded from lists unless requested. Used by support investigating attribution on campaigns with deleted groups or restoring configurations. Does not affect hard-deleted groups (permanently removed). (default true) - name: topLevelOnly in: query required: false schema: type: boolean description: Controls datasource inclusion in response. Default false returns complete configuration with datasources array (filters, values, labels). True retrieves only metadata (id, name, lookback window, timestamps), reducing response size 60-80% and latency 50-100ms for groups with extensive filters. Use true when datasource details are not needed. (default true) responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: conversion_group_get /v1/library/datasourceFilterNameOptionsSearch: post: operationId: datasource_filter_name_search summary: Search Datasource Filter Names tags: - library description: |- ### What Returns available filter names by advertiser (business unit) for a given datasource type for Datasource Group (DSG) or data provider for Conversion Group (CG). Each type or provider has specific set of filter names that must be fetched from this endpoint. ### Why Discovers which filters can be applied when building a DSG or CG. **Business Scenarios:** - Agent finds `network` and `daypart` filters for NATIONAL_LINEAR_BROADCAST_AND_CABLE - User is building a CG with data provider CIRCANA and calls this endpoint to find that `pixel_id` and then `campaign_id` are available to use. ### When Call after selecting a `datasource_type` from `POST /v1/library/datasourceTypeOptionsSearch` for a DSG. If building a CG, call after selecting a `data_provider_id` from `POST /v1/library/conversionDataProviderOptionsSearch`. **Important:** Supports iterative narrowing via `applied_filters`. Pass previously selected filters to see remaining filter names. **Do NOT use when:** - You already know the exact filter names for the datasource type - You need filter values (use `POST /v1/library/datasourceFilterValueOptionsSearch`) **Next Steps:** Select filter names, then call `POST /v1/library/datasourceFilterValueOptionsSearch` to get values for each. ### How **Iterative Discovery:** Call with type or provider + advertiser, select a filter name, get values via `datasourceFilterValueOptionsSearch`, call this endpoint again with `applied_filters`, repeat until done. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp datasource_filter_name_search --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: datasource_filter_name_search /v1/library/datasourceFilterValueOptionsSearch: post: operationId: datasource_filter_value_search summary: Search Datasource Filter Values tags: - library description: |- ### What Returns available filter values (e.g., pixel IDs, campaign IDs, network names) for a given datasource type and filter name. Supports text search via `search` and pagination via `page_size`/`page_token`. ### Why Discovers specific values available for a selected filter when building a Datasource Group (DSG) or Conversion Group (CG). **Business Scenarios:** - Agent retrieves pixel IDs for VA_PIXEL with `datasource_filter_name=pixel_id`, uses `search` to find a specific pixel - User browses network names for NATIONAL_LINEAR_BROADCAST_AND_CABLE, paginating through results ### When Call after selecting a filter name from `POST /v1/library/datasourceFilterNameOptionsSearch`. Pass the same `advertiser_id`, `datasource_type`, `data_provider_id` if for CG, `reporting_scope` if for DSG, and date range. **Important:** Returns paginated results (default 200/page). Use `search` for text filtering or `next_page_token` to iterate pages. If you have already selected values for other filters on this datasource, include them in `applied_filters` to narrow results. **Do NOT use when:** - You already know the exact filter values - You need filter names (use `POST /v1/library/datasourceFilterNameOptionsSearch`) - You need datasource types (use `POST /v1/library/datasourceTypeOptionsSearch`) **Next Steps:** Select values, then call `POST /v1/library/datasourceFilterNameOptionsSearch` with `applied_filters` to add more filters, or `POST /v1/library/datasourceGroups` to create the DSG, or `POST /v1/library/conversionGroups` to create the CG. ### How **Paginated Search:** Call with type + filter name + advertiser. Use `search` to text-filter, `page_token` to paginate, `applied_filters` to narrow results. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp datasource_filter_value_search --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: datasource_filter_value_search /v1/library/datasourceGroups: post: operationId: datasource_group_create summary: Create Datasource Group tags: - library description: |- Creates a new Datasource Group using the provided details. To retrieve the `datasource_type`, use the [`Search Datasource Type Options`](/#tag/datasource-options-service/POST/v1/library/datasourceTypeOptionsSearch) endpoint. To retrieve filters, use the [`Search Datasource Filter Names`](/#tag/datasource-options-service/POST/v1/library/datasourceFilterNameOptionsSearch) and [`Search Datasource Filter Values`](/#tag/datasource-options-service/POST/v1/library/datasourceFilterValueOptionsSearch) endpoints. The response includes the details of the newly created Datasource Group, including its unique identifier, metadata, and associated datasources. Please view our [help page](https://help.videoamp.dev/en/articles/11429358-datasource-groups-and-rules) for more information on how Datasource Groups and Datasource Group Rules are used. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp datasource_group_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: datasource_group_create get: operationId: datasource_group_list summary: List Datasource Groups tags: - library description: |- ### What Retrieves a paginated list of Datasource Groups configured within your organization. Groups define collections of Measurement Datasources with specific filters and date ranges. Response includes group metadata, Datasource configurations, ownership status, and associated advertiser information. ### Why Datasource Groups are foundational resources that define what data gets included in Measurement reports. Before creating any Measurement report, you must first identify available Datasource Groups that contain the appropriate vendor data, date ranges, and filters for your analysis needs. ### When Call this endpoint when you need to: - Discover available Datasource Groups before creating Measurement reports (required prerequisite) - Search Datasource Groups by advertiser, date range, medium, or ownership to filter available Datasources - Audit Datasource Group configurations including currency settings, data latency, and reporting scope ### How - Typical latency under 200ms for queries returning <100 results; pagination recommended for large result sets. Cache responses for up to 1 hour as Datasource Groups change infrequently. - Filter by `advertiserId`, `reportingScope` (`AD_MEASUREMENT` vs `CONTENT_MEASUREMENT`), `includeMedium`/`excludeMedium` (`LINEAR`, `DIGITAL`, `SOCIAL`), `ownership` (`OWNED` vs `SHARED`), and `dataLatency` (`FINAL`, `PRELIMINARY`). Use `search` parameter to find groups by name. ### Related Endpoints - `GET /v1/library/datasourceGroups/{id}` - Retrieve specific group details for a target ID - `GET /v1/library/datasourceGroups/{id}/rules` - Retrieve Measurement Rules available for a Datasource Group - `POST /v1/library/datasourceGroups` - Create a new group - `POST /v2beta/adMeasurements` - Create a Measurement report using specific Datasource Groups Please view our [help page](https://help.videoamp.dev/en/articles/11429358-datasource-groups-and-rules) for more information on how Datasource Groups and Datasource Group Rules are used. parameters: - name: advertiserId in: query required: false schema: type: array items: type: string description: Filter Datasource Groups by advertiser UUID. Supports multiple advertiser IDs via repeated query parameters to retrieve groups across multiple advertisers in a single request. Format is UUID v4. Returns only Datasource Groups associated with specified advertiser(s). Each advertiser ID must be valid UUID belonging to an advertiser your organization has access to, otherwise 403 Forbidden error occurs. - name: agencyAdvertiserId in: query required: false schema: type: string description: '**Deprecated** Optional. Ignored if advertiserId is provided. Supports multiple values via repeated query parameters.' - name: currencyOfRecord in: query required: false schema: type: string description: Filter by currency of record identifier. Must be combined with 'data_latency' filter. Returns groups with matching value or no currency_of_record set. - name: dataLatency in: query required: false schema: type: string description: 'Filter by data latency. Required when using ''currency_of_record'' filter. - DATA_LATENCY_UNSPECIFIED: No selection; Default value. - FINAL: Fully reconciled data with complete accuracy. Available 2-3 weeks after broadcast. **DSGs:** Valid when reporting_scope=AD_MEASUREMENT with KANTAR_COMMINGLE or NATIONAL_LINEAR_AND_BROADCAST_CABLE datasources; or reporting_scope=CONTENT_MEASUREMENT. **CGs:** Required when data_provider_id=linear_tune_in; not valid otherwise. - PRELIMINARY: Fast-processed data, 3-4 days after broadcast, subject to revisions. **DSGs:** Valid when reporting_scope=CONTENT_MEASUREMENT and currency_of_record supports it. **CGs:** Not valid. - NEXT_NEXT_DAY: Near real-time data, ~2 days after broadcast. Volatile. **DSGs:** Valid when reporting_scope=CONTENT_MEASUREMENT and currency_of_record supports it. **CGs:** Not valid.' - name: endDate in: query required: false schema: type: string description: 'Filter Datasource Groups using their configured ''filter_start_date'' and ''filter_end_date'' by verifying if ''[filter_start_date, filter_end_date]'' overlaps with ''[startDate, endDate]'', inclusively. Format ''YYYY-MM-DD'' (ISO 8601 date format). Used to find Datasource Groups that include data within a specific date range. Must be combined with ''startDate'' for complete date range filtering. Useful when creating reports for specific campaign periods - ensures returned groups have data coverage for your analysis timeframe. Validation error occurs if date format is invalid or if ''endDate'' is before ''startDate''. Example use case: Filter to groups covering Q1 2024 data by setting ''endDate'' to 2024-03-31.' - name: excludeDatasourceType in: query required: false schema: type: string description: Excludes Datasource Groups containing the specified datasource type(s). Groups with excluded types are not returned, even if they contain other types. If the same type appears in both includeDatasourceType and `excludeDatasourceType`, `excludeDatasourceType` takes precedence. Valid datasource type values can be retrieved via the `datasource_type_search` operation. - name: excludeMedium in: query required: false schema: type: string description: 'Excludes Datasource Groups containing the specified medium(s). Groups with excluded mediums are not returned, even if they contain other mediums. If the same medium appears in both includeMedium and `excludeMedium`, `excludeMedium` takes precedence. - LINEAR: Category for broadcast/cable TV ads. Example: `KANTAR_COMMINGLE`. - DIGITAL: Category for internet-delivered ads including from streaming, social media, websites and platforms like YouTube and Amazon. Example: `VA_PIXEL`. - SOCIAL: **Deprecated** Migrated to DIGITAL. - CROSS_SCREEN: **Rule Filters Only** Indicates a rule filter is applicable to multiple mediums.' - name: ids in: query required: false schema: type: array items: type: string description: Bulk fetch specific Datasource Groups by UUID identifiers. Optional parameter that accepts multiple Datasource Group IDs via repeated query parameters. Format is UUID v4 for each ID. Use this for efficient batch retrieval when you already know the specific group IDs you need - avoids filtering through large result sets. Common use case is retrieving multiple groups referenced in existing report configurations or fetching groups from saved user preferences. Maximum recommended is 50 IDs per request to avoid URL length limits and maintain reasonable response times. Each ID must be valid UUID - malformed IDs cause 400 Bad Request error. If an ID doesn't exist or user lacks access, it's silently omitted from results rather than causing error. - name: includeDatasourceType in: query required: false schema: type: string description: Includes Datasource Groups with at least one Datasource matching the specified datasource type(s). Groups may also contain other datasource types. Valid datasource type values can be retrieved via the datasource_type_search operation. - name: includeDeleted in: query required: false schema: type: string description: 'Controls whether soft-deleted Datasource Groups appear in results. Default false returns only active non-deleted groups. Set to `true` to include deleted groups in response for auditing purposes or historical data retrieval. Deleted groups retain all configuration data and can be referenced in historical reports but cannot be used for new report creation. Useful for compliance audits, data lineage tracking, or troubleshooting reports created before group deletion. When `true`, response includes `deleted_at` timestamp for each deleted group. Note: Hard-deleted groups (purged from system after retention period) never appear regardless of this setting. (default true)' - name: includeEventCounts in: query required: false schema: type: string description: Opt-in. When true, populates `event_count` on each returned Datasource Group with best-effort event counts. (default true) - name: includeMedium in: query required: false schema: type: string description: 'Includes Datasource Groups with at least one Datasource matching the specified medium(s). Groups may also contain other mediums. - LINEAR: Category for broadcast/cable TV ads. Example: KANTAR_COMMINGLE. - DIGITAL: Category for internet-delivered ads including from streaming, social media, websites and platforms like YouTube and Amazon. Example: `VA_PIXEL`. - SOCIAL: **Deprecated** Migrated to DIGITAL. - CROSS_SCREEN: **Rule Filters Only** Indicates a rule filter is applicable to multiple mediums.' - name: isCompetitor in: query required: false schema: type: string description: 'Filter Datasource Groups by competitive analysis designation. Default null returns all groups regardless of competitive type. Set to `true` to return only groups configured for competitive intelligence reporting (analyzing competitor advertising activity). Set to `false` to return only groups for owned brand measurement (analyzing your own advertising campaigns). Competitive groups typically contain broader market data across multiple brands while non-competitive groups focus on single advertiser measurement. This filter helps separate competitive intelligence workflows from standard campaign Measurement workflows. Note: This field filters the `report_type` attribute of associated Datasource configurations. (default true)' - name: ownership in: query required: false schema: type: string description: 'Filter Datasource Groups by data ownership and access rights. ''OWNED'' returns groups where all Datasources are fully owned by your organization with unrestricted usage rights for any reporting purpose. ''SHARED'' returns groups containing a mix of owned and shared Datasources where some data may have contractual usage restrictions or access limitations. ''OWNERSHIP_FILTER_UNSPECIFIED'' (default) returns all groups regardless of ownership status. - OWNERSHIP_FILTER_UNSPECIFIED: Default filter value that returns all Datasource Groups regardless of ownership status. - OWNED: Returns only Datasource Groups where all constituent Datasources are fully owned by your organization with unrestricted usage rights. - SHARED: Returns only Datasource Groups that contain a mix of owned and shared Datasources where some Datasources may have contractual usage restrictions or access limitations.' - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. Defaults to 20 if not specified. Maximum allowed value is 200. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: reportingScope in: query required: false schema: type: string description: 'Filter Datasource Groups by Measurement request type. Defaults to ''AD_MEASUREMENT'' if not specified. Available, valid scopes are: ''AD_MEASUREMENT'' and ''CONTENT_MEASUREMENT''. This filter is critical for ensuring compatibility between Datasource Groups and target report type: Ad Measurement reports require ''AD_MEASUREMENT'' groups while Content Measurement reports require ''CONTENT_MEASUREMENT'' groups. Groups are configured with specific reporting scope at creation time. Attempting to use groups with mismatched reporting scope in report creation will result in validation error. - REPORTING_SCOPE_UNSPECIFIED: Value when unspecified. Should not be used directly. - AD_MEASUREMENT: For Datasource Groups to be used for advertising campaign measurement and attribution analysis. Groups within this scope contain vendor measurement data focused on ad exposure, reach, frequency, and campaign effectiveness metrics. - CONTENT_MEASUREMENT: For Datasource Groups to be used for content viewership and audience measurement analysis. Groups within this scope contain viewing data focused on program ratings, audience composition, and content consumption patterns.' - name: search in: query required: false schema: type: string description: Free-text search query to filter Datasource Groups by 'name' field. Performs case-insensitive partial match against Datasource Group display names. When omitted, no name filtering is applied and all groups matching other criteria are returned. When provided, only groups with names containing the search term as a substring are included. Useful for quickly finding groups when you remember part of the name but not the full name or ID. Search is not tokenized - the entire search string is matched as a phrase. Does not search other fields like 'description' or 'advertiser_name'. Combine with other filters like 'advertiserId' for more precise results. - name: startDate in: query required: false schema: type: string description: 'Filter Datasource Groups using their configured ''filter_start_date'' and ''filter_end_date'' by verifying if ''[filter_start_date, filter_end_date]'' overlaps with ''[startDate, endDate]'', inclusively. Format ''YYYY-MM-DD'' (ISO 8601 date format). Used to find Datasource Groups that include data within a specific date range. Must be combined with ''endDate'' for complete date range filtering. Useful when creating reports for specific campaign periods - ensures returned groups have data coverage for your analysis timeframe. Validation error occurs if date format is invalid or if ''startDate'' is after ''endDate''. Example use case: Filter to groups covering Q1 2024 data by setting ''startDate'' to 2024-01-01.' responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: datasource_group_list /v1/library/datasourceGroups/{datasourceGroupId}: delete: operationId: datasource_group_delete summary: Delete Datasource Group tags: - library description: |- Soft deletes a Datasource Group by its unique identifier (UUID). The resource can still be referenced by ID but will not be included in list results unless `include_deleted` is set to true. Please view our [help page](https://help.videoamp.dev/en/articles/11429358-datasource-groups-and-rules) for more information on how Datasource Groups and Datasource Group Rules are used. parameters: - name: datasourceGroupId in: path required: true schema: type: string responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: datasource_group_delete get: operationId: datasource_group_get summary: Get Datasource Group tags: - library description: |- ### What Retrieves a complete Datasource Group configuration by UUID, including metadata, Datasources, and Rules count. ### Why Datasource Groups are essential for specifying vendor data, date ranges, and filters to constrain the context when building a Measurement report. ### When - Use this endpoint for validating configuration before report creation, displaying metadata in UI, auditing for compliance, troubleshooting errors, and checking soft-delete status. - Avoid using this endpoint for first-time discovery, bulk retrieval, or existence checks; use `List` for those cases instead. ### Next steps Validate that date ranges match report needs. Use `id` in `POST /v2beta/adMeasurements`. If `total_rules` > 0, call `GET /v1/library/datasourceGroups/{id}/rules` for more associated rule details. ### Related endpoints - `GET /v1/library/datasourceGroups` - List Datasource Groups - `GET /v1/library/datasourceGroups/{id}/rules` - List Rules for a Datasource Group - `POST /v2beta/adMeasurements` - Create a report - `DELETE /v1/library/datasourceGroups/{id}` - Delete a Datasource Group See [help page](https://help.videoamp.dev/en/articles/11429358-datasource-groups-and-rules) for details. parameters: - name: datasourceGroupId in: path required: true schema: type: string description: 'UUID v4 identifier for Datasource Group to retrieve. Obtained from ''List'' endpoint or creation response. Required for all ''GET'' operations. Returns 404 if group doesn''t exist, user lacks access, or group is soft-deleted (set ''includeDeleted = true'' to retrieve deleted groups). Fetches complete configuration including metadata, Datasources, and Rule counts. Primary use: validating group before Measurement report creation.' - name: includeDeleted in: query required: false schema: type: string description: Controls soft-deleted group retrieval. Default false verifies if group is active (404 if ID is deleted). Set to `true` to corroborate if group is deleted. Deleted groups retain configuration and `deleted_at` timestamp but cannot be used in new reports. Useful for lineage tracking, compliance audits, or recovering configuration to recreate. (default true) - name: includeEventCounts in: query required: false schema: type: string description: 'Opt-in. When true, populates `event_count` on the returned Datasource Group with best-effort event counts. No-op when `top_level_only=true`: the summary fetch never populates `datasources`, so `event_count` is always returned as unavailable (empty `counts_by_unit`). (default true)' - name: ownership in: query required: false schema: type: string description: 'Verify Datasource Group ownership and access rights. ''OWNED'' returns group if all Datasources are fully owned by your organization (404 if ''SHARED''). ''SHARED'' returns group if it contains a mix of owned and shared Datasources (404 if all ''OWNED''). ''OWNERSHIP_FILTER_UNSPECIFIED'' (default) returns the group regardless of ownership status. - OWNERSHIP_FILTER_UNSPECIFIED: Default filter value that returns all Datasource Groups regardless of ownership status. - OWNED: Returns only Datasource Groups where all constituent Datasources are fully owned by your organization with unrestricted usage rights. - SHARED: Returns only Datasource Groups that contain a mix of owned and shared Datasources where some Datasources may have contractual usage restrictions or access limitations.' - name: topLevelOnly in: query required: false schema: type: string description: Performance optimization controlling payload size. Default false returns complete group with all Datasources. Set to `true` to retrieve only metadata (ID, name, dates, advertiser, Rule count) excluding `datasources` array. Use for fast UI dropdowns, existence checks, or audits when Datasource details are not necessary. (default true) responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: datasource_group_get /v1/library/datasourceGroups/{datasourceGroupId}/rules: post: operationId: datasource_group_rule_create summary: Create Rule tags: - library description: |- ### What Creates a Rule scoped to a Datasource Group (DSG). The Rule's `strategy_definition` is a tree of `RuleItem`s combining filter conditions with boolean operators; it constrains which underlying datasource records contribute to measurement reports built on the DSG. ### Why Rules persist reusable, label-bearing slices of a DSG so downstream reports render meaningful breakdowns instead of bare identifiers — e.g., an analyst scoping a report to specific LINEAR networks, or a data engineer slicing a DSG by source dimension. ### When Use to programmatically scope DSG measurement to a subset of underlying data. **Do NOT use** for ad-hoc filtering that need not persist, for filters not exposed by `datasource_rule_filter_name_search` on the target DSG, or against competitor / unsupported-scope DSGs (fails `DGR_0001` / `DGR_0003` / `DGR_0004`). ### How **Workflow** to build a leaf `RuleItem`: 1. Call `datasource_rule_filter_name_search` → pick a `RuleFilterNameOption`. Its `value` → `field`; `label` → `field_label`. 2. If the filter is shared across LINEAR/DIGITAL (`advertiser`, `creative`) and medium is ambiguous, **ask — do not guess.** 3. Call `datasource_rule_filter_value_search` with the chosen `field` and `medium` → pick `RuleFilterValueOption`s. Values → `values`; labels → `value_labels`. 4. Wrap leaves per the double-nesting constraint on `RuleDefinition`; populate all four leaf fields. ### Next Steps Reference the new Rule by `id` in measurement-report calls. Use `datasource_group_rule_get` to confirm; `datasource_group_rule_list` to enumerate. ### Related Endpoints `datasource_rule_filter_name_search`, `datasource_rule_filter_value_search`, `datasource_group_rule_get`, `datasource_group_rule_list`, `datasource_group_rule_delete`. See [help page](https://help.videoamp.dev/en/articles/11429358-datasource-groups-and-rules) for more on Datasource Groups and Rules. parameters: - name: datasourceGroupId in: path required: true schema: type: string description: The Datasource Group ID that the Rule belongs to. Must reference a DSG the caller has access to whose reporting scope and datasource types support rules; otherwise the call fails with 'DGR_0001' / 'DGR_0003' / 'DGR_0004'. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp datasource_group_rule_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: datasource_group_rule_create get: operationId: datasource_group_rule_list summary: List Rules tags: - library description: |- Retrieves all Rules associated with a user or by Datasource Group ID, with the ability to bulk fetch by providing a list of Rule IDs. Use the `-` character to list all Rules associated to a user. Otherwise, provide the Datasource Group ID in the path to return Rules associated to the Datasource Group ID. The response includes a list of all Rules. Please view our [help page](https://help.videoamp.dev/en/articles/11429358-datasource-groups-and-rules) for more information on how Datasource Groups and Datasource Group Rules are used. parameters: - name: datasourceGroupId in: path required: true schema: type: string description: Specify the Datasource Group ID to fetch Rules for. Use '-' to retrieve Rules from all Datasource Groups. - name: ids in: query required: false schema: type: array items: type: string description: List of Rule IDs to retrieve a bulk set of specific Rules. - name: includeDeleted in: query required: false schema: type: boolean description: Default false. Deleted Rules will only be included when true. (default true) - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. Defaults to 20 if not specified. Maximum allowed value is 200. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: search in: query required: false schema: type: string description: Free-text search query to filter Rules by 'name' and 'description' fields. Performs case-insensitive partial match against Rule names and descriptions. When omitted, no text filtering is applied and all rules matching other criteria are returned. When provided, only rules with names or descriptions containing the search term as a substring are included. Useful for quickly finding rules when you remember part of the name or description but not the full name or ID. Search is not tokenized - the entire search string is matched as a phrase. Combine with other filters like 'datasource_group_id' for more precise results. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: datasource_group_rule_list /v1/library/datasourceGroups/{datasourceGroupId}/rules/{ruleId}: delete: operationId: datasource_group_rule_delete summary: Delete Rule tags: - library description: |- Soft deletes a Rule by its unique identifier (UUID). The resource can still be referenced by ID but will not be included in list results unless `include_deleted` is set to true. Please view our [help page](https://help.videoamp.dev/en/articles/11429358-datasource-groups-and-rules) for more information on how Datasource Groups and Datasource Group Rules are used. parameters: - name: datasourceGroupId in: path required: true schema: type: string - name: ruleId in: path required: true schema: type: string responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: datasource_group_rule_delete get: operationId: datasource_group_rule_get summary: Get Rule tags: - library description: |- Retrieves complete details of a specific Rule by UUID including name, description, Rule definition with operators and filters, and metadata (creator, timestamps). Use `top_level_only=true` to retrieve metadata without nested items for reduced response size. Use `include_deleted=true` to retrieve soft-deleted Rules. **Why**: Rules define criteria for grouping measurement data within Datasource Groups. Rules are optional to use and they provide customers with additional flexibility to view their data grouped in ways that may not be native in report views. Understanding Rule details is essential for configuring accurate measurement analyses and troubleshooting data grouping behavior. **When to Use**: - Display Rule configuration in UI or validate before applying to reports - Troubleshoot unexpected measurement results or check soft-delete status for lineage tracking **How**: Requires bearer token authentication with read permissions. **Error Handling**: - 404: Rule not found or user lacks access (set `include_deleted=true` to retrieve soft-deleted Rules) - 400: Invalid UUID format **Related Endpoints**: - `GET /v1/library/datasourceGroups/{datasourceGroupId}/rules` - List all Rules for a Datasource Group - `POST /v1/library/datasourceGroups/{datasourceGroupId}/rules` - Create new Rule - `DELETE /v1/library/datasourceGroups/{datasourceGroupId}/rules/{ruleId}` - Delete Rule **Common Workflow**: List Rules -> Get detailed config -> Apply to measurement report See our [help page](https://help.videoamp.dev/en/articles/11429358-datasource-groups-and-rules) for more information on Datasource Groups and Rules. parameters: - name: datasourceGroupId in: path required: true schema: type: string description: 'UUID v4 identifier of Datasource Group containing the target Rule. Datasource Groups are parent containers that organize Rules for measurement analysis. Use ''-'' wildcard to retrieve Rules without knowing parent group ID (returns Rule if found in any accessible group). Format accepts standard UUID or ''-'' character. Common use: retrieving Rules when only Rule ID is known, or validating parent-child relationship for configuration audits. Returns 404 if not found or not accessible.' - name: ruleId in: path required: true schema: type: string description: 'UUID v4 identifier for specific Rule to retrieve. Obtained from List endpoint, creation response, or UI selection. Required for all GET operations. When ''include_deleted'' is false (default), returns 404 if rule is soft-deleted. When ''include_deleted'' is true, retrieves deleted rules. Also returns 404 if rule doesn''t exist or user lacks access. Fetches complete configuration including name, description, strategy definition with operators and filters, and metadata (creator, timestamps). Primary use: validating rule configuration before applying to measurement reports or displaying rule details in UI.' - name: includeDeleted in: query required: false schema: type: boolean description: Controls soft-deleted rule retrieval. Default false returns only active rules (404 if ID is deleted). Set to true to retrieve deleted rules for audit trails, historical analysis, compliance reporting, or recovering configuration to recreate. Deleted rules retain all configuration data and deleted_at timestamp but cannot be used in new measurement reports. Useful for lineage tracking when investigating reports created before rule deletion. (default true) - name: topLevelOnly in: query required: false schema: type: boolean description: Performance optimization controlling payload size. Default false returns complete rule with all nested items (strategy definition, filters, operators, values). Set to true to retrieve only metadata (ID, name, description, timestamps) excluding strategy_definition array. Significantly reduces response size and latency for rules with extensive filter configurations. Use for fast UI dropdowns, existence checks, or audits when item details are unnecessary. (default true) responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: datasource_group_rule_get /v1/library/datasourceTypeOptionsSearch: post: operationId: datasource_type_search summary: Search Datasource Types tags: - library description: |- ### What Returns available datasource types for a given advertiser and filter parameters. Must supply reporting scope and medium filters. ### Why Discovers valid datasource_type values for Datasource Group (DSG) creation. **Business Scenarios:** - User finds VA_PIXEL type is available by searching reporting_scope=AD_MEASUREMENT and medium=DIGITAL - Agent discovers NATIONAL_LINEAR_BROADCAST_AND_CABLE by searching with reporting_scope=CONTENT_MEASUREMENT and medium=LINEAR ### When Call after selecting reporting_scope, advertiser_id, and date range desired for datasource group. **Important:** To discover all available datasource types, call this endpoint twice: once with `medium=DIGITAL` and once with `medium=LINEAR`. If a date range is provided, the types returned have data within that range. **Do NOT use when:** - You already know the exact datasource_type **Next Steps:** Select a type from results, then call `POST /v1/library/datasourceFilterNameOptionsSearch` with that type. ### How **Discovery Pattern:** Try DIGITAL first (faster queries), then LINEAR (slower). Combine results from both calls to see all available types by medium. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp datasource_type_search --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: datasource_type_search /v1/library/ruleFilterNameOptionsSearch: post: operationId: datasource_rule_filter_name_search summary: Search Rule Filter Names tags: - library description: |- ### What Returns the valid filter names (`field` identifiers) for building a leaf `RuleItem` against a specific Datasource Group (DSG). The runtime per-DSG set depends on the DSG's datasource types — always discover via this call; the static `rule_filter_name.in:` list is the cross-DSG universe, not the per-DSG subset. ### Why The valid `field` identifiers vary per DSG based on its constituent datasource types. The static `rule_filter_name.in:` enum is the cross-DSG universe, not the per-DSG allowlist — discover the applicable identifiers here before calling value search to avoid `DSO_0023_RULE_FILTER_NOT_SUPPORTED_ON_DSG` failures and rules that target unsupported filters. ### When Step 1 of the rule-creation chain. Call after picking a DSG, before `RuleFilterValueOptionsSearch`. Skip if you already hold a validated `RuleItem.field` for this DSG. ### How Each `RuleFilterNameOption` supplies: - `value` → `RuleItem.field` - `label` → `RuleItem.field_label` (required to persist the rule with readable field names; used by API/MCP and UI consumers) - `medium` → pass through to `RuleFilterValueOptionsSearchRequest.medium` Shared LINEAR/DIGITAL filters (`advertiser`, `creative`) appear once per medium. When the user's intent doesn't specify, **ask — do not guess.** ### Next Steps For each chosen option, call `RuleFilterValueOptionsSearch` with `datasource_group_id`, `rule_filter_name = option.value`, `medium = option.medium`. ### Related `RuleFilterValueOptionsSearch`, `CreateRule`. [help page](https://help.videoamp.dev/en/articles/11429353-datasource-options). requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp datasource_rule_filter_name_search --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: datasource_rule_filter_name_search /v1/library/ruleFilterValueOptionsSearch: post: operationId: datasource_rule_filter_value_search summary: Search Rule Filter Values tags: - library description: |- ### What Returns the valid values (`RuleItem.values` entries) for a given `rule_filter_name` on a specific Datasource Group (DSG). Each entry carries a label that maps to `RuleItem.value_labels`. ### Why Value identifiers and their human-readable labels are per-DSG and not derivable from the filter name alone. Fetching them here is the only way to obtain the correct `values` and `value_labels` to populate on the leaf `RuleItem`. ### When Step 2 of the rule-creation chain. Call once per leaf `RuleItem`, after `RuleFilterNameOptionsSearch`. **`medium` is effectively required** — pass `RuleFilterNameOption.medium` through; see the `medium` field for the CROSS_SCREEN footgun and `DSO_0023` failure. ### How Each option supplies `value` (→ append to `RuleItem.values`) and `label` (→ `RuleItem.value_labels[value]`; required to persist the rule with readable labels). Populate all four leaf fields together; partial leaves persist with bare identifiers (used by API/MCP and UI consumers alike). Pass the leaf to `CreateRule`. **Worked example:** ``` 1. NameSearch(dsg_id) → {value:"campaign", label:"Campaign", medium:DIGITAL} 2. ValueSearch(dsg_id, rule_filter_name:"campaign", medium:DIGITAL) → {value:"camp_1", label:"Spring 24"} 3. Leaf: {field:"campaign", field_label:"Campaign", operator:"=", values:["camp_1"], value_labels:{"camp_1":"Spring 24"}} ``` ### Next Steps Assemble all four leaf fields together — `field` (from name search), `field_label` (from name search), `values` (from this call), `value_labels` (from this call) — and pass the completed leaf `RuleItem` to `CreateRule`. ### Related `RuleFilterNameOptionsSearch`, `CreateRule`. [help page](https://help.videoamp.dev/en/articles/11429353-datasource-options). requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp datasource_rule_filter_value_search --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: datasource_rule_filter_value_search /v1/me: get: operationId: user_info_get summary: Get Current User tags: - me description: |- ### What Returns authenticated user profile including personal details (name, email), and business entity memberships (holding companies, agencies, advertisers). Delivers identity (UUID, names, email) plus org hierarchy for authorization and multi-tenant resource scoping. ### Why - App initialization: provides identity, org context, and permissions for session management - Multi-tenant isolation: enforces resource scoping and authorization decisions - **Business Name Resolution**: Discover UUIDs from business names (e.g., "Genesis") via `memberships` array ### When - App startup after authentication - Login completion to establish state - User menu rendering - Business entity selector population - Pre-flight validation before mutations - **When users reference businesses by name** - resolve to UUID for API calls ### How - Auth: OAuth2 Bearer token (identity from JWT claims) - Latency: ~100ms - Returns: user UUID, name, email, org UUID, memberships array - Cache per session; refresh on permission changes - **Name→UUID Resolution**: Search `memberships` for `display_name` match, use `id` field in API calls. Filter with `?membership_search=Genesis&membership_kinds=ADVERTISER` ### Organization Identity & Cross-API Usage `current_organization_id`, the deprecated `organizations` array, and the `memberships` entry where `kind = HOLDING_COMPANY` all share the **same UUID** referencing the same organization (tenant). Pass this UUID as `org_id`, `public_org_id`, or `organization_id` in other VideoAmp APIs (Library, Deal, Share, Forecast, etc.). "Organization" = tenant. `HOLDING_COMPANY` in `memberships` = its access-hierarchy representation (1:1, same UUID). Some legacy APIs accept a numeric `holding_company_id` — that is a different identifier, not this UUID. parameters: - name: include_memberships in: query required: false schema: type: string description: Filter support If true, includes the memberships array in the response. Set to false to omit business entity details for lightweight responses when organizational context is not needed. Default is true. (default true) - name: membership_kinds in: query required: false schema: type: string description: 'If provided, filters the memberships array to only include business entities of the specified kinds (e.g., only `ADVERTISER` entities). If empty or not set, all membership kinds are returned. Accepts multiple values for combined filtering.Ex: /v1/me?membership_kinds=ADVERTISER,AD_AGENCY to return both ADVERTISER and AD_AGENCY. **Cross-API note**: The Sharing API uses `ORGANIZATION` instead of `HOLDING_COMPANY` — translate when passing kind values to sharing endpoints. - HOLDING_COMPANY: Top-level entity in the business/access hierarchy, corresponding to "Organization" (tenant) in external terminology. The `id` of a HOLDING_COMPANY business entity is the same UUID as `current_organization_id` from the `/v1/me` response. This UUID can be used as `org_id`, `public_org_id`, or `organization_id` in other APIs accepting string UUIDs. - AD_AGENCY: Media buying agency under a holding company. Same as `AD_AGENCY` in Sharing API''s SubjectKind. - ADVERTISER: Brand or advertiser purchasing media. Same as `ADVERTISER` in Sharing API''s SubjectKind. Use `membership_kinds=ADVERTISER` for name resolution to avoid returning agencies with the same name.' - name: membership_search in: query required: false schema: type: string description: Optional search string to filter 'memberships' by display name. Performs case-insensitive substring match against the 'display_name' field of each business entity. Useful for implementing search-as-you-type functionality in business entity selectors. If empty or not set, no name filtering is applied. - name: page_size in: query required: false schema: type: integer description: Pagination for memberships Number of membership records to return per page. Used for paginating through large sets of business entity memberships. If not set a default page size of 999 is used. - name: page_token in: query required: false schema: type: string description: Token from a previous 'IdentifyUser' response to retrieve the next page of membership results. Used in conjunction with 'page_size' for pagination. If not set, retrieves the first page. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: user_info_get patch: operationId: user_profile_update summary: Update User Profile (Internal Only) tags: - me description: |- ### What Updates the authenticated user's profile settings, specifically the current organization context. Changes which organization the user is operating within, affecting resource visibility, permissions, and data filtering across the platform. Returns updated user profile including the new organization context and available memberships. This endpoint only updates `current_organization_id`. Other profile fields (`given_name`, `family_name`, `email`) are read-only and cannot be modified through this endpoint. ### Access Control **RESTRICTED TO INTERNAL VIDEOAMP USERS ONLY**: This endpoint is only accessible to VideoAmp employees. External users will receive `403 Forbidden` when attempting to access this endpoint. ### Why - Internal users need to switch between organizations for administrative and support operations - Multi-tenant applications require organization context switching for proper resource scoping - Session state must reflect the active organization for authorization and data filtering - UI components (org selectors) need to persist user's organization selection across sessions ### When - Call when user selects a different organization from an org selector dropdown - Use during application initialization if user's last-selected org differs from JWT claim - Execute before cross-organization operations requiring context switch ### How - Auth via OAuth2 Bearer token (identity derived from JWT claims) - Provide organization UUID in request body via `current_organization_id` field - User must have membership in the specified organization - Returns full IdentifyResponse with updated `current_organization_id` field - Client applications may need to refresh session after org switch for updated claims - Response includes updated memberships array with same pagination as `/v1/me`. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp user_profile_update --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '403': description: Forbidden — the caller's organization is not permissioned for this resource. x-videoamp-cli-command: user_profile_update /v1/me/orgs: get: operationId: user_organization_list summary: List All User Organizations tags: - me description: |- ### What Returns **ALL organizations** the authenticated user has access to or can switch to. Provides complete list of organizations with UUID, display name, and organizational kind. **Key Distinction from `/v1/me`:** - This endpoint (`/v1/me/orgs`) returns **ALL** organizations the user can access - `/v1/me` returns only the **current** organization (via `current_organization_id` field) ### Why - Organization switching: Shows which organizations users can switch between - Access discovery: Users need to see what organizations they can access - UI population: Powers organization selector dropdowns - Admin tools: View and manage user organization memberships - Troubleshooting: Verify organizational access for permission issues ### When **Use this endpoint when users ask about:** - "What organizations can I switch to?" / "List all my organizations" - "What organizations do I have access to?" - Any variation of listing/viewing available organizations **Do NOT use for current org context** → Use `GET /v1/me` instead ### How - User identity derived automatically from OAuth2 Bearer token (JWT subject claim) - No request parameters required - operates on authenticated user - Typical latency under 200ms - Returns array of organizations with `id` (UUID), `display_name` (string), `kind` (enum) - No pagination required (users typically belong to <100 organizations) Each organization `id` here is the same UUID that appears as `current_organization_id` in `/v1/me` and as the `HOLDING_COMPANY` membership's `id`. Use it as `org_id`, `public_org_id`, or `organization_id` in other APIs. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: user_organization_list /v1/shares: get: operationId: share_list summary: List Shares tags: - shares description: |- ### What Retrieves a paginated list of resource shares matching filter criteria. Returns share metadata including sharer organization, recipients with permissions, resources with types and names, lifecycle status, and audit trail. ### Why Enables discovery and monitoring of sharing relationships across organizations. Essential for auditing data access, managing permissions, tracking resource distribution, and compliance. Target users: audience owners sharing their data, users viewing and managing shares created by their organization, platform operations via share management UI, and audience teams. ### When - Discover all shares created by your organization - Filter by kind (e.g., ADVANCED_AUDIENCE) to view all audience shares specifically - Validate whether shares are successful or deleted when recipients report access issues - Audit resource access across organizational boundaries for QA and compliance - Monitor share lifecycle status changes between ACTIVE and DELETED - Build share management dashboards and compliance reports Use GET /v1/shares/{id} for single share details. Use POST /v1/shares to create new shares. ### How Requires valid JWT authentication. Use pageSize and pageToken for pagination through results. Use q parameter for filtering by kind or createdAt. Returns 400 for invalid params, 403 for auth errors, 500 for server errors. parameters: - name: fetchRecipientAncestorPath in: query required: false schema: type: boolean description: 'When true, includes the ancestor_path field for each recipient showing their full position in the organizational hierarchy from root to leaf. This hierarchical path is essential for understanding the sharing scope within complex multi-level organizational structures. Use this to display breadcrumb navigation in UIs, validate sharing permissions at the correct org level, or audit which parent entities have inherited access. Performance note: enabling this adds a lookup per recipient, so omit for large result sets where hierarchy is not needed. (default true)' - name: order in: query required: false schema: type: array items: type: string description: 'Order by attribute(s): - createdAt (ASC, DESC) Sort order for results controlling how shares are ordered in the response. Format: ''createdAt ASC'' for oldest first or ''createdAt DESC'' for newest first. Defaults to createdAt DESC when not specified. Important: changing the order parameter between paginated requests invalidates the pageToken and you must restart from page 1. This ensures consistent ordering across pages. For audit workflows, use ASC to process shares chronologically from oldest to newest. For monitoring dashboards, use DESC to see most recent shares first.' - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. - name: pageToken in: query required: false schema: type: string description: 'Query param ''pageToken'' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field ''next_page_token''. When requesting the next page, additional query parameters should NOT change between page requests. - createdAt ISO 8601 formatted string (gt, lt, gte, lte) - kind `string` (eq, in) - resourceId `string` (eq, in) Advanced query filter for attribute-based filtering. Supported attributes: - **kind**: Filter by resource kind. Operators: eq, in. Currently supported: ADVANCED_AUDIENCE. - **createdAt**: Filter by creation date (ISO 8601). Operators: gt, lt, gte, lte. - **resourceId**: Filter by resource id. Operators: eq, in. Use the same id supplied as resource.id in POST /v1/shares (or resources[] in POST /v2/shares). Multiple q parameters are AND''d by default. Prefix with ''or'' for OR logic. Examples: - ?q=kind eq ADVANCED_AUDIENCE - ?q=createdAt gt 2025-01-01T00:00:00Z - ?q=resourceId eq 277777 - ?q=resourceId in 277777,277778 - ?q=kind eq ADVANCED_AUDIENCE&q=createdAt gte 2025-01-01' responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. '403': description: Forbidden — the caller's organization is not permissioned for this resource. '500': description: Internal Server Error. x-videoamp-cli-command: share_list post: operationId: share_resource_create summary: Create Share tags: - shares description: |- ### What Creates a share granting a single recipient access to a single audience resource. Returns the complete Share object including recipients, resources, status, and audit trail. ### Why Provides simple single-recipient, single-resource sharing for straightforward use cases. Returns full share details immediately for verification without requiring an additional GET call. Ideal for simple integrations and UI-driven workflows. ### When - Share one audience with one recipient and verify details in the response - Simple integrations that share one resource at a time - UI-driven sharing where user selects one audience and one recipient For bulk operations (multiple recipients or resources), use POST /v2/shares instead. Verify consent exists via GET /v1/consents before sharing. ### How Requires valid JWT authentication. Provide share object with recipient (kind and id), resource (legacy integer identifier), optional name, and optional permissions. Set fetch_recipient_ancestor_path=true to include organizational hierarchy in response. Returns 400 for validation errors, 403 if not authorized, 409 if share already exists. ### Example ```json { "recipient": {"id": "10", "kind": "ORGANIZATION"}, "resource": {"id": "277777"}, "name": "Share to Partner Org" } ``` **Notes:** - `resource.id`: Use the audience's legacy integer ID (`audienceId` from v1 API, or `legacy_id` from v2 API), not the UUID - `recipient.kind`: ORGANIZATION, ADVERTISER, AD_AGENCY, BRAND, SUB_BRAND, or PRODUCT parameters: - name: fetchRecipientAncestorPath in: query required: false schema: type: boolean description: When true, includes the ancestor_path field in the response showing the recipient's full position in the organizational hierarchy. Useful for verifying the share was created at the correct organizational level. (default true) requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp share_resource_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. '403': description: Forbidden — the caller's organization is not permissioned for this resource. '409': description: Conflict — the request conflicts with the current state of the resource. x-videoamp-cli-command: share_resource_create /v1/shares/audiences/revoke/cancel/{confirmId}: post: operationId: share_audience_revocation_cancel summary: 'Cancel Bulk Audience Revocation (Step 2b: Abort)' tags: - shares description: |- ### Workflow This is **step 2b** of a 2-step confirmation workflow. Call this after reviewing the summary returned by **step 1**: DELETE /v1/shares/audiences/revoke/recipient/{recipient}, and deciding the revocation should NOT proceed. All shares remain active and recipients retain access. To execute the revocation instead, use **step 2a**: POST /v1/shares/audiences/revoke/confirm/{confirmId}. ### What Cancels a pending bulk revocation initiated via DELETE /v1/shares/audiences/revoke/recipient/{recipient}. The shared audiences remain active and recipients retain access. Returns the list of preserved share IDs. ### Why After reviewing the step 1 summary, users may discover the revocation scope is wrong or that it was initiated by mistake. Without an explicit cancel, the only option would be to wait for the 1-hour expiry. ### When - The step 1 summary shows shares or audiences that should not be revoked - The bulk revocation was started by mistake - Must be called within 1 hour of initiation and before confirmation ### How Requires valid JWT authentication. Pass the confirm_id (UUID) from the step 1 response as the path parameter. Only the user who initiated the revocation can cancel it. Expires after 1 hour. Returns the list of share UUIDs that were preserved (remain in ACTIVE status). Returns 404 if the confirm_id does not exist, was already confirmed or canceled, or has expired. parameters: - name: confirmId in: path required: true schema: type: string description: UUID of the pending revocation to cancel. Obtained from the confirm_id field in the response of DELETE /v1/shares/audiences/revoke/recipient/{recipient}. Must reference a revocation that has not yet been confirmed or canceled, and must be used within 1 hour of initiation. Only the user who initiated the revocation can use this confirm_id. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp share_audience_revocation_cancel --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: share_audience_revocation_cancel /v1/shares/audiences/revoke/confirm/{confirmId}: post: operationId: share_audience_revocation_confirm summary: 'Confirm Bulk Audience Revocation (Step 2a: Execute)' tags: - shares description: |- ### Workflow This is **step 2a** of a 2-step confirmation workflow. Call this after reviewing the summary returned by **step 1**: DELETE /v1/shares/audiences/revoke/recipient/{recipient}. This action is irreversible. Once confirmed, all identified shares are permanently revoked and recipient access is terminated. To abort instead, use **step 2b**: POST /v1/shares/audiences/revoke/cancel/{confirmId}. ### What Executes a pending bulk revocation initiated via DELETE /v1/shares/audiences/revoke/recipient/{recipient}. Permanently revokes all identified shares, terminating recipient access. Returns per-share results: revoked_shares for successes and errors for failures. ### Why Bulk revocation is irreversible and high-impact. A separate confirmation step lets users review the step 1 impact summary before committing, so shares are never revoked without explicit intent. ### When - After reviewing the step 1 summary (share_count, share_ids, audience_ids) and deciding to proceed - Must be called within 1 hour of initiation (confirm_id expires) - Cannot be called after the same confirm_id has been canceled ### How Requires valid JWT authentication. Pass the confirm_id (UUID) from the step 1 response as the path parameter. Only the user who initiated the revocation can confirm it. Each share is revoked individually; partial success is possible. Check the revoked_shares array for successes and the errors array for failures. Shares that fail can be retried individually via DELETE /v1/shares/{id}. Use POST /v1/shares/audiences/revoke/cancel/{confirmId} to abort instead. parameters: - name: confirmId in: path required: true schema: type: string description: UUID of the pending revocation to confirm and execute. Obtained from the confirm_id field in the response of DELETE /v1/shares/audiences/revoke/recipient/{recipient}. Must reference a revocation that has not been confirmed, canceled, or expired (1-hour window). Only the user who initiated the revocation can confirm it. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp share_audience_revocation_confirm --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: share_audience_revocation_confirm /v1/shares/audiences/revoke/recipient/{recipient}: delete: operationId: share_audience_recipient_revoke summary: Initiate Bulk Audience Revocation (Step 1 of 2) tags: - shares description: |- ### Workflow **Step 1 of 2.** This endpoint does NOT revoke any shares. You must follow up with: - **Step 2a** (execute): POST /v1/shares/audiences/revoke/confirm/{confirmId} - **Step 2b** (abort): POST /v1/shares/audiences/revoke/cancel/{confirmId} ### What Initiates a bulk revocation of all audience shares with a specific recipient. Does NOT immediately revoke access. Returns a confirm_id (expires in 1 hour) and a summary of affected shares (share_count, share_ids, audience_ids) for review. ### Why Revoking shares individually via DELETE /v1/shares/{id} is impractical at scale. This endpoint handles all shares with a recipient in a single operation. The two-step confirmation workflow prevents accidental bulk access termination. ### When - End of a partner relationship and need to revoke all shared audiences at once - Offboard a recipient organization from all shared data - Respond to compliance or security concerns requiring full access termination ### How Requires valid JWT authentication. Pass the recipient in KIND-ID format (e.g., ORGANIZATION-123) where KIND is ORGANIZATION, ADVERTISER, AD_AGENCY, BRAND, SUB_BRAND, or PRODUCT. Obtain valid identifiers from GET /v1/shares or GET /v1/consents. Response fields: `confirm_id` (UUID, pass to confirm/cancel within 1 hour), `share_count`, `share_ids`, `audience_ids`. Only the initiating user can confirm or cancel. parameters: - name: recipient in: path required: true schema: type: string description: Composite identifier of the recipient to revoke all audience shares with, in the format KIND-ID where KIND is one of ORGANIZATION, ADVERTISER, AD_AGENCY, BRAND, SUB_BRAND, or PRODUCT, and ID is the recipient's numeric identifier. Obtain valid recipient identifiers from GET /v1/shares (recipients[].kind and recipients[].id fields) or GET /v1/consents. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: share_audience_recipient_revoke /v1/shares/{id}: delete: operationId: share_delete summary: Revoke Share tags: - shares description: |- ### What Permanently revokes a resource share, immediately terminating recipient access to all shared resources. ### Why Enables resource owners to control shared data by allowing users to terminate access when partnerships conclude, agreements expire, or access is no longer needed. Critical for data governance and compliance. The share record is retained with DELETED status for audit purposes. ### When - Quickly revoke an incorrect share made by mistake - Terminate a partner relationship or data sharing agreement - Revoke access when a campaign completes - Clean up unwanted shares (e.g., recipient only needs one of multiple shared audiences) - Respond to security concerns requiring immediate access termination - Remove access for recipients who no longer need shared resources Use GET /v1/shares to discover shares. Use GET /v1/shares/{id} to verify details before revoking. ### How Requires valid JWT authentication. Pass share UUID as path parameter. Your organization must own the share. Returns the updated share with status DELETED. Returns 400 for invalid UUID, 403 for insufficient permissions, 404 if share not found or not owned by your organization. parameters: - name: id in: path required: true schema: type: string description: Unique identifier of the share to revoke in standard UUID v4 format. This ID is immutable and globally unique across the platform. Obtained from share creation response, list operations, or UI selection. The share must be owned by your organization to revoke it. Upon successful revocation, the share status changes to DELETED and all recipients immediately lose access to the shared resources. Returns 404 if share doesn't exist or is not owned by your organization. - name: fetchRecipientAncestorPath in: query required: false schema: type: boolean description: 'When true, includes the ancestor_path field for each recipient in the response showing their full position in the organizational hierarchy from root to leaf. This hierarchical path is useful for understanding which organizational levels had access before revocation. Use this for audit logging, compliance documentation, or confirming the correct share was revoked. Performance note: enabling this adds a lookup per recipient. (default true)' responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. '403': description: Forbidden — the caller's organization is not permissioned for this resource. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: share_delete get: operationId: share_get summary: Get Share tags: - shares description: |- ### What Returns a share along with its associated resources and recipients. ### Why Enables retrieval of complete share details for auditing, compliance, and share management. Target users: audience owners sharing their data, users viewing and managing shares created by their organization, platform operations via share management UI, and audience teams. ### When - Confirm a share was created successfully after creation - Validate whether a share is active or deleted when a recipient reports access issues - Retrieve complete share details when you have a share ID from list operations or creation - Display share metadata in UI including recipients, resources, and permissions - Audit share configuration for compliance reporting - Troubleshoot sharing issues by examining full share state Use GET /v1/shares for discovery and bulk retrieval. Use POST /v1/shares to create new shares. ### How Requires valid JWT authentication. Pass share UUID as path parameter. Set fetch_recipient_ancestor_path=true to include organizational hierarchy for recipients. Returns 400 for invalid UUID, 403 for auth errors, 404 if share not found. parameters: - name: id in: path required: true schema: type: string description: Unique identifier for the share to retrieve in standard UUID v4 format. This ID is immutable and globally unique across the platform. Obtained from creation response, list operations, or UI selection. Returns 404 if share doesn't exist, user lacks access, or share is deleted. Use this ID to fetch complete share details including recipients, resources, and audit trail. - name: fetchRecipientAncestorPath in: query required: false schema: type: boolean description: 'When true, includes the ancestor_path field for each recipient showing their full position in the organizational hierarchy from root to leaf. This hierarchical path is essential for understanding the sharing scope within complex multi-level organizational structures. Use this to display breadcrumb navigation in UIs, validate sharing permissions at the correct org level, or audit which parent entities have inherited access. Performance note: enabling this adds a lookup per recipient, so omit for large result sets where hierarchy is not needed. (default true)' responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. '403': description: Forbidden — the caller's organization is not permissioned for this resource. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: share_get /v1alpha/dataStreamTypes: get: operationId: data_stream_type_list summary: List Data Stream Types tags: - dataStreamTypes description: |- ### What Returns the catalog of supported Data Stream types. Each entry includes `name` (the kebab-case URL identifier), `enum_value` (the `dataStream.type` enum form), `display_name` (a human-readable label), and `description` (long-form prose tuned for LLM retrieval). The canonical `fields` schema is omitted — call `GET /dataStreamTypes/{dataStreamTypeName}` to retrieve it. ### Why Lets agents and UIs enumerate the types VideoAmp ingests. The list response is rich enough for an agent to reason about which type a provider feed belongs to without a second round trip per entry; UIs that only need a picker can read just the `name` and `display_name` fields they care about. ### When Before creating a new Data Stream — agents use this to choose a `type`; UIs use it to populate the type selector. ### How Authorization: any authenticated caller. ### Related operations - `GET /v1alpha/dataStreamTypes/{dataStreamTypeName}` — retrieve the full definition for one type, including the canonical `fields` schema. - `POST /v1alpha/dataStreams` — create a new Data Stream; pass one of these `enum_value`s as `dataStream.type`. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: data_stream_type_list /v1alpha/dataStreamTypes/{dataStreamTypeName}: get: operationId: data_stream_type_get summary: Get Data Stream Type tags: - dataStreamTypes description: |- ### What Returns the canonical definition of a single Data Stream type — display metadata (`name`, `enum_value`, `display_name`, `description`) and the canonical `fields` schema (each with `name`, `description`, `type`, `required`, `examples`, `aliases`). ### Why Mapping agents and onboarding UIs use this to learn the field set a provider feed must satisfy. Required fields gate transitioning the parent Data Stream to `PROVISIONING`. ### When After picking a `type` from the list endpoint — fetch the full definition once to drive the schema-mapping flow. ### How Authorization: any authenticated caller. ### Related operations - `GET /v1alpha/dataStreamTypes` — enumerate available types. parameters: - name: dataStreamTypeName in: path required: true schema: type: string description: Kebab-case identifier for the type. Obtainable from 'GET /dataStreamTypes' (each entry's 'name'). responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: data_stream_type_get /v1alpha/dataStreams: post: operationId: data_stream_create summary: Create Data Stream tags: - dataStreams description: |- ### What Creates a new Data Stream resource in `DRAFT` status. The server populates `id`, `org_id`, `advertiser_name`, `status`, `created_by`, `updated_by`, `created_at`, and `updated_at`; client-supplied values for those output-only fields are ignored. ### Why Data Streams register external feeds for ingestion into VideoAmp's measurement pipeline. The `DRAFT` state lets a user describe the stream before it is configured for delivery. ### When The first call in the intake flow — see Lifecycle below for the full sequence. ### How The caller must hold an entitlement on the supplied `advertiser_id`; otherwise the create returns 404 to avoid leaking advertiser existence. Required fields: `advertiser_id`, `name` (1-255 chars), `type`. Optional: `description` (≤ 4096 chars). `name` must be unique among the advertiser's Data Streams; a duplicate returns 409. A stream is scoped to exactly one `advertiser_id`; advertiser names inside the delivered file are descriptive only and do not change this. ### Lifecycle Create only registers metadata — it does **not** deliver or ingest data. The stream becomes consumable after this ordered sequence, each step advancing `status` (paths relative to the stream): 1. Create this stream (**this call**) → `DRAFT`. 2. `PUT .../deliveryConfig` with `method: FILE_UPLOAD`. 3. `POST .../deliveryConfig:approve` → `AWAITING_DELIVERY`. 4. `POST .../deliveryConfig:createUploadUrl`, then `PUT` the file — or send the user to `{{.DashboardUrl}}/data/data-streams/upload/{dataStreamId}` to do it themselves. 5. `POST .../deliveryInspections` → `AWAITING_APPROVAL`. 6. `PUT .../schemaMapping` — bind delivered columns to canonical fields. 7. `POST .../schemaMapping:approve` → `PROVISIONING`, then `PROVISIONED`. ### Related operations - `GET /v1alpha/dataStreams/{dataStreamId}` — retrieve a Data Stream by id. - `PUT /v1alpha/dataStreams/{dataStreamId}/deliveryConfig` — next step: configure how files are delivered. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp data_stream_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. '409': description: Conflict — the request conflicts with the current state of the resource. x-videoamp-cli-command: data_stream_create get: operationId: data_stream_list summary: List Data Streams tags: - dataStreams description: |- ### What Returns a paginated, filterable list of Data Stream resources the caller is entitled to read. ### Why Use this to power Data Stream list views, dashboards, and bulk-management workflows. Results are scoped to the caller's accessible advertisers (across the holdco/agency/advertiser hierarchy), so the same call can be issued by a holdco-tier user (sees every reachable advertiser's rows) or an advertiser-tier user (sees their advertiser's rows). ### When Any time after at least one `CreateDataStream`. Empty result sets are returned as `{ "results": [], "total_size": 0 }` rather than 404 — a caller with no accessible advertisers gets an empty page, not an error. ### How Filters are AND-combined; repeated `status` and `advertiser_id` values are OR-combined within their respective fields. `name` and `advertiser_name` are case-insensitive substring matches. Pagination uses an opaque `page_token`: the response's `next_page_token` is empty on the final page. Filter parameters must remain identical across pages of the same listing — changing any filter value requires a fresh request without `page_token`. ### Related operations - `GET /v1alpha/dataStreams/{dataStreamId}` — retrieve a single Data Stream. parameters: - name: advertiserId in: query required: false schema: type: string description: Filter by advertiser UUID. Repeat to match multiple advertisers. Each value must be a UUID v4 within the caller's accessible advertiser scope; advertisers outside that scope are rejected with InvalidArgument. - name: advertiserName in: query required: false schema: type: string description: Case-insensitive substring filter on the Data Stream's denormalized 'advertiser_name'. Useful for holdco/agency callers narrowing within their access scope by advertiser display name. - name: ingestionStatus in: query required: false schema: type: string description: 'Filter by ingestion health. Repeat to match multiple values (e.g. ?ingestionStatus=HEALTHY&ingestionStatus=DEGRADED). ANDs with the `status` filter, so callers can narrow provisioned streams by ingestion outcome. When omitted, ingestion health is not filtered. - DATA_STREAM_INGESTION_STATUS_UNSPECIFIED: Default unspecified value. - NONE: No ingestion has occurred yet. Default for a newly created Data Stream. - HEALTHY: The most recent ingestion succeeded. - DEGRADED: One or more recent ingestions failed, but a prior ingestion succeeded. - FAILING: No ingestion has ever succeeded, or failures have continued for a sustained consecutive streak.' - name: name in: query required: false schema: type: string description: Case-insensitive substring filter on Data Stream 'name'. Matches anywhere in the value (no leading/trailing wildcards required). - name: orderBy in: query required: false schema: type: string description: 'Sort order applied before pagination. Format: '''' for ascending or '' desc'' for descending. Supported fields: ''created_at'', ''updated_at'', ''name'', ''status''. Defaults to ''updated_at desc'' when omitted. Results carry an additional stable tiebreaker so paging is deterministic.' - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. Defaults to 50 if not specified. Maximum allowed value is 200. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: status in: query required: false schema: type: string description: 'Filter by Data Stream status. Repeat to match multiple statuses (e.g. ?status=DRAFT&status=AWAITING_DELIVERY). When omitted, Data Streams of every status are returned. - DATA_STREAM_STATUS_UNSPECIFIED: Default unspecified value. - DRAFT: Data Stream has been created but delivery configuration or file upload is not yet complete. - AWAITING_DELIVERY: Configuration is set and the Data Stream is awaiting an initial file delivery. - AWAITING_APPROVAL: First successful delivery inspection has completed; the schema mapping is awaiting approval. - PROVISIONING: Schema mapping has been approved; the Data Stream is being provisioned into downstream systems. - PROVISIONED: Ingestion pipeline has acknowledged the provisioning job — the end of the intake/ingestion path. Reached from PROVISIONING.' - name: type in: query required: false schema: type: string description: 'Filter by Data Stream type. Repeat to match multiple types. Supported values: AD_SCHEDULES. - DATA_STREAM_TYPE_UNSPECIFIED: Default unspecified value; rejected at create time. - AD_SCHEDULES: Provider-supplied planned or delivered ad schedule with flight, placement, and inventory metadata.' responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: data_stream_list /v1alpha/dataStreams/{dataStreamId}: get: operationId: data_stream_get summary: Get Data Stream tags: - dataStreams description: |- ### What Retrieves a complete Data Stream configuration by `data_stream_id`, including metadata (`name`, `description`, `type`), lifecycle state (`status`), advertiser (`advertiser_id`, `advertiser_name`), and audit timestamps (`created_at`, `updated_at`) and audit users (`created_by`, `updated_by`). ### Why Use this to validate intake state, display details in UI, or audit configuration. ### When After `CreateDataStream` and at any point in the resource's lifecycle. ### How Returns 404 if the Data Stream does not exist OR is outside the caller's access scope (existence is not leaked across organizations). ### Related operations - `POST /v1alpha/dataStreams` — create a new Data Stream. parameters: - name: dataStreamId in: path required: true schema: type: string description: UUID v4 of the Data Stream to retrieve. Obtained from the response of 'POST /v1alpha/dataStreams'. Returns 404 if the id does not exist OR exists outside the caller's organization/advertiser access scope (existence is not leaked across organizations). responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: data_stream_get patch: operationId: data_stream_update summary: Update Data Stream tags: - dataStreams description: |- ### What Partial-merge update of a Data Stream's editable fields: `name` and `description`. Sending an empty string is interpreted as "leave the stored value unchanged". Output-only fields (`id`, `org_id`, `advertiser_id`, `advertiser_name`, `type`, `status`, audit users + timestamps) cannot be modified through this endpoint. ### Why Lets a caller correct a Data Stream's user-visible metadata without re-reading the full resource first. PATCH semantics keep client integrations simple and avoid clobbering fields the caller did not intend to touch. ### When Any time after `CreateDataStream`. ### How Authorization: the caller must hold `datamanagement.data_stream.write` on the row's advertiser. Cross-advertiser writes return 404 (matching Get's existence-protection). Renaming to a `name` already used by another Data Stream under the same advertiser returns 409. ### Related operations - `GET /v1alpha/dataStreams/{dataStreamId}` — retrieve the resulting Data Stream. parameters: - name: dataStreamId in: path required: true schema: type: string description: UUID v4 of the Data Stream to update. Path parameter only — any value supplied in the body is ignored. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp data_stream_update --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. '409': description: Conflict — the request conflicts with the current state of the resource. x-videoamp-cli-command: data_stream_update /v1alpha/dataStreams/{dataStreamId}/deliveryConfig: get: operationId: delivery_config_get summary: Get Delivery Config tags: - dataStreams description: |- ### What Retrieves the DeliveryConfig for a DataStream, including the delivery `method`, lifecycle `status`, and audit timestamps. ### Why Use this to inspect the current delivery configuration and determine whether to call `:approve` or adjust the method first. ### When After `PUT /deliveryConfig` and at any point in the resource's lifecycle. ### How Returns 404 if the parent DataStream does not exist within the caller's access scope, or if no DeliveryConfig has been created for it. Existence of the DataStream is not leaked across organizations. ### Related operations - `PUT /v1alpha/dataStreams/{dataStreamId}/deliveryConfig` — create or update the DeliveryConfig. - `POST /v1alpha/dataStreams/{dataStreamId}/deliveryConfig:approve` — approve the DeliveryConfig. parameters: - name: dataStreamId in: path required: true schema: type: string description: UUID v4 of the parent DataStream. Returns 404 if the DataStream does not exist within the caller's access scope, or if no DeliveryConfig has been created for it. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: delivery_config_get put: operationId: delivery_config_update summary: Upsert Delivery Config tags: - dataStreams description: |- ### What Creates or replaces the DeliveryConfig for a DataStream. Idempotent for `DRAFT` configs: a second PUT with the same method is a no-op; a PUT with a different method updates it. Output-only fields (`id`, `data_stream_id`, `status`) supplied in the body are ignored. ### Why Lets a caller configure or reconfigure the delivery method before committing to delivery. Separating configuration (this endpoint) from commitment (`:approve`) means a user can change their mind without reprovisioning infrastructure. ### When After `CreateDataStream`. The DeliveryConfig need not exist yet — this call creates it if absent. Returns 400 if a DeliveryConfig exists and its `status` is `APPROVED`. ### How The caller must have write access on the parent DataStream's advertiser. The parent DataStream must exist within the caller's access scope; otherwise 404 is returned. The only required field is `method`; unsupported values return 400. ### Related operations - `GET /v1alpha/dataStreams/{dataStreamId}/deliveryConfig` — retrieve the current DeliveryConfig. - `POST /v1alpha/dataStreams/{dataStreamId}/deliveryConfig:approve` — lock the method and provision delivery infrastructure. parameters: - name: dataStreamId in: path required: true schema: type: string requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp delivery_config_update --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: delivery_config_update /v1alpha/dataStreams/{dataStreamId}/deliveryConfig:approve: post: operationId: delivery_config_approve summary: Approve Delivery Config tags: - dataStreams description: |- ### What Commits the delivery configuration: locks the delivery method, provisions S3 infrastructure for the DataStream, runs S3 access probes, and advances the parent DataStream status to `AWAITING_DELIVERY`. Returns the updated DeliveryConfig with `status: APPROVED`. ### Why Separating configuration (PUT) from commitment (this action) lets callers change the delivery method freely before locking in. Once approved, the DataStream is ready to receive data. ### When After `PUT /deliveryConfig` has set the desired method and the caller is ready to begin delivery. The DeliveryConfig must be in `DRAFT`; returns 400 if already `APPROVED`. ### How The caller must have write access on the parent DataStream's advertiser. On success the DeliveryConfig transitions to `APPROVED` and the parent DataStream transitions to `AWAITING_DELIVERY`. S3 infrastructure provisioning and probe failures are returned as 500; contact VideoAmp Support if this occurs. ### Related operations - `PUT /v1alpha/dataStreams/{dataStreamId}/deliveryConfig` — configure the delivery method before approving. - `POST /v1alpha/dataStreams/{dataStreamId}/deliveryConfig:confirmAccess` — run a read-only connectivity diagnostic. - `POST /v1alpha/dataStreams/{dataStreamId}/deliveryConfig:createUploadUrl` — obtain a pre-signed upload URL after approval. parameters: - name: dataStreamId in: path required: true schema: type: string description: UUID v4 of the parent DataStream. Returns 404 if the DataStream or its DeliveryConfig does not exist within the caller's access scope. Returns 400 if the DeliveryConfig is already APPROVED. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp delivery_config_approve --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. '500': description: Internal Server Error. x-videoamp-cli-command: delivery_config_approve /v1alpha/dataStreams/{dataStreamId}/deliveryConfig:confirmAccess: post: operationId: delivery_config_access_confirm summary: Confirm Delivery Config Access tags: - dataStreams description: |- ### What Runs a read-only connectivity diagnostic against the DataStream's delivery destination. No state is changed. Returns `accessible: true` when probes pass and `accessible: false` with a diagnostic `message` when they fail. ### Why Provides a connectivity check that can be run at any point the config has sufficient information to probe — optionally before `:approve` or as a post-approve re-diagnostic when delivery problems are suspected. ### When Whenever the DeliveryConfig has sufficient configuration to identify the delivery destination. Returns `400 FailedPrecondition` if the config does not yet have enough information to perform a connectivity check. Connectivity failures are reflected in the response payload (`accessible: false`), not as error status codes. ### How The caller must have read access on the parent DataStream's advertiser. Connectivity failures are reflected in the response payload (`accessible: false`) rather than error status codes — the request itself succeeded even when the destination is unreachable. ### Related operations - `POST /v1alpha/dataStreams/{dataStreamId}/deliveryConfig:approve` — the state-changing commitment that also validates connectivity as part of approval. parameters: - name: dataStreamId in: path required: true schema: type: string description: UUID v4 of the parent DataStream. Returns 404 if the DataStream or its DeliveryConfig does not exist within the caller's access scope. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp delivery_config_access_confirm --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: delivery_config_access_confirm /v1alpha/dataStreams/{dataStreamId}/deliveryConfig:createUploadUrl: post: operationId: delivery_config_upload_url_create summary: Create Upload URL tags: - dataStreams description: |- ### What Generates a time-limited upload URL for delivering a data file to the DataStream's delivery destination. Returns the URL and its expiration timestamp. Each call generates a new URL; previous URLs are not invalidated. ### Why The upload URL allows the caller to deliver files directly to the delivery destination without routing data through the API server, supporting large file transfers efficiently. ### When After `:approve` has succeeded (DeliveryConfig `status` must be `APPROVED`). Returns 400 if the DeliveryConfig is still `DRAFT`. Obtain a fresh URL for each file upload — do not cache or reuse URLs. ### How The caller must have write access on the parent DataStream's advertiser. Supply the original `filename` of the file being uploaded — it identifies the file at the delivery destination. The returned `upload_url` accepts a single HTTP PUT with the raw file bytes as the request body. The URL expires at `expires_at`; requests after that time will be rejected. Uploading with the same `filename` twice overwrites the previous file; use distinct filenames to retain multiple uploads. ### For coding agents If the caller can't perform the PUT itself, send the user to `{{.DashboardUrl}}/data/data-streams/upload/{dataStreamId}` instead — a VideoAmp-hosted page where they pick and upload the file directly, no API calls required on their end (they must already be a VideoAmp user; an unauthenticated visit prompts a normal login first). That page only performs the upload — poll `GET .../deliveryConfig:listUploadedFiles` afterward and call `POST .../deliveryInspections` yourself once the file lands. ### Related operations - `POST /v1alpha/dataStreams/{dataStreamId}/deliveryConfig:approve` — required before this endpoint can be called. - `POST /v1alpha/dataStreams/{dataStreamId}/deliveryInspections` — next step: after the file is uploaded, inspect the delivered file(s). parameters: - name: dataStreamId in: path required: true schema: type: string description: UUID v4 of the parent DataStream. Returns 404 if the DataStream or its DeliveryConfig does not exist within the caller's access scope. Returns 400 if the DeliveryConfig is not yet APPROVED. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp delivery_config_upload_url_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: delivery_config_upload_url_create /v1alpha/dataStreams/{dataStreamId}/deliveryConfig:deleteUploadedFile: post: operationId: delivery_config_file_delete summary: Delete Uploaded File tags: - dataStreams description: |- ### What Removes a previously uploaded file from the DataStream's delivery bucket. Returns 204 on success. ### Why Allows a caller to remove an incorrect or superseded file before triggering inspection, avoiding a failed inspection run. ### When While the parent DataStream is in `AWAITING_DELIVERY`. Returns 400 if the DeliveryConfig is not `APPROVED`, or if the DataStream is not in `AWAITING_DELIVERY`. Returns 404 if the specified file does not exist in the bucket. ### How The caller must have write access on the parent DataStream's advertiser. Supply the exact filename used at upload time. After deletion the file is permanently removed; obtain a new upload URL via `:createUploadUrl` to re-upload. ### Related operations - `POST /v1alpha/dataStreams/{dataStreamId}/deliveryConfig:createUploadUrl` — obtain a new upload URL after deleting a file. - `GET /v1alpha/dataStreams/{dataStreamId}/deliveryConfig:listUploadedFiles` — list files currently in the bucket. parameters: - name: dataStreamId in: path required: true schema: type: string description: UUID v4 of the parent DataStream. Returns 404 if the DataStream or its DeliveryConfig does not exist within the caller's access scope. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp delivery_config_file_delete --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: delivery_config_file_delete /v1alpha/dataStreams/{dataStreamId}/deliveryConfig:listUploadedFiles: get: operationId: delivery_config_uploaded_files_get summary: List Uploaded Files tags: - dataStreams description: |- ### What Returns metadata for all files currently in the DataStream's delivery bucket. Returns an empty list if no files have been uploaded. ### Why Allows a caller to verify which files are present before triggering inspection, and to surface existing files when returning to the delivery step. ### When After `:approve` has succeeded (DeliveryConfig `status` must be `APPROVED`). Returns 400 if the DeliveryConfig is still `DRAFT`. ### How The caller must have read access on the parent DataStream's advertiser. Files are returned in undefined order; there is no pagination in this endpoint. ### Related operations - `POST /v1alpha/dataStreams/{dataStreamId}/deliveryConfig:createUploadUrl` — upload a new file. - `POST /v1alpha/dataStreams/{dataStreamId}/deliveryConfig:deleteUploadedFile` — remove a specific file. parameters: - name: dataStreamId in: path required: true schema: type: string description: UUID v4 of the parent DataStream. Returns 404 if the DataStream or its DeliveryConfig does not exist within the caller's access scope. Returns 400 if the DeliveryConfig is not yet APPROVED. responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: delivery_config_uploaded_files_get /v1alpha/dataStreams/{dataStreamId}/deliveryInspections: post: operationId: delivery_inspection_create summary: Create Delivery Inspection tags: - dataStreams description: |- ### What Triggers a delivery inspection for the DataStream. All files at the DataStream's delivery prefix are listed and inspected synchronously. Returns `200` with the full `DeliveryInspection` result — the same shape as `GetDeliveryInspection`. ### Why Inspection detects each file's format and extracts column names and sample values, which drive the schema-mapping step. On first success the parent DataStream transitions from `AWAITING_DELIVERY` to `AWAITING_APPROVAL`. ### When After files have been uploaded via the pre-signed URL from `:createUploadUrl`. The DataStream's `deliveryConfig.status` must be `APPROVED`. Returns `409` if another inspection is already in progress. ### How The caller must have write access on the parent DataStream's advertiser. Inspection may complete synchronously or asynchronously — check `status` in the response. If `status` is `PENDING`, the inspection is still running; poll `GetDeliveryInspection` until `status` is `SUCCEEDED` or `FAILED`. A terminal status in the response means the inspection completed synchronously. ### Related operations - `GET /v1alpha/dataStreams/{dataStreamId}/deliveryInspections/{inspectionId}` — retrieve inspection-level metadata. - `GET /v1alpha/dataStreams/{dataStreamId}/deliveryInspections/{inspectionId}/files` — retrieve per-file results. - `GET /v1alpha/dataStreams/{dataStreamId}/deliveryInspections` — list all inspections. - `PUT /v1alpha/dataStreams/{dataStreamId}/schemaMapping` — next step: map the detected columns to canonical fields. parameters: - name: dataStreamId in: path required: true schema: type: string description: UUID v4 of the DataStream to inspect. Returns 404 if the DataStream does not exist within the caller's access scope. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp delivery_inspection_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '409': description: Conflict — the request conflicts with the current state of the resource. x-videoamp-cli-command: delivery_inspection_create get: operationId: delivery_inspection_list summary: List Delivery Inspections tags: - dataStreams description: |- ### What Returns a paginated list of delivery inspections for a DataStream, ordered by `inspected_at` descending (most recent first). Each result is the full `DeliveryInspection` object — the same shape as `GetDeliveryInspection`. ### Why Provides a history of all inspections for a DataStream. Results are sorted by `inspected_at` descending — call with `page_size=1` to retrieve the most recent inspection without a follow-up `GET`. ### When At any point after `CreateDeliveryInspection` has been called at least once. ### How The caller must have read access on the parent DataStream's advertiser. Paginate using `page_token` from the previous response's `next_page_token`. ### Related operations - `POST /v1alpha/dataStreams/{dataStreamId}/deliveryInspections` — trigger a new inspection. - `GET /v1alpha/dataStreams/{dataStreamId}/deliveryInspections/{inspectionId}` — retrieve full inspection metadata for a specific inspection. parameters: - name: dataStreamId in: path required: true schema: type: string description: UUID v4 of the DataStream whose inspections to list. - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. Defaults to 25 if not specified. Maximum allowed value is 100. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: delivery_inspection_list /v1alpha/dataStreams/{dataStreamId}/deliveryInspections/{inspectionId}: get: operationId: delivery_inspection_get summary: Get Delivery Inspection tags: - dataStreams description: |- ### What Returns inspection-level metadata for a single delivery inspection: `id`, `status`, `inspected_at`, and any inspection-level `errors`. Per-file detail is not included. ### Why Provides the outcome of an inspection and any inspection-level error detail (e.g. no files found at the prefix). Use the returned `id` to fetch per-file results via `ListDeliveryInspectionFiles`. ### When After `CreateDeliveryInspection` returns, use the `id` field on the `DeliveryInspection` response. Or use an `id` from `ListDeliveryInspections`. ### How The caller must have read access on the parent DataStream's advertiser. Returns 404 if the inspection or DataStream does not exist within the caller's access scope. ### Related operations - `GET /v1alpha/dataStreams/{dataStreamId}/deliveryInspections/{inspectionId}/files` — retrieve per-file results. - `GET /v1alpha/dataStreams/{dataStreamId}/deliveryInspections` — list all inspections. - `PUT /v1alpha/dataStreams/{dataStreamId}/schemaMapping` — next step: once inspection succeeds, map the detected columns to canonical fields. parameters: - name: dataStreamId in: path required: true schema: type: string description: UUID v4 of the parent DataStream. - name: inspectionId in: path required: true schema: type: string description: UUID v4 of the inspection to retrieve. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: delivery_inspection_get /v1alpha/dataStreams/{dataStreamId}/deliveryInspections/{inspectionId}/files: get: operationId: delivery_inspection_files_list summary: List Delivery Inspection Files tags: - dataStreams description: |- ### What Returns a paginated list of per-file results for a delivery inspection. Each result includes the filename, detected format, columns detected in that file, and any file-level errors. `columns[].samples` holds up to 3 distinct non-empty values for non-redacted columns (empty if none were sampled); a column whose samples matched a known PII-shaped pattern has `columns[].redacted` set to `true` and never carries samples. ### Why Per-file results expose the column names and sample values collected during inspection. Callers use this data to drive the schema-mapping step. Column samples help users identify which source column maps to which target field. ### When After `GetDeliveryInspection` returns `status: SUCCEEDED` or `status: FAILED`. File rows exist for all files attempted, including files with errors. ### How The caller must have read access on the parent DataStream's advertiser. Paginate using `page_token` from the previous response's `next_page_token`. ### Related operations - `GET /v1alpha/dataStreams/{dataStreamId}/deliveryInspections/{inspectionId}` — retrieve inspection-level metadata and errors. parameters: - name: dataStreamId in: path required: true schema: type: string description: UUID v4 of the parent DataStream. - name: inspectionId in: path required: true schema: type: string description: UUID v4 of the inspection whose file results to list. - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. Defaults to 25 if not specified. Maximum allowed value is 100. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: delivery_inspection_files_list /v1alpha/dataStreams/{dataStreamId}/ingestions: get: operationId: ingestion_list summary: List Ingestions tags: - dataStreams description: |- ### What Returns a paginated list of ingestion runs for a DataStream, ordered newest-first by `completed_at`. Each run summarises the outcome of one or more files processed by the backend. ### Why Allows clients to audit ingestion history, confirm data was received and processed, and identify failed runs that need attention. ### When Call after a DataStream has been provisioned. Results appear as backends complete ingestion runs and notify Data Management. A DataStream in `PROVISIONING` may have no results yet. ### How Filter by `data_stream_id`. Paginate using `page_token` from the previous response. Check `status` on each result — `FAILED` runs have errors retrievable via `GET /v1alpha/dataStreams/{data_stream_id}/ingestions/{ingestion_id}/errors`. ### Related operations - `GET /v1alpha/dataStreams/{data_stream_id}/ingestions/{ingestion_id}/errors` — retrieve errors for a specific ingestion run. parameters: - name: dataStreamId in: path required: true schema: type: string description: The DataStream to list ingestions for. Required. UUID v4. - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. Defaults to 50 if not specified. Maximum allowed value is 200. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: ingestion_list /v1alpha/dataStreams/{dataStreamId}/schemaMapping: get: operationId: schema_mapping_get summary: Get Schema Mapping tags: - dataStreams description: |- ### What Retrieves the SchemaMapping for a DataStream, including its lifecycle `status` and the full set of `column_bindings`. ### Why Use this to inspect the current bindings and decide whether to edit them (PUT) or approve the mapping. ### When After the SchemaMapping has been created, at any point in its lifecycle. ### How The caller must have read access on the parent DataStream's advertiser. Returns 404 if the parent DataStream does not exist within the caller's access scope, or if no SchemaMapping has been created for it. Existence of the DataStream is not leaked across organizations. ### Related operations - `PUT /v1alpha/dataStreams/{dataStreamId}/schemaMapping` — create or replace the SchemaMapping. parameters: - name: dataStreamId in: path required: true schema: type: string description: UUID v4 of the parent DataStream. Returns 404 if the DataStream does not exist within the caller's access scope, or if no SchemaMapping has been created for it. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: schema_mapping_get put: operationId: schema_mapping_update summary: Upsert Schema Mapping tags: - dataStreams description: |- ### What Creates or replaces the SchemaMapping for a DataStream, binding the raw columns discovered in delivered files onto VideoAmp's canonical schema fields. Idempotent: the first PUT creates the mapping with `status: DRAFT`; a subsequent PUT replaces its `column_bindings` wholesale (omitting a binding removes it — this is not a partial merge). Output-only fields (`id`, `data_stream_id`, `status`) supplied in the body are ignored. ### Why The mapping tells VideoAmp how to interpret each delivered column. Separating configuration (this endpoint) from commitment (`:approve`) lets a user refine the bindings before locking them in. ### When After a delivery has been inspected and the parent DataStream has advanced to `AWAITING_APPROVAL`. The first PUT creates the mapping; later PUTs edit it while `status` is `DRAFT`. Returns `400` (`FailedPrecondition`) if the DataStream is not `AWAITING_APPROVAL` — it has not been inspected yet, or the mapping is already approved. ### How The caller must have write access on the parent DataStream's advertiser. Each binding's `raw_columns` must be non-empty, unique within the binding, and drawn from the columns discovered in the latest delivery inspection; otherwise 400 is returned naming the offending column. The parent DataStream must exist within the caller's access scope, otherwise 404 is returned. ### Related operations - `GET /v1alpha/dataStreams/{dataStreamId}/schemaMapping` — retrieve the current SchemaMapping. - `POST /v1alpha/dataStreams/{dataStreamId}/schemaMapping:approve` — next step: lock the mapping and start ingestion. parameters: - name: dataStreamId in: path required: true schema: type: string requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp schema_mapping_update --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: schema_mapping_update /v1alpha/dataStreams/{dataStreamId}/schemaMapping:approve: post: operationId: schema_mapping_approve summary: Approve Schema Mapping tags: - dataStreams description: |- ### What Approves the SchemaMapping for a DataStream. This is an irreversible gate: it locks the column bindings (`status` becomes `APPROVED`), triggers downstream ingestion of the delivered files, and advances the parent DataStream through `PROVISIONING` toward `PROVISIONED`. ### Why Approval is the commitment step that separates configuring the mapping (`PUT .../schemaMapping`) from acting on it. Once approved, the bindings are frozen and the delivered data is handed to the ingestion pipeline. ### When After the column bindings have been configured and the parent DataStream is `AWAITING_APPROVAL`. The call is idempotent: if a previous attempt locked the mapping but did not finish advancing the DataStream, calling `:approve` again re-triggers ingestion and completes the transition. Returns `400` (`FailedPrecondition`) if the DataStream is not in `AWAITING_APPROVAL` — either it has not yet been inspected, or it has already advanced past approval — or if no successful delivery inspection exists, or if any required canonical field is left unmapped. Returns `404` if the DataStream is `AWAITING_APPROVAL` but no SchemaMapping has been created for it yet. ### How The caller must have write access on the parent DataStream's advertiser. The mapping must already exist, a successful delivery inspection must be present (it supplies the file list for ingestion), and the delivery configuration must be approved. Every canonical field marked required for the DataStream's type must be bound; otherwise `400` is returned naming the missing fields. ### Related operations - `PUT /v1alpha/dataStreams/{dataStreamId}/schemaMapping` — configure the bindings before approving. - `GET /v1alpha/dataStreams/{dataStreamId}/schemaMapping` — retrieve the current SchemaMapping. parameters: - name: dataStreamId in: path required: true schema: type: string description: UUID v4 of the parent DataStream. Path parameter only — the request has no body fields. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp schema_mapping_approve --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: schema_mapping_approve /v1alpha/reports/{reportId}:createQuery: post: operationId: report_query_create summary: Create Scoped Query for Report tags: - reports description: 'Execute a query against the report''s semantic model, referencing sources and fields from report_context_search. Why: the data-fetching endpoint — returns a result the client renders inline as a chart or table. When: call AFTER report_context_search so the query is grounded in real entities. How: use exact field paths from the context response; never invent names. Prefer a named view over an ad-hoc aggregation when one matches — views carry visualization annotations that drive rendering. For a chart, apply the rendering annotation (bar_chart, line_chart, currency, big_value, etc.). Pass the returned model file path as modelPath. Do NOT include advertiserId filters — scoping is injected server-side from reportId and cannot be widened. One call renders ONE chart or table: to compare a measure across a categorical dimension (networks, platforms, audiences, conversion groups), put that dimension in one query''s groupBy as the series — do NOT issue one call per value; when a question names two breakdowns, split on at most ONE axis and let the other ride as a groupBy series. Do NOT restate returned rows as a prose/Markdown table, and do NOT hand-compute a derived distributional metric (cumulative share, a threshold like ''frequency where half of conversions land'', running total, median, percentile) by accumulating rows in the reply — express it in the query (e.g. a server-side running-total window), or describe what the distribution shows without re-deriving it. On a validation error, read it: usually an unknown field (re-search with more specific phrasing) or bad syntax near reserved keywords, aggregation placement, or dates — correct and retry. Also inspect render_logs on a successful response: a SEVERITY_ERROR entry means the data is valid but the renderer rejected the chosen chart (e.g. too many dimensions for a bar chart) — do NOT report success; fix the rendering annotation the message describes (reduce dimensions, switch chart type, or tag a series) and retry.' parameters: - name: reportId in: path required: true schema: type: string description: report_id is the UUID of the measurement report the query targets. Server-side, advertiser_id and report_id are bound as Credible filterParams from this UUID — callers cannot widen scope by overriding them in the query body. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp report_query_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: report_query_create /v1alpha/reports/{reportId}:searchContext: get: operationId: report_context_search summary: Search Report Semantic Context tags: - reports description: 'Retrieve semantic context (dimensions, measures, views, documentation) scoped to a single measurement report, ranked by the user''s natural-language query. Why: The semantic layer describes the report''s metrics and dimensions in natural language and maps them to exact field paths. Calling this first prevents hallucinating field names in a follow-up query. When: Call FIRST whenever the user asks a data question about the report. How: Pass the user''s question verbatim as naturalLanguageQuery — phrase as a complete sentence (e.g. ''reach by audience over the last week''), not keyword fragments. Review the returned entities: each has a name (exact path to use in a query), entityType (DIMENSION / MEASURE / VIEW), description, and relevance. Read source.docs and source.summary to pick the right source, and use source.filterParams to discover which filter keys report_query_create accepts. A returned view is a grain-matched starting point, not a mandate: run it verbatim only when the breakdown the user asked for is one the view actually produces — if the question needs a split the view does not carry (e.g. a per-audience breakdown when the view is scoped to a single audience or the total), build the query against the same source using the fields this response returns, rather than running the bare view and silently answering a narrower question. If ANY concept from the user''s question has no matching entity, tell the user that data isn''t available for this report instead of guessing field names. Then call report_query_create using the exact names from this response. Do NOT pass advertiserId or filter clauses — scoping is enforced server-side from reportId.' parameters: - name: reportId in: path required: true schema: type: string description: report_id is the UUID of the measurement report whose semantic model (dimensions, measures, views) the caller wants ranked against natural_language_query. Used server-side to scope the search to this single report — the LLM never supplies advertiser_id or report_id filters directly. - name: naturalLanguageQuery in: query required: true schema: type: string description: Natural language query from the end user (what the user typed in the chat). Used by the semantic search layer to rank relevant dimensions, measures, and views. Phrase as a complete sentence or question describing the analysis to perform (e.g. "reach by audience segment over the last week"). responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: report_context_search /v1beta/campaigns: post: operationId: campaign_create summary: Create Campaign tags: - campaigns description: |- Creates a new Campaign for media planning optimization. The campaign groups target audiences, an inventory set, creative durations, and a date range into a single planning unit. **Why**: Set up a new campaign to run reach and frequency optimization against a defined media universe. The campaign is the top-level resource that ties together all planning inputs. **When**: Call when starting a new media planning effort. Requires valid audience IDs, an inventory set ID, and a date range within a single calendar quarter spanning at least 7 days. Use `validate_only=true` to pre-validate inputs without creating. **How**: Submit a Campaign object in the request body. Returns 201 with the created campaign including the server-assigned `id` (UUID) and `status` (NEW). Store the returned `id` for use in subsequent `GET /v1beta/campaigns/{campaign_id}`, `PATCH /v1beta/campaigns/{campaign_id}`, and `DELETE /v1beta/campaigns/{campaign_id}` operations. parameters: - name: validateOnly in: query required: false schema: type: string description: When set to true, validates the request fields and the caller's permissions without creating a campaign. Returns 200 with a preview of the campaign (excluding `id` and `status`, which are only assigned on actual creation). Defaults to `false`. Use for pre-flight validation in UI forms or API integration testing. (default true) requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp campaign_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: campaign_create get: operationId: campaign_list summary: List Campaigns tags: - campaigns description: |- Returns a paginated, filterable list of Campaigns accessible to the caller. Campaigns are the top-level resource in VideoAmp's media planning system, grouping target audiences, an inventory set, and a date range for optimization and reporting. **Why**: Use to discover and manage campaigns before triggering optimization, building campaign selector UIs, or auditing campaign configurations across your organization. **When**: Call when building a campaign picker UI, checking status before scheduling planning, batch-fetching specific campaigns by ID, or paginating through all campaigns in your organization. **How**: All parameters are optional. Narrow results using `status`, `name`, `createdBy`, or `ids` filters. Sort with `orderBy`. Paginate with `pageSize` and `pageToken`. The `total_size` field reflects all matching campaigns across all pages. parameters: - name: advertiserIds in: query required: false schema: type: string description: 'Optional filter by one or more advertiser UUIDs. Each UUID is resolved to agency_advertiser_id internally. All must be advertisers the caller has permission to access. Example: ?advertiserIds=650e8400-e29b-41d4-a716-446655440000' - name: createdBy in: query required: false schema: type: string description: Optional filter by the user ID who created the campaign. Provide the creator's UUID to retrieve only campaigns created by that user. Obtain user UUIDs from the 'created_by' field on existing campaign resources. Combine with other filters such as 'status' or 'name' for more refined results. - name: ids in: query required: false schema: type: string description: 'Optional filter by campaign UUIDs. Pass multiple values as repeated query params: ?ids=uuid1&ids=uuid2. Use for efficient batch retrieval when you already know which specific campaigns you need. Campaigns not found or not accessible to the caller are silently omitted from results rather than causing an error.' - name: name in: query required: false schema: type: string description: Optional filter by campaign name using case-insensitive substring matching on the 'display_name' field. Returns campaigns whose name contains the provided string. Useful for searching when you know part of a campaign name but not its exact ID. - name: orderBy in: query required: false schema: type: string description: 'This field specifies how to order the list results. If no value is provided, the results will be sorted by created_at descending order. Specify the order by providing a comma separated list of ''field_name direction'' strings. Omitted direction defaults to asc. Example: ''created_at desc, display_name'' Accepted Values: - ''status'' - ''display_name'' - ''created_at'' - ''media_start_date'' - ''media_end_date'' Accepted Sort: - ''desc'' - ''asc''' - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. Defaults to 100 if omitted. Maximum value is 200. Use with `pageToken` to paginate through large result sets. Larger values improve throughput for batch workflows; smaller values reduce latency for interactive UIs. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: status in: query required: false schema: type: string description: 'Optional filter by campaign lifecycle status. Omit to return campaigns of all statuses. - STATUS_UNSPECIFIED: Proto zero value. Never returned in responses; omit from requests. When this value or no status filter is provided to list, all campaigns are returned. - NEW: Initial state after creation. All fields mutable. Transitions to PLANNING automatically when optimization runs and associates a media plan allocation. - PLANNING: Optimization complete. Configuration locked — only ''display_name'' may be updated. Transitions managed by system only.' responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: campaign_list /v1beta/campaigns/{campaignId}: delete: operationId: campaign_delete summary: Delete Campaign tags: - campaigns description: |- Deletes a Campaign, removing it from all API responses and downstream workflows. This action cannot be undone through the API — there is no undelete operation. **Why**: Remove campaigns that are no longer needed, were created in error, or have been superseded by a new campaign configuration. **When**: Call when a campaign is no longer required regardless of its current status (both NEW and PLANNING campaigns can be deleted). Verify the campaign exists and confirm its identity via `GET /v1beta/campaigns/{campaign_id}` before deleting. **How**: Supply the campaign UUID as the `campaign_id` path parameter. Returns 204 with an empty body on success. Returns 404 if the campaign does not exist or is not accessible to the caller. parameters: - name: campaignId in: path required: true schema: type: string description: UUID of the Campaign to delete. Obtain this value from the 'id' field in campaign creation responses or list results. Must be a valid UUID v4 format. Returns 404 if the campaign does not exist or is not accessible to the caller. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: campaign_delete get: operationId: campaign_get summary: Get Campaign tags: - campaigns description: |- Returns the complete Campaign resource for a single known campaign ID. Use this endpoint when you already have the campaign UUID and need to retrieve full details including configuration, status, and metadata. **Why**: Retrieve a specific campaign directly without filtering through paginated list results. Use to verify campaign status before downstream operations such as plan creation, reach curve generation, or deletion. **When**: Call when you need to confirm a campaign exists and check its current state before operating on it, display full campaign details in a UI, or refresh a cached campaign record. **How**: Supply the campaign UUID as the `campaign_id` path parameter. The response includes all campaign fields. Returns 404 if the campaign does not exist or is not accessible to the caller. parameters: - name: campaignId in: path required: true schema: type: string description: UUID of the Campaign to retrieve. Obtain this value from the 'id' field in campaign creation responses or list results. Must be a valid UUID v4 format. Returns 404 if the campaign does not exist or is not accessible to the caller. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: campaign_get patch: operationId: campaign_update summary: Update Campaign tags: - campaigns description: This endpoint can update a new campaign.If a campaign starts, you can only update its display name. parameters: - name: campaignId in: path required: true schema: type: string description: This field is the unique identifier for the Campaign (UUID). requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp campaign_update --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: campaign_update /v1beta/inventories: get: operationId: inventory_list summary: List Inventories tags: - inventories description: |- Returns a paginated list of inventory sets accessible to the caller. **Why**: Discover available inventory sets before creating campaigns or plans. Each inventory set defines the media universe (titles and placements) available for optimization. **When**: Call when building an inventory picker UI, searching for a specific inventory set by name, or discovering what inventory sets are available in your organization. **How**: All parameters are optional. Sort with `orderBy` (defaults to `created_at desc`). Paginate with `pageSize` and `pageToken`. The `total_size` field reflects all matching inventory sets across all pages. Results include summary fields only — use `inventory_get` / GET /v1beta/inventories/{inventoryId} for full title details. **Caution**: `inventory_get` has no bulk mode — answering a question that needs per-title data (e.g. environment, network) across many of the sets returned here means calling `inventory_get` once per set. That is expensive at scale; confirm scope with the user before fetching details for more than a handful of sets, rather than fanning out across every result automatically. **Next Steps**: Use the returned `id` as `inventory_set_id` when creating a Campaign (`POST /v1beta/campaigns`) or Rate Card. parameters: - name: orderBy in: query required: false schema: type: string description: 'This field specifies how to order the list results. If no value is provided, the results will be sorted by created_at descending order. Specify the order by providing a comma separated list of ''field_name direction'' strings. Omitted direction defaults to asc. Example: ''created_at desc, display_name'' Accepted Values: - ''currency_of_record'' - ''display_name'' - ''created_at'' Accepted Sort: - ''desc'' - ''asc''' - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. Defaults to 100 when omitted. Maximum value is 1000. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: inventory_list /v1beta/inventories/{inventoryId}: get: operationId: inventory_get summary: Get Inventory tags: - inventories description: |- Returns the complete inventory set definition including all titles and dimension configuration. **Why**: Retrieve the full inventory set to inspect available titles, their custom parameters, and environment assignments. Required before creating plans to understand what media universe is available. **When**: Call when you need the full title list for a known inventory set — for example, to build rate card overrides or validate constraint title_filters. Use LIST for discovery, GET for full details. **How**: Supply the inventory set UUID as the `inventoryId` path parameter. Response includes the complete `titles` array and `dimension_names` configuration (not available in LIST). Returns 404 if not found or not accessible to the caller — these cases are intentionally indistinguishable. **Caution**: `ListInventories` has no per-title or per-environment summary, so answering a cross-set question (e.g. "which sets have no Linear titles?") by calling this endpoint once per set is expensive — for large accounts this means dozens of calls, some returning hundreds of titles each. Before calling this on more than a handful of sets in one request, confirm scope with the user (e.g. narrow by name, currency of record, or a smaller candidate list) rather than fetching every set automatically. parameters: - name: inventoryId in: path required: true schema: type: string description: UUID of the inventory set to retrieve. Returns 404 if the inventory does not exist or is not accessible to the caller. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: inventory_get patch: operationId: inventory_update summary: Update Inventory Dimension Names tags: - inventories description: |- Updates the dimension name labels for an inventory set's custom parameters. **Why**: Rename dimension labels to align with how your team describes the inventory (e.g., relabel CUSTOM_PARAM_1 as NETWORK). **When**: After initial inventory ingestion, before sharing the inventory set with downstream consumers. **How**: PATCH with the new `dimension_names` array. Existing labels are replaced entirely. parameters: - name: inventoryId in: path required: true schema: type: string description: UUID of the inventory set to update. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp inventory_update --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: inventory_update /v1beta/inventories/{inventoryId}/rateCards: post: operationId: rate_card_create summary: Create Rate Card tags: - inventories description: |- Creates a new rate card with rates for an inventory set. **Why**: Define pricing for inventory titles before creating a plan. Plans require rates (via rate card or inline overrides) to calculate budget allocations. **When**: Call after creating an inventory set and before creating plans. Use `validate_only=true` to pre-validate Kantar rate ranges without persisting. **How**: Submit the rate card in the request body with `display_name` and at least one of: `rates` (array of title_id/rate_type/rate) or `default_rate` (auto-populates from historical Kantar data for titles matching the filter). Returns 201 with the created rate card. parameters: - name: inventoryId in: path required: true schema: type: string description: UUID of the inventory set this rate card belongs to. - name: validateOnly in: query required: false schema: type: boolean description: When true, validates Kantar rates are within the acceptable range ($1.00–$10,000.00) without creating the rate card. Returns 200 if all rates are valid, or 400 with per-title violation details if any rate is out of range. (default true) requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp rate_card_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: rate_card_create get: operationId: rate_card_list summary: List Rate Cards tags: - inventories description: |- Returns a paginated list of rate cards for an inventory set. **Why**: Discover available rate cards before creating a plan. Plans reference rate cards by ID to provide default rates for optimization. **When**: Call when building a rate card picker UI or checking what rates are available for a specific inventory set. **How**: Supply the inventory set UUID as a path parameter. Optionally filter by `advertiser_id` to see advertiser-scoped rate cards (omit to see organization-level cards only). Sort with `orderBy` and paginate with `pageSize`/`pageToken`. parameters: - name: inventoryId in: path required: true schema: type: string description: UUID of the inventory set to list rate cards for. - name: advertiserId in: query required: false schema: type: string description: Filter by advertiser UUID. If not provided, only organization-level rate cards are returned. - name: orderBy in: query required: false schema: type: string description: 'Specify the order and direction of the list with values separated by commas. Omitted direction defaults to asc. Example: ''created_at desc'' Accepted Values: - ''display_name'' - ''created_at'' - ''created_by'' - ''updated_at'' - ''updated_by'' Accepted Sort: - ''desc'' - ''asc''' - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: rate_card_list /v1beta/inventories/{inventoryId}/rateCards/{rateCardId}: delete: operationId: rate_card_delete summary: Delete Rate Card tags: - inventories description: |- Deletes a rate card and its rates. This action cannot be undone. **Why**: Remove rate cards that are no longer needed or were created in error. **When**: Call when a rate card is obsolete. Existing plans that reference this rate card are not affected — their rates are stored independently. **How**: Supply the inventory set UUID and rate card UUID as path parameters. Returns 204 on success. Returns 404 if either does not exist or is not accessible. parameters: - name: inventoryId in: path required: true schema: type: string description: UUID of the inventory set. - name: rateCardId in: path required: true schema: type: string description: UUID of the rate card. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: rate_card_delete get: operationId: rate_card_get summary: Get Rate Card tags: - inventories description: |- Returns a rate card with its rates. **Why**: Retrieve the full rate card to inspect rates before using it in a plan or to verify it was created correctly. **When**: Call when you need the complete rate details for a specific rate card. Use LIST for discovery. **How**: Supply the inventory set UUID and rate card UUID as path parameters. Returns 404 if not found or not accessible to the caller — these cases are intentionally indistinguishable. parameters: - name: inventoryId in: path required: true schema: type: string description: UUID of the inventory set. - name: rateCardId in: path required: true schema: type: string description: UUID of the rate card. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: rate_card_get patch: operationId: rate_card_update summary: Update Rate Card tags: - inventories description: |- Updates an existing rate card. **Why**: Adjust rates, change advertiser scope, or update the display name of an existing rate card. **When**: When rates need correction or the rate card should be reassigned to a different advertiser. **How**: PATCH with the updated `rate_card` body. Supports partial updates. If `rates` are provided, existing rates are replaced entirely; if omitted, existing rates are kept. `advertiser_id` is always overridden from the request — include the current value to preserve it, or omit to clear the advertiser scope (making the rate card organization-level). parameters: - name: inventoryId in: path required: true schema: type: string description: UUID of the inventory set. - name: rateCardId in: path required: true schema: type: string description: UUID of the rate card to update. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp rate_card_update --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: rate_card_update /v1beta/inventories/{inventoryId}/reachCurves: post: operationId: reach_curve_create summary: Create Custom Reach Curve tags: - inventories description: |- Creates a custom reach curve for use in media plan optimization. The curve is processed asynchronously — poll via GET to check status. **Why**: Provide custom audience reach data for Digital inventory titles when default forecasted reach curves are unavailable or need to be overridden. **When**: Call after creating an inventory set and before creating plans that need custom reach data. Only Digital environment titles are supported. Use `validate_only=true` to pre-validate inputs. **How**: Submit the reach curve data with `audience_id`, `start_date`/`end_date` (within a single quarter), and `title_curves` (4–25 impression/reach data points per title). Returns 201 with initial status QUEUED. Poll `GET /v1beta/inventories/{inventoryId}/reachCurves/{reachCurveId}` until status is READY or FAILED. parameters: - name: inventoryId in: path required: true schema: type: string description: UUID of the inventory set this reach curve belongs to. - name: validateOnly in: query required: false schema: type: boolean description: When true, validates the required fields, title IDs, and audience accessibility without creating the reach curve. Returns 200 if valid, 400 with details if not. (default true) requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp reach_curve_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: reach_curve_create get: operationId: reach_curve_list summary: List Custom Reach Curves tags: - inventories description: |- Returns a paginated list of custom reach curves for an inventory set. **Why**: Discover existing custom reach curves and their processing status before creating plans or to audit what curves have been uploaded. **When**: Call to find available reach curves for a specific inventory set, or to monitor processing status across multiple curves. **How**: Supply the inventory set UUID as a path parameter. Sort with `orderBy` (created_at or status). Paginate with `pageSize`/`pageToken`. Use GET for error details on FAILED curves. parameters: - name: inventoryId in: path required: true schema: type: string description: UUID of the inventory set to list reach curves for. - name: orderBy in: query required: false schema: type: string description: 'Specify the order and direction of the list with values separated by commas. Omitted direction defaults to asc. Example: ''created_at desc'' Accepted Values: - ''created_at'' - ''status'' Accepted Sort: - ''desc'' - ''asc''' - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: reach_curve_list /v1beta/inventories/{inventoryId}/reachCurves/{reachCurveId}: delete: operationId: reach_curve_delete summary: Delete Custom Reach Curve tags: - inventories description: |- Deletes a custom reach curve. This action cannot be undone. **Why**: Remove reach curves that are no longer needed, were created in error, or have been superseded by updated data. **When**: Call when a reach curve is obsolete. Existing plans that were optimized using this curve are not affected. **How**: Supply the inventory set UUID and reach curve UUID as path parameters. Returns 204 on success. Returns 404 if either does not exist or is not accessible. parameters: - name: inventoryId in: path required: true schema: type: string description: UUID of the inventory set. - name: reachCurveId in: path required: true schema: type: string description: UUID of the reach curve. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: reach_curve_delete get: operationId: reach_curve_get summary: Get Custom Reach Curve tags: - inventories description: |- Returns the full details of a custom reach curve including status and errors. **Why**: Check the processing status of a reach curve after creation, or retrieve the complete curve data including any errors on FAILED curves. **When**: Poll after creation to check if ingestion completed (QUEUED → READY/FAILED). Also use to inspect error details when status is FAILED. **How**: Supply the inventory set UUID and reach curve UUID as path parameters. Returns 404 if not found or not accessible to the caller — these cases are intentionally indistinguishable. parameters: - name: inventoryId in: path required: true schema: type: string description: UUID of the inventory set. - name: reachCurveId in: path required: true schema: type: string description: UUID of the reach curve. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: reach_curve_get /v1beta/library/datasourceMetadataSearch: post: operationId: datasource_metadata_search summary: Search Datasource Metadata tags: - library description: |- ### What Queries actual data values for a datasource, returning distinct metadata rows based on the requested fields and filters. Supports pagination, search, and ordering. The endpoint automatically injects required fields (parent filters, supplemental labels) into the response based on the datasource schema hierarchy. This means requesting a child field will automatically include its required parent fields. ### Why Retrieves the concrete values available for datasource filters — the data that populates filter dropdowns, catalog tables, and airing selection modals. **Business Scenarios:** - User browses available pixels for VA_PIXEL datasource: `distinct_fields: ["pixel_id"]` returns pixel IDs + names - Agent fetches campaigns under a specific pixel: `distinct_fields: ["campaign_id"], filters: [{name: "pixel_id", values: ["123"], operator: "in"}]` - User searches for airings on a linear network for tune-in CG: `distinct_fields: ["program_name"], search: "NFL"` ### When Call after calling `GET /v1beta/library/datasourceSchema` to discover the available fields and their hierarchy. **Important:** The schema determines which fields are valid for `distinct_fields` and `filters`. Required parent filters are auto-injected, but providing them explicitly in `filters` narrows results. **Do NOT use when:** - You need to discover the field structure (use `GET /v1beta/library/datasourceSchema` first) - You need the list of available datasource types (use `POST /v1/library/datasourceTypeOptionsSearch`) **Next Steps:** Use the returned metadata values as filter selections when creating or editing Datasource Groups or Conversion Groups. ### How **Discovery Pattern:** Call schema first to learn fields. Then call this endpoint with desired `distinct_fields`. Use `filters` to narrow results (e.g., filter by parent hierarchy value). Use `search` for text matching across fields. Paginate with `page_token` from previous response. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp datasource_metadata_search --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: datasource_metadata_search /v1beta/library/datasourceSchema: get: operationId: datasource_schema_get summary: Get Datasource Schema tags: - library description: |- ### What Returns the hierarchical schema for a specific datasource type, describing all available filter hierarchies, rule filter hierarchies, and supporting metadata fields. The schema is a tree structure where each node represents a filterable field. Nodes can have children (forming a hierarchy), supporting data (labels, links, metrics), and a required flag indicating whether the filter must be provided. ### Why Discovers the structure of a datasource before querying its metadata. The schema tells you which fields exist, how they relate hierarchically, and which are required. **Business Scenarios:** - Agent discovers that VA_PIXEL has a hierarchy: advertiser_id → source_type_id → campaign_id → line_item_id - User learns that NATIONAL_LINEAR_BROADCAST_AND_CABLE requires `network` as a mandatory filter - Agent identifies which fields are available as `distinct_fields` for `DatasourceMetadataSearch` ### When Call after selecting a `datasource_type` from `POST /v1/library/datasourceTypeOptionsSearch` for a Datasource Group. If building a Conversion Group, call after selecting a `data_provider_id` from `POST /v1/library/conversionDataProviderOptionsSearch` — each provider has a different schema. Call before `POST /v1beta/library/datasourceMetadataSearch`. **Do NOT use when:** - You need the actual data values (use `POST /v1beta/library/datasourceMetadataSearch`) - You need the list of available datasource types (use `POST /v1/library/datasourceTypeOptionsSearch`) **Next Steps:** Use field names from `datasource_filter_hierarchies` as `distinct_fields` and `filters` in `POST /v1beta/library/datasourceMetadataSearch`. ### How **Discovery Pattern:** Call with datasource_type (+ data_provider_id for CGs). Parse `datasource_filter_hierarchies` to understand the filter tree. Fields marked `is_required: true` must be included when querying metadata. Use `supporting_data` fields to get human-readable labels alongside IDs. parameters: - name: advertiserId in: query required: false schema: type: string description: '**Required** Advertiser (business unit) to scope results to. Obtain available ids by calling ''GET /v1/me?membership_kinds=ADVERTISER'' and using the ''id'' field from the ''memberships'' array.' - name: agencyAdvertiserId in: query required: false schema: type: string description: '**Deprecated** Ignored if advertiser_id is provided.' - name: currencyOfRecord in: query required: false schema: type: string description: '**Conditionally Required** when ''datasource_type=NATIONAL_LINEAR_BROADCAST_AND_CABLE'' or ''data_provider_id=linear_tune_in''. Retrieve valid options from ''GET /external/v1/currency-of-record''. When provided, ''data_latency'' must also be specified. For ConversionGroups with ''data_provider_id=linear_tune_in'', use 26.' - name: dataLatency in: query required: false schema: type: string description: '**Conditionally Required** when ''currency_of_record'' is provided. PRELIMINARY and NEXT_NEXT_DAY are only available when used with NATIONAL_LINEAR_BROADCAST_AND_CABLE datasources. When ''data_provider_id=linear_tune_in'', use FINAL. - DATA_LATENCY_UNSPECIFIED: No selection; Default value. - FINAL: Fully reconciled data with complete accuracy. Available 2-3 weeks after broadcast. **DSGs:** Valid when reporting_scope=AD_MEASUREMENT with KANTAR_COMMINGLE or NATIONAL_LINEAR_AND_BROADCAST_CABLE datasources; or reporting_scope=CONTENT_MEASUREMENT. **CGs:** Required when data_provider_id=linear_tune_in; not valid otherwise. - PRELIMINARY: Fast-processed data, 3-4 days after broadcast, subject to revisions. **DSGs:** Valid when reporting_scope=CONTENT_MEASUREMENT and currency_of_record supports it. **CGs:** Not valid. - NEXT_NEXT_DAY: Near real-time data, ~2 days after broadcast. Volatile. **DSGs:** Valid when reporting_scope=CONTENT_MEASUREMENT and currency_of_record supports it. **CGs:** Not valid.' - name: dataProviderId in: query required: false schema: type: string description: '**Conditionally Required** when ''datasource_type=CONVERSIONS''. Used for ConversionGroups (CGs). Obtain valid values by calling ''POST /v1/library/conversionDataProviderOptionsSearch'' and using the ''value'' field from results.' - name: datasourceType in: query required: true schema: type: string description: Required. The datasource type to retrieve the schema for. Used for DSGs. CGs will use CONVERSIONS as the datasource type and require data provider id to be specified. Obtain valid values by calling 'POST /v1/library/datasourceTypeOptionsSearch' and using the 'value' field from results. - name: reportingScope in: query required: false schema: type: string description: 'Required when DatasourceType is not CONVERSIONS. Should be same value used when calling ''POST /v1/library/datasourceTypeOptionsSearch''. Use AD_MEASUREMENT to query for datasource types used to measure impressions. Use CONTENT_MEASUREMENT to query for datasource types used to measure content viewership. - REPORTING_SCOPE_UNSPECIFIED: Value when unspecified. Should not be used directly. - AD_MEASUREMENT: For Datasource Groups to be used for advertising campaign measurement and attribution analysis. Groups within this scope contain vendor measurement data focused on ad exposure, reach, frequency, and campaign effectiveness metrics. - CONTENT_MEASUREMENT: For Datasource Groups to be used for content viewership and audience measurement analysis. Groups within this scope contain viewing data focused on program ratings, audience composition, and content consumption patterns.' responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: datasource_schema_get /v1beta/plans: post: operationId: plan_create summary: Create Plan tags: - plans description: |- Creates a new media plan optimization scenario. The plan defines a budget allocation strategy across inventory titles and constraints to maximize reach, impressions, or audience concentration for a campaign. **Why**: Run reach and frequency optimization against a campaign's inventory set. Plans are the core output of the media planning workflow, producing optimized budget allocations. Use `OBJECTIVE_FORECAST_ONLY` to skip optimization and forecast reach, impressions, and frequency directly from a fixed unit allocation — useful for secondary-read use cases where the buy has already been committed in another currency. **When**: Call after creating a campaign with valid audiences and an inventory set. Requires a campaign ID, a budget, and rates (via rate card or overrides). Use `validate_only=true` to pre-validate inputs without triggering optimization. **How**: Submit the plan configuration in the request body. Returns 201 with the created plan including server-assigned `id` and initial `status` (QUEUED). The plan processes asynchronously — poll `GET /v1beta/plans/{plan_id}` to check status (QUEUED → PROCESSING → READY or FAILED). **Forecast-only workflow** (skip optimization, forecast from fixed units): 1. Set `primary_objective.objective_type` to `OBJECTIVE_FORECAST_ONLY`. Set `budget` to `"0"`. 2. Add one `FIXED_INVESTMENT_UNITS` constraint per title: `constraint_type: FIXED_INVESTMENT_UNITS`, `operator: EQUAL`, `goal: ""`, `creative_duration_seconds`, and `title_filters` with `title_filter_type: ID`. 3. Omit `target_budget`, saturation rules, and frequency rules — all are rejected with HTTP 400 when combined with `OBJECTIVE_FORECAST_ONLY`. 4. Do not combine `OBJECTIVE_FORECAST_ONLY` with any `OBJECTIVE_MAXIMIZE_*` objective on the same plan. 5. Poll `GET /v1beta/plans/{plan_id}` until `status` is `READY`, then download results from the `output` URL. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp plan_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: plan_create get: operationId: plan_list summary: List Plans tags: - plans description: |- Returns a paginated, filterable list of Plans accessible to the caller. Plans represent optimization scenarios that allocate budget across campaigns and inventory titles. **Why**: Discover and manage plans across your organization. Use to find completed plans for result retrieval, monitor processing status, or audit plan configurations. **When**: Call when building a plan management UI, checking optimization status across multiple plans, or filtering plans by status, creator, or campaign. **How**: All parameters are optional. Narrow results using `statuses`, `displayNames`, `createdBy`, `campaignIds`, or `inventorySetIds` filters. Sort with `orderBy` (defaults to `created_at desc`). Paginate with `pageSize` and `pageToken`. The `total_size` field reflects all matching plans across all pages. parameters: - name: campaignIds in: query required: false schema: type: array items: type: string description: Optional filter by campaign UUID. Returns plans that include the specified campaigns. Pass multiple values as repeated query params for OR logic. - name: createdBy in: query required: false schema: type: array items: type: string description: Optional filter by the user ID who created the plan. Provide creator UUIDs to retrieve only plans created by those users. Pass multiple values as repeated query params for OR logic. - name: displayNames in: query required: false schema: type: string description: Optional filter by plan name using case-insensitive substring matching on the display_name field. Returns plans whose name contains the provided string. Pass multiple values as repeated query params for OR logic. - name: ids in: query required: false schema: type: string description: 'Optional filter by plan UUIDs. Pass multiple values as repeated query params: ?ids=uuid1&ids=uuid2. Use for efficient batch retrieval when you already know which specific plans you need. Plans not found or not accessible to the caller are silently omitted from results rather than causing an error.' - name: inventorySetIds in: query required: false schema: type: array items: type: string description: Optional filter by inventory set UUID. Returns plans associated with the specified inventory sets. Pass multiple values as repeated query params for OR logic. - name: orderBy in: query required: false schema: type: string description: 'This field specifies how to order the list results. If no value is provided, the results will be sorted by created_at descending order. Specify the order by providing a comma separated list of ''field_name direction'' strings. Omitted direction defaults to asc. Example: ''created_at desc, display_name'' Accepted Values: - ''status'' - ''failure_msg'' - ''display_name'' - ''inventory_set_id'' - ''budget'' - ''minimum_investment'' - ''created_at'' - ''created_by'' Accepted Sort: - ''desc'' - ''asc''' - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. Defaults to 100 when omitted. Maximum value is 1000. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: statuses in: query required: false schema: type: string description: 'Optional filter by plan processing status. Use to find completed plans (READY), in-progress plans (PROCESSING/QUEUED), or failed plans (FAILED). Pass multiple values for OR logic. - STATUS_UNSPECIFIED: Status is unspecified. Default proto3 zero value. Do not use in client logic. - QUEUED: The plan has been created and its required data dependencies are being resolved. Transitions to PROCESSING once all required data is available. - PROCESSING: The plan optimization is actively running. Processing time varies based on plan complexity (number of titles, constraints, and audience combinations). - READY: The plan optimization completed successfully. Results are available via the output field which contains a presigned S3 URL for downloading the optimized allocation. - FAILED: The plan optimization failed. Check `failure_msg` for a human-readable error message and `status_info` for structured error details (code, status, diagnostics). Common causes include invalid inventory data, insufficient rates, or optimizer errors. Fix the configuration and create a new plan to retry. - DRAFT: The plan has been created and allows further modification' responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: plan_list /v1beta/plans/{planId}: delete: operationId: plan_delete summary: Delete Plan tags: - plans description: |- Deletes a Plan, removing it from all API responses. This action cannot be undone through the API — there is no undelete operation. **Why**: Remove plans that are no longer needed, were created in error, or have been superseded by a new optimization scenario. **When**: Call when a plan is no longer required regardless of its current status (QUEUED, PROCESSING, READY, and FAILED plans can all be deleted). Verify the plan exists via `GET /v1beta/plans/{plan_id}` before deleting. **How**: Supply the plan UUID as the `plan_id` path parameter. Returns 204 with an empty body on success. Returns 404 if the plan does not exist or is not accessible. In-flight optimization may continue briefly after deletion but will not produce results. parameters: - name: planId in: path required: true schema: type: string description: UUID of the Plan to delete. Obtain this value from the 'id' field in plan creation responses or list results. Must be a valid UUID v4 format. Returns 404 if the plan does not exist or is not accessible to the caller. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: plan_delete get: operationId: plan_get summary: Get Plan tags: - plans description: |- Returns the complete Plan resource for a single known plan ID. Use this endpoint when you already have the plan UUID and need to retrieve full details including status, output, and configuration. **Why**: Retrieve plan details to check optimization status, access results (presigned URL when READY), or review the plan configuration. Essential for polling async plan processing. **When**: Call after creating a plan to poll for completion (QUEUED → PROCESSING → READY/FAILED). Also use to retrieve a specific plan's configuration or download optimized results. **How**: Supply the plan UUID as the `plan_id` path parameter. When status is READY, the response includes an `output` field with a presigned S3 URL for downloading results. Returns 404 if the plan does not exist or is not accessible. parameters: - name: planId in: path required: true schema: type: string description: UUID of the Plan to retrieve. Obtain this value from the 'id' field in plan creation responses or list results. Must be a valid UUID v4 format. Returns 404 if the plan does not exist or is not accessible to the caller. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: plan_get /v2/adMeasurements: post: operationId: measurement_create summary: Create Measurement report tags: - adMeasurements description: |- Create Measurement report to analyze campaign performance across audiences and data sources. Calculates reach, frequency, impressions, and effectiveness metrics. **What This Does**: Creates Measurement report configuration defining audiences, data sources, time period, report type. Processes async, delivers results to S3. Supports one-time and recurring. **Prerequisites**: (1) Ready audiences, (2) Data source access, (3) S3 bucket, (4) CoR, (5) Measurement request type. **Basic Usage**: Identify audience IDs → Set period → Select `streams` → Choose `type` → Configure sources → POST → Get ID → Poll `GET /v2/adMeasurements/{id}` → Download from S3. **Recurring**: Basic + unique `external_id` + `delivery_schedule` + `status` active. Auto-generates outputs on schedule. **Processing**: Returns immediately if successful with general report's metadata. Async computation (30min-4hrs). Becomes "ready"/"failed". Results as CSV/Parquet to S3. **Important**: Audiences share the same CoR. Sources accessible. Recurring needs a unique `external_id`. Suspended can't reactivate. `validate_only=true` for dry-run. **Idempotency**: NOT supported. Use unique `external_id` for no duplicates. Check existing before creating. **Content measurement datasource constraints**: Reports whose data sources include a constrained content-measurement datasource type must satisfy that type's content gates on five categories — a supported audience, the required time shift, a supported Currency of Record (`viewership_type_id`), supported dimension sets, and at least one supported metric type — else a 400 with `MRC_0152`–`MRC_0157` (see the 400 response and the `DataSource.type` field). The supported values for each category are determined at request time and are not enumerated by this API. **Resources**: https://help.videoamp.dev/en/articles/11988861-create-an-ad-measurement-report | support@videoamp.com. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp measurement_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: measurement_create get: operationId: measurement_list summary: List Measurement reports with filtering and pagination tags: - adMeasurements description: |- Retrieve a paginated list of Measurement reports, with comprehensive filtering and sorting capabilities. Measurement reports analyze advertising campaign effectiveness across specified audiences, data sources, and time periods, producing reach, frequency, and conversion metrics. **What**: Returns a list of Measurement reports with their current status, configuration details, and metadata. Each Measurement report represents a configured analysis job that calculates advertising performance metrics across linear TV, streaming, digital, and other media. **Why**: Essential for managing your Measurement request workflow, monitoring analysis progress, tracking historical Measurement reports, and coordinating campaign reporting activities. Use this endpoint to discover completed Measurement reports for result retrieval, monitor processing status, or maintain governance. **When**: Use this endpoint when you need to: - Monitor the status of submitted Measurement requests - Retrieve historical Measurement configurations for reference or replication - Filter Measurement reports by advertiser, creator, or time period for reporting purposes - Implement pagination for large inventories - Build Measurement management interfaces or automated workflows - Audit Measurement report activity across your organization **How**: Requires valid authentication token with appropriate permissions. Supports extensive filtering by advertiser, creator, request type, and creation date. Results are automatically scoped to your organization's accessible Measurement reports. Use pagination tokens for large result sets. Combine with the individual Measurement report retrieval endpoint to access detailed results and output files. **Related Resources**: - `GET /v2/adMeasurements/{id}` - Retrieve specific Measurement report details - `POST /v2/adMeasurements` - Create new Measurement reports - `DELETE /v2/adMeasurements/{id}` - Delete Measurement reports. parameters: - name: advertiser_id in: query required: false schema: type: string description: 'Filter Measurement reports belonging to specific advertisers. Supports multiple advertisers. **Format**: UUID v4 **Important**: - This parameter accepts **UUID v4 format only** - For legacy integer advertiser IDs, use the agency_advertiser_id field in the request body instead - UUIDs are case-insensitive but typically lowercase **Multiple Values**: Repeat parameter for multiple advertisers (e.g., `?advertiser_id=uuid1&advertiser_id=uuid2`) **Authorization**: Automatically filtered to advertisers you have access to via IAM permissions **Use Case**: - Client-specific reporting - Multi-advertiser campaign analysis - Agency-level Measurement report aggregation **Example**: `?advertiser_id=2575fa26-9115-4972-be28-eb2e556e2350&advertiser_id=550e8400-e29b-41d4-a716-446655440000`.' - name: created_by in: query required: false schema: type: string description: 'Filter by Measurement report creator''s user ID. Supports multiple user IDs. **Format**: UUID v4 **Source**: User IDs from IAM system; obtain from user profile or list users endpoint **Multiple Values**: Repeat parameter for multiple creators (e.g., ?created_by=uuid1&created_by=uuid2) **Use Case**: - Audit Measurement reports created by specific users - Filter team member''s Measurement reports - Compliance and governance reporting **Authorization**: Only returns Measurement reports you have permission to access **Example**: `?created_by=550e8400-e29b-41d4-a716-446655440000&created_by=660e8400-e29b-41d4-a716-446655440001`.' - name: creator_name in: query required: false schema: type: string description: 'Filter by Measurement report creator''s display name using fuzzy text search. Supports multiple names. **Matching Behavior**: Case-insensitive partial matching across first name, last name, and full name **Search Strategy**: - Searches ''John'' matches ''John Smith'', ''Johnny Doe'' - Searches ''Smith'' matches ''John Smith'', ''Jane Smith'' - Searches ''John Smith'' matches ''John Smith'' (full name) **Multiple Values**: Repeat parameter for OR logic (e.g., ?creator_name=John%20Smith&creator_name=Jane%20Doe) **Special Characters**: URL-encode spaces **Use Case**: Human-readable search when user IDs are unknown **Performance**: Slightly slower than `created_by` filter due to text search **Example**: `?creator_name=John%20Smith&creator_name=Jane%20Doe`.' - name: eligiblePostProcessesType in: query required: false schema: type: string description: 'Filter by reports eligible for post-processing. **Available Values**: - LIFT - Reports that meet all eligibility criteria for Linear Lift analysis **Multiple Values**: Repeat parameter for OR logic (e.g., `?eligiblePostProcessesType=LIFT` will return reports eligible for Linear Lift) **Eligibility Criteria**: - Agency has < 5 complete Linear Lift runs this calendar year - Report has AlwaysOnOutcomes feature flag - Report has non-affinity conversion datasource - Latest run is complete and within 30 days - Report has no previous successful Linear Lift runs - Schedule status is complete - Report has linear datasource (first_party_ad_schedule, kantar_commingle, or kantar_commingle_daily) **Performance**: This filter requires an additional API call to RCAPI''s eligibility service. Response time may increase by 500-1000ms depending on agency size. **Note**: This filter checks eligibility at query time. A report''s eligibility status may change based on agency quotas and report state. **Example**: `?eligiblePostProcessesType=LIFT` - LINEAR_LIFT: Deprecated: use LIFT instead. ETL handles LINEAR_LIFT vs DIGITAL_LIFT distinction.' - name: external_id in: query required: false schema: type: string description: 'Filter by external campaign or study identifier from your system. **Purpose**: Link VideoAmp Measurement reports to external campaign management systems **Format**: Alphanumeric string (your system''s format) **Uniqueness**: Should be unique per organization but not enforced by API **Use Case**: - Integration with external workflow systems - Cross-platform campaign tracking - Recurring Measurement request identification **Exact Match**: Performs exact string matching (case-sensitive) **Example**: ''?external_id=campaign_rf_q4_2024''.' - name: id in: query required: false schema: type: string description: 'Filter results to Measurement reports matching this specific request identifier. **Format**: UUID v4 **Source**: Returned by ''POST /v2/adMeasurements'' or found in previous list responses **Use Case**: Direct lookup when you have the exact Measurement report ID **Behavior**: Returns array with single item if found, empty array if not found or not accessible **Performance**: Optimized for single-item retrieval (typically <50ms) **Example**: ''?id=58b97c6b-a5a0-4b21-a421-ab7b401c6c27''.' - name: latestRequestDisplayStatus in: query required: false schema: type: string description: 'Filter by the display status of the latest request. **Available Values**: - ''Success'' - Completed successfully - ''Failed'' - Failed to complete - ''Processing'' - Currently processing **Example**: ''?latestRequestDisplayStatus=Success''' - name: name in: query required: false schema: type: string description: 'Filter by Measurement report name using substring-based text search. **Matching Behavior**: Case-insensitive partial substring matching **Search Strategy**: Searches within Measurement report ''name'' field **Examples**: - ''?name=q4'' - Matches ''Q4 2024 Campaign'', ''Q4 Brand Study'', etc. - ''?name=brand%20awareness'' - Matches any name containing ''brand awareness'' **Special Characters**: URL-encode spaces and special characters **Performance**: Indexed search, typically returns in <100ms **Combination**: Can be combined with other filters for refined search.' - name: order_by in: query required: false schema: type: string description: 'Sort field and direction for result ordering. **Supported Fields**: - ''created_at'' - Sort by creation date - ''latest_request_created_at'' - Sort by latest request date **Supported Directions**: - ''asc'' - Ascending order - ''desc'' - Descending order **Default**: ''created_at desc'' if not specified **Syntax**: ''{field_name} {direction}'' (space-separated) **Examples**: - ''?order_by=created_at%20desc'' - Newest first - ''?order_by=created_at%20asc'' - Oldest first' - name: ownership in: query required: false schema: type: string description: 'Filter by report ownership. **Available Values**: - ''OWNED'' (default) - Reports owned by a business entity the user is explicitly assigned to - ''SHARED'' - Reports shared with the user by another business entity **Default Behavior**: When omitted, defaults to ''OWNED'' and returns only the reports from the business entities the user is explicitly assigned to. **Example**: ''?ownership=SHARED'' - OWNED: Reports owned by a business entity the user is explicitly assigned to (default). - SHARED: Reports shared with the user by another business entity.' - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: page_size in: query required: false schema: type: string description: 'Number of Measurement reports to return per page. **Valid Range**: 1-100 **Default**: 100 (system-optimized value) **Recommendations**: - Interactive applications: 25-50 for balanced performance - Batch/background operations: 50-100 for efficiency - Mobile applications: 10-25 for reduced bandwidth **Performance**: Larger page sizes increase response time linearly. A page_size of 100 typically returns in 200-500ms depending on result complexity. **Example**: `?page_size=25`.' - name: postProcessesType in: query required: false schema: type: string description: 'Filter by existing (completed) post-processes. **Available Values**: - ''LIFT'' **Example**: ''?postProcessesType=LIFT'' - LINEAR_LIFT: Deprecated: use LIFT instead. ETL handles LINEAR_LIFT vs DIGITAL_LIFT distinction.' - name: type in: query required: false schema: type: string description: 'Filter by Measurement request type. Each type produces different output formats and metrics. **Available Types**: _For Ad Measurement requests_: - ''ESSENTIALS'': Audience Essentials - ''ADVANCED_RF'': Advanced Reach & Frequency - ''ADVANCED_RF_OUTCOMES'': Advanced Reach & Frequency with Outcomes - ''COMPETITIVE'': Competitive Insights - ''YOUTUBE_URA'': Advanced Reach & Frequency YouTube - ''ADVANCED_RF_SUPPLEMENTAL'': Advanced Reach & Frequency Supplemental - ''ADVANCED_RF_OUTCOMES_SUPPLEMENTAL'': Advanced Reach & Frequency with Outcomes Supplemental - ''TOPLINE_LINEAR'': Topline Linear Focus - ''TOPLINE_LINEAR_OUTCOMES'': Topline Linear Focus With Outcomes _For Content Measurement requests_: - ''PROGRAM'': Program Level Report - ''DAYPART'': Daypart, Custom Daypart, and Network Total Day Report - ''TELECAST'': Telecast Level Report **Use Case**: Filter to specific Measurement methodology for workflow management **Multiple Values**: Not supported; use separate requests for multiple types **Case Sensitivity**: Case-sensitive matching (use exact values) **Example**: ''?type=ADVANCED_RF''.' responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: measurement_list /v2/adMeasurements/trigger: post: operationId: measurement_refresh summary: Trigger delivery of a Measurement report tags: - adMeasurements description: This endpoint will trigger a refresh of an eligible adMeasurement. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp measurement_refresh --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: measurement_refresh /v2/adMeasurements/{adMeasurement_uuid}/postProcesses: post: operationId: measurement_create_post_process summary: Create post-process analysis tags: - adMeasurements description: |- Creates a new post-processing analysis request for a completed Measurement report that may take up to 30 hours to complete. **What**: Triggers additional analysis on baseline Measurement results to derive incremental impact insights **LIFT**: Analyzes the incremental lift effect of linear TV campaigns by comparing exposed versus control audience conversion rates **Prerequisites**: - AdMeasurement must have successfully completed (status='ready') - Must be an outcomes report type (ADVANCED_RF_OUTCOMES) - Must be within 30 days of completion - Must have 1-3 conversion groups with at least one non-Affinity - Must have linear TV datasource group - Conversion groups and audiences must be subsets of baseline report **Processing**: Request is validated and queued for asynchronous processing. Returns immediately with 'pending' status. **Use Case**: Measure incremental impact of linear TV advertising on conversion events **Response**: Returns post-process details with 'pending' status. Monitor the AdMeasurement's existing_post_processes field for completion. parameters: - name: adMeasurement_uuid in: path required: true schema: type: string description: 'The UUID of the AdMeasurement (recurring measurement configuration) to create the post-process for. **Format**: UUID v4 **Purpose**: Identifies the baseline Measurement report to perform post-processing analysis on **Use Case**: The post-process will be applied to the latest successful run of this AdMeasurement.' requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp measurement_create_post_process --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: measurement_create_post_process get: operationId: measurement_list_post_processes summary: List post-processes for an AdMeasurement tags: - adMeasurements description: |- Retrieves a paginated list of all post-process requests for a specific AdMeasurement. **What**: Returns all LIFT post-processes associated with the given AdMeasurement UUID **Use Cases**: - View history of all post-process analyses for a Measurement report - Monitor status of multiple post-processes - Retrieve links to completed post-process outputs **Response Fields**: - `results`: Array of post-process summary items - `id`: Post-process UUID - `status`: Current status (pending, running, complete, failed) - `type`: Always 'linear_lift' - `created_at`: When the post-process was created - `through_date`: Data through date - `outputs`: Result file links (when complete) - `status_info`: Queue position and display status - `next_page_token`: Token for retrieving next page - `total_size`: Total number of post-processes **Pagination**: - Default page size: 50 - Maximum page size: 100 - Results ordered by created_at DESC (newest first) parameters: - name: adMeasurement_uuid in: path required: true schema: type: string description: 'UUID of the AdMeasurement (recurring measurement config) to list post-processes for. **Format**: UUID v4' - name: page_size in: query required: false schema: type: integer description: 'Maximum number of post-processes to return per page. **Default**: 50 **Range**: 1-100' - name: page_token in: query required: false schema: type: string description: 'Page token from a previous ListPostProcesses call. **Purpose**: Used to retrieve the next page of results **Usage**: Pass the ''next_page_token'' from the previous response to get the next page' responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: measurement_list_post_processes /v2/adMeasurements/{adMeasurement_uuid}/postProcesses/{postProcessUuid}: delete: operationId: measurement_delete_post_process summary: Delete a post-process (lift) request tags: - adMeasurements description: Deletes a post-process request under an AdMeasurement without deleting the entire AdMeasurement. The request is marked as deleted but data is retained. parameters: - name: adMeasurement_uuid in: path required: true schema: type: string description: 'UUID of the AdMeasurement (recurring measurement config). **Format**: UUID v4' - name: postProcessUuid in: path required: true schema: type: string description: 'UUID of the post-process request. **Format**: UUID v4' responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: measurement_delete_post_process get: operationId: measurement_get_post_process summary: Get post-process request details tags: - adMeasurements description: "Retrieves detailed information about a LIFT post-process request.\n\n**What**: Fetches the current status, configuration, outputs, and queue information for a post-process analysis\n\n**Use Case**: Monitor post-process execution and retrieve results when complete\n\n**Response Fields**:\n- `id`: Post-process request UUID\n- `ad_measurement_id`: Parent AdMeasurement UUID \n- `status`: Current status (pending, running, complete, failed)\n- `created_at`: When the post-process was created\n- `through_date`: Data through date for the analysis\n- `outputs`: Pre-signed S3 URLs for result files (when complete)\n- `status_info`: Detailed status including queue position and display status\n- `conversion_group_ids`, `audience_ids`, `dimension_set_id`: Configuration\n\n**Status Values**:\n- `pending`: Waiting in queue\n- `running`: Currently processing\n- `complete`: Results available in outputs\n- `failed`: Processing error occurred" parameters: - name: adMeasurement_uuid in: path required: true schema: type: string description: 'UUID of the AdMeasurement (recurring measurement config). **Format**: UUID v4' - name: postProcessUuid in: path required: true schema: type: string description: 'UUID of the post-process request. **Format**: UUID v4' responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: measurement_get_post_process /v2/adMeasurements/{adMeasurement_uuid}/postProcesses:requirements: get: operationId: measurement_get_post_process_requirements summary: Get post-process configuration options tags: - adMeasurements description: |- Retrieve available configuration options for post-processing a completed Measurement report. **What**: Returns the available options (conversion groups, audiences, dimension sets) that can be used to configure a post-process operation for a specific Measurement report. **Purpose**: Before triggering a post-process operation like LIFT, use this endpoint to discover which configuration options are available based on the baseline Measurement report's configuration. **Use Cases**: - Present available conversion groups to users when configuring a Linear Lift analysis - Show which audiences can be included in post-processing - Display dimension set options (e.g., NETWORK) for breakdown analysis - Validate that required options are available before attempting to trigger post-processing **Workflow**: 1. User selects a completed Measurement report with outcomes 2. Call this endpoint with the report's `adMeasurement_uuid` and desired `postProcessType` (e.g., LIFT) 3. Response contains arrays of available conversion_group_ids, audience_ids, and dimension_set_ids 4. User selects from these options 5. Use selected options to trigger the post-process operation **Requirements**: The Measurement report must be eligible for the requested post-process type. Check `eligible_post_processes` field on the AdMeasurementRequest to verify eligibility before calling this endpoint. parameters: - name: adMeasurement_uuid in: path required: true schema: type: string description: 'Unique identifier for the recurring Measurement report. **Format**: UUID v4 **Purpose**: Identifies the baseline Measurement report for which to retrieve post-processing options **Use Case**: Get available configuration options before triggering post-process operations.' - name: postProcessType in: query required: true schema: type: string description: 'Type of post-processing operation to retrieve options for. **Available Values**: ''LIFT'' - Linear Lift analysis **Purpose**: Specifies which post-process options to retrieve. - LINEAR_LIFT: Deprecated: use LIFT instead. ETL handles LINEAR_LIFT vs DIGITAL_LIFT distinction.' responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: measurement_get_post_process_requirements /v2/adMeasurements/{id}: delete: operationId: measurement_delete summary: Delete Measurement report tags: - adMeasurements description: This endpoint will delete a Measurement report. parameters: - name: id in: path required: true schema: type: string description: This field defines the Measurement request identifier. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: measurement_delete get: operationId: measurement_get summary: Get Measurement report details tags: - adMeasurements description: "Retrieves complete details for a specific Measurement report including configuration, processing status, execution history, and downloadable export links. Essential for monitoring Measurement report processing progress, accessing completed analysis results, and tracking the lifecycle of advertising performance analyses from submission through completion. Enables automated polling workflows that wait for result availability and provides real-time status updates. \n**Use for**: monitoring processing status after creating a Measurement report, checking if asynchronous analysis has completed and results are ready, accessing S3 download links for exports (CSV/Excel/Parquet), retrieving detailed error messages on failures, reviewing historical configurations for audit or replication, displaying execution history for recurring Measurement requests, and or verifying parameters before triggering refresh\n**Requires**: Bearer token authentication with read permissions for the specified Measurement report\n**Typical latency**: Under 100ms for direct ID lookups; recommended polling interval 2-5 minutes during processing (typical completion 30min-4hrs)\n**Returns**: 404 error if ID not found or 403 if insufficient permissions\n**Related**:\n- `POST /v2/adMeasurements` (create, returns ID)\n- `GET /v2/adMeasurements` (list with filtering)\n- `PATCH /v2/adMeasurements/{id}` (update)\n- `DELETE /v2/adMeasurements/{id}` (delete)\n- `POST /v2/adMeasurements/trigger` (manually trigger recurring execution)." parameters: - name: id in: path required: true schema: type: string description: 'Unique identifier for the Measurement report to retrieve. Must be a valid UUID v4 representing an existing Measurement report within your organization''s scope. Auto-generated when created via ''POST /v2/adMeasurements'' and returned in the response ''id'' field. Use this ID to poll for processing status, retrieve completed results with download links, or access historical configurations. Immutable throughout the Measurement report''s lifecycle and persists after analysis completes. Common errors: 404 when ID does not exist or was deleted; 403 when user lacks read permissions based on IAM rules. IDs are globally unique across VideoAmp systems preventing collisions. For optimal performance, cache the ID after creation rather than repeatedly searching via list endpoint. Example workflow: Create Measurement report → Save ID → Poll GET every 2-5 minutes → Download results when status is ''ready''.' responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '403': description: Forbidden — the caller's organization is not permissioned for this resource. '404': description: Not Found — the resource does not exist or is not accessible to the calling organization. x-videoamp-cli-command: measurement_get patch: operationId: measurement_update summary: Update Measurement configuration tags: - adMeasurements description: |- Update an existing Measurement configuration. This endpoint allows you to modify specific fields of an Measurement report. **Updatable Fields**: `name`, `start_date`, `end_date`, `streams`, `currency_of_record`, `audience_ids`, `data_source_group_ids`, `conversion_group_ids`, `rule_ids`, `delivery_schedule`, `export_results` **Required Field**: `type` must be provided in every request for validation but is not updatable. **Request Format**: Send a PATCH request with the Measurement report ID in the URL path and the fields to update in the request body. Use `update_mask` query parameter to specify which fields to update. **Example Payload For Editing Name**: ```json { "name": "pt-test-export false 5", "type": "ADVANCED_RF" } ``` **Export Results**: When `export_results` is changed from `false`/`null` to `true`, outputs are automatically generated for the latest successful request. The latest request must be in a succeeded state. Enabling when already enabled has no effect. parameters: - name: id in: path required: true schema: type: string description: The unique identifier of the Measurement report to update. - name: validate_only in: query required: false schema: type: boolean description: to only validate the request When supplied and set to true, the request will be validated to ensure proper access is provided for all values, attributes, and outputs, along with all required fields being present. The updated object will be returned in full. This field is optional. (default true) requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp measurement_update --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: measurement_update /v2/audiences: post: operationId: audience_create summary: Create Audience tags: - audiences description: |- Creates a new audience resource and queues it for processing. Returns the created Audience object with `status=QUEUED`. **Status lifecycle**: `QUEUED` → `PROCESSING` → `READY` (success) or `FAILED` (error). `READY` and `FAILED` are terminal; `QUEUED` and `PROCESSING` are non-terminal. Processing typically takes 10–20 minutes for common audience types; large or complex audiences (e.g., `COMPOSITE`, `USER_PROVIDED` with high identity-match volume) may take longer. Do not treat `PROCESSING` as a terminal state. **Why**: The primary entry point for creating any audience type in the VideoAmp platform. Supports all audience classifications: EXPOSURE, CONTENT, CUSTOM_DEMOGRAPHIC, USER_PROVIDED, COMPOSITE, and MODELED. Use `validate_only=true` to test a request without creating the audience (REST callers: pass as query parameter `?validateOnly=true`). **When**: Call when you need to build a new audience for measurement or export. Classification-specific pre-conditions: **CUSTOM_DEMOGRAPHIC** — discover valid field identifiers via GET /v2/audiences/lookupDemographicFilterFields, then values via GET /v2/audiences/lookupDemographicFilterValues. **USER_PROVIDED** — confirm valid `id_types` values with your VideoAmp representative (account-specific; no v2 discovery endpoint available). **COMPOSITE** — ensure all component audiences have `status=READY` before calling. **MODELED** — the seed audience must be `READY` and an eligible seed type (see `origin_audience`). **How**: Set `classification` and the matching definition object, plus `currency_of_record`. The response `id` (UUID) is used to check status and reference the audience in downstream APIs. Only `READY` audiences are eligible for measurement; exports accept audiences in any status. Related: GET /v2/audiences/{id} (check status), GET /v2/audiences (list), GET /v2/audiences/lookupDemographicFilterFields (discover CUSTOM_DEMOGRAPHIC fields). parameters: - name: validateOnly in: query required: false schema: type: string description: When true, validates the request body (required fields, enum values, permissions) without creating the audience. Use to pre-flight a create request before committing — especially useful when building audience creation UI or automating bulk audience creation workflows where early error detection reduces wasted processing. Defaults to `false`. A successful validate-only response does not guarantee a subsequent create will succeed if underlying data changes between calls. (default true) requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp audience_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: audience_create get: operationId: audience_list summary: List Audiences tags: - audiences description: |- Returns a paginated, filterable list of audiences accessible to the calling organization. The caller's organization context controls visibility; the `use_cases` field on each audience determines eligible downstream operations. **Why**: Discover and enumerate audiences before passing them to downstream workflows. Use this endpoint to find READY audiences by classification, ownership, use case, or name before creating measurements or exports. Use GET /v2/audiences/{id} when the audience UUID is already known. **When**: Call when checking which audiences are available for a measurement campaign; filtering by `useCases` to understand workflow eligibility; discovering SHARED cross-org audiences; retrieving GLOBAL_DEMOGRAPHIC audiences with `broadcastDate` and `currencyOfRecord`; or looking up IDs for share, export, or measurement APIs. **How**: Apply filters to narrow results, then pass the returned `id` (UUID) to downstream APIs. Only READY audiences are eligible for measurement — exports can be created against an audience in any status. Do not change filter parameters between pages. `total_size` is a point-in-time snapshot and may change between page requests — use the absence of `next_page_token` to detect the final page. Related: POST /v2/audiences (create), GET /v2/audiences/{id} (retrieve by ID), GET /v2/audiences/lookupDemographicFilterFields (discover CUSTOM_DEMOGRAPHIC filter fields). parameters: - name: advertiserIds in: query required: false schema: type: string description: 'Filters audiences by permissioned advertiser UUID(s). Includes audiences permissioned directly to the advertiser as well as those permissioned to any ancestor organization. **Org-level inheritance**: Audiences permissioned to a parent org are visible to all child advertisers. Filtering by two advertisers in the same org may return identical results — both inherit the same org-level pool. This is expected behavior, not a bug. **Multi-advertiser queries**: Results are a deduplicated union, not a concatenation. total_size equals the union count — do not sum per-advertiser counts. **Advertiser-exclusive audiences**: To find audiences exclusive to one advertiser, inspect `permissioned_entities` on each result and filter client-side. Values must be valid UUIDs; duplicates are not permitted.' - name: agencyIds in: query required: false schema: type: array items: type: string description: Filters audiences by permissioned agency UUID(s). Returns audiences accessible to the given agency IDs. Includes audiences permissioned directly to the agency as well as those permissioned to any of its ancestor organizations. Values must be valid UUIDs; duplicates are not permitted. - name: broadcastDate in: query required: false schema: type: string description: Selects which broadcast year's metrics to return based on the broadcast year range containing the specified date. Only applies to 'GLOBAL_DEMOGRAPHIC' audiences; ignored for other types. Uses ISO-8601 date format ('YYYY-MM-DD'). If omitted, the most recent metrics for the given 'currencyOfRecord' are returned. If the date falls outside the available range for the currency of record, a 400 error is returned with the valid date range. - name: cadences in: query required: false schema: type: string description: 'Filters audiences by their refresh cadence — how frequently the audience membership is recalculated. Use to find audiences with specific refresh patterns for scheduling-sensitive workflows. Accepts multiple values (OR logic); case-insensitive. Available values: ONE_TIME, `WEEKLY`, `MONTHLY`, `QUARTERLY`.' - name: classifications in: query required: false schema: type: string description: 'Filters audiences by their __classification__. Case-insensitive. Accepts multiple values (OR logic). Available values: - EXPOSURE - `CONTENT` - `CUSTOM_DEMOGRAPHIC` - `USER_PROVIDED` - `GLOBAL_DEMOGRAPHIC` - `COMPOSITE` - `MODELED` **Note on `GLOBAL_DEMOGRAPHIC` and `use_cases`:** `GLOBAL_DEMOGRAPHIC` audiences vary in their supported `use_cases`. Not all `GLOBAL_DEMOGRAPHIC` audiences support `AD_MEASUREMENT` — some only support `CONTENT_MEASUREMENT`. Combining `classifications=GLOBAL_DEMOGRAPHIC` with `useCases=AD_MEASUREMENT` returns only the subset that supports ad measurement. Omit the `useCases` filter to retrieve all `GLOBAL_DEMOGRAPHIC` audiences regardless of supported use cases.' - name: createdByName in: query required: false schema: type: string description: Case-insensitive substring filter on the 'created_by_name' field of the audience. Useful for finding audiences created by a specific user or team. Matches any audience whose creator's display name contains the supplied string. Combine with 'ownership=OWNED' to narrow results to audiences created by your organization. - name: currencyOfRecord in: query required: false schema: type: string description: Filters audiences by their currency of record, which identifies the measurement panel and the data and methodologies used for VideoAmp currency guarantees within a given broadcast year. For 'GLOBAL_DEMOGRAPHIC' audiences, combine with 'broadcastDate' to select the correct metrics. Provide as a numeric string (int64 encoded as string). Invalid or unavailable values return a 400 error listing valid options. - name: description in: query required: false schema: type: string description: Case-insensitive substring filter on the audience 'description' field. Matches any audience whose description contains the supplied string. Useful for finding audiences annotated with specific campaign or workflow context. Combine with 'name' or 'classifications' for more precise filtering. Empty string or omitting this parameter returns all audiences regardless of description. Use the 'search' parameter instead for broader matching across multiple fields. - name: excludeClassifications in: query required: false schema: type: string description: 'Query param excludeClassifications will exclude audiences that have the specified __classification__. This field is case insensitive. The available options and restrictions for this field are the same as the __classifications__ filter. For example, to retrieve all audiences except `GLOBAL_DEMOGRAPHIC` audiences: `excludeClassifications=GLOBAL_DEMOGRAPHIC`.' - name: ids in: query required: false schema: type: string description: Filters to a specific set of audiences by their UUID id values. Use when you already know which audiences you need — e.g., to batch-fetch metadata for a saved list of audience IDs. Values must be valid UUIDs. Combine with `statuses=READY` to verify all listed audiences are usable. - name: legacyIds in: query required: false schema: type: string description: Filters to a specific set of audiences by their legacy numeric legacy_id values. Use when integrating with systems that store legacy integer IDs rather than UUIDs. Prefer `ids` (UUID) for new integrations; use `legacy_ids` only when working with older systems or data stores that reference the numeric ID. - name: level in: query required: false schema: type: string description: 'Filters audiences by measurement granularity. ''HOUSEHOLD'': household-level metrics (default for most classifications). ''PERSON'': person-level metrics for ''GLOBAL_DEMOGRAPHIC'' audiences. Omit to return all levels. Unsupported combinations return empty metrics fields. - LEVEL_UNSPECIFIED: Default filter value; returns all audiences regardless of level. Do not use in requests — omit instead. - HOUSEHOLD: Household-level reach and frequency metrics. The default for most classifications. - PERSON: Person-level demographic metrics. Available only for GLOBAL_DEMOGRAPHIC audiences.' - name: name in: query required: false schema: type: string description: Case-insensitive substring filter on the audience 'name' field. Matches any audience whose name contains the supplied string. Use this to narrow results when browsing audiences for a specific campaign. Combine with 'statuses' or 'classifications' to further refine results. Empty string or omitting this parameter returns all audiences regardless of name. Use the 'search' parameter instead for broader matching across multiple fields. - name: orderBy in: query required: false schema: type: string description: 'Controls the sort order of returned audiences. Specify a comma-separated list of field_name direction pairs. Direction is optional; omit for ascending order, use ''desc'' for descending. Defaults to ''created_at desc'' (most recently created first) when omitted. Sortable fields: ''created_at'', ''created_by_name'', ''name'', ''currency_of_record'', ''legacy_id''. Example: ''currency_of_record, name desc'' sorts by currency of record ascending, then name descending.' - name: ownership in: query required: false schema: type: string description: 'Filters by audience ownership relative to the calling organization. ''OWNED'': audiences created by your organization. ''SHARED'': audiences another organization has granted you access to via the Resource Sharing API — use when collaborating cross-org on measurement or activation campaigns. ''SYSTEM'': VideoAmp-provided audiences such as GLOBAL_DEMOGRAPHIC audiences. Omit to return all three ownership types. Only one value is accepted per request.' - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. Defaults to a server-determined page size when omitted. Use larger values (100-500) for batch processing or data export workflows; use smaller values for interactive UI displays with progressive loading. Pair with `pageToken` to paginate through large result sets. Must be a positive integer; excessively large values may increase response latency. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: search in: query required: false schema: type: string description: Filters audiences by matching the provided string against name, description, id, or uuid (case-insensitive). Returns audiences where any of these fields contain the given value. Use this parameter for broad searches when the exact field is unknown or does not matter. For more precise filtering, use the 'name' or 'description' query parameters instead. - name: statuses in: query required: false schema: type: string description: 'Filters audiences by processing status. Use READY to find audiences eligible for immediate use in measurement workflows. Exports can be created against an audience in any status. `PROCESSING` and `QUEUED` indicate the audience is being built and is not yet usable. `FAILED` indicates processing encountered an error. Accepts multiple values (OR logic); case-insensitive. Available values: `QUEUED`, `PROCESSING`, `READY`, `FAILED`.' - name: useCases in: query required: false schema: type: string description: 'Filters audiences to those supporting at least one of the specified use cases. The use_cases property on an audience determines which downstream operations are available — e.g., only audiences with `AD_MEASUREMENT` can be used in ad measurement campaigns. Case-insensitive; accepts multiple values (OR logic). Available values: `ACTIVATION`, `AD_MEASUREMENT`, `CONTENT_MEASUREMENT`.' responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: audience_list /v2/audiences/lookupDemographicFilterFields: get: operationId: audience_demographic_filter_field_lookup summary: Lookup Demographic Filter Fields tags: - audiences description: |- Returns a paginated list of demographic filter fields available for building Custom Demographic audiences. Each entry contains the field identifier (`field`), a human-readable label, and a detailed description of the demographic attribute. **Why**: Useful for two scenarios: populating UI field selectors (e.g., dropdowns in an audience builder) where the available fields are not known ahead of time, and validating or exploring available field identifiers before writing code that references them. Programmatic callers with known field identifiers (e.g., AGE_RANGE) do not need to call this endpoint at runtime. Results change infrequently; cache for session duration when called. **When**: Call when building a UI that lets users select demographic fields, or when exploring what fields are available for the first time. Not required as a prerequisite before every audience creation — if the field identifiers are already known, use them directly in Filter.field. Use the `search` parameter to filter by keyword when looking for a specific attribute. **How**: Paginate using `pageSize` and `pageToken`. Pass the returned `field` value directly as Filter.field when calling POST /v2/audiences. To discover valid values for a given field, use GET /v2/audiences/lookupDemographicFilterValues. parameters: - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. Defaults to a server-determined page size when omitted. Use larger values (50-100) when building field selectors that display a complete list; use smaller values for progressive-loading UI components. Must be a positive integer. Pair with `pageToken` to paginate through the full catalog. Excessively large values may increase response latency. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: search in: query required: false schema: type: string description: Optional keyword filter to narrow the list of demographic filter fields. Performs a case-insensitive substring match against the 'field' identifier (e.g., AGE_RANGE), the 'description' text, and the 'label' display name (e.g., Age Range). Use when you know part of the field name, description, or display label to quickly locate a specific demographic attribute. Omit to retrieve all available fields. Combine with 'pageSize' for efficient browsing of large field catalogs. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: audience_demographic_filter_field_lookup /v2/audiences/lookupDemographicFilterValues: get: operationId: audience_demographic_filter_value_lookup summary: Lookup Demographic Filter Values tags: - audiences description: |- Returns a paginated list of valid values for a specific demographic filter field. Each entry contains the value identifier (`value`), a human-readable label, and a description of what the value represents. **Why**: Before creating a CUSTOM_DEMOGRAPHIC audience, you must know the valid values for each Filter.field you intend to use. This endpoint is the authoritative source for the allowed Filter.values for a given field — do not hardcode value identifiers. The value catalog is field-specific and may vary by organization; call once per session and cache results. **When**: Call after discovering available filter fields via GET /v2/audiences/lookupDemographicFilterFields. Pass the `field` identifier (e.g., AGE_RANGE) to retrieve its valid values. Use the `search` parameter to narrow results when looking for a specific value. Call once per session per field and cache the results — the value catalog changes infrequently. **How**: Supply the required `field` parameter with a field identifier from the fields endpoint. Pass the returned `value` string directly in Filter.values when calling POST /v2/audiences. Paginate using `pageSize` and `pageToken`. Related: GET /v2/audiences/lookupDemographicFilterFields (discover field identifiers), POST /v2/audiences (create a CUSTOM_DEMOGRAPHIC audience using the discovered values). parameters: - name: field in: query required: true schema: type: string description: 'The demographic filter field identifier to look up values for. Must be a valid field identifier returned by GET /v2/audiences/lookupDemographicFilterFields — e.g., ''AGE_RANGE'', ''GENDER'', ''INCOME''. Values are UPPERCASE with underscore separators. Case-sensitive: use the exact string returned by the fields endpoint. Returns 400 if the field identifier is not recognized for the calling organization.' - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. Defaults to a server-determined page size when omitted. Use larger values (50-100) when building value selectors that display a complete list; use smaller values for progressive-loading UI components. Must be a positive integer. Pair with `pageToken` to paginate through the full value catalog for a field. Excessively large values may increase response latency. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: search in: query required: false schema: type: string description: Optional keyword filter to narrow the list of values for the specified field. Performs a case-insensitive substring match against the 'value' identifier (e.g., 13_15) and the 'description' text. Use when you know part of the value string or its description to quickly locate a specific option. Omit to retrieve all available values for the field. Combine with 'pageSize' for efficient browsing of fields with large value catalogs. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: audience_demographic_filter_value_lookup /v2/audiences/{id}: get: operationId: audience_get summary: Get Audience tags: - audiences description: |- Returns the complete Audience resource for a single known audience ID. Use this endpoint when you already have the audience UUID or legacy integer ID and need to retrieve full details including classification, status, use_cases, owned vs. shared ownership, and the classification-specific definition object (exposure, content, composite, etc.). **Why**: Retrieve a specific audience directly without filtering through paginated list results. Use to verify audience status before downstream operations such as measurement, export, or sharing. Prefer this over GET /v2/audiences when the audience ID is already known. **When**: Call when you need to confirm an audience is READY before use in a downstream workflow, retrieve the full definition object for a known audience ID, or look up audience metadata by ID from an external reference or saved record. **How**: Supply the UUID or legacy integer ID as the `id` path parameter. Only READY audiences are eligible for measurement — exports can be created against an audience in any status. Related: GET /v2/audiences (list with filters), POST /v2/audiences (create). parameters: - name: id in: path required: true schema: type: string description: The unique identifier for the audience to retrieve. Accepts either a UUID v4 (e.g., 'b21fd4c7-2423-4358-830a-41b3d744e663') or a legacy integer ID encoded as a string (e.g., '"101010101"'). UUID is the preferred format for new integrations. Returns 404 if the audience does not exist or is not accessible to the calling organization. responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: audience_get patch: operationId: audience_update summary: Update Audience tags: - audiences description: |- Updates an audience's `name` and/or `description` — the only editable fields. Other attributes (classification, definition, currency of record, use cases, status) are immutable. Provide at least one of `name` or `description`; an empty request returns 400. Returns the full updated Audience. **Why**: Rename or re-describe an audience without rebuilding it or losing its computed members and metrics. **Example**: a planner renames "test aud" to "Q1 2025 CTV Reach" before sharing. **When**: Call to fix a name or description, or to apply naming standards. **How**: Send PATCH /v2/audiences/{id} with the field(s) to change; the update mask is derived from the request body. Precondition: owned by your organization (`ownership=OWNED`; SHARED or SYSTEM returns 403). Editable in any status. **Next Steps**: inspect the returned Audience to confirm the change. Related: GET /v2/audiences/{id}, GET /v2/audiences, POST /v2/audiences. parameters: - name: id in: path required: true schema: type: string description: The unique identifier of the audience to update. Accepts either a UUID v4 (e.g., 'b21fd4c7-2423-4358-830a-41b3d744e663') or a legacy integer ID encoded as a string (e.g., '"311637"'), the same identifier accepted by GetAudience. UUID is the preferred format for new integrations. Supplied as the '{id}' path parameter. Returns 404 if the audience does not exist or is not accessible to the calling organization. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp audience_update --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. '403': description: Forbidden — the caller's organization is not permissioned for this resource. x-videoamp-cli-command: audience_update /v2/shares: post: operationId: share_resources_create summary: Bulk Create Shares tags: - shares description: |- ### What Creates a new resource share granting one or more recipients access to one or more resources such as audiences. Supports bulk operations with up to 100 recipients and 100 resources per request. ### Why Enables organizations to securely share data assets with partners, agencies, and advertisers within the VideoAmp ecosystem. Essential for cross-organizational collaboration on audience targeting, campaign planning, and measurement. Consent-based sharing ensures data governance compliance. ### When - Share audiences with agency partners for campaign activation - Grant advertiser access to custom audience segments - Distribute measurement audiences to multiple recipients simultaneously - Establish data sharing relationships for collaborative analytics Use POST /v1/shares for single-recipient sharing. Use GET /v1/shares to discover existing shares. Use DELETE /v1/shares/{id} to revoke access. ### How Requires valid JWT authentication. Provide recipients array with kind and id for each recipient, resources array with legacy integer identifiers, optional name, and optional permissions beyond read access. Pre-approval may be required for certain resource types - contact VideoAmp support for onboarding. Returns share ID for tracking. Returns 400 for validation errors, 403 for unauthorized sharers. ### Example ```json { "recipients": [{"id": "10", "kind": "ORGANIZATION"}], "resources": ["277777"], "name": "Share to Partner Org" } ``` **Notes:** - `resources`: Use the audience's legacy integer ID (`audienceId` from v1 API, or `legacy_id` from v2 API), not UUIDs - `recipients[].kind`: ORGANIZATION, ADVERTISER, AD_AGENCY, BRAND, SUB_BRAND, or PRODUCT requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp share_resources_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. '403': description: Forbidden — the caller's organization is not permissioned for this resource. x-videoamp-cli-command: share_resources_create /v2beta/plans: post: operationId: plan_draft_create summary: Create Plan (Draft) tags: - plans description: |- Starts the draft branch of the planning workflow by creating a media plan in DRAFT status for a campaign. The draft captures the budget-allocation strategy — budget, constraints, objectives, filters, and rates — so it can be refined before optimization. **Why**: A media plan can be produced two ways — submitted complete and sent straight to optimization, or built incrementally through draft → edit → approve. This endpoint begins the incremental path: create the draft now, refine it, and approve it when ready. Rates are not required while the plan is a draft. **When**: First step of the draft workflow. Call with a campaign_id and display_name; refine the draft with PATCH /v2beta/plans/{plan_id}, then submit it with POST /v2beta/plans/{plan_id}:approve. **How**: Submit the plan configuration in the request body. Returns 201 with the created Plan including server-assigned `id` and `status` = DRAFT. The inventory_set_id, audiences, and creative durations are derived from the campaign. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp plan_draft_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: plan_draft_create /v2beta/plans/{planId}: patch: operationId: draft_plan_update summary: Patch Plan (Draft) tags: - plans description: |- Refines a DRAFT media plan in the draft branch of the planning workflow. Send only the fields you want to change; omitted fields keep their current values. **Why**: Lets planners iterate on a draft — adjust budget, constraints, objectives, filters, or rate card / overrides — between creating it and approving it for optimization. **When**: While the plan is still in DRAFT status, after it is created and before it is approved. **How**: Supply the plan UUID as `plan_id`. Merge semantics: a field omitted (null) is left unchanged; an explicit empty array `[]` clears that collection (e.g. remove all constraints); an empty string for `rate_card_id` detaches the rate card. Returns 200 with the updated Plan. parameters: - name: planId in: path required: true schema: type: string description: Unique identifier for the Plan in UUID v4 format. Auto-generated on creation and immutable thereafter. Use this ID in subsequent get and delete operations. Store this value after creation to poll for optimization status. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp draft_plan_update --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: draft_plan_update /v2beta/plans/{planId}:approve: post: operationId: draft_plan_approve summary: Approve Plan tags: - plans description: |- Approves a DRAFT media plan, completing the draft branch of the planning workflow: it runs full cross-field validation and, on success, submits the plan for asynchronous optimization. **Why**: The commit step of the draft → edit → approve path. Approval transitions the plan from DRAFT to QUEUED and runs the same optimization a directly-submitted plan would, producing the allocated media plan. **When**: After the draft is fully configured. The plan MUST be in DRAFT status. Rates are required at this step — provide a rate card and/or rate overrides covering the plan's titles. **How**: Supply the plan UUID as `plan_id`. Returns 201 with the Plan in status QUEUED; poll the plan (GET /v1beta/plans/{plan_id}) to track QUEUED → PROCESSING → READY/FAILED. Submitting an identical plan within one hour is rejected with 409. parameters: - name: planId in: path required: true schema: type: string description: Unique identifier for the Plan in UUID v4 format. Auto-generated on creation and immutable thereafter. Use this ID in subsequent get and delete operations. Store this value after creation to poll for optimization status. requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp draft_plan_approve --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. '409': description: Conflict — the request conflicts with the current state of the resource. x-videoamp-cli-command: draft_plan_approve /v3/consents: get: operationId: consent_list_v3 summary: List Consents (UUID) tags: - consents description: |- ### What Returns a paginated list of consent records where recipients have authorized your organization to share resources with them. Sharer and recipient are identified exclusively by UUID. ### Why Enables discovery of which recipients have consented to receive shared data from your organization using UUID identifiers. Essential for pre-share validation (verifying consent exists before creating shares via POST /v3/shares), building consent management dashboards, and searching for specific partner organizations by name or type. ### When - Verify a recipient has consented before creating a share via POST /v3/shares - Build consent management dashboards showing all consented partners - Search for specific recipients by name or organizational type - Audit consent relationships for compliance reporting Use GET /v1/consents for composite (kind+id) identifiers. ### How Requires valid JWT authentication. Use optional query parameters for filtering and pagination. Results are automatically filtered to show only consents where your organization is the sharer. parameters: - name: fetchRecipientAncestorPath in: query required: false schema: type: boolean description: When true, populates the recipient_ancestor_path field in each consent showing the recipient's full position in the organizational hierarchy (e.g., 'Organization > Ad Agency > Advertiser'). Useful for consent dashboards that need to display organizational context. May increase response time for large result sets - omit if hierarchy information is not needed. (default true) - name: pageSize in: query required: false schema: type: string description: Query param pageSize specifies the number of results to include in a page of results. - name: pageToken in: query required: false schema: type: string description: Query param 'pageToken' specifies the value of the next page to retrieve within a paginated set of results. Valid values can be found in paginated responses that include field 'next_page_token'. When requesting the next page, additional query parameters should NOT change between page requests. - name: q in: query required: false schema: type: array items: type: string description: 'Advanced query filter for attribute-based filtering. Supported attributes: - **recipient_kind**: Filter by recipient type. Operators: eq, in. Values: ORGANIZATION, ADVERTISER, AD_AGENCY, BRAND, SUB_BRAND, PRODUCT. - **recipient_name**: Filter by recipient organization name. Operators: startswith, endswith, contains. Multiple q parameters are AND''d by default. Use OR keyword between conditions for OR logic. Examples: - ?q=recipient_kind eq ADVERTISER - ?q=recipient_kind in ADVERTISER,AD_AGENCY - ?q=recipient_name startswith Acme - ?q=recipient_name contains Media OR recipient_kind eq AD_AGENCY' responses: '200': description: Successful response. '401': description: Unauthorized — missing or invalid bearer token. x-videoamp-cli-command: consent_list_v3 /v3/shares: post: operationId: share_resources_v3_create summary: Bulk Create Shares (UUID Recipients) tags: - shares description: |- ### What Creates a new resource share granting one or more recipients access to one or more resources such as audiences. Supports bulk operations with up to 100 recipients and 100 resources per request. Recipients are identified by their UUID. ### Why Enables organizations to securely share data assets with partners, agencies, and advertisers within the VideoAmp ecosystem using UUID-based recipient identifiers. Essential for cross-organizational collaboration on audience targeting, campaign planning, and measurement. ### When - Share audiences with agency partners for campaign activation - Grant advertiser access to custom audience segments - Distribute measurement audiences to multiple recipients simultaneously - Establish data sharing relationships for collaborative analytics Use POST /v2/shares for composite (kind+id) recipient identifiers. Use GET /v1/shares to discover existing shares. Use DELETE /v1/shares/{id} to revoke access. ### How Requires valid JWT authentication. Provide recipients array with UUID identifiers for each recipient, resources array with legacy integer identifiers, optional name, and optional permissions beyond read access. Returns share ID for tracking. Returns 400 for validation errors, 403 for unauthorized sharers. ### Example ```json { "recipients": ["550e8400-e29b-41d4-a716-446655440000"], "resources": ["277777"], "name": "Share to Partner Org" } ``` **Notes:** - `recipients`: UUID v4 identifiers for each recipient entity - `resources`: Use the audience's legacy integer ID (`audienceId` from v1 API, or `legacy_id` from v2 API), not UUIDs requestBody: required: true description: JSON request body. The CLI accepts it via `--json`. The body schema is published only in the authenticated OpenAPI document served to logged-in callers (`videoamp share_resources_v3_create --oas`) and at https://docs.videoamp.dev, both of which require an Auth0 session; it is therefore not reproduced here. content: application/json: schema: type: object responses: '200': description: Successful response. '400': description: Bad Request — invalid or unsupported parameter values. '401': description: Unauthorized — missing or invalid bearer token. '403': description: Forbidden — the caller's organization is not permissioned for this resource. x-videoamp-cli-command: share_resources_v3_create components: securitySchemes: videoampOAuth: type: oauth2 description: OAuth 2.0 / OIDC via VideoAmp's Auth0 tenant at https://login.videoamp.com. Verified from https://login.videoamp.com/.well-known/openid-configuration (HTTP 200) and https://api.videoamp.dev/.well-known/oauth-protected-resource/v1/mcp (HTTP 200, RFC 9728). Bearer tokens are presented in the Authorization header. flows: authorizationCode: authorizationUrl: https://login.videoamp.com/authorize tokenUrl: https://login.videoamp.com/oauth/token refreshUrl: https://login.videoamp.com/oauth/token scopes: openid: OIDC subject identifier profile: Basic profile claims email: Email address claim offline_access: Issue a refresh token deviceAuthorization: deviceAuthorizationUrl: https://login.videoamp.com/oauth/device/code tokenUrl: https://login.videoamp.com/oauth/token scopes: openid: OIDC subject identifier profile: Basic profile claims email: Email address claim offline_access: Issue a refresh token externalDocs: url: https://docs.videoamp.dev description: VideoAmp Public API documentation (Auth0-gated) x-evidence: method: derived derived_from: github.com/VideoAmp/cli release v0.148.32 (videoamp_v0.148.32_darwin_arm64.tar.gz) extraction: videoamp --help; videoamp --help fetched: '2026-08-02' operations: 118 parameters: 295 anonymous_openapi_published: false notes: docs.videoamp.dev returns HTTP 302 to Auth0 for every path; api.videoamp.dev returns 404 for /openapi.json, /swagger.json, /v1/openapi.json, /api-docs, /docs, /redoc.