Help / API

API overview

The 42min Public REST API lets you read and write the same data you see in the dashboard — event types, availability, slots, and bookings — from your own systems. It is JSON over HTTPS, versioned at /v1, authenticated with either a personal access token or an OAuth 2.1 access token.

Base URL

https://api.42min.us

All paths in this reference are relative to that origin. Every request must use HTTPS — plain http:// is refused at the edge.

Versioning

The current major version is v1. It appears in every resource path:

GET https://api.42min.us/v1/me

Within a major version, additive changes (new fields, new endpoints, new optional parameters) are made without bumping the version. Breaking changes ship as a new major version. Discovery endpoints are unversioned and live under /.well-known/.

Response envelope

Every successful JSON response is wrapped in a small envelope:

{
  "data": { /* the resource, or a list */ },
  "meta": {
    "request_id": "req_…",
    "next_cursor": "…",
    "has_more": false
  }
}

• data is the resource for single-resource responses, or an array for list endpoints.
• meta.request_id is unique per request and is the value to quote when reporting an issue.
• meta.next_cursor and meta.has_more appear only on paginated list endpoints.

A handful of OAuth and discovery endpoints (the /v1/oauth/* family and /.well-known/*) return the spec-defined raw bodies — those are not wrapped.

Errors

Errors share one shape — see Error envelope:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This action requires the 'bookings:create' scope",
    "details": { "required_scope": "bookings:create" },
    "request_id": "req_…"
  }
}

Pagination

List endpoints (/v1/event-types, /v1/bookings) use cursor pagination. Pass limit (default 20, max 100) and follow meta.next_cursor until meta.has_more is false. Cursors are opaque base64url strings — don't parse them.

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.42min.us/v1/bookings?limit=50&cursor=eyJpZCI6Ii4uLiJ9"

Identifiers

• Event types can be addressed by UUID or by username/event-slug (the same path segments as the public booking page).
• Bookings are always addressed by their UUID (uid).
• All timestamps are ISO 8601 with offset — typically UTC (…Z).
• All durations are integers in minutes.

What's in scope

Webhooks have two sides: managing subscriptions over the API (/v1/webhooks) and receiving the signed callbacks (verification, retries, auto-pause — see API & webhooks).

Conventions

• Authentication — bearer tokens in the Authorization header. See Authentication.
• Scopes — every endpoint declares a required scope; see Scopes.
• Rate limits — 120 rpm authenticated, 30 rpm anonymous; see Rate limits.
• Idempotency — every write requires an Idempotency-Key; see Idempotency.
• Optimistic locking — PATCH requires a matching ETag via If-Match; see Optimistic locking.

Where to mint credentials

• Personal access tokens are minted in Admin Center → API on the API keys tab.
• OAuth clients are registered on the OAuth apps tab of the same page.