# Introduction

# The Open HelpDesk API

One REST API per workspace. It reaches everything a support team accumulates —
tickets and their conversations, the people who wrote in, the companies they
belong to, the help centre — and it writes through the same paths the product
uses itself.

That last point is the one worth remembering: **creating a ticket over the API
runs the same rules, the same SLA policies and the same outbound webhooks as an
email arriving at your support address.** There is no quiet back door, and no
second set of behaviour to learn.

## Before you start

You need an API key. Mint one in your workspace under **Settings → API &
webhooks**. It is shown once, at creation — we store only its hash, so a lost
key is replaced, never recovered.

```bash
curl https://acme.open-helpdesk.com/api/v1/tickets \
  -H "Authorization: Bearer $OHD_TOKEN"
```

The key carries its own workspace, so the call works whatever host it reaches
and only ever sees that one workspace.

## In Postman

**Run in Postman**, top right, downloads a collection with all 32 requests
already laid out. Import it (File → Import, or drag it onto the window), then
fill two collection variables:

| Variable | Value |
|---|---|
| `baseUrl` | `https://acme.open-helpdesk.com/api/v1` |
| `token` | your API key |

Authentication is already set on the collection, so every request inherits it.

The collection is generated from the same OpenAPI document as the reference you
are reading — it is never edited by hand, so it cannot describe a route that no
longer exists. It downloads rather than opening Postman's cloud on purpose: a
published copy would live on someone else's servers and would need
re-publishing by hand on every change.

## What it will not do

Said plainly, because discovering a limit at integration time is worse than
reading it now:

- **It does not import a history.** Bringing tickets over from another product
  keeps their numbers, their dates and their real authors, none of which this
  API can set. That is what the [import screen](https://open-helpdesk.com/migrer-depuis-zendesk)
  is for.
- **It does not create agents.** Accounts arrive by invitation, in the product.
- **It does not configure the workspace.** Rules, SLA policies, macros and views
  are readable so an integration can reason about them, and are changed by a
  human who can see the consequences.
- **It does not expose another workspace.** Ever, by any parameter.

## The shape of everything

Every collection answers with the same envelope:

```json
{
  "data": [ … ],
  "next_cursor": "4788"
}
```

Every failure answers with the same one:

```json
{
  "error": { "code": "invalid_status", "message": "Unknown status \"bidon\"." }
}
```

Branch on `code`; show `message` to a human. Timestamps are ISO 8601 in UTC.

## Rate limit

600 requests per minute, per key. Beyond it you get `429` and a `Retry-After`
header in seconds. It exists to stop a runaway loop, not to meter you — if you
are hitting it in normal use, tell us and we will look at the endpoint rather
than sell you a bigger number.