---
name: build-api
description: Read marketplace and ad data (Amazon, Google Ads) and make guarded changes on Amazon through Build by SellerMate. Use it when a task needs campaign, search term, order or inventory numbers across accounts, or a bid change on Amazon.
---

# Build API (v1)

Build by SellerMate is one API for marketplace and ad data. Every tool is a single POST that returns rows in the same field names on every platform. Call shape v1; it is illustrative until the contract is final.

## When to use it

- You need campaign, search term, order or inventory data for one or more connected accounts.
- You want Amazon and Google Ads in one table. Rows use the same names (`platform`, `account_id`, `campaign_name`, `spend`, `clicks`, `orders`, `sales`, `acos`, `currency`).
- You need to change a bid, budget or target on Amazon, with a dry run first.

Do not use it to write to Google Ads or any other platform. Writes exist on Amazon only. Every other platform is read-only. Amazon and Google Ads are live. Walmart, Flipkart, TikTok Shop and Meta Ads are coming soon.

## The call

```
POST https://build-api.sellermate.ai/v1/tools/{name}
X-API-Key: sm_live_...
Content-Type: application/json
```

Tool names come from https://build.sellermate.ai/openapi.json: each operation's `operationId` is the tool name. Check it before you call; never guess a name. Today they are `get_campaign_performance`, `get_search_term_performance`, `get_orders_report`, `get_inventory`, `update_target`. The body is JSON. The response has `rows` and `meta`.

## Auth

- Send the key in the `X-API-Key` header. Keep it in the `BUILD_API_KEY` environment variable or your tool's secrets, never in page code.
- `sm_live_` keys are made in the console. A key is read, or read and write, scoped to the accounts you pick, and revocable in one click.
- `sm_test_` is the sandbox key: read-only, on demo data, same shape. Find it in the console quickstart.
- Rate limits: 60/min on Free and Build, 300/min on Scale. Over the limit returns `429` with a retry time (`retry`, in seconds) and an `upgrade` link. Wait, then retry.
- Data retention: Free 90 days, Build 12 months, Scale 3 years.

## Writes are Amazon only

Writes need a key with the read and write scope and a real connected Amazon account. Send `"dry_run": true` first. A change that breaks a guardrail (a bid or budget cap, or how far one change can move it) returns `422` and says which guardrail blocked it. Nothing reaches Amazon. Lower the value and retry. Send an `Idempotency-Key` header so a retry never applies twice. Every applied change is in the audit log and can be undone for 24 hours.

## Three example calls

Campaign performance for one account (call it again for a Google Ads account to put the two side by side):

```bash
curl -X POST https://build-api.sellermate.ai/v1/tools/get_campaign_performance \
  -H "X-API-Key: $BUILD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account":"acct_123","start":"2026-10-01","end":"2026-10-28"}'
```

Search terms for one account:

```bash
curl -X POST https://build-api.sellermate.ai/v1/tools/get_search_term_performance \
  -H "X-API-Key: $BUILD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account":"acct_123","start":"2026-10-01","end":"2026-10-28"}'
```

A bid change on Amazon, as a dry run first:

```bash
curl -X POST https://build-api.sellermate.ai/v1/tools/update_target \
  -H "X-API-Key: $BUILD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bid-0142" \
  -d '{"account":"acct_123","dry_run":true,"changes":[{"target_id":"tgt_41c","bid":1.90}]}'
```

## data_as_of

Every answer carries `meta.data_as_of` (UTC) and, when recent days are still moving, `meta.settling_from`. Amazon sales keep moving for up to 14 days; Build re-pulls those days until they settle. Quote `data_as_of` when you report numbers, and treat rows on or after `settling_from` as provisional.

## Docs

Every docs page is also Markdown: add `.md` to its path.

- [First call in 60 seconds](https://build.sellermate.ai/docs/get-started/first-call.md): Make a first real call to Build with the sandbox key or your own, and read the answer.
- [API reference overview](https://build.sellermate.ai/docs/api-reference/overview.md): Every Build tool is one POST with a JSON body, the same fields on every platform, and an X-API-Key header.
- [Keys and scopes](https://build.sellermate.ai/docs/guides/keys-and-scopes.md): How a Build key authenticates, what it can reach, and how to revoke or rotate it.
- [Plans and limits](https://build.sellermate.ai/docs/guides/plans-and-limits.md): What each Build plan includes: accounts, data retention and requests per minute.
- [Writes and guardrails](https://build.sellermate.ai/docs/guides/writes-and-guardrails.md): How changes to an Amazon account work on Build: caps, a dry run, idempotency keys, a 24 hour undo and an audit log.
- [Amazon](https://build.sellermate.ai/docs/platforms/amazon.md): Seller, Vendor, Ads, DSP and AMC under one key, with every data set, its status and its freshness.
- [Google Ads](https://build.sellermate.ai/docs/platforms/google-ads.md): Client and manager accounts under one consent, read-only, with campaigns, search terms and conversions next to your Amazon numbers.
- [Trust](https://build.sellermate.ai/docs/trust.md): What Build claims today about keys, writes, credentials and data, and nothing more.

Full docs: https://build.sellermate.ai/docs. Page list: https://build.sellermate.ai/llms.txt. Every page in one file: https://build.sellermate.ai/llms-full.txt. Tools and schemas: https://build.sellermate.ai/openapi.json.