Ads docs v2

.github/workflows/update-ads-api-docs.yml

@@ -0,0 +1,89 @@
+name: Update Ads API reference
+on:
+  # Triggered from the Ads service repository whenever its OpenAPI contract changes:
+  #   gh api repos/THEOplayer/documentation/dispatches -f event_type=update-ads-api-docs
+  repository_dispatch:
+    types: [update-ads-api-docs]
+  workflow_dispatch:
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    env:
+      # The branch that will receive the regenerated API reference (will be created if it doesn't exist)
+      # Will automatically open a new PR (if no PR exists yet)
+      UPDATE_BRANCH: update-ads-api-docs
+    steps:
+      - name: Create app token
+        uses: actions/create-github-app-token@v3
+        id: app-token
+        with:
+          client-id: ${{ vars.THEOPLAYER_BOT_CLIENT_ID }}
+          private-key: ${{ secrets.THEOPLAYER_BOT_PRIVATE_KEY }}
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          fetch-depth: 1
+      - name: Configure Git user
+        run: |
+          git config user.name 'theoplayer-bot[bot]'
+          git config user.email '873105+theoplayer-bot[bot]@users.noreply.github.com'
+      - name: Create or checkout update branch
+        # language=bash
+        run: |
+          if git fetch --depth 1 origin refs/heads/$UPDATE_BRANCH ; then
+            git checkout -b $UPDATE_BRANCH FETCH_HEAD
+          else
+            git checkout -b $UPDATE_BRANCH HEAD
+          fi
+      - name: Setup Node.JS
+        uses: actions/setup-node@v7
+        with:
+          node-version: '24'
+          cache: 'npm'
+          cache-dependency-path: ./package-lock.json
+      - name: Install dependencies
+        run: npm ci
+      - name: Regenerate Ads API reference
+        run: npm run refresh-ads-api-docs
+      - name: Check for changes
+        id: check_changes
+        # language=bash
+        run: |
+          if [[ -z "$(git status --porcelain ads/api/reference)" ]]; then
+            echo "No API reference changes detected."
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Commit and push changes
+        if: ${{ steps.check_changes.outputs.changed }}
+        # language=bash
+        run: |
+          git add ads/api/reference
+          git commit -m 'Update Ads API reference'
+          git push --force origin HEAD:$UPDATE_BRANCH
+      - name: Check if pull request already exists
+        if: ${{ steps.check_changes.outputs.changed }}
+        id: check_pr_exists
+        # language=bash
+        run: |
+          pr_count=$(gh pr list --base main --head "$UPDATE_BRANCH" --state open --limit 1 --json number --jq length)
+          if ((pr_count > 0)); then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          fi
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+      - name: Create pull request
+        if: ${{ steps.check_changes.outputs.changed && !steps.check_pr_exists.outputs.exists }}
+        # language=bash
+        run: |
+          gh pr create \
+            --base main \
+            --head "$UPDATE_BRANCH" \
+            --title "Update Ads API reference" \
+            --body "This PR regenerates the OptiView Ads API reference from the latest OpenAPI contract."
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}

.prettierignore

@@ -17,6 +17,7 @@ theoplayer_versioned_docs/*/changelog.md
 theoplayer_versioned_docs/*/static/theoplayer/*/api-reference
 ads/api/ads-client.swagger.json
 ads/api/signaling/
+ads_versioned_docs/*/api/
 adengine/static/ad-engine.yaml
 adengine/reference/
 millicast/api/

README.md

@@ -18,3 +18,25 @@ If you're looking to contribute to the developer documentation itself, see https
 1. `npm install` on first usage
 2. `git submodule update --init` to install submodules
 3. `npm start` to open in dev mode
+
+### Ads API reference
+
+The V2 Ads API reference is generated from the public OpenAPI document served
+by the Ads API (`https://us.ads.optiview.dolby.com/api/v1/docs/json`). The
+generated MDX pages are committed, but the fetched spec is not.
+
+The reference is kept in sync by the `update-ads-api-docs` workflow: the Ads
+service repository triggers a `repository_dispatch` event (type
+`update-ads-api-docs`) whenever its contract changes, and the workflow
+regenerates the pages and opens a PR. It can also be run manually from the
+Actions tab.
+
+To refresh locally:
+
+```bash
+npm run refresh-ads-api-docs
+npm run build
+```
+
+Use `ADS_OPENAPI_SPEC_URL` to point at another URL or a local
+`/path/to/openapi.json`.

ads/api/index.mdx

@@ -0,0 +1,27 @@
+---
+title: Ads REST API
+sidebar_label: REST API
+---
+
+# Ads REST API
+
+The Ads REST API manages channels, origins, marker rules, breaks, events, templates, and integrations under `/api/v1`.
+
+## Authentication
+
+Every request requires both:
+
+- HTTP Basic authentication, with the API key as the username and API secret as the password.
+- The `X-Org-ID` header identifying the organization.
+
+```bash
+curl 'https://us.ads.optiview.dolby.com/api/v1/channels' \
+  -u "$ADS_API_KEY:$ADS_API_SECRET" \
+  -H 'X-Org-ID: <org-id>'
+```
+
+Treat the secret like a password. The internal service authentication used between platform components is not a public API authentication method.
+
+## Reference
+
+Browse the [generated Ads REST API reference](/ads/api/reference/optiview-ads-api). Operations are grouped by resource.

ads/api/reference/delete-channels-channel-id-breaks-break-id.api.mdx

@@ -0,0 +1,43 @@
+---
+id: delete-channels-channel-id-breaks-break-id
+title: 'Delete /channels/{channelId}/breaks/{breakId}'
+description: 'Delete a break.'
+sidebar_label: 'Delete /channels/{channelId}/breaks/{breakId}'
+hide_title: true
+hide_table_of_contents: true
+api: eJytVMtu2zAQ/BViTw5AW03Rk24u4oPRAgnSx8XwYS2uLSIyxZArJ67Afy9WlmzHaYO26Emv3ZnZGS1bMBSLYD3b2kEON1QRk0K1CoQPE9DgMeCWmEKEfNFCLEraIuQt8N4T5BA5WLeBpMEKgEcuQYPDrXwsSnSOqrkBDYEeGxvIQM6hIX1BPDfk2K4tBVWvFZek+t4JJP23tJ34fyLtx05LaY2+dpGisL5/90Eul2atsalY3feVkJKG2lNAKZgbyMF0fo77WeL4aMi4Y4rjk1TGjVgMH7sPsNSwJS7rE0oXBpeQQ4beZrvrbIDN2iNuyg7AWdsjJ9AQqWiC5X2X4AqjLaaNAC2WGuqwEaWLpcw8FH4Ruw+Tn5UfzS+ZvcB2VeK31MClu9O7uXqgvRo1kYIkc6XQGRWpCMRq5DHGpzqYK0l4kHGkQG8/0R76eEtCQ+EU8PO4DpuxNa84b8MGnf3RBaDsMd5JF41167qjsFwJyq1n+93Sk5qaqKZ3c9CwoxAPSLtrkeXryFt00tVT9xvyx96/0NdCUTsmx79ctX50pmfOfIXWiYImVNJ3SH4hvojMa9DDckXQkJ8v2kGEvB1+rqWGso4s/W27wkjfQpWSvH5sKOwPP8IOg8WVGLNowdgo9wbyNVbxcnHOxxjd9yt2pd7Y4d8MN4TtJOkdVo08gYYH2r84PeQI+E+S3nb7bUGDn2mZzrbzZvZ59nUGKf0ECTXMMw==
+sidebar_class_name: 'delete api-method'
+info_path: ads/api/reference/optiview-ads-api
+custom_edit_url: null
+hide_send_button: true
+---
+
+import MethodEndpoint from '@theme/ApiExplorer/MethodEndpoint';
+import ParamsDetails from '@theme/ParamsDetails';
+import RequestSchema from '@theme/RequestSchema';
+import StatusCodes from '@theme/StatusCodes';
+import OperationTabs from '@theme/OperationTabs';
+import TabItem from '@theme/TabItem';
+import Heading from '@theme/Heading';
+import Translate from '@docusaurus/Translate';
+
+<Heading as={'h1'} className={'openapi__heading'} children={'Delete /channels/{channelId}/breaks/{breakId}'}></Heading>
+
+<MethodEndpoint method={'delete'} path={'/api/v1/channels/{channelId}/breaks/{breakId}'} context={'endpoint'}></MethodEndpoint>
+
+Delete a break.
+
+<Heading id={'request'} as={'h2'} className={'openapi-tabs__heading'}>
+  <Translate id="theme.openapi.request.title">Request</Translate>
+</Heading>
+
+<ParamsDetails
+  parameters={[
+    { schema: { type: 'string' }, in: 'path', name: 'channelId', required: true, description: 'Identifier of the channel.' },
+    { schema: { type: 'string' }, in: 'path', name: 'breakId', required: true, description: 'Identifier of the break.' },
+  ]}
+></ParamsDetails>
+
+<RequestSchema title={'Body'}></RequestSchema>
+
+<StatusCodes responses={{ '204': { description: 'Default Response' } }}></StatusCodes>

ads/api/reference/delete-channels-channel-id-breaks.api.mdx

@@ -0,0 +1,61 @@
+---
+id: delete-channels-channel-id-breaks
+title: 'Delete /channels/{channelId}/breaks'
+description: 'Bulk delete breaks by IDs.'
+sidebar_label: 'Delete /channels/{channelId}/breaks'
+hide_title: true
+hide_table_of_contents: true
+api: eJyFVE1v2zAM/SsCTy2gJMuwk2/pkkOwAi26bpcgB8ZmbDW2pEpyUs/wfx/or6Tt2vliWyKp9x75VENCPnbKBmU0RHBT5geRUE6BxM4RHrzYVWK99FOQ4Oi5JB9uTFJBVLe/ylECUXAlSYiNDqQDb6G1uYqRi86ePFeuwccZFchfobIEEZjdE8UBJFhnLLmgyPOuStpXofQ6UOEhmsshA53DCiSobmOs5INTOgXJSbek05BBNG/kG27rhHRQe0XOC7MXIRspBtNznopFEDmhD8JoEsqLgeQUmkZeUN60OLdNw8sWHRYUyHmINv9g2uNrJCgGYjFkIEFjwZtxhlpTvk5AvpP0IwID/j53Cs2Wk7012ncqfv3yjV+vCyxpj2UexEMf2XJi7dtOrROIoNNh0hf2kxHdpNMKJARMmSfcdAtbCQWFzJyzuaVMMYIZWjU7zmdDuVk91mtmY0FPcelUqFrxduhVvCg5fbOVYFzKuDZbZjgE/mSBO54X4aPcWQiWy7ZREHUx8FbNxf1aHKgSV6Unx724FqgT4Sl2FMSVRe9PxiXXU+5bD2M8Aq36Qe0ocqmMMCF3bunLxLh0opJ3Z965FLX608ot1NjObrjYKA9ni61esLA5jZbYDGO0bedob1o4KnAI3Nmgfis6iUXixeJ+DRKO5Hx36nHOFKzxocDWij3MZefz/3TnFYP67PLP74pep0AvYWZzVJohlC7nEt1wbFhExjkHOZiAz4suDbEbZywzPnBSXe/Q0y+XNw0vP5fkqm5UjugU7liOTQ2J8vydQLTH3L+10iWNq4fedNfiE4N9wGgYB82zcMS85D+QcKDqlbUbblo/Jgyv2//egZg8cpVz/rvbs7n02HJ1u3pcsTb9PVyYhLMcnvgGwVOHwLRUW4+0azXkqNMSU47tqvLzF5xeDMU=
+sidebar_class_name: 'delete api-method'
+info_path: ads/api/reference/optiview-ads-api
+custom_edit_url: null
+hide_send_button: true
+---
+
+import MethodEndpoint from '@theme/ApiExplorer/MethodEndpoint';
+import ParamsDetails from '@theme/ParamsDetails';
+import RequestSchema from '@theme/RequestSchema';
+import StatusCodes from '@theme/StatusCodes';
+import OperationTabs from '@theme/OperationTabs';
+import TabItem from '@theme/TabItem';
+import Heading from '@theme/Heading';
+import Translate from '@docusaurus/Translate';
+
+<Heading as={'h1'} className={'openapi__heading'} children={'Delete /channels/{channelId}/breaks'}></Heading>
+
+<MethodEndpoint method={'delete'} path={'/api/v1/channels/{channelId}/breaks'} context={'endpoint'}></MethodEndpoint>
+
+Bulk delete breaks by IDs.
+
+<Heading id={'request'} as={'h2'} className={'openapi-tabs__heading'}>
+  <Translate id="theme.openapi.request.title">Request</Translate>
+</Heading>
+
+<ParamsDetails
+  parameters={[{ schema: { type: 'string' }, in: 'path', name: 'channelId', required: true, description: 'Identifier of the channel.' }]}
+></ParamsDetails>
+
+<RequestSchema
+  title={'Body'}
+  body={{
+    required: true,
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            ids: {
+              minItems: 1,
+              type: 'array',
+              items: { type: 'string', minLength: 1 },
+              description: 'Identifiers of the breaks to delete. At least one is required.',
+            },
+          },
+          required: ['ids'],
+        },
+      },
+    },
+  }}
+></RequestSchema>
+
+<StatusCodes responses={{ '204': { description: 'Default Response' } }}></StatusCodes>

ads/api/reference/delete-channels-channel-id-events-event-id.api.mdx

@@ -0,0 +1,43 @@
+---
+id: delete-channels-channel-id-events-event-id
+title: 'Delete /channels/{channelId}/events/{eventId}'
+description: 'Delete /channels/{channelId}/events/{eventId}'
+sidebar_label: 'Delete /channels/{channelId}/events/{eventId}'
+hide_title: true
+hide_table_of_contents: true
+api: eJytVMlu2zAQ/RViTjFAW3XRk24G7IPRAgnS5WL4QItji4hMMeRIiSvw34vR5qVF0QQ9aeHMe2/mzbABp7w6IqEPkG4aCFmORwVpA3RyCCkE8sYeIEowFlJwinKQYNWRD7NcWYvFWoMEj8+V8aghJV+hBI0h88aRKTlvrdGS2Rv0otwLylH0uTOI8q20WKOld5G2mTOIW04NrrQBA7N+/PCJH9fpS9yrqiDx2EdCjBJKh15xwFpDChoLJJz2tYTp2JBpyxSmZ6mkDtxiWLUHsL0Vu2yhRDJgJc0IFpMOLWl6uAgSjkh5edYAsmtSColyJqnn/wwUMKu8oVPr/04Fky0qBtpsJZT+wHVuttyxIfArm9X17SJ8tC4ncgzbRkHaxcBtuYuHtXjCk7irAnr2dSKU1SJg5pHEnVMhvJReT3g+BhkjhXLmM56gH44clUZ/Ho/XaekPU6N/47z3B2XNz9Y+YcbhmLXGGrsvWwpDBaPcOzI/DL6IhQ5i8bAGCTX60CHVc5blykBHZTmrp36riVf6xvIIXylxhTKWWSpf8Fnn7oZrZylzkMP6BZCQXq5iR8R/h/HbSsjLQJzfNDsV8LsvYuTfzxX6U2d2rbxROy5+04A2gd81pHtVhNvVaiArLaElSOHusV/CifjLlss/FzcYatnNWhUVf4GEJzxd3S98SfwnSf0d8C5BQz/jNl5s4HL1ZfVtBTH+Au5f0Mo=
+sidebar_class_name: 'delete api-method'
+info_path: ads/api/reference/optiview-ads-api
+custom_edit_url: null
+hide_send_button: true
+---
+
+import MethodEndpoint from '@theme/ApiExplorer/MethodEndpoint';
+import ParamsDetails from '@theme/ParamsDetails';
+import RequestSchema from '@theme/RequestSchema';
+import StatusCodes from '@theme/StatusCodes';
+import OperationTabs from '@theme/OperationTabs';
+import TabItem from '@theme/TabItem';
+import Heading from '@theme/Heading';
+import Translate from '@docusaurus/Translate';
+
+<Heading as={'h1'} className={'openapi__heading'} children={'Delete /channels/{channelId}/events/{eventId}'}></Heading>
+
+<MethodEndpoint method={'delete'} path={'/api/v1/channels/{channelId}/events/{eventId}'} context={'endpoint'}></MethodEndpoint>
+
+Delete /channels/\{channelId\}/events/\{eventId\}
+
+<Heading id={'request'} as={'h2'} className={'openapi-tabs__heading'}>
+  <Translate id="theme.openapi.request.title">Request</Translate>
+</Heading>
+
+<ParamsDetails
+  parameters={[
+    { schema: { type: 'string' }, in: 'path', name: 'channelId', required: true, description: 'Identifier of the channel.' },
+    { schema: { type: 'string' }, in: 'path', name: 'eventId', required: true, description: 'Identifier of the event.' },
+  ]}
+></ParamsDetails>
+
+<RequestSchema title={'Body'}></RequestSchema>
+
+<StatusCodes responses={{ '204': { description: 'Default Response' } }}></StatusCodes>

ads/api/reference/delete-channels-channel-id-events.api.mdx

@@ -0,0 +1,61 @@
+---
+id: delete-channels-channel-id-events
+title: 'Delete /channels/{channelId}/events'
+description: 'Delete /channels/{channelId}/events'
+sidebar_label: 'Delete /channels/{channelId}/events'
+hide_title: true
+hide_table_of_contents: true
+api: eJyNVMlu2zAQ/RViTglA23XRk25u44PRAAnS5WL4QItji4lEMuTIjivo34uhFmfrooskcubxvXkzbCDgY42RPjt9gqxJvyaghoxCjRJyZwkt8ZbyvjS5IuPs7D46y2sxL7BS/EUnj5CB295jTiDBB+cxkMHIu0anV2XsirCKkM3lkKFCUCeQYLqNESlSMHYPkpOu0e6pgGzeStAY82A804AMVhotmZ3BEIXbCSpQ4AEtRUFOaCyRcCoWJEpUkYSzKEwUg8gptK18JnmdeG7alpe9CqpCwhAhW7+jtOfXSjBMxCsqQIJVFW/mhbIWy5UG+aakfxIw8O9zp9BuODl6Z2NXxY8fPvHrJcAV7lRdkrjrI5Mmrn1yaqUhg64Okx44TkZ2k65WIIHUnnXCslvYvKZ5lSDEbMCYNSNIOxtRKqTCnU/kNuCyZDBT3swO83+kR8zrYOiUCr5V0eSLmtPXGwku7FnLesNVGQK/sSldbZ6FjxYVRJ5hUxRkXQy8lra4XYkHPImLOmJg/y6FslpEzAOSuPAqxqML+nLKXvc0xiOUN18xtS9DFag0hnMbPE1c2E+MfnPmTdgra34li4QZW6BrSB6uu/NYLp9U5Uscx2g9tN4m9d7OJTqGOARuPJmfBo9ioaNY3K5AwgFD7E49zFmCd5Eqlca3p/l/5r5QMBaA8IlmvlTGMnYdSt7rXF9zdZjAHOQwEQyUPZ8OHBuucJE4qWm2KuKPULYtLz/WGE5dDxxUMGrLOtcNaBP5W0O2U2V8PVfN+eaCi7t+Ai/FX6ZNvq9o8NmyyQdV1vwHEh7w9GLOW3aj95/pdftfOhKT74xyzn9zlXJTj8Nztbxefl+ChG1/KVdOc1ZQR75O1LFj4JLU1PxprYFS2X2t9hzbofLzG4ItBOU=
+sidebar_class_name: 'delete api-method'
+info_path: ads/api/reference/optiview-ads-api
+custom_edit_url: null
+hide_send_button: true
+---
+
+import MethodEndpoint from '@theme/ApiExplorer/MethodEndpoint';
+import ParamsDetails from '@theme/ParamsDetails';
+import RequestSchema from '@theme/RequestSchema';
+import StatusCodes from '@theme/StatusCodes';
+import OperationTabs from '@theme/OperationTabs';
+import TabItem from '@theme/TabItem';
+import Heading from '@theme/Heading';
+import Translate from '@docusaurus/Translate';
+
+<Heading as={'h1'} className={'openapi__heading'} children={'Delete /channels/{channelId}/events'}></Heading>
+
+<MethodEndpoint method={'delete'} path={'/api/v1/channels/{channelId}/events'} context={'endpoint'}></MethodEndpoint>
+
+Delete /channels/\{channelId\}/events
+
+<Heading id={'request'} as={'h2'} className={'openapi-tabs__heading'}>
+  <Translate id="theme.openapi.request.title">Request</Translate>
+</Heading>
+
+<ParamsDetails
+  parameters={[{ schema: { type: 'string' }, in: 'path', name: 'channelId', required: true, description: 'Identifier of the channel.' }]}
+></ParamsDetails>
+
+<RequestSchema
+  title={'Body'}
+  body={{
+    required: true,
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            ids: {
+              minItems: 1,
+              type: 'array',
+              items: { type: 'string', minLength: 1 },
+              description: 'Identifiers of the events to delete. At least one is required.',
+            },
+          },
+          required: ['ids'],
+        },
+      },
+    },
+  }}
+></RequestSchema>
+
+<StatusCodes responses={{ '204': { description: 'Default Response' } }}></StatusCodes>