42min developers

42min developers

Public packaging and contracts for 42min, a meeting schedulingplatform. This repository holds what you need to build on 42min or connect an AI agent toit. The product itself is closed source.

What is here

plugins/42min

The 42min plugin for Cursor. Connects the editor's agent to your 42min account over OAuthand exposes 43 scheduling tools. See its README.

Any MCP client can connect without this plugin, by pointing athttps://api.42min.us/mcp. The server publishes OAuth protected-resource metadata, so acompliant client discovers everything else on its own.

openapi/42min.v1.yaml

The OpenAPI 3.1 description of the public REST API, for generating clients, importing intoPostman or Bruno, and feeding to a coding agent.

It is hand-written, and checked against the running API by a contract test suite thatexercises every documented endpoint and validates the live response, headers and errorbodies against these schemas. That is how the first draft's seven mistakes were found,including two that would have broken every generated client on every booking write. Aroute-coverage check fails the build if an endpoint exists but is undocumented, or thereverse.

Those checks run in our private repository, because they boot the API against a realdatabase and cannot run here. What CI in this repository enforces is that the file is avalid OpenAPI 3.1 document, so a malformed spec never reaches you.

If you find a place where this file and the API disagree, the file is probably wrong:please open an issue.

server.json

The official MCP Registry entry.Declares this as a remote server on streamable HTTP at https://api.42min.us/mcp, soregistry-backed directories can list it without anyone hand-filling a form.

mcp/tools.json

The MCP contract, as a machine-readable snapshot: every tool with its JSON Schema forarguments, the scopes it needs, whether it writes, and the annotations a client uses todecide when to ask you before calling. Generated from the running tool registry, nothand-maintained, and gated by a test that fails when the two disagree.

Read it if you are building a client, or feed it to a coding agent. The table in theplugin README is the human summary of the same thing.

examples/webhook-receiver

A working receiver in about 120 lines with no dependencies, and ten tests forverify.js alone. Signature verification is where integrations break: the usual cause isverifying a re-serialized body rather than the raw bytes, which no amount of reading thedocs makes obvious. Copy verify.js and move on.

Built on this API

• n8n community node (n8n-nodes-42min).Bookings, event types, slots and the current user, plus a trigger for every webhookevent with signature verification built in. Runs inside your own n8n, so booking datagoes from 42min to your server and nowhere else.

Authentication in one paragraph

Two mechanisms. OAuth 2.1 with PKCE for applications acting on behalf of a user,including Dynamic Client Registration, so a client can register itself without a supportticket. Personal access tokens for scripts acting as one person. Both carry scopes;the API refuses anything a token's scopes do not cover. Discovery documents live at/.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource.

Full detail: Authentication.

Things worth knowing before you build

• Mutating booking calls accept Idempotency-Key. Retry with the same key. A new keycreates a second booking.
• PATCH /v1/bookings/{uid} uses ETags. Read the ETag, send it back as If-Match, anda concurrent edit fails loudly instead of silently overwriting.
• There is no test environment yet. Write operations act on production: they sendreal email and create real calendar events. Test on event types you own, and clean upafter yourself. (Our help pages use "sandbox" for something else, the per-credentialisolation of webhook subscriptions.)
• Ignore unknown response fields. We add fields without notice; seeCHANGELOG.md for the full versioning policy and the six-monthdeprecation guarantee.

Support

Open an issue for API bugs,specification errors, or plugin problems. Security reports go to [email protected], not to theissue tracker: see SECURITY.md.

License

MIT. See LICENSE.