CurlTi.me/Learn/The club API

The club API

A small, deliberately limited API for a club's own software — a website, a spreadsheet, a bot. Read the club, the roster and the standings; add members; post announcements. It can never touch officers, keys or the presidency.

Last updated 2026-08-16

What this is for#

A club that already has software — a website that lists members, a spreadsheet somebody maintains, a bot in a chat room — should not have to keep two things in step by hand. The v1 API exists so the club's own systems can read from and write to its CurlTi.me page directly.

It is small on purpose. Seven routes, one authentication scheme, one error shape.

Getting a key#

The club president mints keys, in the API tab of the club's management screen. Vice-presidents cannot; this is one of the four things the presidency reserves.

The secret is shown exactly once. The server keeps only its SHA-256, the way it would a password, so there is no route by which anybody — including us — can show it to you again. Copy it at that moment or mint another one.

Authorization: Bearer ck_...

What a key can and cannot do#

A key acts on its own club only, and carries at most the content powers a vice-president has.

The shape of that table is the security model. A leaked key can vandalise things the president can repair — a bad announcement, a removed member — and it can never take the club or lock anyone out. Revoking it is one click.

The endpoints#

The {slug} in the path must be the club the key belongs to. Asking about somebody else's club with your key is a 404, not a 403 — a key cannot be used to discover which clubs exist.

A first request#

curl -H "Authorization: Bearer ck_..." \
  https://curlti.me/api/v1/clubs/your-club/members

curl -X POST https://curlti.me/api/v1/clubs/your-club/announcements \
  -H "Authorization: Bearer ck_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Tuesday league draw","body":"Sheets 1 and 3, 7pm."}'

Rate limits and errors#

Sixty requests per minute per key. Over that you get 429 with a Retry-After header saying how long to wait. Announcements carry a second, tighter limit per club, because an announcement is something members are emailed about.

Every error uses the same envelope, whatever went wrong:

{ "error": "rate limit exceeded: 60 requests per minute per key" }

Webhooks: the same conversation, outbound#

Where the API lets your software ask, webhooks let the club tell it. The president registers hooks beside the keys, in the same API tab. They ride the session rather than the keyed surface, deliberately — registering a hook is administration, not content.

The three events#

The envelope#

Every delivery is JSON in one shape:

{
  "event": "announcement.published",
  "at": "2026-08-16T19:04:11.000Z",
  "club": { "slug": "your-club", "name": "Your Club" },
  "data": { ... }
}

and carries two headers:

• X-Curltime-Event — the event name, so you can route without parsing.
• X-Curltime-Signature — the hex HMAC-SHA256 of the raw request body under the hook's whsec_... secret, which is shown once at creation.

import { createHmac, timingSafeEqual } from 'node:crypto'

function verify(rawBody, header, secret) {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex')
  const a = Buffer.from(expected, 'utf8')
  const b = Buffer.from(header ?? '', 'utf8')
  return a.length === b.length && timingSafeEqual(a, b)
}

Delivery behaviour#

• Success is any 2xx within ten seconds.
• A failure retries at +1 and +5 minutes, then gives up after three attempts.
• Eight consecutive give-ups disable the hook. Editing it re-enables it.
• The management screen shows each hook's recent deliveries and a Test button that sends a test event and reports what happened.

A webhook can never delay or fail the join, announcement or attempt that fired it. That is the same rule the analytics live under: nothing about telling somebody what happened may stop the thing from happening.

Things you may want that are not in v1#

A few useful URLs live outside the keyed API because they are public by nature:

• GET /api/clubs — the public club directory.
• GET /api/clubs/{slug}/events.ics — the club's events as an RFC 5545 calendar feed, for subscribing rather than for scraping.
• /llms.txt — a plain-text summary of the site and the facts most often got wrong about it.
• /sitemap.xml — every indexable page.

Match pages at /m/<id> are not part of any API and are not listed anywhere. The ids are unguessable, and a match means nothing to anybody who is not playing it.

What "v1" promises#

The version is in the path so that a change which would break a client gets a new path rather than a quiet redefinition. Fields may be added to responses without notice, so parse leniently and ignore what you do not recognise.

The OpenAPI document is hand-written rather than generated, which is a deliberate choice: it changes when the routes change, in the same commit, and the difference between the two is something a person reviews.

Read the OpenAPI document Running a club