REST API quickstart

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_...

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 for a key with Amazon writes disabled:

{
  "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"],
    "permissions": ["agent_actions:read"],
    "permissions_semantics": "special_capabilities_not_general_write_scope",
    "tool_access": {
      "basis": "key_configuration",
      "amazon_writes_enabled": false,
      "enabled_write_tools": [],
      "enabled_state_side_effect_tools": ["refresh_listing_offer_observations", "submit_conversation_feedback"]
    },
    "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": []
  }
}

key_scope is tenant, marketplace, or brand. It describes account coverage, not write access. enabled_domains lists the key's data areas. permissions lists special capabilities: agent_actions:read allows action-history reads; fba_inbound:write is an additional requirement for guarded inbound-shipping writes. An empty permissions array does not mean the key is read-only.

Check tool_access.amazon_writes_enabled. A value of false, with an empty tool_access.enabled_write_tools list, means no Amazon-write tools are allowed by the key's current configuration. This check uses key scope, enabled domains, tool exclusions, and special permissions. It does not mistake a missing connection, billing pause, unsupported marketplace, or runtime write gate for a read-only key. Recheck after changing key access.

REST itself has no Amazon-write endpoints, even for a write-enabled key. The same key can use its allowed writes through MCP or the CLI. tool_access.enabled_state_side_effect_tools separately lists registry-classified local workflows, such as observation refreshes. Those can queue refresh work or submit product feedback without changing Amazon business state. Normal usage and audit recording still occurs.

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. Payment balance and financial-summary views return exactly one complete upstream page per call, so they require max_pages=1.

# 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"

Payment balances and summaries

Use the same payment-transactions endpoint with view=balances for current available, reserved, deferred and total funds. Add as_of_date for a historical date instead. view=financial_summary returns net proceeds and breakdowns for start_date/end_date (up to 180 days) or an exact settlement_id. Dates and a settlement ID cannot be combined. The existing summary and detail transaction views are unchanged.

curl -G "https://mcp.agentcentral.to/v1/finance/payment-transactions" \
  -H "Authorization: Bearer ac_live_..." \
  --data-urlencode "view=balances"

Both views use the key's marketplace and finance access. Optional account_type filters by the exact Amazon account type; balance_type applies only to balances. Source amounts keep their currencies and signs, without conversion. TOTAL contains AVAILABLE and RESERVED; RESERVED contains DEFERRED and ACCOUNT_LEVEL_RESERVE. Do not add parent amounts to their children. retrieved_at records the fetch time, separately from Amazon's last_updated_time, which can be null. No fixed Amazon update interval is promised.

Each call returns one complete page, regardless of row limits. Continue with page_token and the same filters while another page exists. Transaction filters and sorting overrides do not apply. Historical dates follow the plan's history window; plans with a bounded history window require a dated financial summary rather than a settlement-only lookup. Settlement lookups verify the returned marketplace and settlement identifier; Amazon may omit the period dates, which remain null.

Error codes

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

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:

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.
• Versioned. New fields can appear within v1. Read fields by name and tolerate new ones.