API conventions

Every API in the xAI ecosystem follows the same set of conventions, so you learn once and apply everywhere.

Base URL & versioning

Each product has its own base URL by subdomain:

• https://identity.xai.io.vn
• https://governance.xai.io.vn
• https://blockchain.xai.io.vn

Format

• Everything over HTTPS.
• Bodies & responses default to JSON (Content-Type: application/json). A few sign-in endpoints accept forms (multipart/form-data).
• Timestamps are ISO 8601 or Unix epoch (seconds) depending on the endpoint — noted in the reference.

Errors

APIs use standard HTTP status codes. The error body looks like:

{ "error": "invalid_credentials" }

Rate limiting

Some endpoints (e.g. the blockchain relayer) apply ~5 requests/min/IP. On exceed, the API returns 429 with a Retry-After header (seconds):

HTTP/1.1 429 Too Many Requests
Retry-After: 12

CORS

The introspection endpoint allows CORS for any *.xai.io.vn and localhost (with credentials). Public verification endpoints (e.g. /api/did/verify, /api/verify) allow any origin.

Idempotency

Anchoring operations are idempotent by fingerprint: resubmitting the same data returns 409 (already anchored) instead of creating a duplicate.