Developers
API reference
Every v1 endpoint with its scope, cost and parameters, plus recording interactions.
Prefer the machine-readable OpenAPI document for code generation; this page is generated from it.
Conventions
- Lists return
{ "data": [...], "nextCursor": "…" | null }. PassnextCursorback ascursoruntil it isnull. Page size islimit(1–500, default 100). - Single items return
{ "data": { … } }. - Team scope: API keys see every team. OAuth tokens see only the teams the approving person can see.
- Date-only values (
2026-10-07) mean that day in your organization’s time zone. - Trim responses with
fields=id,emailon list routes, and save bandwidth withIf-None-Match(answered304when nothing changed). - Cost: most calls cost 1 against your per-minute budget; heavier ones cost more (listed per endpoint below).
- Pagination, errors, rate limits, idempotency and versioning are on the conventions page.
Endpoints
GET /v1/me
Who is calling. The organization, the kind of credential, its scopes, its rate limits and (for API keys) its expiry and network restrictions. A good first call to test a key. Any valid credential.
GET /v1/changelog
API changelog. Releases of the API, newest first, with whether each is breaking. No credential needed. No credential needed.
GET /v1/openapi.json
This document. The OpenAPI 3.1 description of the API. No credential needed. No credential needed.
GET /v1/people
List people. Scope: people:read.
| Parameter | In | Description |
|---|---|---|
| q | query | Match name or email. |
| teamId | query | Only this team. |
| status | query | Employment status. |
| fields | query | Comma-separated properties to return for each item, e.g. `id,email`. Unknown names are ignored. |
| limit | query | Page size (1–500). |
| cursor | query | Opaque cursor from the previous page. |
GET /v1/people/{id}
Get a person. Scope: people:read.
| Parameter | In | Description |
|---|---|---|
| id * | path |
GET /v1/teams
List teams. Scope: people:read.
| Parameter | In | Description |
|---|---|---|
| fields | query | Comma-separated properties to return for each item, e.g. `id,email`. Unknown names are ignored. |
| limit | query | Page size (1–500). |
| cursor | query | Opaque cursor from the previous page. |
GET /v1/status
Live agent status. What every visible agent is doing right now. Scope: status:read.
| Parameter | In | Description |
|---|---|---|
| teamId | query | Only this team. |
| fields | query | Comma-separated properties to return for each item, e.g. `id,email`. Unknown names are ignored. |
| limit | query | Page size (1–500). |
| cursor | query | Opaque cursor from the previous page. |
GET /v1/schedules
List published schedules. Published schedules (one per team and period). Use `/v1/shifts` for the shifts inside them. Scope: schedules:read.
| Parameter | In | Description |
|---|---|---|
| teamId | query | Only this team. |
| from | query | Period ending on or after. Date (YYYY-MM-DD) or date-time. |
| to | query | Period starting on or before. Date (YYYY-MM-DD) or date-time. |
| fields | query | Comma-separated properties to return for each item, e.g. `id,email`. Unknown names are ignored. |
| limit | query | Page size (1–500). |
| cursor | query | Opaque cursor from the previous page. |
GET /v1/shifts
List shifts. Shifts that overlap the period (at most 31 days), with breaks and meals. Scope: schedules:read. Costs 2 calls.
| Parameter | In | Description |
|---|---|---|
| from * | query | Start of the period. Date (YYYY-MM-DD) or date-time. |
| to * | query | End of the period. Date (YYYY-MM-DD) or date-time. |
| teamId | query | Only this team. |
| employeeId | query | Only this person. |
| status | query | Shift status. |
| fields | query | Comma-separated properties to return for each item, e.g. `id,email`. Unknown names are ignored. |
| limit | query | Page size (1–500). |
| cursor | query | Opaque cursor from the previous page. |
GET /v1/exceptions
List exceptions. Scope: exceptions:read.
| Parameter | In | Description |
|---|---|---|
| status | query | Open = open, acknowledged or investigating. |
| teamId | query | Only this team. |
| from | query | Started on or after. Date (YYYY-MM-DD) or date-time. |
| fields | query | Comma-separated properties to return for each item, e.g. `id,email`. Unknown names are ignored. |
| limit | query | Page size (1–500). |
| cursor | query | Opaque cursor from the previous page. |
GET /v1/adherence/daily
Daily adherence per agent. Rolled-up daily figures (refreshed every few minutes). Scope: adherence:read. Costs 3 calls.
| Parameter | In | Description |
|---|---|---|
| from * | query | First day. Date (YYYY-MM-DD) or date-time. |
| to * | query | Last day. Date (YYYY-MM-DD) or date-time. |
| teamId | query | Only this team. |
| employeeId | query | Only this person. |
| fields | query | Comma-separated properties to return for each item, e.g. `id,email`. Unknown names are ignored. |
| limit | query | Page size (1–500). |
| cursor | query | Opaque cursor from the previous page. |
GET /v1/leave-requests
List leave requests. Scope: leave:read.
| Parameter | In | Description |
|---|---|---|
| status | query | Request status. |
| from | query | Leave ending on or after. Date (YYYY-MM-DD) or date-time. |
| to | query | Leave starting on or before. Date (YYYY-MM-DD) or date-time. |
| teamId | query | Only this team. |
| fields | query | Comma-separated properties to return for each item, e.g. `id,email`. Unknown names are ignored. |
| limit | query | Page size (1–500). |
| cursor | query | Opaque cursor from the previous page. |
GET /v1/interactions
List customer interactions. Tickets replied to, conversations handled and calls answered, from connected help desks or sent through this API. Scope: interactions:read. Costs 2 calls.
| Parameter | In | Description |
|---|---|---|
| from | query | Occurred on or after. Date (YYYY-MM-DD) or date-time. |
| to | query | Occurred before. Date (YYYY-MM-DD) or date-time. |
| employeeId | query | Only this agent. |
| source | query | Only this source, e.g. `zendesk`. |
| kind | query | Only this kind, e.g. `ticket_replied`. |
| teamId | query | Only this team. |
| fields | query | Comma-separated properties to return for each item, e.g. `id,email`. Unknown names are ignored. |
| limit | query | Page size (1–500). |
| cursor | query | Opaque cursor from the previous page. |
GET /v1/holidays
List holidays. The holiday calendar. Defaults to the current calendar year; at most 366 days at a time. Scope: holidays:read.
| Parameter | In | Description |
|---|---|---|
| from | query | First day. Date (YYYY-MM-DD) or date-time. |
| to | query | Last day. Date (YYYY-MM-DD) or date-time. |
| fields | query | Comma-separated properties to return for each item, e.g. `id,email`. Unknown names are ignored. |
| limit | query | Page size (1–500). |
| cursor | query | Opaque cursor from the previous page. |
GET /v1/forecast/queues
List forecast queues. Queues that have a forecast, with their channel and the number of agents whose primary queue it is. Scope: forecast:read. Needs the forecasting feature in your plan.
| Parameter | In | Description |
|---|---|---|
| fields | query | Comma-separated properties to return for each item, e.g. `id,email`. Unknown names are ignored. |
| limit | query | Page size (1–500). |
| cursor | query | Opaque cursor from the previous page. |
GET /v1/forecast/staffing
Staffing requirement for a queue and day. Forecast volume, agents required and agents scheduled for each interval of one day (organization time zone). Scope: forecast:read. Costs 5 calls. Needs the forecasting feature in your plan.
| Parameter | In | Description |
|---|---|---|
| queueId * | query | Queue id from `/v1/forecast/queues`. |
| date | query | The day (YYYY-MM-DD). Defaults to today. |
GET /v1/advisor/summary
Coverage and burnout summary. Coverage gaps and burnout-risk counts for the teams the credential can see. Contains no names of people. Scope: advisor:read. Costs 10 calls. Needs the advisor feature in your plan.
| Parameter | In | Description |
|---|---|---|
| teamId | query | Only this team. |
| days | query | Horizon in days. |
POST /v1/interactions
Record interactions. Up to 500 per request. Repeating an `externalId` for the same `source` and `kind` updates nothing and is reported as a duplicate, so retries are safe. Scope: interactions:write. Costs 5 calls. Accepts Idempotency-Key.
POST /mcp
Model Context Protocol endpoint. JSON-RPC 2.0 over Streamable HTTP for AI assistants. See the MCP guide for tools, resources and prompts. Tool calls are limited by the scopes of the credential. Any valid credential.
* required
Recording interactions
Send what agents handled in any system. Each item names the agent by work email or employee number, a source (your system, e.g. zendesk), a kind, your own externalId and when it happened. Repeating the same source + kind + externalId is reported as a duplicate, so retries are safe; add an Idempotency-Key header and a retry gets the original response back unchanged. Items for agents TINIUN doesn’t know are returned in rejected with the reason; the rest are still recorded.
curl https://tiniun.com/api/v1/interactions \
-H "Authorization: Bearer spk_…" -H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2a9e-ticket-4821-r3" \
-d '{ "interactions": [{
"agent": { "email": "[email protected]" },
"source": "helpdesk", "kind": "ticket_replied",
"externalId": "TCK-4821-r3",
"occurredAt": "2026-10-07T09:14:00+08:00",
"channel": "email", "reference": "https://helpdesk.example.com/tickets/4821"
}] }'{ "data": { "recorded": 1, "duplicates": 0, "rejected": [] } }Common kinds: ticket_replied (Ticket replied), ticket_solved (Ticket solved), conversation_replied (Conversation replied), conversation_closed (Conversation closed), call_answered (Call answered), chat_handled (Chat handled). Other kinds are accepted (2–60 characters); the Interactions page shows the common ones as columns.
See it with your own scenarios
A 30-minute walkthrough with our team, tailored to your operation.
Book a demo
