## Get Started with the API

This guide walks you from an API key to your first successful response.

### 1. Get an API key

API keys are issued by Hamlet. Reach out to your account contact to obtain a key for your organization. Keys are prefixed with `hmlt_` and grant access to a specific set of locations (your **entitlements**).

Treat your API key like a password. Send it only over HTTPS, never embed it in client-side code, and store it in a secret manager rather than source control.

### 2. Make your first request

Every `/v1` endpoint requires an `Authorization: Bearer <key>` header. List the locations your key is entitled to:

```
curl https://api.myhamlet.com/v1/locations \
  -H "Authorization: Bearer hmlt_your_api_key"
```

### 3. Read the response

List endpoints return a cursor-paginated envelope — a `data` array plus a `next_cursor`:

```
{
  "data": [\
    {\
      "uuid": "5f2b0c3a-1d4e-4a8b-9f6d-2a1c3e4b5d6f",\
      "type": "CITY",\
      "name": "Palo Alto",\
      "state_name": "California",\
      "state_abbreviation": "CA",\
      "county_names": ["Santa Clara"],\
      "created_at": "2025-01-10T00:00:00.000Z",\
      "updated_at": "2026-05-01T18:22:10.000Z"\
    }\
  ],
  "next_cursor": "eyJ1IjoiMjAyNi0wNS0wMSAxODoyMjoxMCIsImkiOjQyfQ"
}
```