REST API

The REST API lets your own scripts and systems work with Serpier over HTTP. Advertisers on Enterprise can search the Marketplace from their own tools. Publishers can list, create, and update their deals in bulk instead of one at a time. To let an AI assistant work in your account instead, use Serpier MCP.

Base URL#

All endpoints live under https://app.serpier.com/api/v1, on the same host as the MCP server.

Authenticate with a token#

1. Create a personal access token in Settings. It starts with srpr_, and Serpier shows it only once.
2. Send it in the x-api-key header on every request.

curl "https://app.serpier.com/api/v1/publisher/deals?status=pending" \
  -H "x-api-key: srpr_YOUR_TOKEN"

Each request works on the organization that is active on your account. You do not pick an organization per request.

Who can use it#

• Advertisers: marketplace search needs the Enterprise API entitlement, which comes with an Enterprise plan (see Billing). Without it, requests fail with API access is only available on the Enterprise tier.
• Publishers: a publisher organization can create tokens without Enterprise. Those tokens call the publisher deal endpoints only.

Search the marketplace#

POST /api/v1/marketplace/search returns publisher listings. Send the search as a JSON body: a free-text search (a domain, or a comma-separated list of domains), filters, orderBy, page, and limit (at most 100 per page).

curl https://app.serpier.com/api/v1/marketplace/search \
  -H "x-api-key: srpr_YOUR_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "search": "", "filters": [], "orderBy": [], "page": 1, "limit": 20 }'

The response has results, the total number of matches, and currency. Prices are in your organization's payment currency.

Manage publisher deals#

These endpoints work on the deals of the publisher organization behind the token.

• GET /api/v1/publisher/deals lists your deals. Filter by status (active, pending, rejected, or inactive) or by isActive. price is what you receive.
• POST /api/v1/publisher/deals creates up to 1,000 deals in one request. New deals wait for Serpier to approve them before advertisers can order them.
• PATCH /api/v1/publisher/deals updates up to 1,000 deals in one request. Identify each deal by id, or by domain and publicationType.

{
  "deals": [
    {
      "domain": "example.com",
      "publicationType": "ARTICLE",
      "price": 250,
      "priceCurrency": "EUR"
    }
  ]
}

publicationType is ARTICLE, ARTICLE_NOFOLLOW, or HOMEPAGE. A price change applies to future orders; orders already placed keep the price they were placed at.

Create and update return a result for each deal, with succeeded and failed counts. A deal that failed has status: "error" and an error message, so you can fix and resend just those.

Rate limits#

Requests made with a token are rate limited. Over the limit, you get Rate limit exceeded. and a Retry-After header with the number of seconds to wait before you retry.

Try requests in the API reference#

The full reference lists every field and filter, and lets you send requests with your token. On the Personal access tokens card in Settings, open REST API, Marketplace REST API, or Publisher REST API (whichever matches your access) and select Open API docs.