Copy page

Getting started

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.

Code
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 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:

Code
{
  "data": [ … ],
  "next_cursor": "4788"
}

Every failure answers with the same one:

Code
{
  "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.