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.

OpenAPI specification

Every /v1 resource, both ways of authenticating, the error envelope, and the eight webhook events are described in one OpenAPI 3.1 file:

https://api.42min.us/openapi.yaml

Feed it to a client generator, import it into Postman, or hand it to a coding agent. The same file is versioned in the public 42min-developers repository on GitHub, next to a working webhook receiver example you can copy.

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, which 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, so 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: the four booking writes (POST /v1/bookings, cancel, reschedule, and PATCH) require an Idempotency-Key and replay the first result on a retry. Webhook writes don't take the header, so a retried POST /v1/webhooks creates a second subscription. 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.

Without writing code

If you would rather wire 42min to other tools than call the API yourself, there is an n8n community node that covers the same endpoints, plus triggers for every webhook event. It runs inside your own n8n, so booking data goes straight from 42min to your server.