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 Agent Central 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)

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", "fulfillment"],
    "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

The OpenAPI document assigns a named response and row schema to every endpoint. Stable fields carry string, number, integer, boolean, date, or date-time types; bounded raw Amazon maps remain open objects. Standard TypeScript and Python generators therefore produce endpoint methods with named row models instead of any payloads.

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 Agent Central 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 }
  }
}

To monitor listing state, request up to 20 seller SKUs per call. The endpoint reads Amazon live, then returns one row per requested SKU with a deterministic state_hash. Store each observation in your backend; compare the hash on the next poll. When it changes, diff the listing attributes, classifications, dimensions, offers, or issues returned in the row.

curl -G "https://mcp.agentcentral.to/v1/catalog/listing-state" \
  -H "Authorization: Bearer ac_live_..." \
  --data-urlencode "skus=WIDGET-BLUE-01,WIDGET-GREEN-01"

The response below is shortened. Amazon can take time to propagate listing edits, so a 15-minute polling schedule is an observation cadence rather than a detection guarantee. Agent Central does not retain these live observations for you.

{
  "data": [
    {
      "sku": "WIDGET-BLUE-01",
      "listing_found": true,
      "asin": "B0EXAMPLE01",
      "listing_attributes": {
        "item_type_keyword": [{ "value": "widgets" }],
        "item_package_dimensions": [{
          "length": { "value": 12, "unit": "inches" },
          "width": { "value": 8, "unit": "inches" },
          "height": { "value": 3, "unit": "inches" }
        }]
      },
      "listing_issues": [],
      "listing_offers": [{ "price": { "amount": 24.99, "currencyCode": "USD" } }],
      "catalog_found": true,
      "catalog_classifications": [{
        "marketplaceId": "ATVPDKIKX0DER",
        "classifications": [{ "classificationId": "123456789", "displayName": "Widgets" }]
      }],
      "catalog_dimensions": [],
      "amazon_listing_last_updated_at": "2026-08-28T16:40:12.000Z",
      "state_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  ],
  "meta": {
    "version": "v1",
    "endpoint": "catalog.listing_state",
    "generated_at": "2026-08-28T16:45:00.000Z",
    "marketplace_id": "ATVPDKIKX0DER",
    "filters": { "skus": ["WIDGET-BLUE-01", "WIDGET-GREEN-01"], "live": true },
    "warnings": ["This is a live observation, not retained history."]
  }
}

For retained history, use /v1/catalog/listing-changes. It compares the two latest stored snapshots in the requested window, then returns one row per changed field. Catalog history covers content, product type, browse classifications, images, and item or package dimensions; weekly Listings Items history covers backend search terms.

curl -G "https://mcp.agentcentral.to/v1/catalog/listing-changes" \
  -H "Authorization: Bearer ac_live_..." \
  --data-urlencode "asin=B0EXAMPLE01" \
  --data-urlencode "field=title,product_type,classification_ids,package_height" \
  --data-urlencode "lookback_days=60"

{
  "data": [
    {
      "asin": "B0EXAMPLE01",
      "sku": null,
      "current_snapshot_date": "2026-09-04",
      "previous_snapshot_date": "2026-08-28",
      "changed_field": "package_height",
      "previous_value": "2",
      "current_value": "3",
      "source": "catalog_weekly"
    }
  ],
  "meta": {
    "version": "v1",
    "endpoint": "catalog.listing_changes",
    "generated_at": "2026-09-04T16:45:00.000Z",
    "marketplace_id": "ATVPDKIKX0DER",
    "filters": {
      "asin": "B0EXAMPLE01",
      "fields": ["title", "product_type", "classification_ids", "package_height"],
      "lookback_days": 60
    },
    "freshness": {
      "data_through": "2026-09-04",
      "sources": [{ "source": "append-only Catalog Items and weekly Listings Items snapshots", "available": true }]
    },
    "warnings": []
  }
}

Retained history begins with the first successful catalog sync after the history table is enabled. Existing accounts receive one baseline snapshot at that point; Agent Central does not invent earlier history. A first-snapshot account returns an insufficient history warning until a second snapshot exists. The route follows the stored snapshot cadence, not a change-detection SLA.

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"

Live reads that page through Amazon use opaque continuation tokens instead of offsets. Pass max_pages to bound how many Seller Central pages to fetch (1–5; the default is 1). Each response returns the next token in meta.pagination.next_token with pages_fetched and max_pages; some list reads report page_size. Keep passing the returned token until more_rows_possible is false.

# first page of live payment transactions (last 7 days)
curl -G "https://mcp.agentcentral.to/v1/finance/payment-transactions"   -H "Authorization: Bearer ac_live_..."   --data-urlencode "view=summary"   --data-urlencode "start_date=2026-08-11"   --data-urlencode "end_date=2026-08-18"   --data-urlencode "max_pages=1"

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
upstream_unavailable	503	Amazon failed, timed out, or throttled a live read; retry shortly. Amazon 400 rejections (bad parameters) surface as invalid_request (400) instead
internal_error	500	Unexpected server error

Available endpoints

The full, authoritative list of paths, parameters, sort columns, named row models, and response schemas is the public OpenAPI 3.1 document. No key is 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/finance/product-fee-estimates	Current, historical, and changed Amazon fee estimates	finance
/v1/finance/financial-events	Factual fee components and ASIN economics	finance
/v1/ads/promotions	Coupon and deal performance	ads
/v1/ads/brand-search-terms	Brand Analytics term ranks and clicked-product shares	ads
/v1/inventory/pricing-history	Stored Buy Box and competitive-pricing snapshots	inventory
/v1/inventory/listing-offers	Seller price, sale window, List Price, and refresh state	inventory
/v1/catalog/products	Catalog item details and sales rank	catalog
/v1/catalog/product-details	Normalized content, images, dimensions, BSR, and source dates	catalog
/v1/catalog/product-type-definition	Bounded Amazon product-type requirements or schema	catalog
/v1/catalog/listing-registry	Listing, search, and brand-ASIN registry views	inventory
/v1/catalog/listing-quality	Listing summary or Amazon issue details	catalog
/v1/catalog/listing-state	Live listing attributes, classifications, dimensions, offers, issues, and state hash	catalog
/v1/catalog/listing-changes	Retained field changes between catalog and listing snapshots	catalog
/v1/keywords/ranks	Organic keyword rank positions	ranking
/v1/inventory/subscribe-and-save	Live Subscribe & Save status, snapshot history, and metrics	inventory
/v1/finance/payment-transactions	Live payment and refund transactions over a bounded window	finance
/v1/fba-inbound/plan	Live FBA inbound plans, items, boxes, pallets, and shipments	fulfillment
/v1/fba-inbound/options	Live packing, placement, and transportation options	fulfillment
/v1/fba-inbound/operation-status	Live status of an async inbound operation	fulfillment
/v1/fba-inbound/documents	Short-lived download links for inbound shipping documents	fulfillment

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.
Facts and audited actions, not advice. Endpoints return facts, source fields, and deterministic metrics with documented formulas. They do not return recommendations or next actions.
Synced data plus bounded live reads. Most endpoints read the same pre-synced data as the dashboard and the MCP server. A set of live Seller Central reads (Buy Box, competitive pricing, current rank, listing state, Product Type Definitions, offer listings, reviews, Subscribe & Save, payment transactions, FBA inbound plans, options, operation status, and shipping documents) call Amazon in real time when you request them, so they consume your Seller Central API quota and can return upstream_unavailable (503) when Amazon fails or throttles. The full live set is the OpenAPI document; all live routes are marked as live reads there.
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 Agent Central works.