Developers

What it does

Five endpoints, one act each: pick winners from a list, split a list into balanced teams, publish a list as a shared wheel, run a draw with a published record, and read that record back to check it. Every successful answer carries a link to a page a person can open, so an assistant that used one can show its working.

Free, like the rest of it

There is no paid tier, no billing and no card. A key is free and comes with an account, and an account is an email address and a link — no password. Nothing here counts towards a bill; the limits below exist so that one caller cannot spend the day's capacity for everybody else.

Getting a key

Sign in on the account page and press the button. The key is shown once, because only a fingerprint of it is stored — copy it then. Send it in an Authorization: Bearer header. You can hold several keys, name them so you know which program has which, and revoke any of them whenever you like.

Account

Limits

Without a key: 60 calls a day from one address. With a key: 5000 calls a day for the account, however many keys it holds. Both windows reset at midnight UTC. Past the allowance the answer is 429, with a header saying how many seconds to wait.

Not a gambling tool

It never touches money. There are no tickets, no entry fees, no prizes and no odds anywhere in it, in any language, and none are coming — a picker that handled those would be a different product under a different licence. Use it to choose fairly from a list you already have.

The terms

The same terms cover the API as cover the pages, plus three things: it may not be used for gambling, for abuse, or to promote violence or self-harm; the limits can change without notice; and there is no service-level promise at all, so do not build anything critical on it.

Terms

Versions and change

The version is in the path. A change that would break a caller ships as a new version rather than as an edit to this one, and a retired version keeps answering for at least six months after its retirement is announced here. New fields can appear in a response at any time, so read them leniently.

The MCP server

An assistant that speaks the Model Context Protocol can do all of this without writing HTTP itself. The server answers at one address, one message per request, with no session to open or close, and it offers four tools: pick a winner, make teams, publish a wheel, and check a draw somebody else ran. It spends the same key and the same daily allowance as the endpoints do, so nothing about what you may do changes with the door you come in through. The tool names below are part of the protocol, so they are written in English.

POST /mcp

pick_winner
make_teams
create_wheel
verify_draw

Reference

Every endpoint, its fields and the answers it can give. The machine-readable description of the same thing is one file:

/openapi.json

curl -s https://namesome.com/api/v1/picks \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer nsk_…' \
  -d '{"entries":["Ana","Bilal","Chen"],"winners":1}'

{
  "winners": ["Bilal"],
  "url": "https://namesome.com/random-name-picker"
}

request body (application/json)
  entries        string[]        required  The list, in the caller's own order. Names are returned exactly as they are sent.
  winners        integer                   How many names to pick.
  weights        integer[]                 One weight per entry, in the same order. Omit for an even list.
  record         boolean                   Publish a verifiable record of this draw at /d/{id}.
  mask           boolean|object            `true` fingerprints the entries with the draw's own id; `{"salt": "…"}` fingerprints them with a salt you choose and publish. Either way the names never reach the database.

answers
  200   The winners, in the order they came out.
  400   `bad_request` — the body does not meet the contract.
  401   `bad_key` — a key was presented and it is not one that works.
  413   `too_many` or `too_big` — over the entry cap or the byte cap.
  429   `busy` — over the allowance. `Retry-After` says when, in seconds.
  503   `unsigned` — a record was asked for and this deployment cannot sign one.

request body (application/json)
  people         (string|object)[] required  A name, or an object. `skill` 1–5 is what `balance` spreads across the teams.
  teams          integer                   How many teams. Use this or `size`.
  size           integer                   How many people per team. Use this or `teams`.
  rules          object[]                  Pairs to keep together or apart, named by the names in `people`. A rule about somebody who is not on the list is ignored.
  balance        boolean                   Spread the higher `skill` levels across teams.
  captains       boolean                   Name one captain per team.

answers
  200   The teams.
  400   `bad_request` — the body does not meet the contract.
  401   `bad_key` — a key was presented and it is not one that works.
  409   `unsatisfiable` — the rules cannot all hold at once. `rules` names the smallest set that clash.
  413   `too_many` or `too_big` — over the entry cap or the byte cap.
  429   `busy` — over the allowance. `Retry-After` says when, in seconds.

request body (application/json)
  entries        string[]        required  The list, in the caller's own order. Names are returned exactly as they are sent.
  weights        integer[]                 One weight per entry, in the same order. Omit for an even list.
  tool           string                    Which tool the link opens in.

answers
  200   The published wheel.
  400   `bad_request` — the body does not meet the contract.
  400   `blocked` — the word screen refused an entry, or one was a URL.
  401   `bad_key` — a key was presented and it is not one that works.
  413   `too_many` or `too_big` — over the entry cap or the byte cap.
  429   `busy` — over the allowance. `Retry-After` says when, in seconds.

request body (application/json)
  entries        string[]                  The list, in the caller's own order. Names are returned exactly as they are sent.
  masked_hashes  string[]                  Fingerprints you made yourself. Requires `mask` with a salt.
  params         object          required  
  mask           boolean|object            `true` fingerprints the entries with the draw's own id; `{"salt": "…"}` fingerprints them with a salt you choose and publish. Either way the names never reach the database.
  commit         boolean                   Seal the draw: publish the commitment now, the result when you reveal it.

answers
  200   The record, and the creator's own capability over it.
  400   `bad_request` — the body does not meet the contract.
  400   `blocked` — the word screen refused an entry or the salt.
  401   `bad_key` — a key was presented and it is not one that works.
  413   `too_many` or `too_big` — over the entry cap or the byte cap.
  429   `busy` — over the allowance. `Retry-After` says when, in seconds.
  503   `unsigned` — this deployment has no signing key, so it will not mint a record it cannot sign.

path parameter
  id             string          required  The record's id — the last segment of its /d/{id} page.

answers
  200   The record.
  401   `bad_key` — a key was presented and it is not one that works.
  410   `gone` — no such record, or it has reached its twelve months.
  429   `busy` — over the allowance. `Retry-After` says when, in seconds.