> ## Documentation Index
> Fetch the complete documentation index at: https://docs.droplinked.com/llms.txt
> Use this file to discover all available pages before exploring further.

# InventoryOS overview

> The headless inventory data layer — eight streams × five consumer surfaces, exposed via REST + webhook subscriptions.

<Note>**BETA.** Stream shapes, cursor encoding, and webhook event names may change before GA. The surface is gated by the `INVENTORY_OS_API_ENABLED` server flag.</Note>

**InventoryOS** is Droplinked's headless inventory data layer. The same SKU + provenance +
stock-level + sell-through record simultaneously serves five orthogonal consumer surfaces — a
lending underwriter, an agentic buyer surface, a merchant program builder, a 3PL partner, and a
compliance gate — without the surfaces ever speaking to each other.

The API is the partner-facing surface of that layer. You read streams, register for webhook
deliveries, and stitch InventoryOS into your own systems.

## The eight streams

<CardGroup cols={2}>
  <Card title="1. Catalog" icon="box" href="/developers/inventory-os-api/streams/catalog">
    Product records — titles, slugs, type, status, tags. Sourced from `ProductV2`.
  </Card>

  <Card title="2. Inventory level" icon="warehouse" href="/developers/inventory-os-api/streams/inventory-level">
    Stock per SKU. Quantity + available, sourced from `ProductSkuV2`.
  </Card>

  <Card title="3. Sell-through" icon="chart-line" href="/developers/inventory-os-api/streams/sell-through">
    Per-sale commission events — sale amount, commission, status. Sourced from `CommissionEventV2`.
  </Card>

  <Card title="4. Return rate" icon="rotate-left" href="/developers/inventory-os-api/streams/return-rate">
    Refunded + cancelled orders, sourced from `OrderV2`.
  </Card>

  <Card title="5. Pricing" icon="tag" href="/developers/inventory-os-api/streams/pricing">
    List price, raw price, royalty per SKU. Sourced from `ProductSkuV2`.
  </Card>

  <Card title="6. Attribution" icon="link" href="/developers/inventory-os-api/streams/attribution">
    Affiliate attribution records — link token, agent, session. Sourced from `AffiliateAttributionRecord`.
  </Card>

  <Card title="7. Settlement" icon="money-bill-transfer" href="/developers/inventory-os-api/streams/settlement">
    Order payment + financial detail projection. Sourced from `OrderV2`.
  </Card>

  <Card title="8. Provenance" icon="link-simple" href="/developers/inventory-os-api/streams/provenance">
    Onchain NFT recording per product (chain, contract, token, tx). Sourced from `ProductV2.nftRecording`.
  </Card>
</CardGroup>

## The five consumer surfaces

| Surface                      | Streams consumed            | Typical integrator                                        |
| ---------------------------- | --------------------------- | --------------------------------------------------------- |
| **Lending underwriter**      | 2, 3, 4, 7, 8               | CredibleX, US LFI corridor lenders, Tier-3 vault partners |
| **Agentic buyer discovery**  | 1, 2, 5, 8                  | MCP clients, ACP-feed consumers, x402 buyers              |
| **Merchant program builder** | 1, 5, 6, 7                  | Affiliate engine, dynamic-pricing, lending eligibility UX |
| **3PL data partner**         | 2, 3, 4 outbound; 8 inbound | Stord, Flowspace, ShipHero                                |
| **Compliance gate**          | 6, 7, 8                     | FTC engine, 1099-NEC export, AML/Travel Rule              |

You only need the streams that map to your surface. A lender doesn't need attribution (6); a 3PL
doesn't need settlement (7); an agentic buyer doesn't need return-rate (4).

## Why the data layer is multi-purpose

The same canonical record powers multiple surfaces because each stream is a per-surface read
projection over the underlying merchant resources (`ProductV2`, `ProductSkuV2`, `OrderV2`,
`CommissionEventV2`, `AffiliateAttributionRecord`). A merchant updates a SKU once — the catalog
read model reflects it, and the same row underpins the ACP feed, the lending collateral catalog,
the affiliate program builder, the 3PL partner sync, and the compliance audit trail.

## Auth + scopes (quick recap)

* All stream + subscription endpoints require an InventoryOS API key sent as
  `x-droplinked-api-key: <key>`.
* Read endpoints require the `inventory-os:streams:read` scope.
* Listing subscriptions requires `inventory-os:subscriptions:read`; creating/deleting them
  requires `inventory-os:subscriptions:write`.

See [Getting started](/developers/getting-started) for full auth, scopes, rate limits, and
cursor pagination.

## Base path

```
https://apiv3.droplinked.com/v1/api/inventory-os
```

Every stream read lives under `/streams/:streamType`; webhook subscriptions are managed under
`/streams/:streamType/subscribe` and `/streams/:streamType/subscriptions`.

## Endpoints

| Operation                              | Method + path                                                       | Scope                              |
| -------------------------------------- | ------------------------------------------------------------------- | ---------------------------------- |
| Read a stream (paginated)              | `GET /v1/api/inventory-os/streams/:streamType`                      | `inventory-os:streams:read`        |
| Cached snapshot (first 200 rows)       | `GET /v1/api/inventory-os/streams/:streamType/snapshot`             | `inventory-os:streams:read`        |
| Subscribe a webhook to a stream        | `POST /v1/api/inventory-os/streams/:streamType/subscribe`           | `inventory-os:subscriptions:write` |
| List a key's subscriptions on a stream | `GET /v1/api/inventory-os/streams/:streamType/subscriptions`        | `inventory-os:subscriptions:read`  |
| Delete a subscription                  | `DELETE /v1/api/inventory-os/streams/:streamType/subscriptions/:id` | `inventory-os:subscriptions:write` |
| Discovery manifest                     | `GET /v1/api/inventory-os/manifest`                                 | none (public)                      |

`:streamType` is one of: `catalog`, `inventory-level`, `sell-through`, `return-rate`, `pricing`,
`attribution`, `settlement`, `provenance`. An unknown stream type returns a 404-class error.

## Webhook subscriptions

Most integrators subscribe rather than poll. Register a callback URL on a specific stream; we
deliver HMAC-SHA256-signed JSON POSTs when the stream's rows change for your merchant.

See [Webhook subscriptions](/developers/inventory-os-api/subscriptions) for the create flow,
event vocabulary, and the one-time HMAC signing secret.

<a id="discovery-manifest" />

## Discovery manifest

`GET /v1/api/inventory-os/manifest` is intentionally **unauthenticated** so SDK generators,
agent crawlers, and vector indexers can read the API shape at build time. It returns the stream
vocabulary, per-stream rate limits, the scope vocabulary, the auth header names, and a pointer
to the OpenAPI spec (`/api-doc-json`). No merchant data ever surfaces there.

```bash theme={null}
curl https://apiv3.droplinked.com/v1/api/inventory-os/manifest
```

<Card title="Next: catalog stream" icon="box" href="/developers/inventory-os-api/streams/catalog">
  The product record — titles, slugs, status.
</Card>