> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ontime.hosai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> What is in this reference: the supported Public API v1, and the internal platform routes documented for completeness.

This reference is generated directly from OnTime's OpenAPI specification, so it always matches what the server actually implements.

## Two surfaces, different promises

<Warning>
  **Only `/api/public/v1/*` is a supported integration surface.** Everything else in this reference is documented for completeness and may change without notice.
</Warning>

<CardGroup cols={2}>
  <Card title="Public API v1" icon="check">
    `/api/public/v1/*` — API-key authenticated, versioned, and the surface to build against.

    Tagged **Public API** in the sidebar.
  </Card>

  <Card title="Platform API" icon="triangle-alert">
    Everything else under `/api/*` — session-cookie authenticated. These are the routes the OnTime web and mobile apps call.

    Listed here so you can understand the system, **not** as an integration contract.
  </Card>
</CardGroup>

## Why the platform routes are here at all

Two reasons. They document what OnTime can do, which is useful when deciding whether a feature you need exists. And when you are debugging an OnTime app in your browser's network tab, the route you are looking at is in this reference.

<Warning>
  **Do not build integrations against the platform routes.** They authenticate with a session cookie, which would mean storing a user's password; any administrator can revoke that session out from under you; and the routes are not versioned. When one changes, nothing warns you.
</Warning>

## Base URL

```text theme={null}
https://app.ontime.hosai.app
```

## Authentication

Public API endpoints take an API key as a bearer token. See [Authentication](/api-reference/authentication) for how to obtain one and use the playground.

## Versioning and stability

|                        | Public API v1                               | Platform API    |
| ---------------------- | ------------------------------------------- | --------------- |
| **Versioned**          | Yes, in the path.                           | No.             |
| **Breaking changes**   | A new version path.                         | Without notice. |
| **Additive changes**   | New optional fields may appear within `v1`. | Any time.       |
| **Deprecation notice** | Announced in the changelog.                 | None.           |

<Note>
  Within `v1`, be tolerant of new fields appearing in responses. Do not write parsers that fail on unrecognised keys.
</Note>

## What is not in this reference

<AccordionGroup>
  <Accordion title="The MCP server" icon="bot">
    `POST /api/mcp` speaks JSON-RPC, not REST, so it is not described by OpenAPI. It has its own documentation in the **AI & MCP** tab, including the full tool catalog.
  </Accordion>

  <Accordion title="Platform administration" icon="shield-off">
    Vendor-internal routes for provisioning organizations are deliberately excluded. They are not callable by any customer credential.
  </Accordion>

  <Accordion title="OAuth discovery documents" icon="key">
    The RFC 8414 and RFC 9728 documents live at `/.well-known/*`, outside `/api`. See the **AI & MCP** tab.
  </Accordion>
</AccordionGroup>

## Rate limits

600 requests per minute, per key, on the public API. Exceeding it returns `429` with `{"error": "too_many_requests"}`.

## Errors

The error envelope, every status code and every error code are documented in [Errors](/developers/errors).