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

# Your first API call

> Make your first request to the Stora Public API and explore the response.

With your token in hand, let's make some requests and understand how the API responds.

## List your sites

```bash theme={null}
curl -X GET "https://public-api.stora.co/2025-09/sites" \
  -H "accept: application/json" \
  -H "authorization: Bearer YOUR_ACCESS_TOKEN"
```

Response:

```json theme={null}
{
  "sites": [
    {
      "id": "site_14b419f1096013f1",
      "name": "Downtown Storage",
      "description": "Central location with 24/7 access",
      "phone": "+44 20 7946 0958",
      "opened_at": "2024-03-15T00:00:00Z",
      "created_at": "2024-01-10T09:30:00Z",
      "updated_at": "2025-06-01T14:22:00Z",
      "directions": {
        "google_maps_url": "https://maps.google.com/?q=..."
      },
      "access_hours": {
        "monday": { "status": "set_hours", "open": "06:00", "close": "22:00" },
        "tuesday": { "status": "set_hours", "open": "06:00", "close": "22:00" },
        "saturday": { "status": "twenty_four_hours" },
        "sunday": { "status": "closed" }
      },
      "address": {
        "line_1": "42 Storage Lane",
        "line_2": null,
        "city": "London",
        "postal_code": "EC1A 1BB"
      }
    }
  ],
  "meta": {
    "pagination": {
      "count": 1,
      "page": 1,
      "pages": 1,
      "limit": 50,
      "next": null,
      "prev": null,
      "last": 1
    }
  }
}
```

A few things to notice:

* **`sites` array** — resources are wrapped in a key matching the resource name
* **`meta.pagination`** — every list response includes pagination info. Use `page` and `limit` query parameters to navigate.
* **IDs are prefixed strings** — e.g. `site_14b419f1096013f1`. Use these when referencing resources in other endpoints.

## Fetch a single resource

Fetch a single site by its ID:

```bash theme={null}
curl -X GET "https://public-api.stora.co/2025-09/sites/site_14b419f1096013f1" \
  -H "accept: application/json" \
  -H "authorization: Bearer YOUR_ACCESS_TOKEN"
```

```json theme={null}
{
  "site": {
    "id": "site_14b419f1096013f1",
    "name": "Downtown Storage",
    "..."
  },
  "meta": {}
}
```

## Expand related resources

Some endpoints support the `expand` query parameter to include related resources inline. Without `expand`, related resources appear as IDs. With it, they're included as full objects.

```bash theme={null}
curl -X GET "https://public-api.stora.co/2025-09/sites/site_14b419f1096013f1?expand=unit_types" \
  -H "accept: application/json" \
  -H "authorization: Bearer YOUR_ACCESS_TOKEN"
```

You can expand multiple relations with a comma-separated list, and nest with dot notation:

```
?expand=contact,line_items,line_items.item
```

Each expanded resource requires the appropriate read scope on your token.

## Common patterns

These apply across the entire API. Each is covered in more detail in the dedicated guides.

### Pagination

List endpoints return 50 items by default, up to a maximum of 100. Use `page` and `limit` to navigate:

```
GET /2025-09/contacts?page=2&limit=25
```

Check `meta.pagination.pages` for the total number of pages and `meta.pagination.next` for the next page number (`null` on the last page). See [Responses](/2025-09/guides/responses#pagination) for full details.

### Error handling

Errors return a consistent structure with a `code` for programmatic handling and `details` for field-level validation messages. See [Errors](/2025-09/guides/errors) for the full list of error codes.

```json theme={null}
{
  "error": {
    "code": "invalid_content",
    "type": "invalid_request_error",
    "message": "The request body content is not valid.",
    "details": [
      {
        "message": "value at `/email` does not match format: email",
        "pointer": "/email"
      }
    ],
    "request_id": "01563646-58c1-4607-8fe0-cae3e92c4477"
  }
}
```

### Idempotency

For any `POST` request, include an `Idempotency-Key` header to safely retry without creating duplicates. The API stores the response for 24 hours. See [Requests](/2025-09/guides/requests#idempotent-requests) for details.

```bash theme={null}
curl -X POST "https://public-api.stora.co/2025-09/contacts" \
  -H "content-type: application/json" \
  -H "authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "idempotency-key: a1b2c3d4-unique-key" \
  -d '{"full_name": "Jane Smith", "email": "jane@example.com"}'
```

### Rate limits

The API allows 10 requests per second and 60 requests per minute. If you exceed this, you'll receive a `429 Too Many Requests` response. Check the `RateLimit-Reset` header for when to retry. See [Requests](/2025-09/guides/requests#rate-limiting) for details.