> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/api-references/api-documentation/introduction.md).

# Introduction

Build on Harmony: tickets, desks, people, assets, applications, service catalog and AI requests

The Harmony API gives you programmatic access to the same data and actions the Harmony dashboard uses: tickets and their conversations, desks, people, assets, applications, the service catalog, and the requests handled by the Harmony AI agent.

{% hint style="info" %}
New here? Create an access key, then run the [first request](#your-first-request) below. It takes about two minutes.
{% endhint %}

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Tickets</strong></td><td>List, create, update and query tickets, plus messages, watchers, custom fields and links</td><td><a href="/api-references/tickets/list-tickets.md">List tickets</a></td></tr><tr><td><strong>Desks</strong></td><td>Desks, subdesks, tags and custom field definitions</td><td><a href="/api-references/desks/list-desks.md">List desks</a></td></tr><tr><td><strong>People</strong></td><td>Employees synced from your HRIS and identity provider</td><td><a href="/api-references/people/list-employees.md">List employees</a></td></tr><tr><td><strong>Assets</strong></td><td>Devices and hardware from MDM and manual entries</td><td><a href="/api-references/assets/list-assets.md">List assets</a></td></tr><tr><td><strong>Applications</strong></td><td>SaaS and discovered applications</td><td><a href="/api-references/applications/list-applications.md">List applications</a></td></tr><tr><td><strong>Requests</strong></td><td>Conversations handled by the Harmony AI agent</td><td><a href="/api-references/requests/list-requests.md">List requests</a></td></tr></tbody></table>

## Base URLs

All endpoints are served from `https://api.harmony.io`, under a per-service prefix. Every organization uses the same host: your tenant is identified by your access key, not by the URL.

| Area                          | Base URL                                  |
| ----------------------------- | ----------------------------------------- |
| Tickets, desks, custom fields | `https://api.harmony.io/service-desk`     |
| People                        | `https://api.harmony.io/employees`        |
| Assets                        | `https://api.harmony.io/asset-management` |
| Applications                  | `https://api.harmony.io/applications`     |
| Service catalog               | `https://api.harmony.io/service-catalog`  |
| Requests (AI conversations)   | `https://api.harmony.io/agents`           |

A full URL is the base URL plus the endpoint path, for example `https://api.harmony.io/service-desk/api/v1/tickets/`.

## Authentication

Every request must include an access key in the `Authorization` header, using the `AccessKey` scheme (not `Bearer`):

```
Authorization: AccessKey <your-access-key>
```

To create a key, go to **Settings > Access Keys** in the dashboard. See [Managing API Access Keys](https://docs.harmony.io/settings/managing-api-access-keys) for details.

When you create a key you choose its role:

| Key role         | What it can do                                                                        |
| ---------------- | ------------------------------------------------------------------------------------- |
| **Read**         | Read-only access                                                                      |
| **Read + Write** | Read access, plus creating and updating tickets, messages, assets and other resources |

The key determines which tenant a request runs in, so you do not need to send a tenant header such as `X-Tenant-ID`.

{% hint style="warning" %}
Treat access keys like passwords. Store them in a secrets manager, never commit them to source control, use one key per integration, and rotate them regularly.
{% endhint %}

## Your first request

List the 20 most recent tickets in a desk:

```bash
curl "https://api.harmony.io/service-desk/api/v1/tickets/?desk_id=it-desk&page=1&page_size=20" \
  -H "Authorization: AccessKey $HARMONY_ACCESS_KEY" \
  -H "Accept: application/json"
```

Desk IDs are the slugs in the dashboard URL (`/tickets/desk/<desk_id>`). You can also call [List desks](/api-references/desks/list-desks.md) to get them.

## IDs

* **Tickets** accept the display ID, case-insensitive, for example `INC-7814` or `inc-7814`.
* **Desks** use slug IDs such as `it-desk`, `hr` or `custom-people-operations`.
* **Employees, assets, applications and catalog items** use opaque string IDs returned by the list endpoints.

## Pagination

List endpoints use one of two styles. Each endpoint's reference page shows which one applies.

| Style        | Parameters                        | Used by                                                 |
| ------------ | --------------------------------- | ------------------------------------------------------- |
| Page-based   | `page` (starts at 1), `page_size` | Tickets, ticket messages, requests                      |
| Offset-based | `limit`, `offset`                 | People, assets, applications, ticket and asset activity |

Every paginated response returns `items` and `total_count`, the number of items matching the query. On [List assets](/api-references/assets/list-assets.md), set `with_total=false` to skip the count when you only need the current page.

## Idempotency

[Create a ticket](/api-references/tickets/create-ticket.md) and [Add a ticket message](/api-references/tickets/create-ticket-message.md) accept an optional `X-Idempotency-Key` header. Send a unique value (for example a UUID) per logical operation; a retry with the same key will not create a duplicate.

## Errors

Harmony uses standard HTTP status codes. Error bodies are JSON with a `detail` field:

```json
{ "detail": "Ticket not found" }
```

| Status | Meaning                                                      |
| ------ | ------------------------------------------------------------ |
| `400`  | The request is malformed or breaks a business rule           |
| `401`  | Missing or invalid access key (check the `AccessKey` prefix) |
| `403`  | The key is valid but its role does not allow this action     |
| `404`  | The resource does not exist, or the key cannot see it        |
| `422`  | Validation failed; `detail` lists each invalid field         |
| `429`  | Too many requests; back off and retry                        |
| `5xx`  | Server error; retry with exponential backoff                 |

For `422` responses, `detail` is an array:

```json
{
  "detail": [
    { "loc": ["body", "title"], "msg": "Field required", "type": "missing" }
  ]
}
```

## Timestamps

Timestamps are ISO 8601, for example `2026-09-23T10:39:00Z`. Date filters such as `created_after` accept the same format.

## Support

Questions, or an endpoint you need that is not listed here? Contact <support@harmony.io>.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.harmony.io/api-references/api-documentation/introduction.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.