# References

The references describe every endpoint, event and frame exactly as the servers implement them. They are generated from the code and the published OpenAPI specs, so they change when the API changes. For step-by-step explanations, start with the [Guides](https://hatang.dev/docs/guides/getting-started/introduction.md).

| Reference | What it covers | Base URL |
|---|---|---|
| [REST API](https://hatang.dev/docs/reference/api.md) | Email, Support (chat), Payments, API keys and webhooks: every endpoint with parameters, request and response schemas, code samples and a "Try it" console | `https://api.hatang.dev` |
| [Chat gateway API](https://hatang.dev/docs/reference/chat-gateway.md) | What the website widget, the mobile SDKs and the agent apps call: bootstrap, conversations, uploads, devices, the agent API | `https://chat.hatang.dev` |
| [Webhook events](https://hatang.dev/docs/reference/webhooks.md) | Every event with its payload | your endpoint |
| [Realtime protocol](https://hatang.dev/docs/reference/realtime-protocol.md) | The visitor websocket: every frame, field and limit | `wss://chat.hatang.dev/ws` |
| [Errors](https://hatang.dev/docs/reference/errors.md) | Every error code of the API, the realtime protocol and the SMTP relay | |
| [Limits](https://hatang.dev/docs/reference/limits.md) | Rate limits and size limits | |

## SDK references

Generated from the doc comments in each SDK's source, one site per SDK (English only):

| SDK | Reference |
|---|---|
| Node (`@hatang/sdk`) | [TypeDoc](https://hatang.dev/docs/reference/js/index.html) |
| Flutter (`hatang_chat`) | [dartdoc](https://hatang.dev/docs/reference/flutter/index.html) |
| iOS (`HatangChat`, `HatangChatCore`) | [DocC](https://hatang.dev/docs/reference/ios/documentation) |
| Android (`dev.hatang:chat`, `dev.hatang:chat-core`) | [Dokka](https://hatang.dev/docs/reference/android/index.html) |

## Conventions

- **Authentication.** REST calls send `Authorization: Bearer ht_...`. See [Authentication](https://hatang.dev/docs/guides/getting-started/authentication.md) for scopes and test keys.
- **Format.** JSON in and out, UTF-8. Timestamps are ISO 8601 in UTC; amounts in Vietnamese đồng are integers.
- **Errors.** Every error is `{ "statusCode", "name", "message" }`; branch on `name`.
- **Pagination.** List endpoints take `limit` and `after`, and answer with `has_more` and `next_cursor`. See [Pagination](https://hatang.dev/docs/guides/getting-started/pagination.md).
- **Idempotency.** `POST /emails`, `POST /payments` and posting chat messages accept an `Idempotency-Key` header. See [Idempotency](https://hatang.dev/docs/guides/getting-started/idempotency.md).

## Machine-readable specs

- REST API: [`openapi.json`](https://api.hatang.dev/openapi.json) (OpenAPI 3.1, including the `webhooks` section)
- Chat gateway: [`openapi.json`](https://chat.hatang.dev/openapi.json)
- Realtime protocol: JSON Schemas for [visitor frames](https://hatang.dev/docs/schema/chat-protocol-v1/visitor-frames.json), [server frames](https://hatang.dev/docs/schema/chat-protocol-v1/server-frames.json), [HTTP](https://hatang.dev/docs/schema/chat-protocol-v1/http.json) and [protocol constants](https://hatang.dev/docs/schema/chat-protocol-v1/protocol.json)

- The whole hub for AI agents and LLM tools: [`llms.txt`](https://hatang.dev/docs/llms.txt) (an index), [`llms-full.txt`](https://hatang.dev/docs/llms-full.txt) (every page in one file), and a Markdown copy of each page at its URL plus `.md`, such as [`/docs/reference/overview.md`](https://hatang.dev/docs/reference/overview.md)

Use them with any OpenAPI tool (Postman, Insomnia, code generators) or import them into your own tests.

Source: https://hatang.dev/docs/reference/overview