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
# --- truncated at 32 KB (331 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/videoamp/refs/heads/main/openapi/videoamp-public-api-openapi.yml