diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..2c49e52 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,58 @@ +name: Docs + +on: + push: + branches: [main] + paths: + - "mkdocs.yml" + - "requirements-docs.txt" + - "docs/**" + - "api-usage-docs/**" + - "tutorials/**" + - "products/**" + pull_request: + paths: + - "mkdocs.yml" + - "requirements-docs.txt" + - "docs/**" + - "api-usage-docs/**" + - "tutorials/**" + - "products/**" + workflow_dispatch: + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: "3.x" + + - run: pip install -r requirements-docs.txt + + - run: mkdocs build --strict + + - uses: actions/upload-pages-artifact@v3 + with: + path: site + + deploy: + needs: build + if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - uses: actions/configure-pages@v5 + - uses: actions/deploy-pages@v4 + id: deployment diff --git a/.pytest_cache/v/cache/stepwise b/.pytest_cache/v/cache/stepwise new file mode 100644 index 0000000..0637a08 --- /dev/null +++ b/.pytest_cache/v/cache/stepwise @@ -0,0 +1 @@ +[] \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 87d09ea..95a1580 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,12 @@ # Changelog All notable changes to this project will be documented in this file. +## [0.0.8] - 2026-08-11 + +### Added + - Restructured Subscriptions API documentation around v2: `api-usage-docs/subscriptions-api.md` now documents v2 (versioned `/v2/...` routes, `product_parameters`, SPP endpoints, remote identity reconciliation) as the primary/recommended API. + - Added `api-usage-docs/subscriptions-api-legacy.md`, preserving the v1 documentation for existing integrations that have not migrated. + ## [0.0.7] - 2025-01-02 ### Added diff --git a/README.md b/README.md index 5acbeba..c89e87c 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ Use these docs in order if you are building a new integration: Find products and product payload definitions, including valid `stage_id` values. 4. [Remote Identity API](./api-usage-docs/remote-identity-api.md) Find the identities your account can use and inspect identity health. -5. [Subscriptions API](./api-usage-docs/subscriptions-api.md) +5. [Subscriptions API (v2)](./api-usage-docs/subscriptions-api.md) Create, inspect, and update subscriptions. 6. [History API](./api-usage-docs/history-api.md) Request historical backfills after a subscription is active. @@ -63,7 +63,8 @@ Use these docs in order if you are building a new integration: | Account and user lookup | [api-usage-docs/account-user-api.md](./api-usage-docs/account-user-api.md) | | Products | [api-usage-docs/products-api.md](./api-usage-docs/products-api.md) | | Remote identities | [api-usage-docs/remote-identity-api.md](./api-usage-docs/remote-identity-api.md) | -| Subscriptions | [api-usage-docs/subscriptions-api.md](./api-usage-docs/subscriptions-api.md) | +| Subscriptions (v2) | [api-usage-docs/subscriptions-api.md](./api-usage-docs/subscriptions-api.md) | +| Subscriptions (legacy v1) | [api-usage-docs/subscriptions-api-legacy.md](./api-usage-docs/subscriptions-api-legacy.md) | | History | [api-usage-docs/history-api.md](./api-usage-docs/history-api.md) | | OAuth flow and app records | [api-usage-docs/oauth-api.md](./api-usage-docs/oauth-api.md) | | State records | [api-usage-docs/state-api.md](./api-usage-docs/state-api.md) | diff --git a/SKILL.md b/SKILL.md index b697953..1cd1789 100644 --- a/SKILL.md +++ b/SKILL.md @@ -62,7 +62,8 @@ Load these on demand — do not load all at once. Pick the file(s) relevant to t | Authentication & refresh tokens | `api-usage-docs/authentication-api.md` | | Getting account/user IDs | `api-usage-docs/account-user-api.md` | | Getting started / full flow walkthrough | `api-usage-docs/getting-started.md` | -| Subscriptions CRUD | `api-usage-docs/subscriptions-api.md` | +| Subscriptions CRUD (v2) | `api-usage-docs/subscriptions-api.md` | +| Subscriptions CRUD (legacy v1) | `api-usage-docs/subscriptions-api-legacy.md` | | Products & stage IDs | `api-usage-docs/products-api.md` | | Remote identities & identity types (`/ri`, `/sri`, `/rit`) | `api-usage-docs/remote-identity-api.md` | | OAuth flow & OAuth app records | `api-usage-docs/oauth-api.md` | diff --git a/api-usage-docs/service-amazon-advertising-api.md b/api-usage-docs/service-amazon-advertising-api.md index 3062080..a592e41 100644 --- a/api-usage-docs/service-amazon-advertising-api.md +++ b/api-usage-docs/service-amazon-advertising-api.md @@ -30,11 +30,12 @@ GET /service/amzadv/profiles-only/{remote_identity_id} | Parameter | Type | Description | |---|---|---| | `profile_types` | string | Comma-separated filter: `seller`, `vendor`, `dsp`, `attribution`. Omit to return all types. | +| `is_manager` | string | `true` if the identity is connected to a manager account, `false` otherwise. | **Example request** ```http -GET https://service.api.openbridge.io/service/amzadv/profiles-only/112?profile_types=seller,vendor +GET https://service.api.openbridge.io/service/amzadv/profiles-only/112?profile_types=seller,vendor&is_manager=false Authorization: Bearer ``` diff --git a/api-usage-docs/service-ob-api.md b/api-usage-docs/service-ob-api.md index 78af9c8..8c78ffb 100644 --- a/api-usage-docs/service-ob-api.md +++ b/api-usage-docs/service-ob-api.md @@ -76,7 +76,7 @@ Additional keys inside `storage_parameters` depend on the storage type and are p **Supported `storage` values** -See [Storages](../products/storages.md) for all supported storage types and their required fields. +See [Destinations](../products/destinations.md) for all supported storage types and their required fields. --- diff --git a/api-usage-docs/subscriptions-api-legacy.md b/api-usage-docs/subscriptions-api-legacy.md index 8f85c1e..e2fe8b9 100644 --- a/api-usage-docs/subscriptions-api-legacy.md +++ b/api-usage-docs/subscriptions-api-legacy.md @@ -34,7 +34,7 @@ Before creating a subscription you will need your **account ID**, **user ID**, a ### Get Account ID and User ID -See [Account and User API](./account-api.md) for the endpoints that return your account ID and user ID. Use the `id` field from each response as `account` and `user` respectively in subscription requests. +See [Account and User API](./account-user-api.md) for the endpoints that return your account ID and user ID. Use the `id` field from each response as `account` and `user` respectively in subscription requests. --- diff --git a/api-usage-docs/subscriptions-api.md b/api-usage-docs/subscriptions-api.md index 10ac182..187cd6a 100644 --- a/api-usage-docs/subscriptions-api.md +++ b/api-usage-docs/subscriptions-api.md @@ -36,7 +36,7 @@ Before creating a subscription you will need your **account ID**, **user ID**, a ### Get Account ID and User ID -See [Account and User API](./account-api.md) for the endpoints that return your account ID and user ID. Use the `id` field from each response as `account` and `user` respectively in subscription requests. +See [Account and User API](./account-user-api.md) for the endpoints that return your account ID and user ID. Use the `id` field from each response as `account` and `user` respectively in subscription requests. --- diff --git a/docs-hosting-recommendation.md b/docs-hosting-recommendation.md new file mode 100644 index 0000000..ca27da0 --- /dev/null +++ b/docs-hosting-recommendation.md @@ -0,0 +1,72 @@ +# Building & Serving the Docs + +This repo's markdown docs are built into a searchable site with [MkDocs](https://www.mkdocs.org/) and the [Material theme](https://squidfunk.github.io/mkdocs-material/), published via GitHub Pages at **https://openbridge.github.io/embedded-api/**. This file covers how to build/serve locally and how deployment works. (For the original discussion of hosting-platform options — MkDocs vs. Docusaurus vs. Mintlify/ReadMe/GitBook — see git history on this file.) + +## Prerequisites + +``` +pip install -r requirements-docs.txt +``` + +Installs `mkdocs`, `mkdocs-material`, and `mkdocs-llmstxt-md` (pinned in `requirements-docs.txt`). + +## Local development + +``` +mkdocs serve +``` + +Starts a live-reloading dev server — edits to any `.md` file under `api-usage-docs/`, `tutorials/`, or `products/` refresh automatically. Because `site_url` is set to `https://openbridge.github.io/embedded-api/` (matching the real GitHub Pages URL), mkdocs serves locally under that same path prefix: `http://127.0.0.1:8000/embedded-api/`, not the bare root. + +``` +mkdocs build +``` + +Builds the static site into `site/` (gitignored — regenerated on every build, never committed). + +``` +mkdocs build --strict +``` + +Same as above, but treats broken internal links/anchors as errors instead of warnings. This is also what CI runs. + +## Project layout + +| Path | What it is | +|---|---| +| `mkdocs.yml` | Site config: theme, nav structure, markdown extensions | +| `docs/index.md` | Hand-written landing page | +| `docs/api-usage-docs`, `docs/tutorials`, `docs/products` | Symlinks to the existing top-level content directories — edit content in `api-usage-docs/`, `tutorials/`, `products/` directly, not under `docs/` | +| `site/` | Generated build output — gitignored | +| `requirements-docs.txt` | Pinned Python deps for building the site | + +`api-usage-docs/data-model.md` is intentionally excluded from the build (`exclude_docs` in `mkdocs.yml`) since it's gitignored/internal and shouldn't be published even unlinked. Verified this exclusion also holds for the raw-markdown/llms.txt output below — it doesn't leak in either. + +## Raw markdown for AI/LLM consumption + +`SKILL.md` in this repo already lets local tools (Claude Code, etc.) read the source `.md` files directly from a git checkout — that's unaffected by any of this. The gap this closes is for AI agents/tools that only have **web access** to the deployed site and would otherwise have to scrape rendered HTML. + +The `mkdocs-llmstxt-md` plugin adds three things, generated automatically on every build: + +- **Per-page raw markdown**: every rendered page `/index.html` gets a sibling `/index.md` with the original source. E.g. `/embedded-api/api-usage-docs/getting-started/index.html` → `/embedded-api/api-usage-docs/getting-started/index.md`. + - Note: this is `/index.md`, not the bare `.md` sibling that fastmcp/Mintlify use — MkDocs' default directory-URL layout (`/index.html`) makes a same-directory `index.md` the natural fit, and a bare `.md` file would collide with the `/` directory on most web servers. Functionally equivalent for AI consumption; just a different URL shape. +- **`/llms.txt`** — a page index (title + link per doc) at the site root, pointing at the working `index.md` URLs above. +- **`/llms-full.txt`** — the entire doc set concatenated into one file. + +No config was needed beyond adding `- llmstxt-md` to `plugins:` in `mkdocs.yml` — all three are on by default. Verified locally: builds cleanly through the `docs/api-usage-docs`, `docs/tutorials`, `docs/products` symlinks, respects `exclude_docs`, and serves the expected content/content-type (`text/markdown`) at runtime. + +## GitHub Actions & deployment + +`.github/workflows/docs.yml` has two jobs: + +- **`build`** — runs on push to `main`, on pull requests touching docs-related paths (`mkdocs.yml`, `requirements-docs.txt`, `docs/**`, `api-usage-docs/**`, `tutorials/**`, `products/**`), and on manual dispatch. Installs `requirements-docs.txt`, runs `mkdocs build --strict`, and uploads `site/` as a Pages artifact. +- **`deploy`** — runs only after `build` succeeds on a push to `main` (never on PRs, so untrusted PR content never publishes). Publishes the artifact via GitHub's official `actions/deploy-pages` action to **https://openbridge.github.io/embedded-api/**. + +One-time repo setting required (not part of this repo's files): Settings → Pages → Build and deployment → Source = **GitHub Actions**. Once that's set and this config is merged to `main`, every push to `main` auto-deploys; the first deploy (or any manual re-run) can also be triggered from the Actions tab via the `workflow_dispatch` trigger. + +## Content fixes already made + +A round of pre-existing broken links and anchors (not caused by the MkDocs setup — these were always broken on GitHub too, just never validated) were fixed to get `--strict` passing: + +- Relative links that didn't resolve, e.g. `./account-api.md` → `account-user-api.md`, `../products/storages.md` → `destinations.md`, and several `service-api.md` references from `products/` and `tutorials/` files that needed either a corrected path or a redirect to the specific per-service doc (`service-amazon-advertising-api.md`, `service-facebook-api.md`, `service-google-api.md`, `service-shopify-api.md`) where that content now actually lives. +- Anchor mismatches in `product-overview.md` (added a missing `## Mixed Amazon Seller and Vendor Products` header the table of contents already pointed at) and `identity-configuration.md` (TOC anchor updated to match a since-renamed header). diff --git a/docs/api-usage-docs b/docs/api-usage-docs new file mode 120000 index 0000000..e6f0cc5 --- /dev/null +++ b/docs/api-usage-docs @@ -0,0 +1 @@ +../api-usage-docs \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..16f77ff --- /dev/null +++ b/docs/index.md @@ -0,0 +1,56 @@ +# Openbridge Embedded API + +Integrate with the Openbridge Embedded API to authenticate, create subscriptions, inspect identities, and work with service-specific integration endpoints. + +## What This API Does + +Openbridge subscriptions connect three things: + +1. A source product +2. A storage destination +3. A remote identity that authorizes Openbridge to access a third-party platform on your behalf + +In practice, most integrations follow this sequence: + +1. Create a refresh token in the Openbridge UI +2. Exchange that refresh token for a JWT access token +3. Look up your account, user, product, destination, and remote identity IDs +4. Create a subscription +5. Optionally trigger historical data retrieval + +If you want the end-to-end sequence first, start with [Getting Started](api-usage-docs/getting-started.md). + +## Before You Begin + +- API access must be enabled for your Openbridge account by the Openbridge team. +- The account owner must have the `api-user` role. +- Refresh tokens are created in the Openbridge UI under `Account -> API Management`. +- Refresh tokens are shown only once. Store them securely. +- Destinations are managed in the Openbridge UI, not through the API. +- Remote identities are typically created and authorized through the Openbridge UI and OAuth flow, then referenced by ID when creating subscriptions. + +For the authentication flow, see [Authentication API](api-usage-docs/authentication-api.md). + +## Quick Start Path + +Use these docs in order if you are building a new integration: + +1. [Authentication API](api-usage-docs/authentication-api.md) — create a refresh token in the UI and exchange it for a JWT access token. +2. [Getting Started](api-usage-docs/getting-started.md) — follow the normal sequence for building a subscription-backed integration. +3. [Products API](api-usage-docs/products-api.md) — find products and product payload definitions, including valid `stage_id` values. +4. [Remote Identity API](api-usage-docs/remote-identity-api.md) — find the identities your account can use and inspect identity health. +5. [Subscriptions API (v2)](api-usage-docs/subscriptions-api.md) — create, inspect, and update subscriptions. +6. [History API](api-usage-docs/history-api.md) — request historical backfills after a subscription is active. + +## Support + +If you have a documentation problem, an API question, or a reproducible issue: + +- Open a GitHub issue in the [embedded-api repository](https://github.com/openbridge/embedded-api) +- Contact Openbridge through the official support channel + +Additional product and platform documentation: + +- [Openbridge Documentation](https://docs.openbridge.com/) +- [Openbridge Website](https://www.openbridge.com) +- [Openbridge Blog](https://blog.openbridge.com) diff --git a/docs/products b/docs/products new file mode 120000 index 0000000..8fddc4f --- /dev/null +++ b/docs/products @@ -0,0 +1 @@ +../products \ No newline at end of file diff --git a/docs/tutorials b/docs/tutorials new file mode 120000 index 0000000..d32c36f --- /dev/null +++ b/docs/tutorials @@ -0,0 +1 @@ +../tutorials \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..cb66ae3 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,89 @@ +site_name: Openbridge Embedded API +site_description: Documentation for integrating with the Openbridge Embedded API +site_url: https://openbridge.github.io/embedded-api/ +repo_url: https://github.com/openbridge/embedded-api +repo_name: openbridge/embedded-api +edit_uri: edit/main/docs/ + +theme: + name: material + features: + - navigation.tabs + - navigation.sections + - navigation.top + - navigation.indexes + - search.suggest + - search.highlight + - content.code.copy + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: indigo + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: indigo + toggle: + icon: material/brightness-4 + name: Switch to light mode + +markdown_extensions: + - admonition + - tables + - toc: + permalink: true + slugify: !!python/object/apply:pymdownx.slugs.slugify + kwds: + case: lower + - pymdownx.details + - pymdownx.superfences + - pymdownx.highlight + +plugins: + - search + - llmstxt-md + +exclude_docs: | + api-usage-docs/data-model.md + +nav: + - Home: index.md + - Getting Started: + - Overview: api-usage-docs/getting-started.md + - Authentication: api-usage-docs/authentication-api.md + - Account & User Lookup: api-usage-docs/account-user-api.md + - API Reference: + - Products: api-usage-docs/products-api.md + - Remote Identities: api-usage-docs/remote-identity-api.md + - Subscriptions (v2): api-usage-docs/subscriptions-api.md + - Subscriptions (Legacy v1): api-usage-docs/subscriptions-api-legacy.md + - History: api-usage-docs/history-api.md + - OAuth: api-usage-docs/oauth-api.md + - State: api-usage-docs/state-api.md + - Jobs: api-usage-docs/jobs-api.md + - Rate Limiting: api-usage-docs/rate-limiting.md + - Service API Overview: api-usage-docs/service-api.md + - Service Integrations: + - Amazon Advertising: api-usage-docs/service-amazon-advertising-api.md + - Amazon SP-API: api-usage-docs/service-amazon-sp-api.md + - Google: api-usage-docs/service-google-api.md + - Facebook: api-usage-docs/service-facebook-api.md + - Shopify: api-usage-docs/service-shopify-api.md + - Healthchecks: api-usage-docs/service-healthchecks-api.md + - Openbridge (OB) API: api-usage-docs/service-ob-api.md + - Product Cards: api-usage-docs/service-product-cards-api.md + - Rules: api-usage-docs/service-rules-api.md + - Tutorials: + - Identity Configuration: tutorials/identity-configuration.md + - Subscription Configuration: tutorials/subscription-configuration.md + - Requesting Historical Data: tutorials/history-backfill.md + - Monitoring Pipeline Health: tutorials/monitoring-healthchecks.md + - Amazon Order Product Jobs: tutorials/amazon-order-product-jobs.md + - Amazon Advertising Marketing Stream Pipeline: tutorials/amazon-advertising-marketing-stream-pipeline.md + - Amazon Notifications Pipeline: tutorials/amazon-notifications-pipeline.md + - Products: + - Overview: products/product-overview.md + - Amazon Advertising DSP v3: products/amazon-advertising-dsp-v3.md + - Destinations: products/destinations.md diff --git a/products/amazon-advertising-dsp-v3.md b/products/amazon-advertising-dsp-v3.md index 57f49f4..43f3a6f 100644 --- a/products/amazon-advertising-dsp-v3.md +++ b/products/amazon-advertising-dsp-v3.md @@ -182,10 +182,10 @@ The Managed Ads accounts require the following subscription_product_meta_attribu `remote_identity_id`: The remote identity associated with the DSP profile and accounts. -`profile_id`: This field is only required for `self-served` DSP accounts, this will be the Amazon advertising profile associated with the DSP ads account. To retrieve this value a request to the [Amazon Advertising Profile endpoint](https://github.com/openbridge/embedded-api/blob/main/service-api.md#amazon-advertising-profiles) of the Serive API must be made. With profile_types parameter set to `dsp`. +`profile_id`: This field is only required for `self-served` DSP accounts, this will be the Amazon advertising profile associated with the DSP ads account. To retrieve this value a request to the [Amazon Advertising Profile endpoint](../api-usage-docs/service-amazon-advertising-api.md#list-profiles) of the Serive API must be made. With profile_types parameter set to `dsp`. `account_id`: The DSP account ID. This value required for both types. - * For Managed accounts a call a request to the [Amazon Advertising Profile endpoint](https://github.com/openbridge/embedded-api/blob/main/service-api.md#amazon-advertising-profiles) of the Serive API must be made. With `profile_types` parameter set to `dsp` and the `is_managed` parameter set to `true`. The `account_id` in the response is is labled `dsp_advertiser_id`. In this response the ID is the `account_id` and the `dsp_advertiser_id` will need to be placed in the `advertiser_ids` JSON array. + * For Managed accounts a call a request to the [Amazon Advertising Profile endpoint](../api-usage-docs/service-amazon-advertising-api.md#list-profiles) of the Service API must be made with `profile_types` parameter set to `dsp` and the `is_manager` parameter set to `true`. The `account_id` in the response is is labled `dsp_advertiser_id`. In this response the ID is the `account_id` and the `dsp_advertiser_id` will need to be placed in the `advertiser_ids` JSON array. ``` [ @@ -204,7 +204,7 @@ The Managed Ads accounts require the following subscription_product_meta_attribu ] ``` - * For `self served` accounts, a call to the [Amazon Advertising Profile endpoint](https://github.com/openbridge/embedded-api/blob/main/service-api.md#amazon-advertising-profiles) of the Serive API must be made. With `profile_types` parameter set to `dsp`. The output response will provide both the `profile_id` as the `id` and the `account_id` as the `account_info.id`.s + * For `self-serve` accounts, a call to the [Amazon Advertising Profile endpoint](../api-usage-docs/service-amazon-advertising-api.md#list-profiles) of the Serive API must be made with `profile_types` parameter set to `dsp`. The output response will provide both the `profile_id` as the `id` and the `account_id` as the `account_info.id`. ``` { @@ -235,16 +235,16 @@ The Managed Ads accounts require the following subscription_product_meta_attribu } ``` -`managed`: This is a boolean value in string format. For `managed` accounts the value should be `true`. For `self-serve` it should be `false`. +`is_manager`: This is a boolean value in string format. For `manager` accounts the value should be `true`. For `self-serve` it should be `false`. `advertiser_ids`: A list of advertiser IDS to collect data for. The value is a stringified JSON array. A `self-serve` account can collect data for multiple advertiser IDS. However a `managed` account can only collect data for that managed account. - * For `self-served` accounts, a call to the [Amazon Advertising DSP Advertisers](../service-api.md#amazon-advertising-dsp-advertisers) endpoint on the service API will provide a list of available `advertiser_ids` associated with the given profile. + * For `self-served` accounts, a call to the [Amazon Advertising DSP Advertisers](../api-usage-docs/service-amazon-advertising-api.md#list-advertisers) endpoint on the service API will provide a list of available `advertiser_ids` associated with the given profile. - * For `managed` accounts, please read the above section on `account_id` for `managed` accounts which describes where the adveritiser ID can be found. + * For `manager` accounts, please read the above section on `account_id` for `manager` accounts which describes where the adveritiser ID can be found. `stage_ids`: Stage IDs define what metrics will be collected with the pipeline. For Amazon Advertising DSP there are over 500 different combinations. For this reason we provide two endpoints to sort out what data to collect. - * The [first service api endpoint](../service-api.md#amazon-advertising-dsp-category-to-metrics-map) contains a map of the metric categories and their associated metrics. You can use this map to build out interfaces to let your customers choose the metrics they desire. + * The [first Service API endpoint](../api-usage-docs/service-amazon-advertising-api.md#dsp-report-field-maps) contains a map of the metric categories and their associated metrics. You can use this map to build out interfaces to let your customers choose the metrics they desire. - * The [second service api endpoint](../service-api.md#amazon-advertising-dsp-metric-map-reports) contains a map of of catagory metrics to stage IDS. Based on the desired metrics for a given category you can find the stage ID that is associated with that report. + * The [second Service API endpoint](../api-usage-docs/service-amazon-advertising-api.md#dsp-report-metrics) contains a map of of catagory metrics to stage IDS. Based on the desired metrics for a given category you can find the stage ID that is associated with that report. diff --git a/products/product-overview.md b/products/product-overview.md index d7ca41c..f9d41bc 100644 --- a/products/product-overview.md +++ b/products/product-overview.md @@ -6,7 +6,7 @@ This document provides information required when creating subscriptions for Open - [Amazon Sponsored Ads (V3)](#amazon-sponsored-ads-v3) - [Amazon Advertising Brand Metrics](#amazon-advertising-brand-metrics) - [Amazon Attribution](#amazon-attribution) - - [Amazon DSP](./products/amazon-advertising-dsp-v3.md) + - [Amazon DSP](./amazon-advertising-dsp-v3.md) - [Amazon Seller Products](#amazon-seller-products) - [Amazon Orders API](#amazon-orders-api) @@ -28,8 +28,8 @@ This document provides information required when creating subscriptions for Open - [Amazon Vendor Real-time Reports](#amazon-vendor-real-time-reports) - [Mixed Amazon Seller and Vendor Products](#mixed-amazon-seller-and-vendor-products) - - [Amazon Catalog Keyword Tracker](#amazon-seller-vendor-catalog-keyword-tracker) - - [Amazon Catalog API](#amazon-seller-vendor-catalog-api) + - [Amazon Catalog Keyword Tracker](#amazon-catalog-keyword-tracker) + - [Amazon Catalog API](#amazon-catalog-api) - [Facebook Products](#facebook-products) @@ -56,9 +56,9 @@ This document provides information required when creating subscriptions for Open These products pull reports from resources attributed to the Amazon Advertising API. ### Amazon Sponsored Ads (V3) -This product requires a call to the service API to get the requisit information for the subscription product meta. +This product requires a call to the service API to get the requisite information for the subscription product meta. -The first call that needs to be made is to the [Amazon Advertising profiles](service-api.md#amazon-advertising-profiles) endpoint. This endpoint will return a list of Amazon Advertising profiles based on the requested type. This list will provide the `profile_id` meta data. If you need more information to display you can request the brand information for the profiles by calling the [Amazon Advertising Profile Brands](service-api.md#amazon-advertising-brands) endpoint. You can pass up to five profile IDs to retrieve their brand information simultaniously. If you had more than five profiles you would need to iterate through them in groups of five to get them all. +The first call that needs to be made is to the [Amazon Advertising profiles](../api-usage-docs/service-amazon-advertising-api.md#list-profiles) endpoint. This endpoint will return a list of Amazon Advertising profiles based on the requested type This list will provide the `profile_id` metadata. If you need more information to display you can request the brand information for the profiles by calling the [Amazon Advertising Profile Brands](../api-usage-docs/service-amazon-advertising-api.md#list-brands) endpoint. You can pass up to five profile IDs to retrieve their brand information simultaneously. __Product Attributes__ > | Key | Value | @@ -74,9 +74,9 @@ __Required Subscription Product Meta__ ### Amazon Advertising Brand Metrics -This product requires a call to the service API to get the requisit information for the subscription product meta. +This product requires a call to the service API to get the requisite information for the subscription product meta. -The first call that needs to be made is to the [Amazon Advertising profiles](service-api.md#amazon) endpoint. This endpoint will return a list of Amazon Advertising profiles based on the requested type. This list will provide the `profile_id` meta data. If you need more information to display you can request the brand information for the profiles by calling the [Amazon Advertising Profile Brands](service-api.md#amazon-advertising) endpoint. You can pass up to five profile IDs to retrieve their brand information simultaniously. If you had more than five profiles you would need to iterate through them in groups of five to get them all. +The first call that needs to be made is to the [Amazon Advertising profiles](../api-usage-docs/service-amazon-advertising-api.md#list-profiles) endpoint This endpoint will return a list of Amazon Advertising profiles based on the requested type This list will provide the `profile_id` meta data If you need more information to display you can request the brand information for the profiles by calling the [Amazon Advertising Profile Brands](../api-usage-docs/service-amazon-advertising-api.md#list-brands) endpoint. You may pass up to five profile IDs to retrieve their brand information simultaneously. __Product Attributes__ > | Key | Value | @@ -93,9 +93,9 @@ __Required Subscription Product Meta__ ### Amazon Attribution -This product requires a call to the service API to get the requisit information for the subscription product meta. +This product requires a call to the service API to get the requisite information for the subscription product meta. -The first call that needs to be made is to the [Amazon Advertising profiles](service-api.md#amazon-advertising-profiles) endpoint. This endpoint will return a list of Amazon Advertising profiles based on the requested type. This list will provide the `profile_id` meta data. If you need more information to display you can request the brand information for the profiles by calling the [Amazon Advertising Profile Brands](service-api.md#amazon-advertising-profile-brands) endpoint. You can pass up to five profile IDs to retrieve their brand information simultaniously. If you had more than five profiles you would need to iterate through them in groups of five to get them all. +The first call that needs to be made is to the [Amazon Advertising profiles](../api-usage-docs/service-amazon-advertising-api.md#list-profiles) endpoint. This endpoint will return a list of Amazon Advertising profiles based on the requested type This list will provide the `profile_id` meta data If you need more information to display you can request the brand information for the profiles by calling the [Amazon Advertising Profile Brands](../api-usage-docs/service-amazon-advertising-api.md#list-brands) endpoint. You may pass up to five profile IDs to retrieve their brand information simultaneously. __Product Attributes__ > | Key | Value | @@ -323,7 +323,9 @@ __Required Subscription Product Meta__ > |-|-|-| > | remote_identity_id | `STRING` | Remote identity associated with the associated profile. | -#### Amazon Catalog Keyword Tracker +## Mixed Amazon Seller and Vendor Products + +### Amazon Catalog Keyword Tracker Amazon Catalog Keyword Tracker requires no additional API lookups with the Openbridge Service API. @@ -337,12 +339,12 @@ __Required Subscription Product Meta__ > | Data Key | Data Format Value | Data Value | > |-|-|-| > | remote_identity_id | `STRING` | Remote identity associated with the associated profile. | -> | keywords | `STRING` | A stringified JSON array of keywords. The limit is 100 keywords to prevent Amazon API rate limiting. Subscriptions with more than 100 may fail to generate reports. | +> | keywords | `STRING` | A stringified JSON array of keywords The limit is 100 keywords to prevent Amazon API rate limiting. Subscriptions with more than 100 may fail to generate reports. | > | subproduct_id | `STRING` | This product requires a subproduct id which will always be the string `keywords`. | ### Amazon Catalog API -Amazon Catalog API requires no additional API lookups with the Openbridge Service API. However, it is recommended that when choosing the `id_type` of `ASIN` that you use the Openbridge Service API for validating `ASIN` numbers if you are not 100% sure the ASINs you are providing are correct. +Amazon Catalog API requires no additional API lookups with the Openbridge Service API However, it is recommended that when choosing the `id_type` of `ASIN` that you use the Openbridge Service API for validating `ASIN` numbers if you are not 100% sure the ASINs you are providing are correct. __Product Attributes__ > | Key | Value | @@ -354,16 +356,18 @@ __Required Subscription Product Meta__ > | Data Key | Data Format Value | Data Value | > |-|-|-| > | remote_identity_id | `STRING` | Remote identity associated with the associated profile. | -> | ids | `STRING` | A stringified JSON array of ids of the type defined by `id_type`. The limit should be 100 ids to prevent Amazon API rate limiting. Subscriptions with more than 100 may fail to generate reports. | +> | ids | `STRING` | A stringified JSON array of ids of the type defined by `id_type` The limit should be 100 ids to prevent Amazon API rate limiting. Subscriptions with more than 100 may fail to generate reports. | > | identity_type | `STRING` | `seller` or `vendor` depending if the identity type is a seller or a vendor identity. | -> | id_type | `STRING` | The catalog API can be used to request reports on different types of identifiers. `ASIN`,`EAN`, `GTIN`, `ISBN`, `JAN`, `MINSAN`, `SKU`, and `UPC`. Note: that `SKU` types can not be used with `vendor` type identities due to permission restrictions. | +> | id_type | `STRING` | The catalog API can be used to request reports on different types of identifiers `ASIN`,`EAN`, `GTIN`, `ISBN`, `JAN`, `MINSAN`, `SKU`, and `UPC` Note: that `SKU` types can not be used with `vendor` type identities due to permission restrictions. | > | subproduct_id | `STRING` | This product requires a subproduct id which will always be the string `identifiers`. | ## Facebook Products ### Facebook Marketing -Facebook marketing requires a Facebook Ad account ID that is connected to the authorized identity attached to the subscription. A list of available Facebook Ad account IDs can be requested with the [Facebook Ads](service-api.md#facebook-ads) endpoint on the Openbridge Service API. +Facebook marketing requires a Facebook Ad account ID that is connected to the authorized identity attached to the subscription. + +A list of available Facebook Ad account IDs can be requested with the [Facebook Ads](../api-usage-docs/service-facebook-api.md#list-ad-accounts) endpoint on the Openbridge Service API. __Product Attributes__ > | Key | Value | @@ -378,7 +382,10 @@ __Product Attributes__ ### Facebook Page Insights -Facebook marketing requires a Facebook Page account ID that is connected to the authorized identity attached to the subscription. A list of available Facebook Page account IDs can be requested with the [Facebook Page Profiles](service-api.md#facebook-page-profiles) endpoint on the Openbridge Service API. +Facebook marketing requires a Facebook Page account ID that is connected to the authorized identity attached to the subscription. + +A list of available Facebook Page account IDs can be requested with the [Facebook Page Profiles](../api-usage-docs/service-facebook-api.md#list-page-profiles) endpoint on the Openbridge Service API. + __Product Attributes__ > | Key | Value | > |-|-| @@ -392,7 +399,9 @@ __Product Attributes__ ### Instagram Insights -Instagram Insights requires a Instagram account ID that is connected to the authorized identity attached to the subscription. As well as the Facebook page ID that the instagram account is connected too. A list of available Facebook Page account IDs and their attached Instagram Account Ids can be requested with the [Facebook Page Profiles](service-api.md#facebook-page-profiles) endpoint on the Openbridge Service API. +Instagram Insights requires a Instagram account ID that is connected to the authorized identity attached to the subscription as well as the Facebook page ID that the instagram account is connected to. + +A list of available Facebook Page account IDs and their attached Instagram Account Ids can be requested with the [Facebook Page Profiles](../api-usage-docs/service-facebook-api.md#list-page-profiles) endpoint on the Openbridge Service API. __Product Attributes__ > | Key | Value | @@ -409,7 +418,9 @@ __Required Subscription Product Meta__ ### Instagram Stories -Instagram Stories requires a Instagram account ID that is connected to the authorized identity attached to the subscription. As well as the Facebook page ID that the instagram account is connected too. A list of available Facebook Page account IDs and their attached Instagram Account Ids can be requested with the [Facebook Page Profiles](service-api.md#facebook-page-profiles) endpoint on the Openbridge Service API. +Instagram Stories requires a Instagram account ID that is connected to the authorized identity attached to the subscription, as well as the Facebook page ID that the instagram account is connected to. + +A list of available Facebook Page account IDs and their attached Instagram Account Ids can be requested with the [Facebook Page Profiles](../api-usage-docs/service-facebook-api.md#list-page-profiles) endpoint on the Openbridge Service API. __Product Attributes__ @@ -429,7 +440,9 @@ __Required Subscription Product Meta__ ### Google Ads -Google Ads requires a manager customer ID and client customer ID associated with the remote identity attached to the subsciption. A list of available manager customer and client customer IDs can be requested from the Openbridge Service API. +Google Ads requires a manager customer ID and client customer ID associated with the remote identity attached to the subscription. + +A list of available manager customer and client customer IDs can be requested with the [](../api-usage-docs/service-google-api.md#list-managed-customers) in the Openbridge Service API. __Product Attributes__ > | Key | Value | @@ -446,7 +459,9 @@ __Required Subscription Product Meta__ ### Google Analytics 360 -Google Analytics 360 requires a project ID and dataset ID associated with the remote identity attached to the subsciption. A list of available project and dataset IDs can be requested with the [Google Ads](service-api.md#google-ads) endpoint on the Openbridge Service API. +Google Analytics 360 requires a project ID and dataset ID associated with the remote identity attached to the subscription. + +A list of available project and dataset IDs can be requested with the [Google Ads](../api-usage-docs/service-google-api.md#google-search-ads-360) endpoint in the Openbridge Service API. __Product Attributes__ > | Key | Value | @@ -463,7 +478,9 @@ __Required Subscription Product Meta__ ### Google Campaign Manager -Google Campaign Manager requires a profile ID and report ID associated with the remote identity attached to the subsciption. A list of available profile can be requested with the [Google Campaign Manager Profiles](service-api.md#google-campaign-manager-reports) endpoint on the Openbridge Service API and report IDs can be requested with the [Google Campaign Manager Profiles](service-api.md#google-campaign-manager-reports) endpoint +Google Campaign Manager requires a profile ID and report ID associated with the remote identity attached to the subscription. + +A list of available profile can be requested with the [Google Campaign Manager Profiles](../api-usage-docs/service-google-api.md#list-user-profiles) endpoint and report IDs can be requested with the [Google Campaign Manager Reports](../api-usage-docs/service-google-api.md#list-reports) endpoint in the Openbridge Service API. __Product Attributes__ > | Key | Value | @@ -480,7 +497,9 @@ __Required Subscription Product Meta__ ### Google Search Ads 360 -Google Search Ads 360 requires a profile ID and report ID associated with the remote identity attached to the subsciption. A list of available profile and report IDs can be requested with the [Google Search Ads 360](service-api.md#google-search-ads-360) endpoint on the Openbridge Service API. +Google Search Ads 360 requires a profile ID and report ID associated with the remote identity attached to the subscription. + +A list of available profile and report IDs can be requested with the [Google Search Ads 360](../api-usage-docs/service-google-api.md#google-search-ads-360) endpoint on the Openbridge Service API. __Product Attributes__ > | Key | Value | @@ -497,7 +516,9 @@ __Required Subscription Product Meta__ ## Shopify -Shopify 360 requires the shop creation date associated with the remote identity attached to the subsciption. Shopify info can be requested with the [Shopify Info](service-api.md#shopify-info) endpoint on the Openbridge Service API. +Shopify 360 requires the shop creation date associated with the remote identity attached to the subscription. + +Shopify info can be requested with the [Shopify Info](../api-usage-docs/service-shopify-api.md#get-shop-info-graphql) endpoint on the Openbridge Service API. __Product Attributes__ > | Key | Value | @@ -509,13 +530,15 @@ __Required Subscription Product Meta__ > | Data Key | Data Format Value | Data Value | > |-|-|-| > | remote_identity_id | `STRING` | Remote identity associated with the associated profile. | -> | shop_created_at | `STRING` | THe shop creation date in the format of YYYY-mm-dd example 2010-03-01 for March 1st 2010. This information is provided by the shop info endpoint. | +> | shop_created_at | `STRING` | THe shop creation date in the format of YYYY-mm-dd example 2010-03-01 for March 1st 2010 This information is provided by the shop info endpoint | ## Youtube Products ### Youtube Channel Insights -Youtube Channel Insights requires a channgel ID associated with the remote identity attached to the subsciption. A list of available channgel ID can be requested from the Openbridge Service API. +Youtube Channel Insights requires a channel ID associated with a remote identity. + +The [Channel Metadata](../api-usage-docs/service-google-api.md#get-channel-metadata) endpoint of the Openbridge Service API allows you to get youtube channel IDs for a specified Youtube URL. You can provide a maximum of 7 IDs per subscription. __Product Attributes__ > | Key | Value | @@ -531,7 +554,9 @@ __Required Subscription Product Meta__ ### Youtube Competitor Channels -Youtube Competitor Channels requires a list of channel ids as a stringified JSON array. The Openbridge service API allows you to get youtube channel IDs based on various Youtube URLs. You can provide a maximum of 7 IDs per subscription. +Youtube Competitor Channels requires a list of channel ids as a stringified JSON array. + + The [Channel Metadata](../api-usage-docs/service-google-api.md#get-channel-metadata) endpoint of the Openbridge Service API allows you to get youtube channel IDs for a specified Youtube URL. You can provide a maximum of 7 IDs per subscription. __Product Attributes__ > | Key | Value | @@ -547,7 +572,9 @@ __Required Subscription Product Meta__ ### Youtube Competitor Videos -Youtube Competitor Channels requires a list of channel ids as a stringified JSON array. The Openbridge service API allows you to get youtube channel IDs based on various Youtube URLs. You can provide a maximum of 7 IDs per subscription. +Youtube Competitor Videos requires a list of channel IDs as a stringified JSON array. + + The [Channel Metadata](../api-usage-docs/service-google-api.md#get-channel-metadata) endpoint of the Openbridge Service API allows you to get youtube channel IDs for a specified Youtube URL. You can provide a maximum of 7 IDs per subscription. __Product Attributes__ > | Key | Value | @@ -563,7 +590,9 @@ __Required Subscription Product Meta__ ### Youtube Video Insights -Youtube Video Insights requires a channgel ID associated with the remote identity attached to the subsciption. A list of available channgel ID can be requested from the Openbridge Service API. +Youtube Video Insights requires a channgel ID associated with the remote identity attached to the subscription. + +A list of available channgel ID can be requested with the [List Channels](../api-usage-docs/service-google-api.md#list-channels) endpoint the Openbridge Service API. __Product Attributes__ diff --git a/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 0000000..873e13d --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1,3 @@ +mkdocs>=1.6,<2 +mkdocs-material>=9.7,<10 +mkdocs-llmstxt-md>=0.3,<0.4 diff --git a/tutorials/identity-configuration.md b/tutorials/identity-configuration.md index d9c1dc6..e8e07ea 100644 --- a/tutorials/identity-configuration.md +++ b/tutorials/identity-configuration.md @@ -11,7 +11,7 @@ - [Regions](#regions) - [Amazon Advertising regions](#amazon-advertising-regions) - [Amazon Selling Partner and Vendor Central regions](#amazon-selling-partner-and-vendor-central-regions) -- [Step 3 — (Shopify / Snowflake only) Create an OAuth App record](#step-3--shopify--snowflake-only-create-an-oauth-app-record) +- [Step 3 — (Shopify / Snowflake only) Create an OAuth App record](#step-3--create-an-oauth-app-record-if-needed) - [Step 4 — Create a state record](#step-4--create-a-state-record) - [State payload fields](#state-payload-fields) - [Return URL](#return-url) diff --git a/tutorials/subscription-configuration.md b/tutorials/subscription-configuration.md index 36b6ea2..b50e898 100644 --- a/tutorials/subscription-configuration.md +++ b/tutorials/subscription-configuration.md @@ -164,15 +164,15 @@ Use the `id` from the matching record as both the top-level `remote_identity` fi Some products require additional metadata beyond `remote_identity_id` and `stage_ids`. This data typically comes from a third-party API call through the Openbridge Service API. -**Amazon Advertising products** (`profile_id`): Call the [Amazon Advertising Profiles](../service-api.md#amazon-advertising-profiles) endpoint to get available profile IDs for the remote identity. +**Amazon Advertising products** (`profile_id`): Call the [Amazon Advertising Profiles](../api-usage-docs/service-amazon-advertising-api.md#list-profiles) endpoint to get available profile IDs for the remote identity. -**Facebook products** (`ad_account_id`, `account_id`): Call the [Facebook Ads](../service-api.md#facebook-ads) or [Facebook Page Profiles](../service-api.md#facebook-page-insights-instagram-insights-instagram-stories) endpoint. +**Facebook products** (`ad_account_id`, `account_id`): Call the [Facebook Ads](../api-usage-docs/service-facebook-api.md#list-ad-accounts) or [Facebook Page Profiles](../api-usage-docs/service-facebook-api.md#list-page-profiles) endpoint. -**Google products** (`manager_customer_id`, `client_customer_id`, `project_id`, `dataset_id`): Call the relevant [Google endpoint](../service-api.md#google) on the Service API. +**Google products** (`manager_customer_id`, `client_customer_id`, `project_id`, `dataset_id`): Call the relevant [Google endpoint](../api-usage-docs/service-google-api.md) on the Service API. -**Shopify** (`shop_created_at`): Call the [Shopify Info](../service-api.md#shopify-info) endpoint. +**Shopify** (`shop_created_at`): Call the [Shopify Info](../api-usage-docs/service-shopify-api.md#get-shop-info-rest) endpoint. -See the [Product Overview](../products/product-overview.md) for the exact meta fields required per product and the [Service API](../service-api.md) for the endpoint details. +See the [Product Overview](../products/product-overview.md) for the exact meta fields required per product and the [Service API](../api-usage-docs/service-api.md) for the endpoint details. --- @@ -230,7 +230,7 @@ Replace the placeholder values (`account`, `user`, `remote_identity`, `storage_g Amazon Sponsored Ads V3 (product `70`) requires a remote identity plus `profile_id`. It uses identity type `14` (Amazon Advertising). -The `profile_id` comes from calling the [Amazon Advertising Profiles](../service-api.md#amazon-advertising-profiles) endpoint with the remote identity ID. The response returns the available profiles — use the profile ID for the account you want to collect data from. +The `profile_id` comes from calling the [Amazon Advertising Profiles](../api-usage-docs/service-amazon-advertising-api.md#list-profiles) endpoint with the remote identity ID. The response returns the available profiles — use the profile ID for the account you want to collect data from. ```json {