openapi: 3.2.0 info: title: VideoAmp Public Data Streams 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. 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: Data Streams description: dataStreams operations. paths: /v1alpha/dataStreams: post: operationId: data_stream_create summary: Create Data Stream tags: - Data Streams 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: - Data Streams 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: - Data Streams 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: - Data Streams 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: - Data Streams 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: - Data Streams 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: - Data Streams 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: - Data Streams 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: - Data Streams 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: - Data Streams 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: - Data Streams 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: - Data Streams 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: - Data Streams 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: - Data Streams 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: - Data Streams 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: - Data Streams 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: - Data Streams 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: - Data Streams 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: - Data Streams 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 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.