Synchronity
Reference

REST API

Every gateway endpoint, grouped by capability. For the full machine-readable spec, see openapi-spec.json.

The complete machine-readable spec lives at:

https://api.synchronity.app/openapi-spec.json

Import that into Postman, Insomnia, or any OpenAPI client. Or fire live requests directly from your browser in the interactive API Explorer. The list below is the cliff-notes version — most endpoints below have a Run button to try them inline.

Try it inline

Health

GET/health
Liveness + dependency status (no auth required).
Equivalent curl
curl -X GET https://api.synchronity.app/health

Issue an AIT

POST/v1/auth/agents/register
Issue a new agent identity token. The response includes the JWT — keep it safe.
Equivalent curl
curl -X POST https://api.synchronity.app/v1/auth/agents/register \
  -H 'content-type: application/json' \
  -d '{ "agent_name": "docs_test_agent", "scopes": [ "read_products" ] }'

List sites visible to an agent

GET/v1/sites
Authorize with the AIT you got above (paste it into the Bearer field).
Equivalent curl
curl -X GET https://api.synchronity.app/v1/sites

Auth

MethodPathWhat
POST/v1/auth/agents/registerIssue a new AIT
POST/v1/auth/agents/refreshRotate an AIT
GET/v1/auth/agents/validateVerify a token
POST/v1/auth/delegateBegin OAuth Device Flow
GET/v1/auth/delegate/statusPoll for buyer approval
POST/v1/auth/delegate/otpApprove with an emailed one-time passcode
GET/.well-known/jwks.jsonPublic verification keys

Discovery

MethodPathWhat
GET/v1/sitesSites this agent can access
GET/v1/sites/:id/manifestA site's connector capabilities

Products

MethodPathWhat
POST/v1/products/searchCross-store search
GET/v1/products/:site_id/:product_idSingle product
POST/v1/products/compareSide-by-side
GET/v1/products/:site_id/:product_id/reviewsReviews

Cart

MethodPathWhat
POST/v1/cartCreate a cart
GET/v1/cart/:idFetch cart
POST/v1/cart/:id/itemsAdd an item
DELETE/v1/cart/:id/items/:item_idRemove an item
POST/v1/cart/:id/couponApply discount

Checkout

MethodPathWhat
POST/v1/cart/:id/shipping/addressSet destination + get rates
POST/v1/cart/:id/shipping/optionPick a rate
POST/v1/cart/:id/checkoutFinalize order (may return 401 delegation_required)

Orders

MethodPathWhat
GET/v1/ordersList orders
GET/v1/orders/:idOne order

Payments

Inline (in-chat) payments against an existing order. The gateway proxies these to the connector, which derives the amount/currency from the order — no amount field is ever accepted. initiate and submit-otp always require delegation (spending money needs human approval); methods and status are read-only.

MethodPathWhat
GET/v1/sites/:site_id/orders/:order_id/payment/methodsChannels available for the order (mobile_money, card)
POST/v1/sites/:site_id/orders/:order_id/payment/initiateStart a payment session — returns a PaymentSession + instruction
POST/v1/sites/:site_id/orders/:order_id/payment/submit-otpSubmit a mobile-money OTP
GET/v1/sites/:site_id/orders/:order_id/payment/statusPoll until paid/processing (success) or failed

Shoutouts

Public, no-auth endpoints behind the landing page's shoutout wall. Submissions are auto-published; handles and bodies are validated and screened, and avatars are generated deterministically from the handle.

MethodPathWhat
GET/v1/shoutoutsLatest visible shoutouts (most recent first)
POST/v1/shoutoutsSubmit a shoutout (handle 1–32 chars, body 8–280 chars)

Health

MethodPathWhat
GET/healthLiveness + dependency status

Cursor

Run Synchronity inside Cursor as a local MCP server so coding agents can query inventory and place test orders.

API Explorer

Next Page

On this page

Try it inlineHealthIssue an AITList sites visible to an agentAuthDiscoveryProductsCartCheckoutOrdersPaymentsShoutoutsHealth