Signups
AI

Draft a signup from a plain-language description

Returns a structured draft (title, time slots, items, reminder cadence) ready for review. Free-tier orgs are capped at 3 lifetime drafts across the in-app wizard and this endpoint combined; the cap returns 402 with an upgrade_required payload. The draft is not saved — pass it to POST /v1/signups to create the actual signup.

Upstream AI failures return 502 with a classified aiCode on the problem+json body so agents can branch on the cause. Possible values:

  • RATE_LIMITED — upstream provider rate limit (e.g. Vercel AI Gateway free credits). Retryable; honor the Retry-After header when present.
  • UPSTREAM_TIMEOUT — model call timed out. Retryable.
  • UPSTREAM_UNAVAILABLE — generic 5xx from the upstream provider. Retryable.
  • SCHEMA_INVALID — model returned output that did not conform to the draft schema. Not retryable — the same prompt will fail again; surface the error to the user.
  • CONTENT_FILTERED — request was blocked by the provider's content policy. Not retryable — surface to the user so they can edit the prompt.

The retryable boolean mirrors the table above for callers that don't want to encode the per-code policy themselves. When the upstream supplied a hint, retryAfterMs is included.

post/signups/from-description

Request

  • Base URL: https://thesignup.app/api/v1
  • URL: https://thesignup.app/api/v1/signups/from-description
  • Auth: HTTP bearer

Request body

descriptionstring required

Plain-language event description. Same prompt the in-app wizard accepts.

Example request

{
  "description": "Saturday potluck for my soccer team after practice, around 20 people. Need salads, sides, desserts, and drinks."
}

Response

Generated draft

Changes

No recorded changes to this operation across all 1 revision of this API.