Mkdocs hosting

.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

.pytest_cache/v/cache/stepwise

@@ -0,0 +1 @@
+[]

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

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) |

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` |

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 <jwt>
 ```
 

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.
 
 ---
 

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.
 
 ---
 

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.
 
 ---
 

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 `<path>/index.html` gets a sibling `<path>/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 `<path>/index.md`, not the bare `<path>.md` sibling that fastmcp/Mintlify use — MkDocs' default directory-URL layout (`<path>/index.html`) makes a same-directory `index.md` the natural fit, and a bare `<path>.md` file would collide with the `<path>/` 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).

docs/api-usage-docs

@@ -0,0 +1 @@
+../api-usage-docs

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)

docs/products

@@ -0,0 +1 @@
+../products

docs/tutorials

@@ -0,0 +1 @@
+../tutorials

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