REST API

HTTPS Session and console APIs at api.getagentmall.com.

Base URL:

https://api.getagentmall.com

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

Authorization: Bearer <partner-key>

GET /health is open.

Walmart only in beta: merchantId must be mrc_walmart. Prefer MCP 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)
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 (productId or product url, optional quantity)
POST	/v1/sessions/:id/place-order	Two-call checkout (review → confirm)

MCP exposes more cart mutations (update / remove / clear) and address/payment helpers that are not all mirrored as separate REST routes yet — for those, use MCP or pass address/card fields on place-order.

Happy path

# 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. Place order — prepare (returns review)
curl -sS https://api.getagentmall.com/v1/sessions/$SESSION_ID/place-order \
  -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":"…"},
    "deliveryPreference":"shipping"
  }'

# 5. Place order — commit
curl -sS https://api.getagentmall.com/v1/sessions/$SESSION_ID/place-order \
  -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":"…"},
    "confirmation":"yes, place it for $12.34",
    "reviewHash":"<from prepare>",
    "totalMinor":1234
  }'

Without confirmation, place-order returns status: "awaiting_confirmation" and a review (reviewHash, totals). Missing confirmation never places an order. See Order flow and Errors.

Console read API

Used by console.getagentmall.com. 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, Quickstart, and MCP tools.