---
title: "Draft a signup from a plain-language description"
method: POST
path: "/signups/from-description"
tags: ["Signups", "AI"]
---

# Draft a signup from a plain-language description

`POST /signups/from-description`

## Request

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

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.

## Request body

- FromDescriptionRequest
  - `description` string, required: Plain-language event description. Same prompt the in-app wizard accepts.

## Response `200`

Generated draft

- FromDescriptionResponse
  - `draft` SignupDraft, required
    - `title` string, required
    - `description` string, required
    - `category` 'potluck' | 'snack-rotation' | 'volunteer-shift' | 'carpool' | 'classroom-party' | 'other', required
    - `location` string, nullable, required: Physical or virtual location if the user named one; otherwise null.
    - `suggestedDate` string, nullable, required: ISO 8601 date (YYYY-MM-DD) if a date was named or implied; otherwise null. For multi-day events, the first day.
    - `endDate` string, nullable, required: ISO 8601 date (YYYY-MM-DD) of the last day of a multi-day event (inclusive); null for single-day events.
    - `startTime` string, nullable: The event's own wall-clock start, 24-hour HH:MM, for events without per-slot shifts. Null or omitted when the times live on timeSlots or none was given.
    - `endTime` string, nullable: The event's own wall-clock end, 24-hour HH:MM, paired with startTime. Null or omitted when unknown or when the event uses timeSlots.
    - `timezone` string, nullable, required: IANA timezone name (e.g. "America/Los_Angeles") when it could be inferred; otherwise null.
    - `timeSlots` object[], required
      - `label` string, required
      - `description` string: Per-slot description shown to participants, when slot-specific instructions were given.
      - `startTime` string, required: 24-hour HH:MM
      - `endTime` string, required
      - `capacity` integer, required
    - `itemList` object[], required
      - `name` string, required
      - `quantityNeeded` integer, required
      - `notes` string
    - `reminderCadence` 'none' | 'day-before' | 'week-and-day-before', required
    - `estimatedParticipants` integer, nullable, required

## Other responses

- `400`: Bad request — body or path could not be parsed
- `401`: Unauthenticated — credentials missing, malformed, invalid, or revoked
- `402`: Upgrade required — feature is gated by a higher billing tier
- `422`: Validation failed — request body / query / path is structurally wrong
- `429`: Rate limited or daily ceiling exceeded
- `500`: Internal server error
- `502`: Upstream unavailable — a third-party dependency (e.g. AI provider) failed

---

[API](https://skmtc.dev/thesignup/apis/thesignup-api.md) · [All operations](https://skmtc.dev/thesignup/apis/thesignup-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thesignup/apis/thesignup-api/revisions/c6da7cf92172?raw)