> ## Documentation Index
> Fetch the complete documentation index at: https://tatallo-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> From a staging key to a working call in a few minutes.

You need a staging PMS credential. If you don't have one yet, [request access](https://tatallo-docs.mintlify.site/get-started/access.md).

## 1. Set two environment variables

```bash theme={null}
export TATALLO_BASE_URL="https://staging.api.tatallo.com"
export TATALLO_API_KEY="tat_stg_sk_<credential-id>_<secret>"   # your staging key
```

Every example in these docs reads these two variables. To move to production later, change `TATALLO_BASE_URL` to `https://api.tatallo.com` and use your production key.

## 2. Check your key

```bash theme={null}
curl -s "$TATALLO_BASE_URL/v1/me" \
  -H "Authorization: Bearer $TATALLO_API_KEY"
```

You see which key you used, your PMS, the environment and the scopes:

```json theme={null}
{
  "credential_id": "5d4e040b-61c1-44a4-a4ca-9a751dc05133",
  "pms_name": "Test PMS",
  "environment": "staging",
  "scopes": [
    "properties:read"
  ]
}
```

`credential_id` is your key's own ID, so yours may differ from the example. `environment` must say `staging`, and `scopes` must include `properties:read`.

## 3. List your properties

```bash theme={null}
curl -s "$TATALLO_BASE_URL/v1/properties" \
  -H "Authorization: Bearer $TATALLO_API_KEY"
```

On staging you get the fixture properties connected to your PMS, exactly these:

```json theme={null}
{
  "data": [
    {
      "id": "6cfa992d-1805-4de6-892c-23785031aba0",
      "name": "Fixture Loft Kreuzberg",
      "timezone": "Europe/Berlin",
      "status": "active",
      "country": "Germany",
      "city": "Berlin",
      "max_guests": 2,
      "currency": "EUR",
      "updated_at": "2026-10-01T09:00:00.000Z"
    },
    {
      "id": "934f807c-39d6-45de-b107-d5c9e03cb041",
      "name": "Fixture House Alfama",
      "timezone": "Europe/Lisbon",
      "status": "inactive",
      "country": "Portugal",
      "city": "Lisbon",
      "max_guests": 6,
      "currency": "EUR",
      "updated_at": "2026-10-01T09:00:00.000Z"
    },
    {
      "id": "bef2859f-2444-47ec-b5f4-f1e6701f087f",
      "name": "Fixture Apartment Trastevere",
      "timezone": "Europe/Rome",
      "status": "active",
      "country": "Italy",
      "city": "Rome",
      "max_guests": 4,
      "currency": "EUR",
      "updated_at": "2026-10-01T09:00:00.000Z"
    }
  ],
  "page": {
    "next_cursor": null
  }
}
```

`page.next_cursor` is `null`, so this is the whole list. With more properties than fit on a page, follow the cursor: see [Property discovery on staging](https://tatallo-docs.mintlify.site/guides/property-discovery.md).

## 4. Read one property

```bash theme={null}
curl -s "$TATALLO_BASE_URL/v1/properties/bef2859f-2444-47ec-b5f4-f1e6701f087f" \
  -H "Authorization: Bearer $TATALLO_API_KEY"
```

```json theme={null}
{
  "id": "bef2859f-2444-47ec-b5f4-f1e6701f087f",
  "name": "Fixture Apartment Trastevere",
  "timezone": "Europe/Rome",
  "status": "active",
  "country": "Italy",
  "city": "Rome",
  "max_guests": 4,
  "currency": "EUR",
  "updated_at": "2026-10-01T09:00:00.000Z"
}
```

Store each property's `id` in your mapping table: it never changes. What every field means: [Properties](https://tatallo-docs.mintlify.site/concepts/properties.md).

## Troubleshooting

Every error has the same shape, `{ "error": { "code", "message", "request_id" } }`. Branch on `code`.

### 401 unauthorized

The key is missing, malformed, for the other environment, expired or revoked. Check that `TATALLO_API_KEY` starts with `tat_stg_sk_` when `TATALLO_BASE_URL` is staging, that the header is exactly `Authorization: Bearer <key>`, and that nothing was cut when you copied it. See [Authentication](https://tatallo-docs.mintlify.site/get-started/authentication.md).

### 403 insufficient\_scope

The key is valid but lacks `properties:read`. `GET /v1/me` shows its scopes. Ask [developers@tatallo.com](mailto:developers@tatallo.com) for a key with the scope you need.

### 404 property\_not\_found

The property is not connected to your PMS, or does not exist. Tatallo answers both the same way on purpose. List your properties first and use their `id`s. See [why an unconnected property is a 404](https://tatallo-docs.mintlify.site/guides/property-discovery.md#a-property-that-is-not-connected-to-your-pms).

### 429 rate\_limited

More than 60 requests in a minute with this key. Wait for the number of seconds in the `Retry-After` header, then try again.

When you write to support, quote the `X-Request-Id` header of the failing response.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.