API reference

The thesignup REST API is OpenAPI 3.1, Bearer-authenticated via long-lived API keys, rate-limited per credential, and idempotency-keyed for safe retries. Errors follow RFC 7807 problem details with stable machine-readable code enums.

The full operation list is in the sidebar.

Get started

Base URL

https://thesignup.app/api/v1

The version is in the URL prefix, not in path segments — GET /api/v1/signups, not /api/v1/v1/signups.

Authentication

Every request needs a Bearer token. Use a long-lived API key for first-party scripts; use OAuth for third-party apps acting on behalf of a user.

Authorization: Bearer sgn_live_abcd_xxxxxxxxxxxxxxxx

See API keys and OAuth for setup.

Idempotency

Send Idempotency-Key: <opaque-string> on POST / PATCH requests. Same key + same body within 24h replays the original response (including the original status code and headers). Same key + different body returns 422 with code: idempotency_key_reuse.

POST /api/v1/signups
Authorization: Bearer sgn_live_…
Idempotency-Key: 9d8a1f64-3c2a-4f6b-9c89-7c5d1a2b8e90
Content-Type: application/json

{ "title": "Spring potluck", "eventDate": "2026-04-12T17:00:00Z" }

UUID v4 per logical operation is the recommended shape.

Rate limits

Every response carries:

On 429, a Retry-After header is included.

A separate per-org daily ceiling caps POST /signups at 50 per day across all credentials. Hitting it returns 429 with code: daily_ceiling_exceeded.

Errors

All errors are application/problem+json:

{
  "type": "https://thesignup.app/problems/not-found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "Signup sg_123 doesn't exist."
}

Switch on code, not title or detail — those are for humans and may change. The full code enum is documented on the ProblemDetails schema.

Common codes