Giveaway comment picker API

Paste the comments from your giveaway post or upload a CSV, then draw winners and alternates in your browser. Publish a fingerprint when you announce the giveaway and the seed after the draw, so anyone can re-run it and check.

• Endpoint: POST https://postboost.co/app/api/tools/giveaway-comment-picker (operationId pickGiveawayWinners)
• Web tool: postboost.co/tools/giveaway-comment-picker
• Token: optional (limits)
• MCP: tool pick-giveaway-winners on https://postboost.co/mcp/tools

Request

Field	Type	Default	Description
entrants	array of object		The comments, one item each. The request body is capped at 128 KB.
seed	string		The secret seed, 64 hex characters (32 bytes), whose fingerprint you published before the entries closed. Without it, a seed is generated and pre_committed is false. The steps of the draw (pb-draw-v1) and a test vector are on the web tool page.
one_per_person	boolean	true	Count each username once. Off: every comment is an entry, so one person can win more than once.
keywords	array of string	[]	Keep only comments that contain at least one of these, case-insensitive.
min_mentions	integer	0	Keep only comments that tag at least this many other @handles.
exclude	array of string	[]	Usernames to leave out of the draw, such as the host account.
winners	integer	1
alternates	integer	0	Runners-up drawn after the winners, in order.

Call it

curl

curl -X POST https://postboost.co/app/api/tools/giveaway-comment-picker \
  -H 'Content-Type: application/json' \
  -d '{"entrants":[{"username":"@Bob","comment":"c"},{"username":"alice","comment":"x"},{"username":"bob","comment":"again"},{"username":"carol"}],"seed":"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f","winners":2,"alternates":1}'

Python

from postboost import ApiClient, Configuration
from postboost.api.free_tools_api import FreeToolsApi
from postboost.models import FreeToolPickGiveawayWinnersRequest

with ApiClient(Configuration()) as client:
    api = FreeToolsApi(client)
    result = api.pick_giveaway_winners(FreeToolPickGiveawayWinnersRequest.from_dict({"entrants": [{"username": "@Bob", "comment": "c"}, {"username": "alice", "comment": "x"}, {"username": "bob", "comment": "again"}, {"username": "carol"}], "seed": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f", "winners": 2, "alternates": 1}))
    print(result.to_dict())

Node.js

import { FreeToolsApi } from 'postboost';

const api = new FreeToolsApi();
const { body } = await api.pickGiveawayWinners({ entrants: [{ username: "@Bob", comment: "c" }, { username: "alice", comment: "x" }, { username: "bob", comment: "again" }, { username: "carol" }], seed: "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f", winners: 2, alternates: 1 });
console.log(body);

PHP

use PostBoostClient\Api\FreeToolsApi;
use PostBoostClient\Model\FreeToolPickGiveawayWinnersRequest;

$api = new FreeToolsApi(new GuzzleHttp\Client());
$result = $api->pickGiveawayWinners(new FreeToolPickGiveawayWinnersRequest(['entrants' => [['username' => "@Bob", 'comment' => "c"], ['username' => "alice", 'comment' => "x"], ['username' => "bob", 'comment' => "again"], ['username' => "carol"]], 'seed' => "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f", 'winners' => 2, 'alternates' => 1]));
echo $result;

Go

import (
    "context"
    "encoding/json"
    "fmt"

    postboost "github.com/postboost-co/postboost-go"
)

var request postboost.FreeToolPickGiveawayWinnersRequest
if err := json.Unmarshal([]byte(`{"entrants":[{"username":"@Bob","comment":"c"},{"username":"alice","comment":"x"},{"username":"bob","comment":"again"},{"username":"carol"}],"seed":"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f","winners":2,"alternates":1}`), &request); err != nil {
    panic(err)
}

client := postboost.NewAPIClient(postboost.NewConfiguration())
result, _, err := client.FreeToolsAPI.PickGiveawayWinners(context.Background()).FreeToolPickGiveawayWinnersRequest(request).Execute()
fmt.Println(result, err)

Ruby

require 'postboost'

api = PostBoost::FreeToolsApi.new
result = api.pick_giveaway_winners(PostBoost::FreeToolPickGiveawayWinnersRequest.new({ entrants: [{ username: "@Bob", comment: "c" }, { username: "alice", comment: "x" }, { username: "bob", comment: "again" }, { username: "carol" }], seed: "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f", winners: 2, alternates: 1 }))
puts result.to_hash

Java

import com.postboost.ApiClient;
import com.postboost.api.FreeToolsApi;
import com.postboost.model.FreeToolPickGiveawayWinnersRequest;
import com.postboost.model.FreeToolPickGiveawayWinnersResponse;

FreeToolsApi api = new FreeToolsApi(new ApiClient());
FreeToolPickGiveawayWinnersRequest request = FreeToolPickGiveawayWinnersRequest.fromJson("{\"entrants\":[{\"username\":\"@Bob\",\"comment\":\"c\"},{\"username\":\"alice\",\"comment\":\"x\"},{\"username\":\"bob\",\"comment\":\"again\"},{\"username\":\"carol\"}],\"seed\":\"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f\",\"winners\":2,\"alternates\":1}");
FreeToolPickGiveawayWinnersResponse result = api.pickGiveawayWinners(request);
System.out.println(result.toJson());

C#

using Newtonsoft.Json;
using PostBoost.Client.Api;
using PostBoost.Client.Client;
using PostBoost.Client.Model;

var api = new FreeToolsApi(new Configuration());
var request = JsonConvert.DeserializeObject<FreeToolPickGiveawayWinnersRequest>(@"{""entrants"":[{""username"":""@Bob"",""comment"":""c""},{""username"":""alice"",""comment"":""x""},{""username"":""bob"",""comment"":""again""},{""username"":""carol""}],""seed"":""000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f"",""winners"":2,""alternates"":1}");
var result = await api.PickGiveawayWinnersAsync(request);
Console.WriteLine(result.ToJson());

Rust

use postboost::apis::configuration::Configuration;
use postboost::apis::free_tools_api;
use postboost::models::FreeToolPickGiveawayWinnersRequest;

let config = Configuration::new();
let request: FreeToolPickGiveawayWinnersRequest = serde_json::from_str(r##"{"entrants":[{"username":"@Bob","comment":"c"},{"username":"alice","comment":"x"},{"username":"bob","comment":"again"},{"username":"carol"}],"seed":"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f","winners":2,"alternates":1}"##)?;
let result = free_tools_api::pick_giveaway_winners(&config, request).await?;
println!("{:?}", result);

CLI

echo '{"entrants":[{"username":"@Bob","comment":"c"},{"username":"alice","comment":"x"},{"username":"bob","comment":"again"},{"username":"carol"}],"seed":"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f","winners":2,"alternates":1}' | ./postboost-cli --content-type application/json pickGiveawayWinners -

With a token, send Authorization: Bearer YOUR_API_TOKEN as a default header (how, per SDK).

Response

{
    "winners": [
        "alice",
        "bob"
    ],
    "alternates": [
        "carol"
    ],
    "entrants_before": 4,
    "entrants_after": 3,
    "entrant_list": [
        "alice",
        "bob",
        "carol"
    ],
    "entrants_hash": "180fb4068fd5af9e707e2cd14ea439ac159703e1baef83af87e8cf2f1868d10f",
    "fingerprint": "630dcd2966c4336691125448bbb25b4ff412a49c732db2c8abc1b8581bd710dd",
    "seed": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
    "pre_committed": true,
    "algorithm": "pb-draw-v1",
    "warnings": []
}

With MCP

Connect https://postboost.co/mcp/tools (setup) and ask, for example: Pick giveaway winners with a draw anyone can verify with the PostBoost pick-giveaway-winners tool.

Errors

Status	When
401	The Authorization header holds an invalid token. Leave it out to call as a guest.
413	The JSON body is larger than 128 KB.
422	A field is invalid; the body lists the errors per field.
429	A limit is reached; see limits.