# Introduction

> A REST API over your workspace — conversations, leads, bookings, knowledge, and analytics.

Source: https://www.hey.support/docs/api

---

The Hey Support API is organised around REST. It has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON responses, and uses standard HTTP status codes, authentication, and verbs.

It is available on **Scale and above**. Every endpoint is listed in the sidebar with its method and shape.

## Base URL

All requests go to:

```
https://www.hey.support/api/v1
```

<Callout type="warn">
  Use the `www` host. The bare apex redirects with a 308, and while browsers follow that, several HTTP clients drop the body and the `Authorization` header on a redirected `POST`.
</Callout>

## Versioning

The version is in the path. `v1` is the current version and we will not make breaking changes within it — new fields may be added to responses, so parse defensively and ignore what you do not recognise.

## Authentication

Every request needs an API key as a bearer token. See [Authentication](/docs/api/authentication).

```bash
curl https://www.hey.support/api/v1/me \
  -H 'Authorization: Bearer hs_live_…'
```

## Rate limiting

**1,000 requests per hour, per key.** Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` so you can pace yourself rather than discover the ceiling. Over the limit you get a `429`.

## IDs

IDs are short encoded strings — the same ones in your dashboard URLs — not raw integers. Treat them as opaque.

Requesting a resource that belongs to another workspace returns **`404`, not `403`**, so the API cannot be used to probe whether an id exists.

## Pagination

List endpoints use offset pagination and share one envelope:

```json
{
  "data": [],
  "pagination": { "limit": 20, "offset": 0, "total": 0, "has_more": false }
}
```

`limit` defaults to 20 and caps at 100. Page with `offset`, and stop when `has_more` is `false`.

## Timestamps

All timestamps are ISO 8601 in UTC, for example `2026-08-26T09:30:00Z`.

## Errors

Every failure shares one envelope with a stable `code` to branch on. See [Errors](/docs/api/errors).

## OpenAPI

The machine-readable spec is served at:

```
https://www.hey.support/api/v1/openapi.json
```

Every page in this reference is generated from it, so the two cannot disagree. Point a client generator or an agent toolchain straight at that URL.

<Callout>
  Prefer no code? The [Zapier integration](/docs/integrations/zapier) runs on this same API, with triggers and actions you can wire up without writing anything.
</Callout>