# Placement API

> One API for buying SEO link placements across many suppliers. Named,
> inspectable domains with live prices, verified metrics and real turnaround
> times, bought with prepaid credits on a single invoice.

## What it is
Placement API aggregates backlink placement inventory from multiple
marketplaces into one normalised catalogue, deduplicated by domain, and lets
software purchase from it programmatically.

## Key semantics
- metrics.verification tells you whether a domain's authority is real. "ok"
  means we measured it independently and its search presence matches its
  rating. "suspect" means high link authority with little or no organic
  traffic or keyword footprint, which is what a link farm looks like: do not
  plan around these. "unverified" means we have not measured it yet, which is
  not the same as a pass.
- metrics.dr is the supplier-claimed rating, kept on the scale buyers use.
  metrics.verified_traffic and verified_organic_keywords are ours, measured
  independently. Where a claimed figure and a measured one disagree, the
  measured one is the one to trust.

- inventory_mode: "named" means a specific, identified domain you can inspect
  before buying. "pre_approval" means the supplier proposes domains you approve
  before placement. "blind" means characteristics are guaranteed but the domain
  is assigned at fulfilment. Never present blind inventory as a specific site.
- Prices are integer minor units. Only usd_minor is comparable across
  suppliers; null means not comparable, not free.
- Every price carries observed_at and a stale flag. Prices are periodic
  observations, not live quotes, and are refused at order time beyond 48h.
- Credits are pegged 1:1 to US cents.
- POST /v1/orders requires an Idempotency-Key header.
- Supplier identity is not exposed. You buy from us; which upstream
  marketplace fulfils a placement is not something you can act on.
  /v1/sites/{domain} returns supplier_count and a per-response ordinal so a
  price spread is explicable without naming anyone.
- offer_id values are opaque. Pass back exactly what you were given.
- Rate limits: 1,000 requests and 20,000 returned rows per key per hour, max
  offset 10,000. Separately, a monthly read allowance that grows with credits
  purchased (a new account starts at 5,000 rows). Exceeding any of these
  returns 429 with a reason field and Retry-After. Search with filters
  rather than paginating the whole catalogue; the filters are there so you
  do not have to.

## Endpoints
- GET  /v1/offers            search inventory (DR, price, niche, geo, language)
- POST /v1/quote             a brief in, a costed basket out, at a HELD price
- GET  /v1/sites/{domain}    every way to buy one domain, cheapest first
- POST /v1/orders            place an order (Idempotency-Key required)
- GET  /v1/orders            delivery state: in_progress, overdue, refund_eligible
- GET  /v1/credits           balance, spend limits, ledger entries
- GET  /v1/schema            machine-readable description of the whole API

Base URL: https://api.placementapi.com
Auth: Authorization: Bearer <key>
Start here: GET /v1/schema

## MCP
The same product is a remote MCP server, which is the shorter path if your
host speaks MCP.

  URL     https://api.placementapi.com/mcp
  Auth    Authorization: Bearer <key>
  Add it  claude mcp add --transport http placement-api \
            https://api.placementapi.com/mcp \
            --header "Authorization: Bearer $PLACEMENT_KEY"

Tools: search_placements, plan_links, compare_domain, check_balance,
list_orders.
place_order and cancel_order are listed only for a key issued with the
ordering scope, so a read-only key cannot spend and is not tempted to try.

## Contact
hello@placementapi.com