Spark REST API — reference

curl -sS -o /dev/null -w "%{http_code}" "${BASE}/health"
# expect: 200 and body {"ok":true}

import requests

BASE = "__ORIGIN__"   # replaced when viewing /docs on your API host
r = requests.get(f"{BASE}/health", timeout=30)
r.raise_for_status()
print(r.json())   # {"ok": true}

const BASE = "__ORIGIN__";
const r = await fetch(`${BASE}/health`, { method: "GET" });
console.log(r.status, await r.json());

<?php
$base = "__ORIGIN__";
echo file_get_contents($base . "/health");

// go run: needs package main, import "net/http", "io", "log"
resp, err := http.Get("__ORIGIN__/health")
if err != nil { log.Fatal(err) }
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
println(string(body))

curl -sS "${BASE}/v1/quota" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" \
  -H "Accept: application/json"

import requests

# Same pattern used for every authenticated GET under /v1/
BASE = "__ORIGIN__"
API_KEY = "pk_YOUR_KEY_HERE"

r = requests.get(
    f"{BASE}/v1/quota",
    headers={"X-API-Key": API_KEY, "Accept": "application/json"},
    timeout=60,
)
r.raise_for_status()
data = r.json()
# Example fields: trial_remaining, daily_limit_combined, usage_today,
# daily_left_subscription, total_requests_left_approx
print(data)

const BASE = "__ORIGIN__";
const API_KEY = "pk_YOUR_KEY_HERE";

const r = await fetch(`${BASE}/v1/quota`, {
  headers: { "X-API-Key": API_KEY, Accept: "application/json" },
});
if (!r.ok) throw new Error(await r.text());
console.log(await r.json());

<?php
$base = "__ORIGIN__";
$key = "pk_YOUR_KEY_HERE";
$ctx = stream_context_create([
  "http" => ["header" => "X-API-Key: $key\r\nAccept: application/json\r\n"],
]);
echo file_get_contents($base . "/v1/quota", false, $ctx);

// Quick check with net/http — set apiKey constant
req, _ := http.NewRequest("GET", "__ORIGIN__/v1/quota", nil)
req.Header.Set("X-API-Key", "pk_YOUR_KEY_HERE")
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
// defer resp.Body.Close(); io.ReadAll(resp.Body)

curl -sS "${BASE}/health"

import requests

print(requests.get("__ORIGIN__/health", timeout=15).json())

const r = await fetch("__ORIGIN__/health");
console.log(await r.json());

<?php echo file_get_contents("__ORIGIN__/health");

resp, err := http.Get("__ORIGIN__/health")
if err != nil { panic(err) }
defer resp.Body.Close()

curl -sS "${BASE}/v1/player/lookup?player_id=5123456789" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" \
  -H "Accept: application/json"

import requests

BASE = "__ORIGIN__"
API_KEY = "pk_YOUR_KEY_HERE"

r = requests.get(
    f"{BASE}/v1/player/lookup",
    params={"player_id": "5123456789"},
    headers={"X-API-Key": API_KEY, "Accept": "application/json"},
    timeout=120,
)
print(r.status_code, r.json())

const BASE = "__ORIGIN__";
const API_KEY = "pk_YOUR_KEY_HERE";
const u = new URL(`${BASE}/v1/player/lookup`);
u.searchParams.set("player_id", "5123456789");
const r = await fetch(u, {
  headers: { "X-API-Key": API_KEY, Accept: "application/json" },
});
console.log(r.status, await r.json());

<?php
$key = "pk_YOUR_KEY_HERE";
$q = http_build_query(["player_id" => "5123456789"]);
$ctx = stream_context_create([
  "http" => ["header" => "X-API-Key: $key\r\nAccept: application/json\r\n"],
]);
echo file_get_contents("__ORIGIN__/v1/player/lookup?" . $q, false, $ctx);

req, _ := http.NewRequest("GET", "__ORIGIN__/v1/player/lookup?player_id=5123456789", nil)
req.Header.Set("X-API-Key", "pk_YOUR_KEY_HERE")
req.Header.Set("Accept", "application/json")
// resp, err := http.DefaultClient.Do(req)

curl -sS "${BASE}/v1/me" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" \
  -H "Accept: application/json"

import requests

print(requests.get("__ORIGIN__/v1/me", headers={"X-API-Key": "pk_YOUR_KEY_HERE"}, timeout=60).json())

const r = await fetch("__ORIGIN__/v1/me", {
  headers: { "X-API-Key": "pk_YOUR_KEY_HERE", Accept: "application/json" },
});
console.log(await r.json());

<?php
$ctx = stream_context_create(["http" => ["header" => "X-API-Key: pk_YOUR_KEY_HERE\r\nAccept: application/json\r\n"]]);
echo file_get_contents("__ORIGIN__/v1/me", false, $ctx);

req, _ := http.NewRequest("GET", "__ORIGIN__/v1/me", nil)
req.Header.Set("X-API-Key", "pk_YOUR_KEY_HERE")

curl -sS "${BASE}/v1/quota" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" \
  -H "Accept: application/json"

import requests

print(requests.get("__ORIGIN__/v1/quota", headers={"X-API-Key": "pk_YOUR_KEY_HERE"}).json())

const r = await fetch("__ORIGIN__/v1/quota", {
  headers: { "X-API-Key": "pk_YOUR_KEY_HERE" },
});
console.log(await r.json());

<?php
$ctx = stream_context_create(["http" => ["header" => "X-API-Key: pk_YOUR_KEY_HERE\r\n"]]);
echo file_get_contents("__ORIGIN__/v1/quota", false, $ctx);

req, _ := http.NewRequest("GET", "__ORIGIN__/v1/quota", nil)
req.Header.Set("X-API-Key", "pk_YOUR_KEY_HERE")

curl -sS "${BASE}/v1/stock/summary" \
  -H "X-API-Key: pk_YOUR_KEY_HERE"

import requests

print(requests.get("__ORIGIN__/v1/stock/summary", headers={"X-API-Key": "pk_YOUR_KEY_HERE"}).json())

const r = await fetch("__ORIGIN__/v1/stock/summary", {
  headers: { "X-API-Key": "pk_YOUR_KEY_HERE" },
});
console.log(await r.json());

<?php
$ctx = stream_context_create(["http" => ["header" => "X-API-Key: pk_YOUR_KEY_HERE\r\n"]]);
echo file_get_contents("__ORIGIN__/v1/stock/summary", false, $ctx);

req, _ := http.NewRequest("GET", "__ORIGIN__/v1/stock/summary", nil)
req.Header.Set("X-API-Key", "pk_YOUR_KEY_HERE")

curl -sS "${BASE}/v1/history?limit=20&offset=0" \
  -H "X-API-Key: pk_YOUR_KEY_HERE"

import requests

print(requests.get(
    "__ORIGIN__/v1/history",
    params={"limit": 20, "offset": 0},
    headers={"X-API-Key": "pk_YOUR_KEY_HERE"},
).json())

const u = new URL("__ORIGIN__/v1/history");
u.searchParams.set("limit", "20");
u.searchParams.set("offset", "0");
const r = await fetch(u, { headers: { "X-API-Key": "pk_YOUR_KEY_HERE" } });
console.log(await r.json());

<?php
$ctx = stream_context_create(["http" => ["header" => "X-API-Key: pk_YOUR_KEY_HERE\r\n"]]);
echo file_get_contents("__ORIGIN__/v1/history?limit=20&offset=0", false, $ctx);

req, _ := http.NewRequest("GET", "__ORIGIN__/v1/history?limit=20&offset=0", nil)
req.Header.Set("X-API-Key", "pk_YOUR_KEY_HERE")

curl -sS -X POST "${BASE}/v1/subscription/purchase" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d "{\"plan_key\":\"p2\",\"api_enabled\":false}"

# Re-buy same tier you already have: choose extend or stack
curl -sS -X POST "${BASE}/v1/subscription/purchase" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d "{\"plan_key\":\"p2\",\"api_enabled\":false,\"same_plan_action\":\"extend\"}"
curl -sS -X POST "${BASE}/v1/subscription/purchase-api-addon" \
  -H "X-API-Key: pk_YOUR_KEY_HERE"

import requests

r = requests.post(
    "__ORIGIN__/v1/subscription/purchase",
    headers={"X-API-Key": "pk_YOUR_KEY_HERE", "Content-Type": "application/json"},
    json={"plan_key": "p2", "api_enabled": False},
    timeout=60,
)
print(r.status_code, r.json())

r2 = requests.post(
    "__ORIGIN__/v1/subscription/purchase",
    headers={"X-API-Key": "pk_YOUR_KEY_HERE", "Content-Type": "application/json"},
    json={"plan_key": "p2", "api_enabled": False, "same_plan_action": "stack"},
    timeout=60,
)
print(r2.status_code, r2.json())

# Standalone HTTP API add-on:
r = requests.post(
    "__ORIGIN__/v1/subscription/purchase-api-addon",
    headers={"X-API-Key": "pk_YOUR_KEY_HERE"},
    timeout=60,
)
print(r.status_code, r.json())

const r = await fetch("__ORIGIN__/v1/subscription/purchase", {
  method: "POST",
  headers: { "X-API-Key": "pk_YOUR_KEY_HERE", "Content-Type": "application/json" },
  body: JSON.stringify({ plan_key: "p2", api_enabled: false }),
});
console.log(await r.json());

// Standalone HTTP API add-on:
const r2 = await fetch("__ORIGIN__/v1/subscription/purchase-api-addon", {
  method: "POST",
  headers: { "X-API-Key": "pk_YOUR_KEY_HERE" },
});
console.log(await r2.json());

<?php
$body = json_encode(["plan_key" => "p2", "api_enabled" => false]);
$ctx = stream_context_create(["http" => [
  "method" => "POST",
  "header" => "X-API-Key: pk_YOUR_KEY_HERE\r\nContent-Type: application/json\r\n",
  "content" => $body,
]]);
echo file_get_contents("__ORIGIN__/v1/subscription/purchase", false, $ctx);

body := strings.NewReader(`{"plan_key":"p2","api_enabled":false}`)
req, _ := http.NewRequest("POST", "__ORIGIN__/v1/subscription/purchase", body)
req.Header.Set("X-API-Key", "pk_YOUR_KEY_HERE")
req.Header.Set("Content-Type", "application/json")

# Single voucher (still use `codes` as a JSON array)
curl -sS -X POST "${BASE}/v1/jobs/check-code" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d "{\"codes\":[\"a1B2c3D4e5F6g7H8i9\"]}"

# Up to 10 codes — quota: 1 request per array element when the worker runs
curl -sS -X POST "${BASE}/v1/jobs/check-code" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d "{\"codes\":[\"a1B2c3D4e5F6g7H8i9\",\"x9Y8z7W6v5U4t3S2r1\",\"b2C3d4E5f6G7h8I9j0\"]}"

import requests

BASE = "__ORIGIN__"
API_KEY = "pk_YOUR_KEY_HERE"

# Always pass `codes` as a list — one element for a single code, many for a batch (max 10).
body_single = {"codes": ["a1B2c3D4e5F6g7H8i9"]}
body_batch = {
    "codes": [
        "a1B2c3D4e5F6g7H8i9",
        "x9Y8z7W6v5U4t3S2r1",
        "b2C3d4E5f6G7h8I9j0",
    ]
}
body = body_single

resp = requests.post(
    f"{BASE}/v1/jobs/check-code",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json=body,
    timeout=60,
)
resp.raise_for_status()
pending = resp.json()
job_id = pending["job_id"]
print("Queued:", pending)

const body = { codes: ["a1B2c3D4e5F6g7H8i9"] };
const r = await fetch(BASE + "/v1/jobs/check-code", {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify(body),
});
console.log(await r.json());

<?php
$body = json_encode(["codes" => ["a1B2c3D4e5F6g7H8i9"]]);
$ctx = stream_context_create(["http" => ["method"=>"POST","header"=>"X-API-Key: $key\r\nContent-Type: application/json\r\n","content"=>$body]]);
echo file_get_contents(BASE . "/v1/jobs/check-code", false, $ctx);

body := strings.NewReader(`{"codes":["a1B2c3D4e5F6g7H8i9"]}`)
req, _ := http.NewRequest("POST", BASE+"/v1/jobs/check-code", body)
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")

curl -sS -X POST "${BASE}/v1/jobs/manual-redeem" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d "{\"player_id\":\"5123456789\",\"codes\":[\"a1B2c3D4e5F6g7H8i9\",\"x9Y8z7W6v5U4t3S2r1\"]}"

import requests

BASE = "__ORIGIN__"
API_KEY = "pk_YOUR_KEY_HERE"

payload = {
    "player_id": "5123456789",
    "codes": [
        "a1B2c3D4e5F6g7H8i9",
        "x9Y8z7W6v5U4t3S2r1",
    ],
}
resp = requests.post(
    f"{BASE}/v1/jobs/manual-redeem",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json=payload,
    timeout=60,
)
print(resp.status_code, resp.json())

const r = await fetch(BASE + "/v1/jobs/manual-redeem", {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    player_id: "5123456789",
    codes: ["a1B2c3D4e5F6g7H8i9", "x9Y8z7W6v5U4t3S2r1"],
  }),
});
console.log(await r.json());

<?php
$b = json_encode(["player_id"=>"5123456789","codes"=>["a1B2c3D4e5F6g7H8i9","x9Y8z7W6v5U4t3S2r1"]]);
$ctx = stream_context_create(["http" => ["method"=>"POST","header"=>"X-API-Key: $key\r\nContent-Type: application/json\r\n","content"=>$b]]);
echo file_get_contents(BASE . "/v1/jobs/manual-redeem", false, $ctx);

body := strings.NewReader(`{"player_id":"5123456789","codes":["a1B2c3D4e5F6g7H8i9","x9Y8z7W6v5U4t3S2r1"]}`)
req, _ := http.NewRequest("POST", BASE+"/v1/jobs/manual-redeem", body)
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")

curl -sS -X POST "${BASE}/v1/jobs/stock-redeem" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" -H "Content-Type: application/json" \
  -d "{\"player_id\":\"5123456789\",\"picks\":{\"60\":1,\"325\":1}}"

import requests

BASE = "__ORIGIN__"
API_KEY = "pk_YOUR_KEY_HERE"

# Redeem one 60 UC code and one 325 UC code from uploaded stock
body = {
    "player_id": "5123456789",
    "picks": {"60": 1, "325": 1},
}
resp = requests.post(
    f"{BASE}/v1/jobs/stock-redeem",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json=body,
    timeout=60,
)
print(resp.status_code, resp.json())

const r = await fetch(BASE + "/v1/jobs/stock-redeem", {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ player_id: "5123456789", picks: { 60: 1, 325: 1 } }),
});
console.log(await r.json());

<?php
$b = json_encode(["player_id"=>"5123456789","picks"=>["60"=>1,"325"=>1]]);
$ctx = stream_context_create(["http" => ["method"=>"POST","header"=>"X-API-Key: $key\r\nContent-Type: application/json\r\n","content"=>$b]]);
echo file_get_contents(BASE . "/v1/jobs/stock-redeem", false, $ctx);

body := strings.NewReader(`{"player_id":"5123456789","picks":{"60":1,"325":1}}`)
req, _ := http.NewRequest("POST", BASE+"/v1/jobs/stock-redeem", body)
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")

curl -sS "${BASE}/v1/jobs/JOB_ID" -H "X-API-Key: pk_YOUR_KEY_HERE"

import requests

BASE = "__ORIGIN__"
API_KEY = "pk_YOUR_KEY_HERE"
job_id = "674a1b2c3d4e5f60718293a4"

r = requests.get(
    f"{BASE}/v1/jobs/{job_id}",
    headers={"X-API-Key": API_KEY, "Accept": "application/json"},
    timeout=60,
)
print(r.status_code, r.json())

const jid = "JOB_ID";
const r = await fetch(BASE + "/v1/jobs/" + jid, { headers: { "X-API-Key": API_KEY } });
console.log(await r.json());

<?php
$id = "JOB_ID";
$ctx = stream_context_create(["http" => ["header" => "X-API-Key: $key\r\n"]]);
echo file_get_contents(BASE . "/v1/jobs/" . $id, false, $ctx);

req, _ := http.NewRequest("GET", BASE+"/v1/jobs/"+jobID, nil)
req.Header.Set("X-API-Key", apiKey)

curl -sS "${BASE}/v1/jobs?limit=10&offset=0" -H "X-API-Key: pk_YOUR_KEY_HERE"

import requests
print(requests.get(BASE + "/v1/jobs", params={"limit": 10, "offset": 0}, headers={"X-API-Key": API_KEY}).json())

const r = await fetch(BASE + "/v1/jobs?limit=10&offset=0", { headers: { "X-API-Key": API_KEY } });
console.log(await r.json());

<?php
$ctx = stream_context_create(["http" => ["header" => "X-API-Key: $key\r\n"]]);
echo file_get_contents(BASE . "/v1/jobs?limit=10&offset=0", false, $ctx);

req, _ := http.NewRequest("GET", BASE+"/v1/jobs?limit=10&offset=0", nil)
req.Header.Set("X-API-Key", apiKey)

curl -sS -X POST "${BASE}/api/v1/order/screenshot" \
  -H "X-API-Key: pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: image/webp" \
  -d '{"job_id":"674a1b2c3d4e5f60718293a4"}' \
  -o order.webp

import pathlib
import requests

BASE = "__ORIGIN__"
API_KEY = "pk_YOUR_KEY_HERE"
JOB_ID = "674a1b2c3d4e5f60718293a4"

r = requests.post(
    f"{BASE}/api/v1/order/screenshot",
    headers={"X-API-Key": API_KEY, "Accept": "image/webp"},
    json={"job_id": JOB_ID, "webp_quality": 88},
    timeout=60,
)
if r.status_code == 200 and r.headers.get("Content-Type", "").startswith("image/webp"):
    pathlib.Path("order.webp").write_bytes(r.content)
    print("saved order.webp", len(r.content), "bytes")
else:
    print(r.status_code, r.text)

const r = await fetch(BASE + "/api/v1/order/screenshot", {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
    Accept: "image/webp",
  },
  body: JSON.stringify({ job_id: "674a1b2c3d4e5f60718293a4" }),
});
if (!r.ok) {
  console.log(await r.text());
} else {
  const buf = await r.arrayBuffer();
  console.log("webp bytes", buf.byteLength);
}

<?php
$payload = json_encode(["job_id" => "674a1b2c3d4e5f60718293a4"]);
$ctx = stream_context_create([
  "http" => [
    "method" => "POST",
    "header" => "X-API-Key: $key\r\nContent-Type: application/json\r\nAccept: image/webp\r\n",
    "content" => $payload,
  ],
]);
$raw = file_get_contents(BASE . "/api/v1/order/screenshot", false, $ctx);
file_put_contents("order.webp", $raw);

payload := strings.NewReader(`{"job_id":"674a1b2c3d4e5f60718293a4"}`)
req, _ := http.NewRequest("POST", BASE+"/api/v1/order/screenshot", payload)
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Accept", "image/webp")
resp, err := http.DefaultClient.Do(req)
// defer resp.Body.Close(); io.Copy(outFile, resp.Body)