# REST API

> Search the marketplace from your own tools, or list, create, and update publisher deals in bulk, using a personal access token and HTTP requests.

Source: https://docs.serpier.com/rest-api

The REST API lets your own scripts and systems work with Serpier over HTTP. Advertisers on Enterprise can search the [Marketplace](https://docs.serpier.com/marketplace) from their own tools. Publishers can list, create, and update their [deals](https://docs.serpier.com/publisher-deals) in bulk instead of one at a time. To let an AI assistant work in your account instead, use [Serpier MCP](https://docs.serpier.com/mcp).

## Base URL

All endpoints live under `https://app.serpier.com/api/v1`, on the same host as the [MCP server](https://docs.serpier.com/mcp).

## Authenticate with a token

1. Create a personal access token in [Settings](https://docs.serpier.com/account-settings#create-a-personal-access-token). It starts with `srpr_`, and Serpier shows it only once.
2. Send it in the `x-api-key` header on every request.

```bash
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](https://docs.serpier.com/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).

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

```json
{
  "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](https://app.serpier.com/account/settings), open **REST API**, **Marketplace REST API**, or **Publisher REST API** (whichever matches your access) and select **Open API docs**.

## Related

- [Serpier MCP](https://docs.serpier.com/mcp.md)
- [Settings](https://docs.serpier.com/account-settings.md)
- [My Deals](https://docs.serpier.com/publisher-deals.md)
- [Marketplace](https://docs.serpier.com/marketplace.md)