api reference.md

API and SDK Reference

This page defines what agents may rely on from public docs today.

Public Integration Preference

Prefer the official Hexagon SDK when current docs support the target framework. The SDK documentation is published at https://joinhexagon.com/docs/sdk.md.

Current public Markdown examples cover:

Node.js / Express
Next.js App Router

The docs include status notes for Python, Ruby, and PHP. Do not install packages for those ecosystems unless current Hexagon documentation lists an official package and example.

Public Discovery Endpoints

These endpoints are safe for agents to fetch:

Endpoint	Format	Purpose
`https://joinhexagon.com/llms.txt`	Markdown	Short discovery index.
`https://joinhexagon.com/llms-full.txt`	Markdown	Full docs corpus at root.
`https://joinhexagon.com/docs`	Markdown	Documentation home.
`https://joinhexagon.com/docs/index.md`	Markdown	Documentation home alias.
`https://joinhexagon.com/docs/llms.txt`	Markdown	Concise docs index alias.
`https://joinhexagon.com/docs/llms-full.txt`	Markdown	Full docs corpus alias.
`https://joinhexagon.com/docs/sdk.md`	Markdown	SDK examples and availability notes.
`https://joinhexagon.com/.well-known/agent-onboarding`	JSON	No-Hexagon-UI agent onboarding manifest and direct Stripe Payment Link discovery.
`https://joinhexagon.com/agents.md`	Markdown	Copy-ready agent instructions.
`https://joinhexagon.com/.well-known/ucp`	JSON	Discovery-only provider profile.
`https://joinhexagon.com/sitemap.xml`	XML	Sitemap.
`https://joinhexagon.com/robots.txt`	Text	Crawler and discovery hints.

Do Not Invent Raw API Endpoints

Do not generate code against guessed endpoints such as /v1/catalog, /api/products/sync, /checkout/create, or /events/purchase unless current Hexagon docs explicitly list them.

When the SDK does not cover the required platform, treat the work as a custom rollout:

document the merchant's backend
document the desired data sync
document auth and security boundaries
contact sales@joinhexagon.com for the official integration path

Error Handling Guidance

For SDK or custom integration code:

fail closed on missing API keys
return clear server-side errors for missing merchant configuration
retry transient network failures with backoff where the SDK does not handle it
avoid retrying invalid credentials without operator action
do not expose sensitive provider errors to shoppers
log non-sensitive request IDs and status codes