> ## 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.

# Responses

> Response formats, expanding, pagination, and links in the Stora Public API.

## Response formats

The API supports JSON, CSV, and PDF response formats. Specify your preferred format using the `Accept` header.

<Tabs>
  <Tab title="JSON">
    ```bash theme={null}
    curl -X GET "https://public-api.stora.co/2025-09/contacts" \
     -H 'accept: application/json' \
     -H 'authorization: Bearer ACCESS_TOKEN'
    ```
  </Tab>

  <Tab title="CSV">
    ```bash theme={null}
    curl -X GET "https://public-api.stora.co/2025-09/contacts" \
     -H 'accept: text/csv' \
     -H 'authorization: Bearer ACCESS_TOKEN'
    ```
  </Tab>

  <Tab title="PDF">
    <Note>
      PDF format is only supported for specific resources such as Invoices and Credit Notes. The endpoint returns a `406 Not Acceptable` if the content cannot be returned in PDF format.
    </Note>

    ```bash theme={null}
    curl -X GET "https://public-api.stora.co/2025-09/invoices/inv_195h6kfm9ro15lof" \
     -H 'accept: application/pdf' \
     -H 'authorization: Bearer ACCESS_TOKEN'
    ```
  </Tab>
</Tabs>

## Expanding responses

Some endpoints support expanding nested objects in the response using the `expand` query parameter. You can expand multiple objects with a comma-separated list, and use dot notation for nested objects.

For example, when retrieving an order, you can expand the `contact`, `line_items`, and `line_items.item`:

```bash theme={null}
curl -X GET "https://public-api.stora.co/2025-09/orders?expand=contact,line_items,line_items.item" \
 -H 'accept: application/json' \
 -H 'authorization: Bearer ACCESS_TOKEN'
```

You can find examples of fully expanded responses in the "Show a \<RESOURCE\_NAME>" endpoints.

<Note>
  For each expanded resource, ensure the access token has read scope for that resource. For example, when expanding the `site` on `subscription`, the `public.site:read` scope is required.
</Note>

## Pagination

List endpoints are paginated. The defaults are:

* **50 items per page** by default
* **100 items per page** maximum (set via the `limit` query parameter)
* Use the `page` query parameter to navigate through pages

Pagination data (`count`, `last`, `limit`, `next`, `page`, `pages`, and `prev`) is returned in the response's `meta/pagination` field.

## Links

Some resources include a `_links` field containing [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS)-style links. These provide URLs to related actions or pages, such as signing a contract on the storefront or starting a new booking for a unit type.

### Structure

Each link is keyed by a namespaced relation name and contains an `href` (relative path) and a human-readable `title`:

```json theme={null}
{
  "unit_type": {
    "id": "utype_f18fc91387cdf710",
    "name": "5x5 Storage Unit",
    "_links": {
      "sf:new_order": {
        "href": "/sites/belfast-self-storage/5x5-unit/order/contact-details?unit_type_slug=5x5-unit",
        "title": "New order"
      }
    }
  }
}
```

### CURIEs

Link relation names use a [CURIE](https://www.w3.org/TR/curie/) (Compact URI) prefix to indicate which application the link points to:

| Prefix | Application                               | Example           |
| ------ | ----------------------------------------- | ----------------- |
| `sf`   | Storefront (customer-facing booking site) | `sf:new_order`    |
| `bo`   | Backoffice (operator dashboard)           | `bo:view_contact` |

The `meta` object includes a `curies` array that maps each prefix to a URL template. To resolve a full URL, replace `{rel}` in the CURIE `href` with the link's `href`:

```json theme={null}
{
  "meta": {
    "curies": [
      {
        "name": "bo",
        "href": "https://app.stora.co{rel}",
        "templated": true,
        "title": "Backoffice"
      },
      {
        "name": "sf",
        "href": "https://acme.stora.co{rel}",
        "templated": true,
        "title": "Storefront"
      }
    ]
  }
}
```

For example, a link `sf:new_order` with `href` `/sites/belfast/5x5-unit/order/contact-details?unit_type_slug=5x5-unit` resolves to:

```
https://acme.stora.co/sites/belfast/5x5-unit/order/contact-details?unit_type_slug=5x5-unit
```

### Conditional links

Links can be conditional — they only appear when the action is available. For example:

* A **contract** only has `sf:show_contract` when it is not voided or deleted
* A **unit type** only has `sf:new_order` when its status is `bookable`

When no links are available, the `_links` field is an empty object `{}`.