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.

New here? Create an access key, then run the first request below. It takes about two minutes.

Tickets

List, create, update and query tickets, plus messages, watchers, custom fields and links

Desks

Desks, subdesks, tags and custom field definitions

People

Employees synced from your HRIS and identity provider

Assets

Devices and hardware from MDM and manual entries

Applications

SaaS and discovered applications

Requests

Conversations handled by the Harmony AI agent

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 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.

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.

Your first request

List the 20 most recent tickets in a desk:

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 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, set with_total=false to skip the count when you only need the current page.

Idempotency

Create a ticket and Add a ticket message 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:

{ "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:

{
  "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 [e-mail].