Public API

With /public/v1 your code works with the same data you see in the cabinet: accounts, tasks, drops, matches and slots.

Base URL: https://split-team.com/public/v1

Farming is started by tasks (/tasks). POST /jobs only creates a drop claim (cs2_claim_drop).

The key

Send the key in an Authorization: Bearer sft_… header with every request.

A key is issued in the cabinet, under API.

GET /public/v1/whoami answers any valid key, even one with no scopes, and returns the key's label, prefix, scopes and expiry.

Scopes

A key is issued with one or more scopes. An operation the key lacks a scope for answers 403 insufficient_scope, listing what's missing in error.missing.

ScopeGrants
account:read
Account: readSee slots, subscriptions and the drop week.
bots:read
Accounts: readSee accounts with their drops, matches and runs.
bots:write
Accounts: changeChange account labels and groups, delete accounts, cancel runs and start a manual drop claim.
bots:credentials
Accounts: passwordsAdd accounts and change their password and shared secret. The key can never read a password back.
tasks:read
Tasks: readSee tasks and what they contain.
tasks:write
Tasks: changeCreate and change tasks.

Pagination

Lists are paginated. Parameters: limit from 1 to 200 (default 50) and cursor, set to the previous page's next_cursor. The response has items and next_cursor; the last page has no next_cursor.

An account's drops, drop offers and matches only cover the most recent entries. The operation reference below says how many.

Idempotency-Key

POST /bots, /bots/batch, /tasks and /jobs accept an Idempotency-Key header of 1 to 255 printable ASCII characters. A key is kept for 24 hours. A retry with the same key and body returns the first attempt's response with Idempotent-Replayed: true. The same key with a different body gets 422 idempotency_key_reused, and a retry while the first request is still running gets 409 idempotency_in_progress.

Always send it with batches: without it, a retry after a dropped connection gets an "already added" refusal for the accounts the first request managed to add.

Open enums

Account states, run stop reasons, event types and error codes can gain new values without a new version of /public/v1. Show an unfamiliar value as unknown and don't treat it as an error.

Rate limit

All your keys together can make 10 requests per second, burst 30. POST /bots/batch has its own limit: 1 request per 5 seconds. RateLimit-Limit and RateLimit-Remaining come with every response to a request that passed the key and scope checks. Going over returns 429 rate_limited with RateLimit-Reset and Retry-After (seconds to wait). All requests from one IP address (one /64 network for IPv6) are also counted, including those refused over the key or scope: 60 per second, burst 120. A client acting for one user that keeps to that limit stays below it; keys of several users used from one address share this limit. Going over returns the same 429 rate_limited with Retry-After, without the RateLimit-* headers.

These numbers may change.

Error codes

An error is an error object with code and message, plus missing on a scope refusal. Next to it is request_id, the same value as the X-Request-Id header. The code list can grow; below are the codes in use today.

  • invalid_api_key
  • insufficient_scope
  • rate_limited
  • internal
  • bad_idempotency_key
  • idempotency_key_reused
  • idempotency_in_progress
  • not_found
  • bad_limit
  • bad_cursor
  • bad_request
  • method_not_allowed
  • job_type_not_allowed
  • bad_game_id
  • bad_label
  • bad_steam_username
  • bad_steam_password
  • bad_steam_shared_secret
  • bad_steam_identity_secret
  • duplicate_steam_username
  • bot_limit
  • bad_batch_size
  • bad_name
  • bad_webhook_url
  • duplicate_name
  • bad_bot_id
  • bot_group_mismatch
  • field_not_supported
  • bad_config
  • unknown_type
  • type_not_live
  • bad_job_data
  • bot_busy
  • bot_needs_relogin
  • bot_banned
  • bot_quarantined
  • not_cancellable
  • bad_schedule
  • bad_minutes
  • no_targets
  • bad_target
  • duplicate_target
  • target_not_found
  • bot_in_other_task
  • bad_state

Data format

  • 64-bit ids (steam_id, item_id) come as strings: a JavaScript number can't hold them exactly.
  • Amounts are integer cents in *_cents fields, with the currency in currency.
  • Times are RFC 3339, in UTC. The exception is offer_time in drop offers: an integer taken from the game.
  • The Steam password, shared secret and identity secret are write-only: no API response returns them.

Operations

Each operation lists its method, path, required scope and what it does. Parameters and the request body are shown under the row.

  • GET/public/v1/whoami
    any key

    The key this request was made with.

    Works with any valid key, regardless of scopes.

  • GET/public/v1/bots
    bots:read

    List accounts.

    Query: limit, cursor, status, group_id, task_id

  • POST/public/v1/bots
    bots:credentials

    Add a Steam account.

    Body: PubBotCreate

    Send Idempotency-Key: without it, a retry after a dropped connection gets duplicate_steam_username for the account the first request added. The password and secrets are never returned.

  • POST/public/v1/bots/batch
    bots:credentials

    Add up to 200 accounts in one request.

    Body: PubBotBatchCreate

    Send Idempotency-Key for the same reason as with a single account. Each row is processed on its own: a failed row doesn't cancel the others. Match results to request rows by index. duplicate_in_batch only catches repeats within one request, so remove repeated steam_username values from the whole file before splitting it into batches. Otherwise a repeat in another batch comes back as duplicate_steam_username, as if the account had been added earlier.

  • GET/public/v1/bots/{id}
    bots:read

    One account.

    Path: id

  • PATCH/public/v1/bots/{id}
    bots:write

    Rename an account.

    Path: id · Body: PubBotUpdate

    Only label changes here. The password and shared secret go through PUT /bots/{id}/credentials. Other fields in the body are ignored.

  • DELETE/public/v1/bots/{id}
    bots:write

    Delete an account together with its password and secrets.

    Path: id

  • PUT/public/v1/bots/{id}/credentials
    bots:credentials

    Replace an account's Steam password or shared secret.

    Path: id · Body: PubBotCredentials

    Send at least one of the two fields; an empty body gets bad_request. An account in needs_relogin moves to pending_login after the change.

  • GET/public/v1/bots/{id}/drops
    bots:read

    Items of one account, newest first.

    Path: id · Query: limit, cursor

    Covers the 500 most recent items, paginated.

  • GET/public/v1/bots/{id}/drop-offers
    bots:read

    Drop offers of one account, newest first.

    Path: id · Query: limit, cursor

    Covers the 200 most recent offers, paginated.

  • GET/public/v1/bots/{id}/matches
    bots:read

    Completed matches of one account, newest first.

    Path: id · Query: limit, cursor

    Covers the 200 most recent matches, paginated.

  • GET/public/v1/account
    account:read

    Slot usage and active subscriptions.

  • GET/public/v1/account/overview
    account:read

    Summary: this week's drop, drops by day, recent drops, matches in the last 24 hours.

  • GET/public/v1/groups
    bots:read

    List groups.

    Query: limit, cursor

  • POST/public/v1/groups
    bots:write

    Create a group.

    Body: PubGroupCreate

    A group has only a name and members, no settings.

  • GET/public/v1/groups/{id}
    bots:read

    One group.

    Path: id

  • PATCH/public/v1/groups/{id}
    bots:write

    Rename a group.

    Path: id · Body: PubGroupUpdate

  • DELETE/public/v1/groups/{id}
    bots:write

    Delete a group.

    Path: id

    The accounts stay in the cabinet. The group is removed from task targets, and its accounts leave the tasks they joined through it.

  • PUT/public/v1/groups/{id}/members/{bot_id}
    bots:write

    Add an account to a group.

    Path: id, bot_id

    Adding an account that's already a member changes nothing and isn't an error. Someone else's or a nonexistent account or group gets 404 not_found.

  • DELETE/public/v1/groups/{id}/members/{bot_id}
    bots:write

    Remove an account from a group.

    Path: id, bot_id

  • GET/public/v1/jobs
    bots:read

    List runs.

    Query: limit, cursor, bot_id, state

    For each account you get its current run and its last finished one, so up to two entries. Runs of every type are listed, including cs2_farm runs started by tasks.

  • POST/public/v1/jobs
    bots:write

    Claim an account's drop.

    Body: PubJobCreate

    Only type: cs2_claim_drop is accepted. cs2_farm gets 400 job_type_not_allowed: farming is started by tasks. If the account already has an active run, you get 409 bot_busy. Send Idempotency-Key.

  • GET/public/v1/jobs/capabilities
    bots:read

    Task settings fields.

    These fields go into a task's config when you create or update it (POST /tasks, PATCH /tasks/{id}). A drop claim via POST /jobs takes no settings.

  • POST/public/v1/jobs/{id}/cancel
    bots:write

    Cancel a run.

    Path: id

    A cancelled run won't start again. A run in progress doesn't stop instantly.

  • GET/public/v1/tasks
    tasks:read

    List tasks.

    Query: limit, cursor

  • POST/public/v1/tasks
    tasks:write

    Create a task.

    Body: PubTaskInput

    Send Idempotency-Key. Targets can be left empty and added later. An account can belong to only one active or paused task; otherwise you get 409 bot_in_other_task listing the tasks that hold it.

  • GET/public/v1/tasks/{id}
    tasks:read

    One task.

    Path: id

  • PATCH/public/v1/tasks/{id}
    tasks:write

    Replace a task whole (name, targets, schedule, config, minutes).

    Path: id · Body: PubTaskInput

    409 bot_in_other_task only comes back when the update adds an account that already belongs to another active or paused task.

  • DELETE/public/v1/tasks/{id}
    tasks:write

    Delete a task.

    Path: id

    Running matches play out, pending runs are dropped.

  • POST/public/v1/tasks/{id}/pause
    tasks:write

    Pause a task.

    Path: id

    Matches in progress play out, pending runs are dropped. The accounts stay with this task.

  • POST/public/v1/tasks/{id}/resume
    tasks:write

    Resume a paused task.

    Path: id

    If, through group changes during the pause, an account ended up in another active or paused task, you get 409 bot_in_other_task.

  • POST/public/v1/tasks/{id}/stop
    tasks:write

    Stop a task and cut its runs short.

    Path: id

    The task is paused and its runs in progress are cancelled, though not instantly. Cancelled runs don't count toward the account's week. On a paused task, stop cuts short the matches still playing out.

Webhooks

A webhook sends a POST request to your address when something happens to an account, drop, run, task or payment. Endpoints are created and edited only in the cabinet, under API → Webhooks.

Up to 5 endpoints per user. The URL must be public and start with https://; local and internal addresses are rejected.

Request body

The body is JSON with id (the event id, use it to drop repeats), type (a type from the table below), created_at (when the event happened) and data (the event payload). Header Content-Type: application/json.

Headers

HeaderValue
X-Split-EventThe event type, the same one as in the body.
X-Split-DeliveryDelivery id, the same across all retries.
X-Split-SignatureThe signature, see below.
User-AgentAlways SplitTeam-Webhooks/1.

Verifying the signature

X-Split-Signature carries a timestamp and a signature: HMAC-SHA256 of the string "timestamp, dot, request body" as hex. The header format is shown below. The signature covers the body exactly as received, before JSON parsing. Reject deliveries whose timestamp is more than 5 minutes old, and compare signatures with a constant-time function: hmac.Equal in Go, crypto.timingSafeEqual in Node, hmac.compare_digest in Python.

Header format
t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>
Go
package splitwebhook

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"math"
	"strconv"
	"strings"
	"time"
)

// Verify checks the X-Split-Signature header against the RAW request body —
// before any JSON parsing, since the signature is computed over the exact
// bytes that were sent. header looks like "t=<unix seconds>,v1=<hex
// HMAC-SHA256(secret, "<t>.<raw body>")>".
func Verify(header string, body []byte, secret string, now time.Time) error {
	var t, v1 string
	for _, part := range strings.Split(header, ",") {
		kv := strings.SplitN(part, "=", 2)
		if len(kv) != 2 {
			continue
		}
		switch kv[0] {
		case "t":
			t = kv[1]
		case "v1":
			v1 = kv[1]
		}
	}
	if t == "" || v1 == "" {
		return errors.New("malformed signature header")
	}

	ts, err := strconv.ParseInt(t, 10, 64)
	if err != nil {
		return errors.New("malformed timestamp")
	}
	// Reject a delivery older or newer than 5 minutes — this stops a
	// captured delivery from being replayed later.
	if age := now.Sub(time.Unix(ts, 0)); math.Abs(age.Seconds()) > 5*60 {
		return errors.New("timestamp outside 5-minute tolerance")
	}

	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(t + "."))
	mac.Write(body)
	expected := hex.EncodeToString(mac.Sum(nil))

	if !hmac.Equal([]byte(expected), []byte(v1)) {
		return errors.New("signature mismatch")
	}
	return nil
}
Node
import { createHmac, timingSafeEqual } from 'node:crypto';

/**
 * Verifies the `X-Split-Signature` header of a Split Team webhook delivery
 * against the RAW request body — before any JSON parsing, since the
 * signature is computed over the exact bytes that were sent.
 *
 * The header looks like `t=<unix seconds>,v1=<hex HMAC-SHA256(secret,
 * "<t>.<raw body>")>`. A delivery older or newer than `toleranceSeconds`
 * (default 5 minutes) is rejected — that stops a captured delivery from
 * being replayed later. `now` is only there so this same function can be
 * exercised against fixed test vectors; leave it out in real code and it
 * defaults to the current time.
 */
export function verifySplitSignature(
  header: string,
  rawBody: string | Buffer,
  secret: string,
  options: { toleranceSeconds?: number; now?: number } = {}
): boolean {
  const toleranceSeconds = options.toleranceSeconds ?? 5 * 60;
  const now = options.now ?? Date.now();

  const parts = new Map(
    header.split(',').map((pair) => {
      const [key, value] = pair.split('=');
      return [key, value] as const;
    })
  );
  const t = parts.get('t');
  const v1 = parts.get('v1');
  if (!t || !v1) return false;

  const timestamp = Number(t);
  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(now / 1000 - timestamp) > toleranceSeconds) return false;

  const body = typeof rawBody === 'string' ? Buffer.from(rawBody, 'utf8') : rawBody;
  const expected = createHmac('sha256', secret).update(`${t}.`).update(body).digest('hex');

  const expectedBuf = Buffer.from(expected, 'utf8');
  const receivedBuf = Buffer.from(v1, 'utf8');
  // Length check before timingSafeEqual: it throws on mismatched lengths
  // instead of returning false, and a thrown error here must not be read
  // as "signature valid" by a caller that only checks for an exception.
  if (expectedBuf.length !== receivedBuf.length) return false;

  return timingSafeEqual(expectedBuf, receivedBuf);
}
Python
import hashlib
import hmac
import time


def verify_split_signature(header, body, secret, now=None, tolerance_seconds=5 * 60):
    """Verifies X-Split-Signature against the RAW request body (bytes),
    before any JSON parsing — the signature is computed over the exact
    bytes that were sent. header looks like "t=<unix seconds>,v1=<hex
    HMAC-SHA256(secret, "<t>.<raw body>")>".
    """
    if now is None:
        now = time.time()

    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t"), parts.get("v1")
    if not t or not v1:
        return False

    # Reject a delivery older or newer than 5 minutes — this stops a
    # captured delivery from being replayed later.
    if abs(now - int(t)) > tolerance_seconds:
        return False

    signed_payload = f"{t}.".encode() + body
    expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()

    return hmac.compare_digest(expected, v1)

Success, timeout, redirects

A delivery succeeds when your server answers 2xx within 10 seconds. Redirects aren't followed: a 3xx, like any code outside 2xx, counts as a failure. The response body isn't parsed; the delivery log shows only its beginning.

Retries and auto-disable

A failed delivery is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, then once a day. After the ninth failed attempt, about 2.9 days after the first, retries stop.

If three days pass after the first failure without a single successful delivery, the endpoint is switched off. You can switch it back on in the cabinet, and deliveries whose retries haven't run out are then sent. Events that happen while the endpoint is off aren't sent and won't arrive later: check the current state through the API (GET /bots, /jobs, /tasks).

The cabinet keeps the delivery log for 7 days; events themselves are kept for 30 days.

At-least-once, no ordering

One event can arrive more than once, and different events can arrive in any order. Drop repeats by id and treat an event as a signal that something changed: read the current state through the API.

Event types

Besides the types below there's ping: the "Send test event" button in the cabinet sends it, and you don't subscribe to it.

TypeWhendata
bot.logged_inThe account is ready to work.PubBot
bot.needs_reloginSteam rejected the password or session, and the account left the queue.PubBot
bot.quarantinedA VACnet kick, a ban, or another final disconnect.PubBot + code
bot.cooldownMatchmaking is penalizing the account temporarily.PubBot + until
drop.receivedThe account received a weekly drop item.PubDrop + bot_id
drop.claimedThe farm sent a claim request for the offer.PubDropOffer + bot_id
job.completedThe account's job finished successfully.PubJob
job.failedThe account's job ended in failure.PubJob
task.doneThe owner's task ran to completion.PubTask
payment.paidA slot purchase was confirmed by the payment gateway.PubPayment
subscription.expiringSlots from this subscription are about to run out.PubSubscription
subscription.expiredSlots from this subscription no longer apply.PubSubscription

Client

The OpenAPI spec is linked below. Generate a client from it with any tool, such as openapi-typescript or openapi-generator.

Open openapi.yaml