Developer overview

OnTime exposes three ways to work with it programmatically.

Public REST API

Key-authenticated, read-only. Pull employees and attendance into your own systems.

Webhooks

Outbound, HMAC-signed. OnTime posts to you when something happens.

MCP server

Lets an AI agent operate OnTime as a specific employee. See the AI & MCP tab.

Base URL

https://app.ontime.hosai.app

Two API surfaces, one host

Only /api/public/v1/* is a supported integration surface.The rest of /api/* is what the OnTime web and mobile apps call. It is documented in the API Reference for completeness, it authenticates with a session cookie rather than an API key, and it may change without notice. Build against /api/public/v1/*.

Surface	Auth	Stability
`/api/public/v1/*`	API key	Versioned. Additive changes only within `v1`.
Everything else under `/api/*`	Session cookie	Internal. Subject to change without notice.

Your first request

Issue a key

In the admin console, API & webhooks → Issue key. You need the api:manage permission.

The key is displayed once. OnTime stores only a hash — there is no way to retrieve it later.

Call the API

curl https://app.ontime.hosai.app/api/public/v1/employees \
  -H "Authorization: Bearer ont_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8"

const res = await fetch(
  "https://app.ontime.hosai.app/api/public/v1/employees",
  { headers: { Authorization: `Bearer ${process.env.ONTIME_API_KEY}` } },
);
if (!res.ok) throw new Error(`OnTime ${res.status}: ${await res.text()}`);
const { meta, data } = await res.json();
console.log(`${meta.count} employees`);

import os, requests

res = requests.get(
    "https://app.ontime.hosai.app/api/public/v1/employees",
    headers={"Authorization": f"Bearer {os.environ['ONTIME_API_KEY']}"},
    timeout=30,
)
res.raise_for_status()
body = res.json()
print(body["meta"]["count"], "employees")

Read the response

Every public endpoint returns the same envelope: a meta object and a data array.

{
  "meta": { "count": 2 },
  "data": [
    {
      "id": "3f1c9b2a-5d84-4e7a-9c11-2b6f8d0a4e73",
      "code": "EMP-0421",
      "name": "Rhea Varma",
      "email": "rhea.varma@example.com",
      "department": "Operations",
      "status": "Active"
    },
    {
      "id": "8a2e4d61-7c93-4b05-8f2d-1e5c9a3b7d40",
      "code": "EMP-0518",
      "name": "Arjun Nair",
      "email": "arjun.nair@example.com",
      "department": "Sales",
      "status": "Probation"
    }
  ]
}

So you find out when something happens rather than polling for it. API & webhooks → Register webhook, then verify the signature — see Webhooks.

What the public API covers

Two endpoints:

Endpoint	Returns
`GET /api/public/v1/employees`	The organization’s employee directory.
`GET /api/public/v1/attendance?date=YYYY-MM-DD`	Every employee’s day record for one date.

The public API is read-only. There are no write endpoints. A key issued with the ReadWrite scope currently grants exactly the same access as ReadOnly — see Authentication.If you need to write, use the MCP server (which does support writes, under the bound employee’s permissions) or the admin console.

Rate limit

600 requests per minute, per key. Exceeding it returns 429 with {"error": "too_many_requests"}.

Counters are held in process memory, so a backend restart resets them. Treat 600 as the intended budget rather than a hard guarantee, and back off on 429 regardless.

Where to go next

Authentication

Keys, scopes, headers and secret handling.

Errors

The error envelope and what each status means.

Webhooks

Registering, verifying signatures, retries and replay.

Guides

Worked end-to-end integrations.

Getting Started

Concepts

Webhooks

Guides

Developer overview

Public REST API

Webhooks

MCP server

Base URL

Two API surfaces, one host

Your first request

What the public API covers

Rate limit

Where to go next

Authentication

Errors

Webhooks

Guides

Public REST API

Webhooks

MCP server

​Base URL

​Two API surfaces, one host

​Your first request

​What the public API covers

​Rate limit

​Where to go next

Authentication

Errors

Webhooks

Guides

Base URL

Two API surfaces, one host

Your first request

What the public API covers

Rate limit

Where to go next