VideoAmp Consents API

openapi: 3.2.0
info:
  title: VideoAmp Public Consents 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: consents
  description: consents operations.
paths:
  /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
  /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
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 <command> --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.