RandNext Draws API

openapi: 3.2.0
info:
  title: RandNext Draws API
  version: 1.5.0
  description: 'Free random content and generator results from 48 RandNext tools, plus verifiable draw records. No API key needed; only draw management uses the draw''s manage token. Limits: 60 requests/minute and 1,000/day per IP. Free use requires a visible "Powered by RandNext" link to https://randnext.com, and the attribution field must be shown when present.'
servers:
- url: https://randnext.com
tags:
- name: Draws
paths:
  /api/v1/draws:
    get:
      summary: Recent public draws
      description: Drawn records whose organizers chose to list them, newest first, 24 per page. Scheduled, cancelled and removed draws never appear.
      parameters:
      - name: page
        in: query
        description: Page number, starting at 1 (max 1000).
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 1
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
              description: Unix time (seconds) when the window resets
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Draw'
                  page:
                    type: integer
                  page_size:
                    type: integer
                  total:
                    type: integer
        '400':
          description: Invalid parameter (INVALID_PARAMETER)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited (RATE_LIMITED)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              schema:
                type: integer
      tags:
      - Draws
      operationId: getApiV1Draws
      x-operation-id-source: derived
  /api/v1/draws/signing-keys:
    get:
      summary: Public keys that sign draw statements
      description: Ed25519 public keys (raw 32 bytes, hex) used to sign each draw's lock and result statements. key_id is the first 16 hex characters of SHA-256 over the raw key.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    type: array
                    items:
                      type: object
                      properties:
                        key_id:
                          type: string
                        algorithm:
                          type: string
                          enum:
                          - Ed25519
                        public_key:
                          type: string
      tags:
      - Draws
      operationId: getApiV1DrawsSigningKeys
      x-operation-id-source: derived
  /api/v1/draws/{id}:
    get:
      summary: A verifiable draw record
      description: Returns the commitment, entries hash and, once the draw time has passed, the revealed server seed, final seed and winners. Reading a draw whose time has passed reveals it. Recompute the result with the published algorithm at https://randnext.com/draws/how-it-works.
      parameters:
      - name: id
        in: path
        required: true
        description: Draw ID from the record URL, for example dr_7kq2m9x4tb1c (dr_ followed by 12 lowercase base32 characters).
        schema:
          type: string
          pattern: ^dr_[0-9a-hjkmnp-tv-z]{12}$
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
              description: Unix time (seconds) when the window resets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Draw'
        '404':
          description: No such draw (NOT_FOUND)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited (RATE_LIMITED)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              schema:
                type: integer
      tags:
      - Draws
      operationId: getApiV1DrawsById
      x-operation-id-source: derived
    patch:
      summary: Change a draw's settings (organizer)
      description: Requires the manage token returned when the draw was created. purge_entries deletes the stored entry list after the draw; the hashes and winners stay, so anyone with a copy of the list can still verify. Same-origin only.
      security:
      - manageToken: []
      parameters:
      - name: id
        in: path
        required: true
        description: Draw ID from the record URL, for example dr_7kq2m9x4tb1c (dr_ followed by 12 lowercase base32 characters).
        schema:
          type: string
          pattern: ^dr_[0-9a-hjkmnp-tv-z]{12}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DrawSettings'
      responses:
        '200':
          description: Updated record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Draw'
        '400':
          description: Invalid body (INVALID_PARAMETER)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or wrong manage token (UNAUTHORIZED)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such draw (NOT_FOUND)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Entries can be purged only after the draw, and removed draws cannot change (CONFLICT)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited (RATE_LIMITED)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              schema:
                type: integer
      tags:
      - Draws
      operationId: patchApiV1DrawsById
      x-operation-id-source: derived
  /api/v1/draws/{id}/entries:
    get:
      summary: A draw's entry list
      description: 'The exact UTF-8 bytes behind entries_hash: normalized entries joined by \n, no trailing newline. SHA-256 of the body equals entries_hash. Public lists are available to anyone from the moment the draw is locked; a hidden list only with the organizer''s manage token (never cached).'
      security:
      - {}
      - manageToken: []
      parameters:
      - name: id
        in: path
        required: true
        description: Draw ID from the record URL, for example dr_7kq2m9x4tb1c (dr_ followed by 12 lowercase base32 characters).
        schema:
          type: string
          pattern: ^dr_[0-9a-hjkmnp-tv-z]{12}$
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
              description: Unix time (seconds) when the window resets
            ETag:
              schema:
                type: string
              description: The quoted entries_hash
          content:
            text/plain:
              schema:
                type: string
        '304':
          description: Not modified (If-None-Match matched)
        '404':
          description: No such draw, or the list is hidden, purged or removed (NOT_FOUND)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited (RATE_LIMITED)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              schema:
                type: integer
      tags:
      - Draws
      operationId: getApiV1DrawsByIdEntries
      x-operation-id-source: derived
  /api/v1/draws/{id}/prizes/{tier}/start:
    post:
      summary: Start the next prize of a prize draw (organizer)
      description: Requires the manage token. Prizes start in order, once each, after the previous one is drawn. Starting fixes the first drand round at least 3 seconds away; the prize is revealed when that round is published. Same-origin only.
      security:
      - manageToken: []
      parameters:
      - name: id
        in: path
        required: true
        description: Draw ID from the record URL, for example dr_7kq2m9x4tb1c (dr_ followed by 12 lowercase base32 characters).
        schema:
          type: string
          pattern: ^dr_[0-9a-hjkmnp-tv-z]{12}$
      - name: tier
        in: path
        required: true
        description: Prize number, starting at 1, in the locked order.
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: Updated record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Draw'
        '401':
          description: Missing or wrong manage token (UNAUTHORIZED)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such prize draw (NOT_FOUND)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Out of order, already started, or the draw was cancelled (CONFLICT)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited (RATE_LIMITED)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              schema:
                type: integer
      tags:
      - Draws
      operationId: postApiV1DrawsByIdPrizesByTierStart
      x-operation-id-source: derived
  /api/v1/draws/{id}/cancel:
    post:
      summary: Cancel a scheduled draw (organizer)
      description: Requires the manage token. Only before the draw time; the record stays public with status cancelled, so a draw cannot be quietly discarded and re-run. After the draw time this reveals the result and answers 409. Same-origin only.
      security:
      - manageToken: []
      parameters:
      - name: id
        in: path
        required: true
        description: Draw ID from the record URL, for example dr_7kq2m9x4tb1c (dr_ followed by 12 lowercase base32 characters).
        schema:
          type: string
          pattern: ^dr_[0-9a-hjkmnp-tv-z]{12}$
      responses:
        '200':
          description: Cancelled record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Draw'
        '401':
          description: Missing or wrong manage token (UNAUTHORIZED)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such draw (NOT_FOUND)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The draw already happened or was cancelled (CONFLICT)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited (RATE_LIMITED)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              schema:
                type: integer
      tags:
      - Draws
      operationId: postApiV1DrawsByIdCancel
      x-operation-id-source: derived
components:
  schemas:
    Draw:
      type: object
      description: Fields needed to verify a draw are documented at https://randnext.com/draws/how-it-works.
      properties:
        id:
          type: string
          example: dr_7kq2m9x4tb1c
        seq:
          type: integer
          description: Public draw number.
        title:
          type:
          - string
          - 'null'
          description: null when removed by moderation.
        description:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - scheduled
          - drawn
          - cancelled
          - removed
        algorithm:
          type: string
          enum:
          - randnext-draw-v1
          - randnext-draw-v2
          - randnext-draw-v3
          example: randnext-draw-v2
        entry_count:
          type: integer
        winner_count:
          type: integer
        duplicates:
          type: string
          enum:
          - keep
          - merge
        entries_visibility:
          type: string
          enum:
          - hidden
          - public
        entries_hash:
          type: string
          description: SHA-256 (hex) of the normalized entry list.
        commitment:
          type: string
          description: SHA-256 (hex) of the server seed, published when the draw was locked.
        server_seed:
          type:
          - string
          - 'null'
          description: Revealed at the draw time; null before.
        params:
          type: string
          description: id, winners and entries, bound into the final seed.
        final_seed:
          type:
          - string
          - 'null'
        beacon:
          type:
          - object
          - 'null'
          description: 'randnext-draw-v2: the drand quicknet round fixed at lock time. randomness and signature (BLS, G1) appear after the reveal.'
          properties:
            chain_hash:
              type: string
            round:
              type: integer
            randomness:
              type:
              - string
              - 'null'
            signature:
              type:
              - string
              - 'null'
            url:
              type: string
              format: uri
        prizes:
          type:
          - array
          - 'null'
          description: 'randnext-draw-v3 prize draws: prize tiers in locked order, drawn live by the host one by one. Each tier has its own drand round; winners of earlier tiers are excluded. Null for single draws.'
          items:
            type: object
            properties:
              tier:
                type: integer
              name:
                type:
                - string
                - 'null'
              winner_count:
                type: integer
              status:
                type: string
                enum:
                - pending
                - drawing
                - drawn
              beacon:
                type:
                - object
                - 'null'
                properties:
                  chain_hash:
                    type: string
                  round:
                    type: integer
                  randomness:
                    type:
                    - string
                    - 'null'
                  signature:
                    type:
                    - string
                    - 'null'
                  url:
                    type: string
              started_at:
                type:
                - string
                - 'null'
                format: date-time
              drawn_at:
                type:
                - string
                - 'null'
                format: date-time
              params:
                type:
                - string
                - 'null'
              final_seed:
                type:
                - string
                - 'null'
              winners:
                type:
                - array
                - 'null'
                items:
                  type: object
                  properties:
                    rank:
                      type: integer
                    index:
                      type: integer
                    entry:
                      type:
                      - string
                      - 'null'
              signatures:
                type: object
                properties:
                  start:
                    type:
                    - string
                    - 'null'
                  result:
                    type:
                    - string
                    - 'null'
        signatures:
          type: object
          description: 'Ed25519 signatures (hex) over the lock and result statements; null on v1 records. Public key: /api/v1/draws/signing-keys.'
          properties:
            key_id:
              type:
              - string
              - 'null'
            lock:
              type:
              - string
              - 'null'
            result:
              type:
              - string
              - 'null'
        winners:
          type:
          - array
          - 'null'
          items:
            type: object
            properties:
              rank:
                type: integer
              index:
                type: integer
                description: 0-based position in the normalized entry list.
              entry:
                type:
                - string
                - 'null'
                description: null when removed by moderation.
        created_at:
          type: string
          format: date-time
          description: When the entry list was locked.
        draw_at:
          type: string
          format: date-time
        drawn_at:
          type:
          - string
          - 'null'
          format: date-time
        cancelled_at:
          type:
          - string
          - 'null'
          format: date-time
        pre_announced:
          type: boolean
          description: false when the draw happened less than 10 minutes after locking.
        listed:
          type: boolean
          description: Whether the organizer shows this record in the public list.
        entries_purged:
          type: boolean
        entries_url:
          type:
          - string
          - 'null'
          format: uri
        url:
          type: string
          format: uri
        verify_url:
          type: string
          format: uri
    DrawSettings:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        listed:
          type: boolean
          description: Show the record in the public list of draws.
        purge_entries:
          type: boolean
          enum:
          - true
          description: Delete the stored entry list (after the draw only).
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - INVALID_PARAMETER
              - UNAUTHORIZED
              - NOT_FOUND
              - CONFLICT
              - RATE_LIMITED
              - INTERNAL_ERROR
              - SERVICE_UNAVAILABLE
            message:
              type: string
  securitySchemes:
    manageToken:
      type: http
      scheme: bearer
      description: The manage token returned once when the draw was created.