Overview

The Partner API lets an external platform read the LinkWatcher marketplace catalog, place orders that are paid from your LinkWatcher wallet, and track those orders until delivery. It is built for partners who resell or embed our marketplace inside their own product.

Base URL: https://app.linkwatcher.io/api/v1

Everything is JSON over HTTPS. Timestamps are ISO-8601 in UTC (2026-09-24T08:15:30.000Z). Money is in US dollars as plain numbers (52.5).

The API is split over four articles: this overview, the catalog, orders, and security.

Getting access

1. Partner API access is part of Marketplace Enterprise ($45/month): everything in Marketplace Pro plus the API. Upgrade under Marketplace Settings > Marketplace Pro in the LinkWatcher app. Existing Pro subscribers upgrade in place and only pay the prorated difference. Agencies and platforms with special requirements can also write to support@linkwatcher.io.
2. Once Enterprise is active, open Marketplace Settings > API Access.
3. Create a key. The full key is shown exactly once. Store it in your platform's secret manager; it can never be displayed again.
4. Top up your LinkWatcher wallet in the dashboard. Orders placed through the API are paid from this balance (see Payments and balance).

What a key carries

You can have up to 5 active keys. Give every integration its own key and revoke it from the same page the moment you suspect a leak. Creating and revoking keys always emails the account owner.

Authentication

Send the key as a bearer token on every request:

curl https://app.linkwatcher.io/api/v1/me \
  -H "Authorization: Bearer lw_live_YOUR_KEY"

Response:

{
  "userId": "e66f5d28-...",
  "email": "you@example.com",
  "fullName": "Your Name",
  "apiKey": { "id": "...", "name": "production", "prefix": "lw_live_45d0e7b1", "scopes": ["catalog:read", "orders:read", "orders:write"] }
}

Rules:

• HTTPS only. Plain HTTP is refused.
• Keys look like lw_live_ followed by 64 hex characters. Only a hash is stored on our side.
• A key belongs to one LinkWatcher account. Everything it reads or writes is scoped to that account.
• Keys cannot create, list or revoke keys; that only happens in the dashboard with a logged-in session.

Quick start for developers

Every request is a plain HTTPS call with one header. Below are the same two calls in Node.js and Python; the full contract is also published as an OpenAPI 3.1 document at linkwatcher.io/partner-api/openapi.yaml for client generators and API tools.

Node.js (18+, built-in fetch):

const BASE = "https://app.linkwatcher.io/api/v1";
const headers = { Authorization: `Bearer ${process.env.LINKWATCHER_API_KEY}`, "Content-Type": "application/json" };

async function api(path, init = {}) {
  const res = await fetch(BASE + path, { ...init, headers });
  const body = await res.json();
  if (!res.ok) throw Object.assign(new Error(body.error?.message), { code: body.error?.code, status: res.status, body });
  return body;
}

const me = await api("/me");
const page = await api("/catalog/domains?hasCompletedOrders=true&sortBy=completed&limit=100&page=1");
const order = await api("/orders", {
  method: "POST",
  body: JSON.stringify({
    domainId: page.domains[0].id,
    publisherId: page.domains[0].offerings[0].publisherId,
    serviceType: "link_insertion",
    targetUrl: "https://client-site.com/page",
    anchorText: "best running shoes",
    externalRef: "your-order-123",
  }),
});
console.log(order.order.orderNumber, order.order.status);

Python (3.9+, requests):

import os, requests

BASE = "https://app.linkwatcher.io/api/v1"
S = requests.Session()
S.headers["Authorization"] = f"Bearer {os.environ['LINKWATCHER_API_KEY']}"

def api(method, path, **kwargs):
    r = S.request(method, BASE + path, timeout=30, **kwargs)
    body = r.json()
    if not r.ok:
        raise RuntimeError(f"{r.status_code} {body['error']['code']}: {body['error']['message']}")
    return body

me = api("GET", "/me")
page = api("GET", "/catalog/domains", params={"hasCompletedOrders": "true", "sortBy": "completed", "limit": 100, "page": 1})
order = api("POST", "/orders", json={
    "domainId": page["domains"][0]["id"],
    "publisherId": page["domains"][0]["offerings"][0]["publisherId"],
    "serviceType": "link_insertion",
    "targetUrl": "https://client-site.com/page",
    "anchorText": "best running shoes",
    "externalRef": "your-order-123",
})
print(order["order"]["orderNumber"], order["order"]["status"])

Integration walkthrough

A typical integration has three jobs:

1. Catalog sync (daily). Page through GET /catalog/domains?hasCompletedOrders=true&limit=100 and store each domain with the offering you chose (see Catalog endpoints for the selection recipe). On later runs pass updatedAfter=<last sync> to fetch only changes, and drop domains that no longer come back.
2. Ordering. Re-fetch the domain with GET /catalog/domains/{id} right before ordering (price and availability can change), then POST /orders with your own id in externalRef. Store the returned order.id and orderNumber. Handle 402 insufficient_balance by topping up the wallet in the dashboard; nothing was charged.
3. Tracking (every 15 to 60 minutes). GET /orders?statusIn=paid,accepted,in_progress,clarification_requested,submitted,revision_requested and update your records from status, publishedUrl and deadlineAt. Answer clarification_requested orders promptly, and approve or request a revision on submitted ones within 72 hours. See Order endpoints.

Treat every non-2xx response as described in the error table below, honour Retry-After on 429, and never log the key.

Rate limits

Limits are per key, in fixed one-minute windows.

Every successful response carries X-RateLimit-Limit and X-RateLimit-Remaining. When you exceed a limit you get 429 rate_limited with a Retry-After header (seconds) and retryAfter in the body. Back off until then. Unknown keys are throttled per source IP as well.

Errors

Every error uses the same envelope:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient wallet balance. Top up your LinkWatcher balance in the dashboard and retry.",
    "required": 52.5,
    "available": 20,
    "topUpUrl": "https://app.linkwatcher.io/marketplace/balance"
  }
}

Error messages never contain your input, stack traces or internal ids.

Pagination

List endpoints take page (from 1) and limit (1 to 100, default 50) and return:

"pagination": { "page": 1, "limit": 50, "total": 312, "totalPages": 7 }

Pages are stable between calls (deterministic ordering), so you can walk them safely.

Endpoints at a glance

Changelog

• 2026-09-24: v1 released. Catalog, wallet balance, place and track orders, approve, revision, clarification answers. Access is included in Marketplace Enterprise.