API Versions & Routes

Helpdocs Admin Updated by Helpdocs Admin

Version history

Our API is currently on v4, which is what all new integrations should use. Earlier versions come from our previous product, DeskDirector:

Version

Status

Notes

v1

Retired

No longer available

v2

Legacy

From the DeskDirector era, PascalCase properties

v3

Legacy

From the DeskDirector era, camelCase properties

v4

Current — use this

Introduced with Tokity, later back-ported to some DeskDirector endpoints

A few naming notes:

  • v1 used PascalCase property names (e.g., TicketEntityId).
  • v2 onward switched to camelCase (e.g., ticketEntityId).
  • A small number of endpoints return snake_case properties — this is rare and not the standard.

v4's biggest strength is its flexible query model. Rather than a dedicated query language, v4 uses a JSON object to describe common filtering needs — we cover this in Querying the API.

Our versioning promise

Within a given version, we guarantee:

  • Property names won't change.
  • Response behavior stays consistent.
  • Property types never change, even if a property is removed.
  • Removing a property is rare; adding new properties is normal and expected.

In short: if your code deserializes a response today, it will keep working tomorrow.

We don't use headers to indicate API versions — the version is always part of the URL, not something you negotiate separately.

Swagger categories

Full endpoint definitions live in Swagger at https://<your-instance-host>/swagger, grouped into four categories:

Category

What it's for

Public v4

Our current public API — tenant-level access via API key

Legacy public API

The older v2 public API, kept for backward compatibility

Internal v1–v4

Originally built for our Admin Portal, TECH Portal, and Client Portal. Now also accessible via personal API keys and OAuth

Connector API

Used by our registered Power Automate connector (published in OpenAPI v2 format — a Microsoft requirement)

How routes are structured

Toki Iti has two distinct user types, stored in completely separate tables:

  • Agent — internal staff/technicians
  • Contact — end customers using the Client Portal

Because these user types are structurally distinct, their APIs are separated at the URL level:

Route prefix

Portal

User type

/v4/...

System-wide / tenant-wide

N/A — no per-user restrictions

/v4/tech/...

TECH Portal

Agent

/v4/tech/configs/...

Admin Portal

Agent (admin role)

/v4/portal/...

Client Portal

Contact

Examples:

  • /v4/accounts — system-wide, no restrictions
  • /v4/tech/accounts — TECH Portal, agent-level
  • /v4/tech/configs/accounts — Admin Portal, agent-level (admin)
  • /v4/portal/tickets — Client Portal, contact-level
Note: The TECH Portal and Admin Portal UIs have merged over time, so in practice they're often treated as one thing. Technically, Admin Portal routes are just TECH Portal routes gated by the admin role.

Data access by route type

  • System-wide APIs (/v4/...): no restrictions on queues, ticket categories, or accounts.
  • Agent APIs (/v4/tech/...): restricted by the agent's assigned queues, accounts, and ticket categories.
  • Contact APIs (/v4/portal/...): restricted by queue access and the contact's current account.

Where to go next

How did we do?

What is the Toki Iti API

Roles & Scopes

Contact