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

# Quickstart

> What the Opencals Storefront API is, how to get an API key, and how to make your first request.

The Opencals Storefront API is a REST booking API for developers. It exposes everything a booking website needs — services, real-time availability, staff members, locations, carts, checkout, and payments — so you can build a fully custom booking experience on any stack while Opencals handles scheduling logic, conflict prevention, and order management behind the scenes.

Every screen in the Opencals dashboard has a programmatic equivalent. If you can configure it in Opencals, you can read it over the API.

## Base URL

All Storefront API endpoints live under a single base URL:

```text theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
https://api.opencals.com
```

Endpoint paths are prefixed with `/storefront` — for example `GET /storefront/products` lists your bookable services. Responses are JSON with camelCase property names.

## Make your first request

<Steps>
  <Step title="Get an API key">
    1. Sign up at [opencals.com](https://opencals.com) and set up your store — services, staff members, locations, and schedules.
    2. In the dashboard, go to **Settings → API Keys** and create a new **Storefront API Key**.
    3. Each key is scoped to your store and starts with `sfk_`.

    <Warning>
      Keep the key server-side (for example in an environment variable). It identifies your store and should never be shipped to the browser.
    </Warning>
  </Step>

  <Step title="List your services">
    List your store's active services with a single call:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
    curl "https://api.opencals.com/storefront/products" \
      -H "X-Api-Key: sfk_your_key_here"
    ```
  </Step>

  <Step title="Read the response">
    The response is a paginated collection:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
    {
      "data": [
        {
          "id": "9c6f7c2e-…",
          "title": "Haircut",
          "duration": 3600,
          "price": 4500,
          "maxAttendees": 1
        }
      ],
      "meta": {
        "page": 1,
        "take": 50,
        "itemCount": 12,
        "pageCount": 1,
        "hasPreviousPage": false,
        "hasNextPage": false
      }
    }
    ```
  </Step>
</Steps>

You can also try every endpoint directly in the [interactive API reference](/docs/api-reference/introduction).

## Pagination

List endpoints accept `page` (1-indexed) and `take` (items per page, maximum 100) query parameters and return a `meta` object with `page`, `take`, `itemCount`, `pageCount`, `hasPreviousPage`, and `hasNextPage`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl "https://api.opencals.com/storefront/products" \
  -H "X-Api-Key: sfk_your_key_here" \
  --url-query "page=2" \
  --url-query "take=20"
```

## Rate limits

Requests are rate-limited per API key:

| Category       | Limit                     |
| -------------- | ------------------------- |
| General        | 100 requests / 60 seconds |
| Authentication | 20 requests / 10 seconds  |
| Password reset | 5 requests / hour         |
| Registration   | 10 requests / minute      |

When you exceed a limit the API responds with `429 Too Many Requests`.

## Timezones

<Note>
  All date and time values in requests and responses are in **UTC**. Availability endpoints accept a `timezone` query parameter (for example `America/New_York`) so slots come back converted for display, and you should convert user-selected times back to UTC before creating appointments.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/docs/authentication">
    API keys, customer tokens, and error responses.
  </Card>

  <Card title="Build a booking page" icon="calendar-check" href="/docs/guides/build-a-booking-page">
    The full flow from listing services to a confirmed booking.
  </Card>

  <Card title="Storefront SDK" icon="cube" href="/docs/guides/storefront-sdk">
    The typed TypeScript client for this API.
  </Card>

  <Card title="API reference" icon="code" href="/docs/api-reference/introduction">
    Every endpoint, parameter, and response shape.
  </Card>
</CardGroup>