---
title: "Create a draw"
method: POST
path: "/v1/draws"
tags: ["Draws"]
---

# Create a draw

`POST /v1/draws`

Creates a draw in state `open`. If `callback_url` is set, the response
includes `callback_secret` (HMAC key for webhook signatures) — this is
the **only** time it is returned.

## Request body

- DrawCreate
  - `name` string, required
  - `description` string, nullable
  - `direction` 'winner' | 'loser'
  - `winner_count` integer — Multi-winner draws are enterprise-only in v1.
  - `drand_chain` 'quicknet' | 'classic'
  - `callback_url` string, nullable — Webhook target for draw.sealed / draw.resolved / draw.cancelled events.
  - `metadata` object, nullable — Opaque

## Response `201`

Draw created.

- DrawResponse
  - `success` boolean
  - `message` string
  - `data` object
    - `draw` Draw
      - `id` string
      - `name` string
      - `description` string, nullable
      - `state` 'open' | 'sealed' | 'resolved' | 'cancelled'
      - `direction` 'winner' | 'loser'
      - `winner_count` integer
      - `entry_count` integer
      - `drand_chain` 'quicknet' | 'classic'
      - `drand_round` integer, nullable
      - `drand_round_time` string, date-time, nullable
      - `list_hash` string, nullable — SHA-256 over the sealed list bytes.
      - `list_url` string, nullable
      - `verify_url` string, nullable — Public per-draw verification page.
      - `winner_row` integer, nullable — 0-based index into the sealed list.
      - `winner_ticket` string, nullable
      - `callback_url` string, nullable
      - `callback_secret` string, nullable — Returned only on the creating response. HMAC key for webhook signatures.
      - `public_commit_url` string, nullable
      - `sealed_at` string, date-time, nullable
      - `resolved_at` string, date-time, nullable
      - `created_at` string, date-time
      - `ots_proof_url` string, nullable
      - `ots_calendar_url` string, nullable
      - `ots_attested_at` string, date-time, nullable

## Other responses

- `401` — Missing or invalid API key (`unauthenticated`).
- `403` — Plan draw cap reached (`tier_limit_exceeded`).
- `422` — Invalid payload (`validation_failed` / `entry_limit_exceeded`).

---

[API](https://skmtc.net/proofdraw/apis/proofdraw-api.md) · [All operations](https://skmtc.net/proofdraw/apis/proofdraw-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/proofdraw/proofdraw-api/revisions/5d4ce7cb355d/schema)