# 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

## Related Docs

- [SDK Documentation](https://joinhexagon.com/docs/sdk.md)
- [Merchant Integration Guide](https://joinhexagon.com/docs/merchant-integration.md)
- [Troubleshooting](https://joinhexagon.com/docs/troubleshooting.md)