REST API

REST API quickstart

A read-only JSON API over your synced Amazon seller data, for server-side dashboards and reporting backends. Same account, same API key, same data as the MCP server, addressed over plain HTTP instead of MCP. It is read-only and currently in beta.

When to use the REST API

Use the REST API when code, not an agent, is the caller: a nightly job that refreshes a dashboard, a reporting backend, or a script that pulls a few hundred SKUs on a schedule. If you are connecting Claude, ChatGPT, OpenClaw, or another assistant, use the MCP quickstarts instead. Both surfaces read the same data.

Prerequisites

An agentcentral account with a connected Amazon account
An API key from the dashboard (starts with ac_live_)
The data domains you plan to read enabled on that key (for example ads and inventory)

Let your coding agent build the client

Copy this into Claude Code, Cursor, or any coding agent to scaffold a typed client straight from the live OpenAPI spec.

Base URL and authentication

All endpoints live under one base URL:

https://mcp.agentcentral.to/v1

Authenticate every request with your API key as a bearer token. It is the same key the MCP server uses.

Authorization: Bearer ac_live_...

Server-side only

The REST API does not send permissive CORS headers, so browser preflight requests are rejected. Call it from your backend and keep ac_live_ keys out of client-side code. Each call is metered against the same rate limit and hourly request quota as MCP.

Your first request

GET /v1/account confirms which account and marketplace a key is bound to, with no data query and no domain requirement. It is the fastest way to verify a key works.

curl "https://mcp.agentcentral.to/v1/account" \
  -H "Authorization: Bearer ac_live_..."

A successful response:

{
  "data": {
    "api_version": "v1",
    "tenant_id": "tenant_8f2c",
    "key_prefix": "ac_live_a1b2c3d4",
    "key_scope": "marketplace",
    "status": "active",
    "marketplace_id": "ATVPDKIKX0DER",
    "connection_id": "conn_3a91",
    "reporting_time_zone": "America/Los_Angeles",
    "enabled_domains": ["ads", "inventory", "catalog", "finance", "ranking"],
    "ads_profile_ids": ["1234567890"],
    "max_exposure_lookback_days": null,
    "connections": {
      "amazon_ads": { "connected": true, "connected_at": "2026-05-01T12:00:00.000Z" },
      "seller_central": { "connected": true, "connected_at": "2026-05-01T12:00:00.000Z" }
    }
  },
  "meta": {
    "version": "v1",
    "endpoint": "account",
    "generated_at": "2026-06-17T18:30:00.000Z",
    "marketplace_id": "ATVPDKIKX0DER",
    "filters": {},
    "warnings": []
  }
}

Response envelope

Every successful response is { data, meta }. data is an array of rows for list endpoints, or an object for /v1/account and /v1/freshness. meta carries the request context:

version, endpoint, generated_at, and marketplace_id
filters: the resolved filters and sort the query actually ran with, including defaults applied on your behalf
warnings: non-fatal notes, such as a metric returned null because its domain is not enabled, or a date range trimmed to what a trial key can read
pagination on list endpoints, and freshness where a “data through” date applies

Every failure is { error: { code, message, details } } with a stable, machine-readable code. Messages never contain SQL, stack traces, or secrets.

{
  "error": {
    "code": "domain_not_enabled",
    "message": "This endpoint requires the 'inventory' domain. Enable it for this key in the agentcentral dashboard.",
    "details": []
  }
}

More examples

Per-SKU performance joins sales, advertising, and the latest inventory snapshot over a date range. Filters and sort are passed as query parameters; allowed sort columns are listed per endpoint in the OpenAPI document.

curl -G "https://mcp.agentcentral.to/v1/skus/performance" \
  -H "Authorization: Bearer ac_live_..." \
  --data-urlencode "start_date=2026-05-18" \
  --data-urlencode "end_date=2026-06-17" \
  --data-urlencode "sort_by=ad_spend" \
  --data-urlencode "limit=50"

The response (one row shown, trimmed for brevity):

{
  "data": [
    {
      "sku": "WIDGET-BLUE-01",
      "asin": "B0EXAMPLE01",
      "parent_asin": "B0EXAMPLE00",
      "item_name": "Blue Widget, 2-Pack",
      "units_ordered": 412,
      "ordered_product_sales": 8230.88,
      "sessions": 5120,
      "unit_session_percentage": 8.05,
      "ad_spend": 940.5,
      "ad_sales": 4120.0,
      "acos": 22.83,
      "roas": 4.38,
      "inventory_fulfillable": 1340,
      "inventory_inbound": 600,
      "latest_inventory_snapshot_date": "2026-06-17"
    }
  ],
  "meta": {
    "version": "v1",
    "endpoint": "skus.performance",
    "generated_at": "2026-06-17T18:30:00.000Z",
    "marketplace_id": "ATVPDKIKX0DER",
    "filters": {
      "start_date": "2026-05-18",
      "end_date": "2026-06-17",
      "asin": null,
      "sku": null,
      "sort_by": "ad_spend",
      "sort_order": "desc"
    },
    "warnings": [],
    "pagination": { "limit": 50, "offset": 0, "next_offset": 50, "more_rows_possible": true },
    "freshness": {
      "data_through": "2026-06-17",
      "sources": [{ "source": "fba_inventory", "data_through": "2026-06-17", "available": true }]
    }
  }
}

Customer search terms that triggered Sponsored Products or Sponsored Brands ads, with derived ACOS, ROAS, CTR, CPC, and CVR:

curl -G "https://mcp.agentcentral.to/v1/ads/search-terms" \
  -H "Authorization: Bearer ac_live_..." \
  --data-urlencode "ad_product=SP" \
  --data-urlencode "sort_by=spend" \
  --data-urlencode "limit=25"

{
  "data": [
    {
      "ad_product": "SP",
      "campaign_id": "300000000000001",
      "campaign_name": "SP | Widgets | Exact",
      "ad_group_name": "Blue Widgets",
      "search_term": "blue widget 2 pack",
      "keyword": "blue widget",
      "match_type": "EXACT",
      "impressions": 9820,
      "clicks": 214,
      "spend": 168.42,
      "sales": 742.0,
      "orders": 37,
      "acos": 22.7,
      "roas": 4.4,
      "ctr": 2.18,
      "cpc": 0.79,
      "cvr": 17.29
    }
  ],
  "meta": {
    "version": "v1",
    "endpoint": "ads.search_terms",
    "generated_at": "2026-06-17T18:30:00.000Z",
    "marketplace_id": "ATVPDKIKX0DER",
    "filters": {
      "start_date": "2026-05-18",
      "end_date": "2026-06-17",
      "ad_product": "SP",
      "sort_by": "spend",
      "sort_order": "desc"
    },
    "warnings": [],
    "pagination": { "limit": 25, "offset": 0, "next_offset": 25, "more_rows_possible": true }
  }
}

Pagination

List endpoints use offset pagination. limit defaults to 100 and caps at 1000; offset caps at 10000. When a page comes back full, meta.pagination.next_offset is set to the next offset and more_rows_possible is true; when it is the last page, next_offset is null. The API does not run a separate count, so this signals “there may be more” rather than an exact total. Page until next_offset is null.

# next page of the SKU example above
curl -G "https://mcp.agentcentral.to/v1/skus/performance" \
  -H "Authorization: Bearer ac_live_..." \
  --data-urlencode "sort_by=ad_spend" \
  --data-urlencode "limit=50" \
  --data-urlencode "offset=50"

Error codes

code is stable across the v1 lifetime; branch on it rather than on HTTP status or message text.

Code	HTTP	When
invalid_request	400	Unknown sort_by, malformed date, or an out-of-range limit/offset
unauthorized	401	Missing, malformed, or invalid API key
domain_not_enabled	403	The endpoint's data domain is not enabled for this key
connection_required	403	The required Amazon connection is not set up yet
forbidden	403	The key lacks a permission the endpoint requires
not_found	404	Unknown path, or a write method (the API is read-only)
rate_limited	429	Burst rate limit exceeded; retry after a short pause
quota_exceeded	429	Hourly request quota exhausted for the key
internal_error	500	Unexpected server error

Available endpoints

The full, authoritative list of paths, parameters, sort columns, and schemas is the public OpenAPI 3.1 document. No key required:

https://mcp.agentcentral.to/v1/openapi.json

A representative sample across domains:

Endpoint	Returns	Domain
/v1/account	Key scope, marketplace, enabled domains, connection status	none
/v1/freshness	Most recent date available per data source	any
/v1/skus/performance	Per-SKU sales, advertising, and latest inventory	ads or inventory
/v1/ads/campaigns	Sponsored Products campaign performance	ads
/v1/ads/search-terms	Customer search terms that triggered SP/SB ads	ads
/v1/sales/daily	Per-day units, sales, sessions, conversion	ads
/v1/inventory	Latest FBA inventory snapshot by SKU/ASIN	inventory
/v1/inventory/days-of-cover	Deterministic days of cover per SKU	inventory
/v1/orders	Order headers over a date range	inventory
/v1/finance/settlements	Settlement line items	finance
/v1/catalog/products	Catalog item details and sales rank	catalog
/v1/keywords/ranks	Organic keyword rank positions	ranking

Scope and limits

Read-only. No write methods are exposed. There is no SQL endpoint and no arbitrary table access; filters and sorts are matched against per-endpoint allowlists and bound as query parameters.
Data layer, not advice. Endpoints return facts, source fields, and deterministic metrics with documented formulas. They do not return recommendations or next actions.
Synced data. v1 reads the same pre-synced data as the dashboard and the MCP server. Live SP-API and Amazon Ads direct calls are not exposed over REST.
Per-key scope. Responses are scoped to the key’s account, marketplace, and Ads profiles, and to the domains enabled on the key. Trial keys see a bounded recent window; an out-of-range request returns a warning in meta.warnings.
Beta. Response shapes may evolve within v1. Read fields by name and tolerate new ones.

New to the platform? Read how agentcentral works.