Skip to content
Documentation
Advanced use
REST API

REST API

Integrate your own systems with mTime through its REST API.

Overview

Everything a customer integration may call is described in the API reference — the complete, always-current list of endpoints, request and response shapes, and a changelog of breaking changes. The same document is available in machine-readable form at /api/openapi.yaml (OpenAPI 3.1).

The API is served under /api on the same host as the application, for example https://mtime.app/api.

Authentication

API access always goes through a service user — a non-person user that represents one integration — and its API keys. Creating both is described in Users & permissions.

Send the key as a bearer token on every request:

Authorization: Bearer mtime_ak_...
An API key is shown only once, when it is created. Keys expire on the date set at creation and can be revoked at any time.

API versions

The API is versioned by date. Your integration carries one compatibility date — the day it was written against the API — and every endpoint answers with the shape it had on that day, even if the endpoint has changed since. New endpoints and other compatible additions reach you regardless of your date.

  • When a service user is created, its compatibility date is set to that day, so future breaking changes never surprise the integration.
  • The date actually used is echoed back on every response in the X-Mtime-Api-Version header. You can also send that header on a request to override the stored date for one call.
  • An administrator can move the stored date forward — for the whole service user, or for a single API key — under Admin › Users. Do this deliberately, after updating the integration against the changelog.

Breaking changes and deprecation

Only backwards-incompatible changes create a new version, and each one is documented — what changed and why — in the Breaking changes section of the API reference.

When a shape is replaced, the old one keeps serving callers pinned before the change for at least 18 months. Once its removal is scheduled, responses served from it carry Deprecation and Sunset headers, and mTime warns administrators under Admin › Users which service users and API keys are still pinned to the retiring version.

Data importExcel import