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
POST/v1/sites/:site_id/products/:product_id/notify-restockSubscribe to a back-in-stock alert

Cart

MethodPathWhat
POST/v1/cartCreate a cart
GET/v1/cart/:idFetch cart
POST/v1/cart/:id/itemsAdd an item
PUT/v1/cart/:id/items/:item_idSet a line's quantity (0 removes it)
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) plus a gateways[] array of enabled gateways
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

When a store has more than one payment gateway enabled (e.g. Paystack, Stripe, PayPal), methods returns a gateways[] array (each with id, label, and its channels). Present the choice to the buyer and pass the chosen gateway (paystack | stripe | paypal) on initiate. Omitting gateway uses the store's first enabled gateway. Stripe and PayPal are card/redirect via a hosted Checkout page (PayPal shows only for PayPal-supported currencies); Paystack additionally supports Ghana mobile money.

Health

MethodPathWhat
GET/healthLiveness + dependency status

Codex

Connect Synchronity to OpenAI Codex CLI via the plugin or its MCP server config.

API Explorer

Next Page

On this page

Try it inlineHealthIssue an AITList sites visible to an agentAuthDiscoveryProductsCartCheckoutOrdersPaymentsHealth