> ## 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 Session and console APIs at api.getagentmall.com.

Base URL:

```text theme={null}
https://api.getagentmall.com
```

All `/v1/*` routes need a beta partner key:

```http theme={null}
Authorization: Bearer <partner-key>
```

`GET /health` is open.

Walmart only in beta: `merchantId` must be `mrc_walmart`. Prefer [MCP](https://agentmall.mintlify.site/connect-your-agent.md) for coding agents; use REST from your own server.

## Session and commerce

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/health` | Liveness |
| `POST` | `/v1/sessions` | Start a session (`merchantId`, optional `shopperId`, optional `account`: `guest` \| `platform`) |
| `GET` | `/v1/sessions/:id` | Read session record |
| `POST` | `/v1/sessions/:id/end` | Close without ordering |
| `POST` | `/v1/sessions/:id/sign-in` | Platform Walmart sign-in (optional body `otp`) |
| `POST` | `/v1/sessions/:id/sign-in/otp` | Submit SMS OTP (`code` or `otp`) |
| `POST` | `/v1/sessions/:id/search` | Search (`query`, optional `source`: `catalog` \| `merchant`) |
| `GET` | `/v1/sessions/:id/cart` | Live cart |
| `POST` | `/v1/sessions/:id/cart/items` | Add item (`url`, optional `quantity`) |
| `POST` | `/v1/sessions/:id/cart/ensure` | Clear, then add `{ items: [{ url, quantity }] }` |
| `POST` | `/v1/sessions/:id/prepare_checkout` | Open checkout and return the review |
| `POST` | `/v1/sessions/:id/checkout` | Place with `review_hash` and `total_minor` |

`account: "platform"` reuses the seeded signed-in context and clears the shared cart. MCP still has quantity, remove, and clear tools that are not separate REST routes — use MCP for those, or pass address and card fields on `prepare_checkout`.

## Happy path

```bash theme={null}
# 1. Session
curl -sS https://api.getagentmall.com/v1/sessions \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"merchantId":"mrc_walmart"}'

# 2. Search (catalog)
curl -sS https://api.getagentmall.com/v1/sessions/$SESSION_ID/search \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"query":"AA batteries"}'

# Optional: live merchant search
curl -sS https://api.getagentmall.com/v1/sessions/$SESSION_ID/search \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"query":"AA batteries","source":"merchant"}'

# 3. Add to cart
curl -sS https://api.getagentmall.com/v1/sessions/$SESSION_ID/cart/items \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"productId":"<id from search>","quantity":1}'

# 4. Prepare checkout (returns review; nothing placed)
curl -sS https://api.getagentmall.com/v1/sessions/$SESSION_ID/prepare_checkout \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{
    "address":{"name":"Alex","line1":"1 Market St","city":"San Francisco","region":"CA","postal":"94105"},
    "card":{"number":"…","expiration_month":12,"expiration_year":2030,"cvc":"…"},
    "delivery_preference":"shipping"
  }'

# 5. Place
curl -sS https://api.getagentmall.com/v1/sessions/$SESSION_ID/checkout \
  -H "authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"review_hash":"<from prepare>","total_minor":1234}'
```

`prepare_checkout` returns `status: "prepared"` and a `review` (`review_hash`, `total.amountMinor`). `checkout` places only if that hash and total still match. On `commit_unknown`, read the order and do not retry. See [Order flow](https://agentmall.mintlify.site/concepts/order-flow.md) and [Errors](https://agentmall.mintlify.site/errors.md).

## Console read API

Used by [console.getagentmall.com](https://agentmall.mintlify.site/console.md). CORS allowlisted for console origins and localhost.

| Method | Path | Body |
| - | - | - |
| `GET` | `/v1/console/me` | `{ partner, cap, used_today }` |
| `GET` | `/v1/console/sessions` | `{ sessions: [...] }` |
| `GET` | `/v1/console/sessions/:id` | `{ session, events }` — events for that session only; no raw `args` |
| `GET` | `/v1/console/orders` | `{ orders: [...] }` |
| `GET` | `/v1/console/orders/:id` | `{ order }` or 404 |
| `GET` | `/v1/console/billing` | Month usage: fees, GMV, searches, `price_minor` |

Org always comes from the key. Other orgs' ids return 404.

## MCP vs REST

| | MCP | REST |
| - | - | - |
| Address | `https://mcp.getagentmall.com` | `https://api.getagentmall.com` |
| Clients | Claude, Cursor, other MCP hosts | curl, SDKs, your backend, console |
| Model | Same Session thread and checkout rules | Same |

See [Connect your agent](https://agentmall.mintlify.site/connect-your-agent.md), [Quickstart](https://agentmall.mintlify.site/quickstart.md), and [MCP tools](https://agentmall.mintlify.site/mcp/tools.md).


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