Conventions

A handful of rules hold across every HAPI v3 endpoint. Learn them once and the flights, hotels, and activities APIs all read the same way.

Base URL and transport

Every request goes to https://api.hermeseus.com/v3/HAPI over HTTPS. Bodies and responses are JSON encoded as UTF-8. Send Content-Type: application/json on requests that carry a body.

Field naming

All JSON keys are snake_case. Fields are stable: we add new ones over time but do not rename or remove them within a version.

Resource ids

Every object has a string id with a short type prefix, so an id is self-describing and hard to confuse. Ids are opaque, treat them as strings and do not parse them.

Money

Amounts are objects, never bare numbers. The amount is a decimal string to avoid floating-point rounding, and the currency is always USD.

{
  "total": { "amount": "412.00", "currency": "USD" }
}

Timestamps

All dates and times are RFC 3339 in UTC, for example 2026-11-14T09:40:00Z. Plain calendar dates use YYYY-MM-DD.

Request ids

Every response carries a Request-Id header, and error bodies repeat it as request_id. Log it, and quote it when you contact support so a call can be traced end to end.

Idempotency

Send an Idempotency-Key header on any POST that creates a resource (an order, a ticket request). If a call is retried with the same key, the original result is returned instead of creating a duplicate, so a dropped connection never double-books.

Idempotency-Key: 5f2b8c1a-3e4d-4a6b-9c7e-1d2f3a4b5c6d

Pagination

List endpoints are cursor paginated. Pass limit and, to continue, the after cursor from the previous page. The envelope tells you whether more remain.

{
  "data": [ /* … */ ],
  "has_more": true,
  "next_cursor": "crs_9f3c81d2"
}

HTTP status codes

HAPI uses real status codes. A 2xx means success; a 4xx means the request was wrong; a 5xx means the platform failed.

The body of every failure follows the shape on the errors reference.