> ## Documentation Index
> Fetch the complete documentation index at: https://agentmall.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> HTTPS routes at api.getagentmall.com — the same operations as MCP, over REST.

![Client sends HTTPS requests to api.getagentmall.com and receives JSON responses](https://mintcdn.com/agentmall/ZuoglRqW4CDsIaRs/images/rest-api.svg?fit=max\&auto=format\&n=ZuoglRqW4CDsIaRs\&q=85\&s=5b441100d7037e22b4f33b83c20b9690)

The REST API exposes the same operations as MCP, over HTTPS at `api.getagentmall.com`.

Every `/v1/*` route needs `Authorization: Bearer <key>`. Request and response bodies are JSON. Prices and totals are integer minor units of the merchant's currency (cents for USD, pence for GBP). `GET /v1/merchants` lists the nine live merchant ids.

`get_product` and `sign_out` are MCP only. The console is not on this API.

## Health

### `GET /health`

No auth required. Returns 200 when the server is up.

```bash theme={null}
curl https://api.getagentmall.com/health
```

```json theme={null}
{ "status": "ok" }
```

## Catalog

### `POST /v1/catalog/search`

Equivalent to MCP `search_catalog`.

```bash theme={null}
curl -X POST https://api.getagentmall.com/v1/catalog/search \
  -H "Authorization: Bearer am_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "merchant_id": "mrc_walmart", "query": "AA batteries" }'
```

```json theme={null}
{
  "products": [
    {
      "id": "27574659",
      "merchant_id": "mrc_walmart",
      "title": "Energizer MAX AA Batteries, 24 Pack",
      "brand": "Energizer",
      "url": "https://www.walmart.com/ip/27574659",
      "image_url": "https://i5.walmartimages.com/...",
      "price": 1697,
      "currency": "USD",
      "availability": "in_stock"
    }
  ],
  "source": "oxylabs",
  "relevance": "ok"
}
```

### `POST /v1/catalog/lookup`

Equivalent to MCP `lookup_catalog`. Reads up to 10 product pages in one call.

```bash theme={null}
curl -X POST https://api.getagentmall.com/v1/catalog/lookup \
  -H "Authorization: Bearer am_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "merchant_id": "mrc_walmart", "session_id": "ses_01JB7PK8M2A...", "ids": ["27574659"] }'
```

```json theme={null}
{
  "products": [
    {
      "id": "27574659",
      "title": "Energizer MAX AA Batteries, 24 Pack",
      "price": 1697,
      "currency": "USD",
      "availability": "in_stock",
      "reviews": { "rating": 4.7, "count": 12480 }
    }
  ],
  "failed": []
}
```

## Cart

### `POST /v1/carts`

Equivalent to MCP `create_cart`. Starts an empty cart and returns its `id`.

```bash theme={null}
curl -X POST https://api.getagentmall.com/v1/carts \
  -H "Authorization: Bearer am_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "shopper_id": "shp_demo", "merchant_id": "mrc_walmart", "account": "platform" }'
```

```json theme={null}
{
  "id": "ses_01JB7PK8M2AN4R8D091CD",
  "merchant_id": "mrc_walmart",
  "currency": "USD",
  "line_items": [],
  "totals": { "subtotal": 0, "total": 0 }
}
```

### `GET /v1/carts/:id`

Equivalent to MCP `get_cart`. Reads the live merchant cart.

```bash theme={null}
curl https://api.getagentmall.com/v1/carts/ses_01JB7PK8M2AN4R8D091CD \
  -H "Authorization: Bearer am_live_example"
```

```json theme={null}
{
  "id": "ses_01JB7PK8M2AN4R8D091CD",
  "merchant_id": "mrc_walmart",
  "currency": "USD",
  "line_items": [
    {
      "id": "27574659",
      "item": {
        "id": "27574659",
        "title": "Energizer MAX AA Batteries, 24 Pack",
        "price": 1697,
        "url": "https://www.walmart.com/ip/27574659"
      },
      "quantity": 1,
      "totals": { "subtotal": 1697, "total": 1697 }
    }
  ],
  "totals": { "subtotal": 1697, "total": 1697 }
}
```

### `PUT /v1/carts/:id`

Equivalent to MCP `update_cart`. Replaces the cart: clears, then adds each line.

```bash theme={null}
curl -X PUT https://api.getagentmall.com/v1/carts/ses_01JB7PK8M2AN4R8D091CD \
  -H "Authorization: Bearer am_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      { "item": { "id": "27574659", "url": "https://www.walmart.com/ip/27574659" }, "quantity": 2 }
    ]
  }'
```

Response is the same shape as `GET /v1/carts/:id`.

### `POST /v1/carts/:id/cancel`

Equivalent to MCP `cancel_cart`. Returns the cart as last stored, then releases the browser.

```bash theme={null}
curl -X POST https://api.getagentmall.com/v1/carts/ses_01JB7PK8M2AN4R8D091CD/cancel \
  -H "Authorization: Bearer am_live_example"
```

## Sign-in

### `POST /v1/carts/:id/sign-in`

Equivalent to MCP `sign_in`. Pass Evervault-encrypted (`ev:…`) email and password.

```bash theme={null}
curl -X POST https://api.getagentmall.com/v1/carts/ses_01JB7PK8M2AN4R8D091CD/sign-in \
  -H "Authorization: Bearer am_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ev:AAAB...", "password": "ev:AAAC..." }'
```

```json theme={null}
{ "signed_in": true }
```

When the merchant sends an SMS challenge:

```json theme={null}
{ "status": "challenge_required" }
```

### `POST /v1/carts/:id/sign-in/otp`

Equivalent to MCP `submit_sign_in_otp`. Submits the SMS code after a challenge.

```bash theme={null}
curl -X POST https://api.getagentmall.com/v1/carts/ses_01JB7PK8M2AN4R8D091CD/sign-in/otp \
  -H "Authorization: Bearer am_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "code": "482910" }'
```

```json theme={null}
{ "signed_in": true }
```

## Checkout

### `POST /v1/carts/:id/checkout`

Equivalent to MCP `create_checkout`. Opens checkout and returns the review.

```bash theme={null}
curl -X POST https://api.getagentmall.com/v1/carts/ses_01JB7PK8M2AN4R8D091CD/checkout \
  -H "Authorization: Bearer am_live_example"
```

```json theme={null}
{
  "id": "ses_01JB7PK8M2AN4R8D091CD",
  "status": "incomplete",
  "line_items": [
    { "itemId": "27574659", "quantity": 2, "linePrice": { "amountMinor": 3394, "currency": "USD" } }
  ],
  "totals": { "subtotal": 3394, "tax": 280, "total": 3674 },
  "fulfillment": {
    "methods": [
      { "id": "shipping_standard", "kind": "shipping", "label": "Standard shipping" },
      { "id": "pickup_store_3795", "kind": "pickup", "label": "Pickup at Supercenter #3795" }
    ]
  },
  "review_hash": "a1b2c3d4e5f6..."
}
```

### `GET /v1/carts/:id/checkout`

Equivalent to MCP `get_checkout`. Re-reads without changing the page.

```bash theme={null}
curl https://api.getagentmall.com/v1/carts/ses_01JB7PK8M2AN4R8D091CD/checkout \
  -H "Authorization: Bearer am_live_example"
```

Same response shape as `POST /v1/carts/:id/checkout`.

### `PUT /v1/carts/:id/checkout`

Equivalent to MCP `update_checkout`. Writes an address, selects a method, or adds a card.

```bash theme={null}
curl -X PUT https://api.getagentmall.com/v1/carts/ses_01JB7PK8M2AN4R8D091CD/checkout \
  -H "Authorization: Bearer am_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "fulfillment": {
      "address": {
        "first_name": "Jane",
        "last_name": "Doe",
        "street_address": "123 Main St",
        "address_locality": "Austin",
        "address_region": "TX",
        "postal_code": "78701",
        "address_country": "US"
      },
      "method": { "id": "shipping_standard", "kind": "shipping", "label": "Standard shipping" }
    }
  }'
```

Returns the checkout with updated totals and a new `review_hash`.

### `POST /v1/carts/:id/checkout/cancel`

Equivalent to MCP `cancel_checkout`. Leaves checkout without placing. The cart stays open.

```bash theme={null}
curl -X POST https://api.getagentmall.com/v1/carts/ses_01JB7PK8M2AN4R8D091CD/checkout/cancel \
  -H "Authorization: Bearer am_live_example"
```

```json theme={null}
{ "id": "ses_01JB7PK8M2AN4R8D091CD", "status": "canceled" }
```

### `POST /v1/carts/:id/checkout/complete`

Equivalent to MCP `complete_checkout`. Places the order when `review_hash` and `total_minor` match.

```bash theme={null}
curl -X POST https://api.getagentmall.com/v1/carts/ses_01JB7PK8M2AN4R8D091CD/checkout/complete \
  -H "Authorization: Bearer am_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "review_hash": "a1b2c3d4e5f6...", "total_minor": 3674 }'
```

```json theme={null}
{
  "id": "ses_01JB7PK8M2AN4R8D091CD",
  "status": "completed",
  "order": { "id": "ord_01JB7QR9N3BP5S2E082AB" },
  "test": false
}
```

## Order

### `GET /v1/orders/:id`

Equivalent to MCP `get_order`. Reads an order by platform `id`.

```bash theme={null}
curl https://api.getagentmall.com/v1/orders/ord_01JB7QR9N3BP5S2E082AB \
  -H "Authorization: Bearer am_live_example"
```

```json theme={null}
{
  "id": "ord_01JB7QR9N3BP5S2E082AB",
  "checkout_id": "ses_01JB7PK8M2AN4R8D091CD",
  "merchant_id": "mrc_walmart",
  "status": "completed",
  "merchant_status": "Shipped",
  "currency": "USD",
  "totals": { "subtotal": 3394, "tax": 280, "total": 3674 },
  "permalink_url": "https://www.walmart.com/orders/2000123-45678901",
  "test": false
}
```

## Errors

Every error response has `error.code` and `error.message`:

```json theme={null}
{
  "error": {
    "code": "session_not_found",
    "message": "No cart with that id."
  }
}
```

HTTP status codes follow standard conventions: 400 for bad input, 401 for auth failures, 404 for not found, 410 for expired sessions, 429 for rate limits. See [Error codes](https://agentmall.mintlify.site/reference/errors.md) for the full list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.