API reference

Build on Arvesk

A versioned REST API, signed webhooks and inbound email. Everything goes through the same rules as the app, so SLAs, automations and notifications just work.

Arvesk REST API

The API gives programmatic access to a workspace: tickets and their conversations, assets, people, problems, changes and published solutions. It is a JSON API over HTTPS, versioned in the path. Writes go through the same service layer as the app, so SLA targets, automatic assignment, automations, notifications and webhooks behave exactly as they do for agents.

Base URL
https://helpdesk.terrafirma.dev/api/v1

Every request is scoped to the workspace the API key belongs to. Ids and numbers from other workspaces are simply not found. A machine-readable health check is available, without authentication, at GET https://helpdesk.terrafirma.dev/api/health.

Authentication

Authenticate with an API key sent as a bearer token. Workspace admins create keys in Admin → API keys; the full key is shown once, so store it in a secret manager.

curl https://helpdesk.terrafirma.dev/api/v1/me \
  -H "Authorization: Bearer ksk_…"

A key acts as the person who created it and can never do more than they can: each endpoint lists the role permission it needs. On top of that, every key has scopes:

  • read: GET requests.
  • write: POST, PATCH and DELETE.

Keys stop working when they are revoked, when they expire, when their user is deactivated or when the workspace is suspended.

Requests and responses

Send JSON bodies with Content-Type: application/json (1 MB maximum). Field names are snake_case; the camelCase names used in responses are accepted too, so a record you fetched can be sent back. Enum values are case-insensitive (in_progress, IN_PROGRESS and in progress are the same). Unknown fields are rejected rather than ignored.

Rich-text fields take HTML or plain text. HTML is sanitized; plain text becomes paragraphs. Successful responses wrap the record in data; dates are ISO 8601 in UTC.

{ "data": { "id": "…", "ref": "INC-1042", … } }

Pagination

List endpoints take page (from 1) and per_page (default 25, maximum 100) and return the total alongside the page. Most lists also take sort and updated_since, which together make incremental sync simple.

{
  "data": [
    "…"
  ],
  "meta": {
    "page": 2,
    "per_page": 25,
    "total": 137
  }
}

Errors

Errors use conventional status codes and one shape. code is stable and safe to branch on; message is for people. Validation errors list every offending field in details.

{
  "error": {
    "code": "validation_failed",
    "message": "priority: Invalid enum value. Expected 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT', received 'CRITICAL'",
    "details": [
      {
        "field": "priority",
        "message": "Invalid enum value. Expected 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT', received 'CRITICAL'"
      },
      {
        "field": "group_id",
        "message": "No group with that id in this workspace."
      }
    ]
  }
}
StatusCodeMeaning
400invalid_jsonThe body is not a JSON object.
400invalid_requestThe request broke a business rule. The message says which.
401unauthorizedThe API key is missing, wrong, revoked or expired.
403insufficient_scopeThe key lacks the read or write scope the endpoint needs.
403forbiddenThe key's user does not have the permission the endpoint needs.
403plan_requiredThe workspace's plan does not include this feature.
404not_foundNo such record in this workspace.
409conflictThe record already exists (for example a duplicate email).
413payload_too_largeThe body is larger than 1 MB.
422validation_failedOne or more fields are invalid. details lists each field and what is wrong with it.
429rate_limitedToo many requests. Wait for the number of seconds in Retry-After.
429limit_reachedA plan limit was reached.
500internal_errorSomething went wrong on our side. Safe to retry.

Rate limits

Each key may make 120 requests per minute. Every response reports the budget in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). Over the limit the API answers 429 with a Retry-After header in seconds. Wait that long before retrying.

Current key

A quick way to check that a key works and to see what it may do.

GET/api/v1/me

Who am I

Returns the key, its workspace and the user it acts as.

Scope: read
Example request
curl "https://helpdesk.terrafirma.dev/api/v1/me" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": {
    "key": {
      "id": "cm4x0z9yx0000l508n1m2k3j4",
      "name": "Monitoring",
      "prefix": "ksk_Zq3vT8aL",
      "scopes": [
        "read",
        "write"
      ],
      "expiresAt": null,
      "lastUsedAt": "2026-03-02T09:59:12.000Z",
      "createdAt": "2026-01-08T13:00:00.000Z"
    },
    "workspace": {
      "name": "Brightwater Systems",
      "slug": "brightwater",
      "timezone": "America/New_York",
      "plan": "PRO"
    },
    "user": {
      "id": "cm4x1h9a10003l508q9r5t2nb",
      "name": "Alex Morgan",
      "email": "alex@example.com",
      "type": "AGENT",
      "role": {
        "id": "cm4x1h7aa0000l508a1b2c3d4",
        "name": "Account Admin"
      },
      "permissions": [
        "tickets.manage",
        "tickets.view"
      ]
    }
  }
}

Tickets

Incidents and service requests. Tickets are addressed by their number. Creating and updating tickets through the API applies the same SLA policies, automatic assignment, automations, notifications and webhooks as the agent workspace.

GET/api/v1/tickets

List tickets

Tickets that are not deleted or marked as spam, newest first. Tickets in a restricted service desk are only returned when the key's user is in one of its groups or is an admin.

Scope: readPermission: View tickets
Query parameters
status
string
One or more of open, in_progress, pending, on_hold, resolved, closed (comma-separated).
priority
string
One or more of low, medium, high, urgent.
type
string
incident or service_request.
desk
string
One or more service desk keys (comma-separated), or none for tickets without a desk.
group_id
string
A group id, or none for tickets without a group.
assignee_id
string
An agent id, or none for unassigned tickets.
requester_id
string
Tickets raised by this person.
tag
string
Tickets carrying this tag.
updated_since
ISO 8601 date
Only records changed at or after this time. Use it for incremental sync.
q
string
Search in the subject, the requester's name and email, or a ticket number.
sort
string
One of created_at, updated_at, number, priority, resolution_due_at. Prefix with a minus sign (-) for descending. Default -created_at.
page
integer
Page number, starting at 1.
per_page
integer
Items per page. Default 25, maximum 100.
Example request
curl "https://helpdesk.terrafirma.dev/api/v1/tickets?status=open,in_progress&priority=high,urgent&per_page=25" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": [
    {
      "id": "cm4x1k2ab0001l5087d1f3q9z",
      "ref": "INC-1042",
      "number": 1042,
      "type": "INCIDENT",
      "subject": "VPN disconnects every hour",
      "status": "OPEN",
      "priority": "HIGH",
      "urgency": "HIGH",
      "impact": "MEDIUM",
      "source": "API",
      "category": "Network",
      "subcategory": "VPN",
      "tags": [
        "vpn",
        "remote"
      ],
      "requesterId": "cm4x1h9zt0004l508k2v7c1ma",
      "assigneeId": null,
      "groupId": "cm4x1h8qe0002l508x0w3p6rd",
      "departmentId": null,
      "customFields": {},
      "firstResponseDueAt": "2026-03-02T11:00:00.000Z",
      "resolutionDueAt": "2026-03-03T10:00:00.000Z",
      "firstRespondedAt": null,
      "resolvedAt": null,
      "closedAt": null,
      "createdAt": "2026-03-02T10:00:00.000Z",
      "updatedAt": "2026-03-02T10:00:00.000Z",
      "url": "https://desk.example.com/tickets/1042",
      "desk": {
        "key": "it",
        "name": "IT"
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}
POST/api/v1/tickets

Create a ticket

The source is recorded as API. Identify the requester by id or by email. An unknown email address creates a new requester.

Scope: writePermission: Work on tickets
Body (JSON)
subjectrequired
string
Up to 300 characters.
description
string
HTML or plain text. HTML is sanitized; plain text becomes paragraphs.
requester_id
string
Required unless requester_email is given.
requester_email
string
Finds the person by email or creates a requester.
requester_name
string
Name for a newly created requester.
type
string
incident (default) or service_request.
status
string
open, in_progress, pending, on_hold, resolved or closed.
priority
string
low, medium, high or urgent. When omitted on create it is derived from impact × urgency.
impact
string
low, medium or high.
urgency
string
low, medium or high.
category
string | null
Category name.
subcategory
string | null
Subcategory name.
desk
string
Service desk key, such as it or facilities. On create it defaults to the group's desk, then the workspace's default desk. Moving a ticket to another desk drops a group that belongs to a different desk.
group_id
string | null
Group (queue) to route to. Groups with automatic assignment pick an agent.
assignee_id
string | null
An active agent.
department_id
string | null
Defaults to the requester's department.
tags
string[]
Up to 20 tags; stored lower-case.
custom_fields
object
Values keyed by custom field key. Unknown keys are rejected.
Example request
curl -X POST "https://helpdesk.terrafirma.dev/api/v1/tickets" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "VPN disconnects every hour",
    "description": "The client drops the tunnel roughly once an hour on Wi-Fi.",
    "requester_email": "jane.doe@example.com",
    "priority": "high",
    "category": "Network",
    "tags": [
      "vpn",
      "remote"
    ]
  }'
Response · 201
{
  "data": {
    "id": "cm4x1k2ab0001l5087d1f3q9z",
    "ref": "INC-1042",
    "number": 1042,
    "type": "INCIDENT",
    "subject": "VPN disconnects every hour",
    "status": "OPEN",
    "priority": "HIGH",
    "urgency": "HIGH",
    "impact": "MEDIUM",
    "source": "API",
    "category": "Network",
    "subcategory": "VPN",
    "tags": [
      "vpn",
      "remote"
    ],
    "requesterId": "cm4x1h9zt0004l508k2v7c1ma",
    "assigneeId": null,
    "groupId": "cm4x1h8qe0002l508x0w3p6rd",
    "departmentId": null,
    "customFields": {},
    "firstResponseDueAt": "2026-03-02T11:00:00.000Z",
    "resolutionDueAt": "2026-03-03T10:00:00.000Z",
    "firstRespondedAt": null,
    "resolvedAt": null,
    "closedAt": null,
    "createdAt": "2026-03-02T10:00:00.000Z",
    "updatedAt": "2026-03-02T10:00:00.000Z",
    "url": "https://desk.example.com/tickets/1042",
    "desk": {
      "key": "it",
      "name": "IT"
    },
    "description": "<p>The client drops the tunnel roughly once an hour on Wi-Fi.</p>",
    "descriptionText": "The client drops the tunnel roughly once an hour on Wi-Fi.",
    "resolutionNote": null,
    "isSpam": false,
    "approvalState": "NOT_REQUESTED",
    "firstResponseBreached": false,
    "resolutionBreached": false,
    "slaPaused": false,
    "requester": {
      "id": "cm4x1h9zt0004l508k2v7c1ma",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    },
    "assignee": null,
    "group": {
      "id": "cm4x1h8qe0002l508x0w3p6rd",
      "name": "Network"
    }
  }
}
GET/api/v1/tickets/{number}

Get a ticket

The full ticket, including its description and the people involved.

Scope: readPermission: View tickets
Path parameters
numberrequired
integer
The ticket's number. The reference form (INC-1042) is accepted too.
Example request
curl "https://helpdesk.terrafirma.dev/api/v1/tickets/1042" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": {
    "id": "cm4x1k2ab0001l5087d1f3q9z",
    "ref": "INC-1042",
    "number": 1042,
    "type": "INCIDENT",
    "subject": "VPN disconnects every hour",
    "status": "OPEN",
    "priority": "HIGH",
    "urgency": "HIGH",
    "impact": "MEDIUM",
    "source": "API",
    "category": "Network",
    "subcategory": "VPN",
    "tags": [
      "vpn",
      "remote"
    ],
    "requesterId": "cm4x1h9zt0004l508k2v7c1ma",
    "assigneeId": null,
    "groupId": "cm4x1h8qe0002l508x0w3p6rd",
    "departmentId": null,
    "customFields": {},
    "firstResponseDueAt": "2026-03-02T11:00:00.000Z",
    "resolutionDueAt": "2026-03-03T10:00:00.000Z",
    "firstRespondedAt": null,
    "resolvedAt": null,
    "closedAt": null,
    "createdAt": "2026-03-02T10:00:00.000Z",
    "updatedAt": "2026-03-02T10:00:00.000Z",
    "url": "https://desk.example.com/tickets/1042",
    "desk": {
      "key": "it",
      "name": "IT"
    },
    "description": "<p>The client drops the tunnel roughly once an hour on Wi-Fi.</p>",
    "descriptionText": "The client drops the tunnel roughly once an hour on Wi-Fi.",
    "resolutionNote": null,
    "isSpam": false,
    "approvalState": "NOT_REQUESTED",
    "firstResponseBreached": false,
    "resolutionBreached": false,
    "slaPaused": false,
    "requester": {
      "id": "cm4x1h9zt0004l508k2v7c1ma",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    },
    "assignee": null,
    "group": {
      "id": "cm4x1h8qe0002l508x0w3p6rd",
      "name": "Network"
    }
  }
}
PATCH/api/v1/tickets/{number}

Update a ticket

Send only the fields to change. Resolving or closing enforces the workspace's close rules (required fields, open tasks). Custom fields are merged, not replaced.

Scope: writePermission: Work on tickets
Path parameters
numberrequired
integer
The ticket's number. The reference form (INC-1042) is accepted too.
Body (JSON)
subject
string
Up to 300 characters.
description
string
HTML or plain text.
type
string
incident (default) or service_request.
status
string
open, in_progress, pending, on_hold, resolved or closed.
priority
string
low, medium, high or urgent. When omitted on create it is derived from impact × urgency.
impact
string
low, medium or high.
urgency
string
low, medium or high.
category
string | null
Category name.
subcategory
string | null
Subcategory name.
desk
string
Service desk key, such as it or facilities. On create it defaults to the group's desk, then the workspace's default desk. Moving a ticket to another desk drops a group that belongs to a different desk.
group_id
string | null
Group (queue) to route to. Groups with automatic assignment pick an agent.
assignee_id
string | null
An active agent.
department_id
string | null
Defaults to the requester's department.
tags
string[]
Up to 20 tags; stored lower-case.
custom_fields
object
Values keyed by custom field key. Unknown keys are rejected.
requester_id
string
Change who the ticket belongs to.
resolution_note
string | null
Shown to the requester when the ticket is resolved.
is_spam
boolean
Needs the Delete tickets permission.
Example request
curl -X PATCH "https://helpdesk.terrafirma.dev/api/v1/tickets/1042" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "resolution_note": "New VPN profile pushed to the device."
  }'
Response · 200
{
  "data": {
    "id": "cm4x1k2ab0001l5087d1f3q9z",
    "ref": "INC-1042",
    "number": 1042,
    "type": "INCIDENT",
    "subject": "VPN disconnects every hour",
    "status": "RESOLVED",
    "priority": "HIGH",
    "urgency": "HIGH",
    "impact": "MEDIUM",
    "source": "API",
    "category": "Network",
    "subcategory": "VPN",
    "tags": [
      "vpn",
      "remote"
    ],
    "requesterId": "cm4x1h9zt0004l508k2v7c1ma",
    "assigneeId": null,
    "groupId": "cm4x1h8qe0002l508x0w3p6rd",
    "departmentId": null,
    "customFields": {},
    "firstResponseDueAt": "2026-03-02T11:00:00.000Z",
    "resolutionDueAt": "2026-03-03T10:00:00.000Z",
    "firstRespondedAt": null,
    "resolvedAt": "2026-03-02T15:12:00.000Z",
    "closedAt": null,
    "createdAt": "2026-03-02T10:00:00.000Z",
    "updatedAt": "2026-03-02T15:12:00.000Z",
    "url": "https://desk.example.com/tickets/1042",
    "desk": {
      "key": "it",
      "name": "IT"
    },
    "description": "<p>The client drops the tunnel roughly once an hour on Wi-Fi.</p>",
    "descriptionText": "The client drops the tunnel roughly once an hour on Wi-Fi.",
    "resolutionNote": "New VPN profile pushed to the device.",
    "isSpam": false,
    "approvalState": "NOT_REQUESTED",
    "firstResponseBreached": false,
    "resolutionBreached": false,
    "slaPaused": false,
    "requester": {
      "id": "cm4x1h9zt0004l508k2v7c1ma",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    },
    "assignee": null,
    "group": {
      "id": "cm4x1h8qe0002l508x0w3p6rd",
      "name": "Network"
    }
  }
}
DELETE/api/v1/tickets/{number}

Delete a ticket

Moves the ticket to the trash. It disappears from the API and can be restored in the agent workspace.

Scope: writePermission: Delete tickets
Path parameters
numberrequired
integer
The ticket's number. The reference form (INC-1042) is accepted too.
Example request
curl -X DELETE "https://helpdesk.terrafirma.dev/api/v1/tickets/1042" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": {
    "id": "cm4x1k2ab0001l5087d1f3q9z",
    "ref": "INC-1042",
    "number": 1042,
    "deleted": true
  }
}

Ticket messages

The conversation on a ticket: public replies, private notes and system entries.

GET/api/v1/tickets/{number}/messages

List messages

Oldest first.

Scope: readPermission: View tickets
Path parameters
numberrequired
integer
The ticket's number. The reference form (INC-1042) is accepted too.
Query parameters
kind
string
reply, note or system (comma-separated).
page
integer
Page number, starting at 1.
per_page
integer
Items per page. Default 25, maximum 100.
Example request
curl "https://helpdesk.terrafirma.dev/api/v1/tickets/1042/messages" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": [
    {
      "id": "cm4x2a7pk0009l508u4m2e8hy",
      "kind": "reply",
      "isPublic": true,
      "bodyHtml": "<p>We have pushed a new VPN profile, please reconnect and let us know.</p>",
      "bodyText": "We have pushed a new VPN profile, please reconnect and let us know.",
      "author": {
        "id": "cm4x1h9a10003l508q9r5t2nb",
        "name": "Alex Morgan",
        "email": "alex@example.com",
        "type": "AGENT"
      },
      "attachments": [],
      "createdAt": "2026-03-02T10:20:00.000Z",
      "updatedAt": "2026-03-02T10:20:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}
POST/api/v1/tickets/{number}/messages

Add a reply or note

A reply is public and is emailed to the requester; a note is visible to agents only. The author is the key's user.

Scope: writePermission: Work on tickets
Path parameters
numberrequired
integer
The ticket's number. The reference form (INC-1042) is accepted too.
Body (JSON)
bodyrequired
string
HTML or plain text.
kind
string
reply (default) or note.
status
string
Optionally move the ticket to this status in the same step, e.g. resolved.
Example request
curl -X POST "https://helpdesk.terrafirma.dev/api/v1/tickets/1042/messages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "We have pushed a new VPN profile, please reconnect and let us know.",
    "kind": "reply"
  }'
Response · 201
{
  "data": {
    "id": "cm4x2a7pk0009l508u4m2e8hy",
    "kind": "reply",
    "isPublic": true,
    "bodyHtml": "<p>We have pushed a new VPN profile, please reconnect and let us know.</p>",
    "bodyText": "We have pushed a new VPN profile, please reconnect and let us know.",
    "author": {
      "id": "cm4x1h9a10003l508q9r5t2nb",
      "name": "Alex Morgan",
      "email": "alex@example.com",
      "type": "AGENT"
    },
    "attachments": [],
    "createdAt": "2026-03-02T10:20:00.000Z",
    "updatedAt": "2026-03-02T10:20:00.000Z"
  }
}

Assets

Hardware, software, cloud resources and services in the inventory. Assets are addressed by their number.

GET/api/v1/assets

List assets

Assets that are not deleted, newest first.

Scope: readPermission: View assets
Query parameters
state
string
One or more of in_stock, in_use, in_repair, on_order, retired, missing, disposed.
asset_type_id
string
Assets of this type.
type
string
Assets of the type with this name, e.g. Laptop.
used_by_id
string
A person's id, or none for unassigned assets.
managed_by_id · group_id · department_id · location_id
string
Filter by the matching reference (or none).
serial_number
string
Exact serial number.
updated_since
ISO 8601 date
Only records changed at or after this time. Use it for incremental sync.
q
string
Search in name, asset tag, serial number, hostname, or an asset number.
sort
string
One of created_at, updated_at, number, name. Prefix with a minus sign (-) for descending. Default -created_at.
page
integer
Page number, starting at 1.
per_page
integer
Items per page. Default 25, maximum 100.
Example request
curl "https://helpdesk.terrafirma.dev/api/v1/assets?state=in_use&type=Laptop" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": [
    {
      "id": "cm4x3b1cd000cl508h6s9w0xa",
      "ref": "AST-17",
      "number": 17,
      "name": "MacBook Pro 14 (Jane Doe)",
      "assetTag": "IT-00017",
      "type": {
        "id": "cm4x1h8c20001l508y7n4b3vf",
        "name": "Laptop",
        "class": "HARDWARE"
      },
      "typeId": "cm4x1h8c20001l508y7n4b3vf",
      "state": "IN_USE",
      "impact": "LOW",
      "description": null,
      "serialNumber": "C02XK0AAJGH5",
      "manufacturer": "Apple",
      "model": "MacBook Pro 14-inch (M3)",
      "hostname": "mbp-jdoe",
      "ipAddress": null,
      "macAddress": null,
      "os": "macOS",
      "osVersion": "15.3",
      "cpu": "Apple M3 Pro",
      "memoryGb": 18,
      "storageGb": 512,
      "cost": 2399,
      "salvageValue": null,
      "purchaseDate": "2025-09-01T12:00:00.000Z",
      "warrantyExpiresAt": "2028-09-01T12:00:00.000Z",
      "endOfLifeAt": null,
      "vendorId": null,
      "usedById": "cm4x1h9zt0004l508k2v7c1ma",
      "managedById": null,
      "groupId": null,
      "departmentId": null,
      "locationId": null,
      "assignedAt": "2025-09-03T09:12:00.000Z",
      "externalSource": null,
      "lastSeenAt": null,
      "tags": [
        "mac"
      ],
      "customFields": {},
      "createdAt": "2025-09-03T09:12:00.000Z",
      "updatedAt": "2026-02-11T14:05:00.000Z",
      "url": "https://desk.example.com/assets/17"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}
POST/api/v1/assets

Create an asset

Give the asset type by id or by name. Emits the asset.created webhook event.

Scope: writePermission: Manage assets
Body (JSON)
namerequired
string
Up to 160 characters.
asset_type_id
string
Required unless type is given.
type
string
Asset type by name, e.g. Laptop.
state
string
Defaults to in_use when used_by_id is set, otherwise in_stock.
impact
string
low, medium or high.
asset_tag · serial_number · manufacturer · model · description
string | null
Identification.
hostname · ip_address · mac_address · os · os_version · cpu
string | null
Technical details.
memory_gb · storage_gb · cost · salvage_value
number | null
Sizes in GB; money in the workspace currency.
purchase_date · warranty_expires_at · end_of_life_at
ISO 8601 date | null
Calendar dates such as 2026-03-01.
used_by_id · managed_by_id
string | null
Who uses the asset, and the agent responsible for it.
group_id · department_id · location_id · vendor_id
string | null
Ownership and location.
tags
string[]
Up to 20 tags.
custom_fields
object
Values for the asset type's custom fields.
Example request
curl -X POST "https://helpdesk.terrafirma.dev/api/v1/assets" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MacBook Pro 14 (Jane Doe)",
    "type": "Laptop",
    "serial_number": "C02XK0AAJGH5",
    "manufacturer": "Apple",
    "used_by_id": "cm4x1h9zt0004l508k2v7c1ma",
    "cost": 2399,
    "purchase_date": "2025-09-01"
  }'
Response · 201
{
  "data": {
    "id": "cm4x3b1cd000cl508h6s9w0xa",
    "ref": "AST-17",
    "number": 17,
    "name": "MacBook Pro 14 (Jane Doe)",
    "assetTag": "IT-00017",
    "type": {
      "id": "cm4x1h8c20001l508y7n4b3vf",
      "name": "Laptop",
      "class": "HARDWARE"
    },
    "typeId": "cm4x1h8c20001l508y7n4b3vf",
    "state": "IN_USE",
    "impact": "LOW",
    "description": null,
    "serialNumber": "C02XK0AAJGH5",
    "manufacturer": "Apple",
    "model": "MacBook Pro 14-inch (M3)",
    "hostname": "mbp-jdoe",
    "ipAddress": null,
    "macAddress": null,
    "os": "macOS",
    "osVersion": "15.3",
    "cpu": "Apple M3 Pro",
    "memoryGb": 18,
    "storageGb": 512,
    "cost": 2399,
    "salvageValue": null,
    "purchaseDate": "2025-09-01T12:00:00.000Z",
    "warrantyExpiresAt": "2028-09-01T12:00:00.000Z",
    "endOfLifeAt": null,
    "vendorId": null,
    "usedById": "cm4x1h9zt0004l508k2v7c1ma",
    "managedById": null,
    "groupId": null,
    "departmentId": null,
    "locationId": null,
    "assignedAt": "2025-09-03T09:12:00.000Z",
    "externalSource": null,
    "lastSeenAt": null,
    "tags": [
      "mac"
    ],
    "customFields": {},
    "createdAt": "2025-09-03T09:12:00.000Z",
    "updatedAt": "2026-02-11T14:05:00.000Z",
    "url": "https://desk.example.com/assets/17"
  }
}
GET/api/v1/assets/{number}

Get an asset

One asset by number.

Scope: readPermission: View assets
Path parameters
numberrequired
integer
The asset's number. The reference form (AST-1042) is accepted too.
Example request
curl "https://helpdesk.terrafirma.dev/api/v1/assets/17" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": {
    "id": "cm4x3b1cd000cl508h6s9w0xa",
    "ref": "AST-17",
    "number": 17,
    "name": "MacBook Pro 14 (Jane Doe)",
    "assetTag": "IT-00017",
    "type": {
      "id": "cm4x1h8c20001l508y7n4b3vf",
      "name": "Laptop",
      "class": "HARDWARE"
    },
    "typeId": "cm4x1h8c20001l508y7n4b3vf",
    "state": "IN_USE",
    "impact": "LOW",
    "description": null,
    "serialNumber": "C02XK0AAJGH5",
    "manufacturer": "Apple",
    "model": "MacBook Pro 14-inch (M3)",
    "hostname": "mbp-jdoe",
    "ipAddress": null,
    "macAddress": null,
    "os": "macOS",
    "osVersion": "15.3",
    "cpu": "Apple M3 Pro",
    "memoryGb": 18,
    "storageGb": 512,
    "cost": 2399,
    "salvageValue": null,
    "purchaseDate": "2025-09-01T12:00:00.000Z",
    "warrantyExpiresAt": "2028-09-01T12:00:00.000Z",
    "endOfLifeAt": null,
    "vendorId": null,
    "usedById": "cm4x1h9zt0004l508k2v7c1ma",
    "managedById": null,
    "groupId": null,
    "departmentId": null,
    "locationId": null,
    "assignedAt": "2025-09-03T09:12:00.000Z",
    "externalSource": null,
    "lastSeenAt": null,
    "tags": [
      "mac"
    ],
    "customFields": {},
    "createdAt": "2025-09-03T09:12:00.000Z",
    "updatedAt": "2026-02-11T14:05:00.000Z",
    "url": "https://desk.example.com/assets/17"
  }
}
PATCH/api/v1/assets/{number}

Update an asset

Send only the fields to change: any field accepted on create. Changing used_by_id records the assignment date. Emits asset.updated when something changed.

Scope: writePermission: Manage assets
Path parameters
numberrequired
integer
The asset's number. The reference form (AST-1042) is accepted too.
Example request
curl -X PATCH "https://helpdesk.terrafirma.dev/api/v1/assets/17" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "in_repair",
    "used_by_id": null
  }'
Response · 200
{
  "data": {
    "id": "cm4x3b1cd000cl508h6s9w0xa",
    "ref": "AST-17",
    "number": 17,
    "name": "MacBook Pro 14 (Jane Doe)",
    "assetTag": "IT-00017",
    "type": {
      "id": "cm4x1h8c20001l508y7n4b3vf",
      "name": "Laptop",
      "class": "HARDWARE"
    },
    "typeId": "cm4x1h8c20001l508y7n4b3vf",
    "state": "IN_REPAIR",
    "impact": "LOW",
    "description": null,
    "serialNumber": "C02XK0AAJGH5",
    "manufacturer": "Apple",
    "model": "MacBook Pro 14-inch (M3)",
    "hostname": "mbp-jdoe",
    "ipAddress": null,
    "macAddress": null,
    "os": "macOS",
    "osVersion": "15.3",
    "cpu": "Apple M3 Pro",
    "memoryGb": 18,
    "storageGb": 512,
    "cost": 2399,
    "salvageValue": null,
    "purchaseDate": "2025-09-01T12:00:00.000Z",
    "warrantyExpiresAt": "2028-09-01T12:00:00.000Z",
    "endOfLifeAt": null,
    "vendorId": null,
    "usedById": null,
    "managedById": null,
    "groupId": null,
    "departmentId": null,
    "locationId": null,
    "assignedAt": null,
    "externalSource": null,
    "lastSeenAt": null,
    "tags": [
      "mac"
    ],
    "customFields": {},
    "createdAt": "2025-09-03T09:12:00.000Z",
    "updatedAt": "2026-03-02T15:30:00.000Z",
    "url": "https://desk.example.com/assets/17"
  }
}

Requesters

The people IT supports. Requesters are addressed by id.

GET/api/v1/requesters

List requesters

Sorted by name.

Scope: readPermission: View tickets
Query parameters
email
string
Exact email address.
department_id
string
A department id, or none.
is_active
boolean
true or false.
is_vip
boolean
true or false.
updated_since
ISO 8601 date
Only records changed at or after this time. Use it for incremental sync.
q
string
Search in name and email.
sort
string
One of name, email, created_at, updated_at. Prefix with a minus sign (-) for descending. Default name.
page
integer
Page number, starting at 1.
per_page
integer
Items per page. Default 25, maximum 100.
Example request
curl "https://helpdesk.terrafirma.dev/api/v1/requesters?email=jane.doe@example.com" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": [
    {
      "id": "cm4x1h9zt0004l508k2v7c1ma",
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "type": "REQUESTER",
      "isActive": true,
      "isVip": false,
      "jobTitle": "Account Executive",
      "phone": "+1 212 555 0100",
      "timezone": "America/New_York",
      "departmentId": "cm4x1h8zz0006l508d3k1j5wq",
      "locationId": null,
      "managerId": null,
      "customFields": {},
      "createdAt": "2025-06-12T08:30:00.000Z",
      "updatedAt": "2026-01-20T16:42:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}
POST/api/v1/requesters

Create a requester

Responds with 409 when someone with that email already exists; the error details carry the existing id.

Scope: writePermission: Work on tickets, or Manage people
Body (JSON)
emailrequired
string
Unique within the workspace.
namerequired
string
Full name.
phone · job_title · timezone
string | null
Profile details.
department_id · location_id · manager_id
string | null
Organisation.
is_vip
boolean
VIP requesters can be prioritised by SLA policies and automations.
Example request
curl -X POST "https://helpdesk.terrafirma.dev/api/v1/requesters" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@example.com",
    "name": "Jane Doe",
    "job_title": "Account Executive"
  }'
Response · 201
{
  "data": {
    "id": "cm4x1h9zt0004l508k2v7c1ma",
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "type": "REQUESTER",
    "isActive": true,
    "isVip": false,
    "jobTitle": "Account Executive",
    "phone": "+1 212 555 0100",
    "timezone": "America/New_York",
    "departmentId": "cm4x1h8zz0006l508d3k1j5wq",
    "locationId": null,
    "managerId": null,
    "customFields": {},
    "createdAt": "2025-06-12T08:30:00.000Z",
    "updatedAt": "2026-01-20T16:42:00.000Z"
  }
}
GET/api/v1/requesters/{id}

Get a requester

One requester by id.

Scope: readPermission: View tickets
Path parameters
idrequired
string
The requester's id.
Example request
curl "https://helpdesk.terrafirma.dev/api/v1/requesters/cm4x1h9zt0004l508k2v7c1ma" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": {
    "id": "cm4x1h9zt0004l508k2v7c1ma",
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "type": "REQUESTER",
    "isActive": true,
    "isVip": false,
    "jobTitle": "Account Executive",
    "phone": "+1 212 555 0100",
    "timezone": "America/New_York",
    "departmentId": "cm4x1h8zz0006l508d3k1j5wq",
    "locationId": null,
    "managerId": null,
    "customFields": {},
    "createdAt": "2025-06-12T08:30:00.000Z",
    "updatedAt": "2026-01-20T16:42:00.000Z"
  }
}

Agents, groups and departments

Read-only lookups for the ids used elsewhere in the API.

GET/api/v1/agents

List agents

IT staff with their role and group memberships.

Scope: readPermission: View tickets
Query parameters
is_active
boolean
true or false.
group_id
string
Members of this group.
email
string
Exact email address.
q
string
Search in name and email.
sort
string
One of name, email, created_at, updated_at. Prefix with a minus sign (-) for descending. Default name.
page
integer
Page number, starting at 1.
per_page
integer
Items per page. Default 25, maximum 100.
Example request
curl "https://helpdesk.terrafirma.dev/api/v1/agents" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": [
    {
      "id": "cm4x1h9a10003l508q9r5t2nb",
      "name": "Alex Morgan",
      "email": "alex@example.com",
      "type": "AGENT",
      "isActive": true,
      "isVip": false,
      "jobTitle": "IT Administrator",
      "phone": "+1 212 555 0100",
      "timezone": "America/New_York",
      "departmentId": "cm4x1h8zz0006l508d3k1j5wq",
      "locationId": null,
      "managerId": null,
      "customFields": {},
      "createdAt": "2025-06-12T08:30:00.000Z",
      "updatedAt": "2026-01-20T16:42:00.000Z",
      "role": {
        "id": "cm4x1h7aa0000l508a1b2c3d4",
        "name": "Account Admin"
      },
      "groupIds": [
        "cm4x1h8qe0002l508x0w3p6rd"
      ],
      "lastLoginAt": "2026-03-02T08:01:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}
GET/api/v1/groups

List groups

Queues that tickets, problems and changes are routed to, with their active members.

Scope: readPermission: View tickets
Query parameters
q
string
Search by name.
page
integer
Page number, starting at 1.
per_page
integer
Items per page. Default 25, maximum 100.
Example request
curl "https://helpdesk.terrafirma.dev/api/v1/groups" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": [
    {
      "id": "cm4x1h8qe0002l508x0w3p6rd",
      "name": "Network",
      "description": "LAN, Wi-Fi, VPN and firewalls",
      "email": "network@example.com",
      "color": "#2563eb",
      "assignmentMode": "ROUND_ROBIN",
      "businessHoursId": "cm4x1h8b70005l508m2n3b4v5",
      "deskId": "cm4x1h7d10000l508it0desk01",
      "memberIds": [
        "cm4x1h9a10003l508q9r5t2nb"
      ],
      "createdAt": "2025-06-12T08:30:00.000Z",
      "updatedAt": "2025-06-12T08:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}
GET/api/v1/departments

List departments

Departments with their member counts.

Scope: readPermission: View tickets
Query parameters
q
string
Search by name.
page
integer
Page number, starting at 1.
per_page
integer
Items per page. Default 25, maximum 100.
Example request
curl "https://helpdesk.terrafirma.dev/api/v1/departments" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": [
    {
      "id": "cm4x1h8zz0006l508d3k1j5wq",
      "name": "Sales",
      "description": "Field and inside sales",
      "headId": null,
      "domains": [
        "sales.example.com"
      ],
      "memberCount": 14,
      "createdAt": "2025-06-12T08:30:00.000Z",
      "updatedAt": "2025-06-12T08:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}

Problems

Root-cause investigations behind recurring incidents. Requires a plan with problem management.

GET/api/v1/problems

List problems

Newest first.

Scope: readPermission: View problems
Query parameters
status
string
One or more of open, investigating, known_error, resolved, closed.
priority
string
One or more of low, medium, high, urgent.
assignee_id · group_id · requester_id
string
Filter by the matching reference (or none).
updated_since
ISO 8601 date
Only records changed at or after this time. Use it for incremental sync.
q
string
Search in the subject, or a problem number.
sort
string
One of created_at, updated_at, number, priority, due_by. Prefix with a minus sign (-) for descending. Default -created_at.
page
integer
Page number, starting at 1.
per_page
integer
Items per page. Default 25, maximum 100.
Example request
curl "https://helpdesk.terrafirma.dev/api/v1/problems?status=open,investigating" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": [
    {
      "id": "cm4x4c2de000fl508p1q2r3s4",
      "ref": "PRB-7",
      "number": 7,
      "subject": "Recurring VPN disconnects on the new firmware",
      "status": "INVESTIGATING",
      "priority": "HIGH",
      "impact": "HIGH",
      "urgency": "MEDIUM",
      "category": "Network",
      "knownError": false,
      "dueBy": "2026-03-10T17:00:00.000Z",
      "tags": [
        "vpn"
      ],
      "requesterId": "cm4x1h9a10003l508q9r5t2nb",
      "assigneeId": "cm4x1h9a10003l508q9r5t2nb",
      "groupId": "cm4x1h8qe0002l508x0w3p6rd",
      "departmentId": null,
      "customFields": {},
      "closedAt": null,
      "createdAt": "2026-03-02T11:00:00.000Z",
      "updatedAt": "2026-03-02T11:00:00.000Z",
      "url": "https://desk.example.com/problems/7"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}
POST/api/v1/problems

Create a problem

Emits the problem.created webhook event.

Scope: writePermission: Manage problems
Body (JSON)
subjectrequired
string
Up to 300 characters.
description · symptoms · root_cause · impact_analysis · workaround
string
HTML or plain text.
status
string
open (default), investigating or known_error.
priority · impact · urgency
string
As for tickets; priority is derived from impact × urgency when omitted.
category
string | null
Category name.
known_error
boolean
Flag the problem as a known error.
due_by
ISO 8601 date | null
Target date.
requester_id
string | null
Defaults to the key's user.
assignee_id · group_id · department_id
string | null
Ownership.
tags
string[]
Up to 20 tags.
Example request
curl -X POST "https://helpdesk.terrafirma.dev/api/v1/problems" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Recurring VPN disconnects on the new firmware",
    "impact": "high",
    "urgency": "medium",
    "workaround": "Reconnect; pin the previous firmware where possible."
  }'
Response · 201
{
  "data": {
    "id": "cm4x4c2de000fl508p1q2r3s4",
    "ref": "PRB-7",
    "number": 7,
    "subject": "Recurring VPN disconnects on the new firmware",
    "status": "INVESTIGATING",
    "priority": "HIGH",
    "impact": "HIGH",
    "urgency": "MEDIUM",
    "category": "Network",
    "knownError": false,
    "dueBy": "2026-03-10T17:00:00.000Z",
    "tags": [
      "vpn"
    ],
    "requesterId": "cm4x1h9a10003l508q9r5t2nb",
    "assigneeId": "cm4x1h9a10003l508q9r5t2nb",
    "groupId": "cm4x1h8qe0002l508x0w3p6rd",
    "departmentId": null,
    "customFields": {},
    "closedAt": null,
    "createdAt": "2026-03-02T11:00:00.000Z",
    "updatedAt": "2026-03-02T11:00:00.000Z",
    "url": "https://desk.example.com/problems/7",
    "description": "<p>Twelve incidents in two weeks share the same symptom.</p>",
    "symptoms": "<p>Tunnel drops after about 60 minutes.</p>",
    "rootCause": null,
    "impactAnalysis": null,
    "workaround": "<p>Reconnect; pin the previous firmware where possible.</p>",
    "resolution": null
  }
}
GET/api/v1/problems/{number}

Get a problem

The full problem with its analysis and the numbers of linked tickets.

Scope: readPermission: View problems
Path parameters
numberrequired
integer
The problem's number. The reference form (PRB-1042) is accepted too.
Example request
curl "https://helpdesk.terrafirma.dev/api/v1/problems/7" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": {
    "id": "cm4x4c2de000fl508p1q2r3s4",
    "ref": "PRB-7",
    "number": 7,
    "subject": "Recurring VPN disconnects on the new firmware",
    "status": "INVESTIGATING",
    "priority": "HIGH",
    "impact": "HIGH",
    "urgency": "MEDIUM",
    "category": "Network",
    "knownError": false,
    "dueBy": "2026-03-10T17:00:00.000Z",
    "tags": [
      "vpn"
    ],
    "requesterId": "cm4x1h9a10003l508q9r5t2nb",
    "assigneeId": "cm4x1h9a10003l508q9r5t2nb",
    "groupId": "cm4x1h8qe0002l508x0w3p6rd",
    "departmentId": null,
    "customFields": {},
    "closedAt": null,
    "createdAt": "2026-03-02T11:00:00.000Z",
    "updatedAt": "2026-03-02T11:00:00.000Z",
    "url": "https://desk.example.com/problems/7",
    "description": "<p>Twelve incidents in two weeks share the same symptom.</p>",
    "symptoms": "<p>Tunnel drops after about 60 minutes.</p>",
    "rootCause": null,
    "impactAnalysis": null,
    "workaround": "<p>Reconnect; pin the previous firmware where possible.</p>",
    "resolution": null,
    "ticketNumbers": [
      1042,
      1057
    ]
  }
}

Changes

Planned changes to infrastructure and services. Requires a plan with change management.

GET/api/v1/changes

List changes

Newest first.

Scope: readPermission: View changes and releases
Query parameters
status
string
One or more of draft, planning, awaiting_approval, approved, implementing, in_review, completed, rejected, cancelled.
type
string
One or more of standard, minor, major, emergency.
priority · risk
string
Priority (low…urgent) and risk (low, medium, high, very_high).
assignee_id · group_id · requester_id
string
Filter by the matching reference (or none).
planned_after · planned_before
ISO 8601 date
Changes whose planned start falls in this range.
updated_since
ISO 8601 date
Only records changed at or after this time. Use it for incremental sync.
q
string
Search in the subject, or a change number.
sort
string
One of created_at, updated_at, number, priority, planned_start. Prefix with a minus sign (-) for descending. Default -created_at.
page
integer
Page number, starting at 1.
per_page
integer
Items per page. Default 25, maximum 100.
Example request
curl "https://helpdesk.terrafirma.dev/api/v1/changes?status=approved&planned_after=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": [
    {
      "id": "cm4x5d3ef000jl508t5u6v7w8",
      "ref": "CHG-12",
      "number": 12,
      "subject": "Roll back VPN concentrator firmware",
      "type": "MINOR",
      "status": "DRAFT",
      "priority": "HIGH",
      "impact": "MEDIUM",
      "risk": "LOW",
      "category": "Network",
      "approvalState": "NOT_REQUESTED",
      "plannedStart": "2026-03-05T22:00:00.000Z",
      "plannedEnd": "2026-03-05T23:00:00.000Z",
      "actualStart": null,
      "actualEnd": null,
      "tags": [],
      "requesterId": "cm4x1h9a10003l508q9r5t2nb",
      "assigneeId": null,
      "groupId": "cm4x1h8qe0002l508x0w3p6rd",
      "departmentId": null,
      "releaseId": null,
      "customFields": {},
      "closedAt": null,
      "createdAt": "2026-03-02T11:30:00.000Z",
      "updatedAt": "2026-03-02T11:30:00.000Z",
      "url": "https://desk.example.com/changes/12"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}
POST/api/v1/changes

Create a change

New changes start as drafts; planning, approval and scheduling continue in the agent workspace. Emits the change.created webhook event.

Scope: writePermission: Manage changes and releases
Body (JSON)
subjectrequired
string
Up to 300 characters.
description · reason_for_change · impact_plan · rollout_plan · backout_plan · test_plan
string
HTML or plain text.
type
string
standard, minor (default), major or emergency.
priority · impact · risk
string
Priority (low…urgent), impact (low…high), risk (low…very_high).
category
string | null
Category name.
planned_start · planned_end
ISO 8601 date | null
The end must be after the start.
requester_id
string | null
Defaults to the key's user.
assignee_id · group_id · department_id
string | null
Ownership.
tags
string[]
Up to 20 tags.
Example request
curl -X POST "https://helpdesk.terrafirma.dev/api/v1/changes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Roll back VPN concentrator firmware",
    "type": "minor",
    "risk": "low",
    "planned_start": "2026-03-05T22:00:00Z",
    "planned_end": "2026-03-05T23:00:00Z",
    "backout_plan": "Re-apply the current firmware image."
  }'
Response · 201
{
  "data": {
    "id": "cm4x5d3ef000jl508t5u6v7w8",
    "ref": "CHG-12",
    "number": 12,
    "subject": "Roll back VPN concentrator firmware",
    "type": "MINOR",
    "status": "DRAFT",
    "priority": "HIGH",
    "impact": "MEDIUM",
    "risk": "LOW",
    "category": "Network",
    "approvalState": "NOT_REQUESTED",
    "plannedStart": "2026-03-05T22:00:00.000Z",
    "plannedEnd": "2026-03-05T23:00:00.000Z",
    "actualStart": null,
    "actualEnd": null,
    "tags": [],
    "requesterId": "cm4x1h9a10003l508q9r5t2nb",
    "assigneeId": null,
    "groupId": "cm4x1h8qe0002l508x0w3p6rd",
    "departmentId": null,
    "releaseId": null,
    "customFields": {},
    "closedAt": null,
    "createdAt": "2026-03-02T11:30:00.000Z",
    "updatedAt": "2026-03-02T11:30:00.000Z",
    "url": "https://desk.example.com/changes/12",
    "description": "<p>Return both concentrators to the previous firmware.</p>",
    "reasonForChange": "<p>Fixes PRB-7.</p>",
    "impactPlan": null,
    "rolloutPlan": "<p>Standby node first, then fail over.</p>",
    "backoutPlan": "<p>Re-apply the current firmware image.</p>",
    "testPlan": null
  }
}
GET/api/v1/changes/{number}

Get a change

The full change with its plans.

Scope: readPermission: View changes and releases
Path parameters
numberrequired
integer
The change's number. The reference form (CHG-1042) is accepted too.
Example request
curl "https://helpdesk.terrafirma.dev/api/v1/changes/12" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": {
    "id": "cm4x5d3ef000jl508t5u6v7w8",
    "ref": "CHG-12",
    "number": 12,
    "subject": "Roll back VPN concentrator firmware",
    "type": "MINOR",
    "status": "DRAFT",
    "priority": "HIGH",
    "impact": "MEDIUM",
    "risk": "LOW",
    "category": "Network",
    "approvalState": "NOT_REQUESTED",
    "plannedStart": "2026-03-05T22:00:00.000Z",
    "plannedEnd": "2026-03-05T23:00:00.000Z",
    "actualStart": null,
    "actualEnd": null,
    "tags": [],
    "requesterId": "cm4x1h9a10003l508q9r5t2nb",
    "assigneeId": null,
    "groupId": "cm4x1h8qe0002l508x0w3p6rd",
    "departmentId": null,
    "releaseId": null,
    "customFields": {},
    "closedAt": null,
    "createdAt": "2026-03-02T11:30:00.000Z",
    "updatedAt": "2026-03-02T11:30:00.000Z",
    "url": "https://desk.example.com/changes/12",
    "description": "<p>Return both concentrators to the previous firmware.</p>",
    "reasonForChange": "<p>Fixes PRB-7.</p>",
    "impactPlan": null,
    "rolloutPlan": "<p>Standby node first, then fail over.</p>",
    "backoutPlan": "<p>Re-apply the current firmware image.</p>",
    "testPlan": null
  }
}

Solutions

Published knowledge base articles. Keys whose user may view internal articles see everything published; other keys see what requesters see in the portal.

GET/api/v1/solutions

List articles

Published articles, most recently published first.

Scope: read
Query parameters
q
string
Search in title, excerpt, body and tags.
folder_id · category_id
string
Articles in this folder or category.
kind
string
solution, how_to, faq, known_error or policy.
tag
string
Articles carrying this tag.
updated_since
ISO 8601 date
Only records changed at or after this time. Use it for incremental sync.
sort
string
One of published_at, updated_at, created_at, title, views. Prefix with a minus sign (-) for descending. Default -published_at.
page
integer
Page number, starting at 1.
per_page
integer
Items per page. Default 25, maximum 100.
Example request
curl "https://helpdesk.terrafirma.dev/api/v1/solutions?q=vpn" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": [
    {
      "id": "cm4x6e4fg000nl508x9y0z1a2",
      "title": "Connect to the VPN",
      "slug": "connect-to-the-vpn",
      "excerpt": "Install the client, sign in and stay connected.",
      "kind": "how_to",
      "tags": [
        "vpn",
        "remote"
      ],
      "visibility": "PUBLIC",
      "folder": {
        "id": "cm4x6e1aa000ll508b3c4d5e6",
        "name": "Remote access"
      },
      "category": {
        "id": "cm4x6e0zz000kl508f7g8h9i0",
        "name": "Network"
      },
      "authorId": "cm4x1h9a10003l508q9r5t2nb",
      "views": 412,
      "helpful": 37,
      "notHelpful": 2,
      "publishedAt": "2025-11-04T09:00:00.000Z",
      "createdAt": "2025-11-03T15:20:00.000Z",
      "updatedAt": "2026-01-15T10:10:00.000Z",
      "url": "https://desk.example.com/solutions/cm4x6e4fg000nl508x9y0z1a2"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}
GET/api/v1/solutions/{id}

Get an article

One published article, with its body, by id or slug.

Scope: read
Path parameters
idrequired
string
The article's id or slug.
Example request
curl "https://helpdesk.terrafirma.dev/api/v1/solutions/connect-to-the-vpn" \
  -H "Authorization: Bearer $API_KEY"
Response · 200
{
  "data": {
    "id": "cm4x6e4fg000nl508x9y0z1a2",
    "title": "Connect to the VPN",
    "slug": "connect-to-the-vpn",
    "excerpt": "Install the client, sign in and stay connected.",
    "kind": "how_to",
    "tags": [
      "vpn",
      "remote"
    ],
    "visibility": "PUBLIC",
    "folder": {
      "id": "cm4x6e1aa000ll508b3c4d5e6",
      "name": "Remote access"
    },
    "category": {
      "id": "cm4x6e0zz000kl508f7g8h9i0",
      "name": "Network"
    },
    "authorId": "cm4x1h9a10003l508q9r5t2nb",
    "views": 412,
    "helpful": 37,
    "notHelpful": 2,
    "publishedAt": "2025-11-04T09:00:00.000Z",
    "createdAt": "2025-11-03T15:20:00.000Z",
    "updatedAt": "2026-01-15T10:10:00.000Z",
    "url": "https://desk.example.com/solutions/cm4x6e4fg000nl508x9y0z1a2",
    "bodyHtml": "<h2>Install the client</h2><p>Open Self Service and install the VPN client…</p>",
    "bodyText": "Install the client Open Self Service and install the VPN client…"
  }
}

Webhooks

Webhooks push events to your endpoint as they happen. Admins add them in Admin → Webhooks, choose the events and get a signing secret. Each delivery is an HTTP POST with a JSON body:

{
  "event": "ticket.created",
  "occurredAt": "2026-03-02T10:00:00.412Z",
  "data": {
    "id": "…",
    "ref": "INC-1042",
    "subject": "VPN disconnects every hour",
    "status": "OPEN",
    "…": "…"
  }
}
EventWhen
ticket.createdTicket created
ticket.updatedTicket updated
ticket.resolvedTicket resolved
ticket.closedTicket closed
ticket.replyReply added to a ticket
problem.createdProblem created
change.createdChange created
change.updatedChange updated
asset.createdAsset created
asset.updatedAsset updated

data is the record in the same shape the API returns (ticket.reply carries { ticket, message }). Headers:

  • X-Webhook-Event: the event name.
  • X-Webhook-Delivery: the delivery id, unchanged across retries.
  • X-Webhook-Signature: sha256= followed by the hex HMAC-SHA256 of the raw body, keyed with the webhook's secret.
  • User-Agent: Arvesk-Webhooks/1.0.

Answer with any 2xx status within 10 seconds. Anything else (an error status, a redirect, a timeout) is retried with exponential backoff (30 seconds, 2 minutes, 8 minutes, 32 minutes, 1 hour) and given up after 6 attempts. Delivery is at least once, so de-duplicate on X-Webhook-Delivery. Verify the signature before trusting a payload:

import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

const app = express();

// Verify against the raw body: re-serialising parsed JSON changes the bytes.
app.post("/webhooks/helpdesk", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + createHmac("sha256", process.env.WEBHOOK_SECRET).update(req.body).digest("hex");
  const given = req.get("X-Webhook-Signature") ?? "";
  const ok = given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
  if (!ok) return res.status(401).send("bad signature");

  const deliveryId = req.get("X-Webhook-Delivery"); // stable across retries, use it to de-duplicate
  const { event, occurredAt, data } = JSON.parse(req.body.toString("utf8"));
  // …queue the work, then answer quickly
  res.sendStatus(204);
});

Inbound email

Point your mail provider's inbound webhook (Postmark, Mailgun, SendGrid, SES via a small relay…) at the endpoint below. It turns new emails into tickets and replies into conversation entries.

POST https://helpdesk.terrafirma.dev/api/inbound/email?workspace=<workspace-slug>
x-inbound-secret: <INBOUND_EMAIL_SECRET>

The body is JSON or form-encoded with the fields from (required, "Name" <address> or a bare address), fromName, subject, text, html, to and cc. Common provider spellings such as body-plain and HtmlBody are recognised as well.

  • A subject containing a ticket reference such as [INC-1042] or [SR-1042], sent by that ticket's requester or by an agent, is added to the ticket as a reply. Quoted history (“On … wrote:”, “-----Original Message-----”) is stripped.
  • Anything else opens a new ticket with source Email. Unknown senders become requesters, unless the workspace only accepts mail from people it knows. Mail sent to a group's address is routed to that group; agents on cc follow the ticket.
{
  "data": {
    "ticket": "INC-1042",
    "number": 1042,
    "action": "replied"
  }
}

action is created (status 201) or replied (200). Errors use the same shape as the REST API; a wrong or missing secret is a 401.

© 2026 Arvesk. Questions about the API? Write to support@arvesk.local.