Ky, from your own code.

curl https://ky.ax/api/v1/me \
  -H "Authorization: Bearer $KY_API_KEY"

import os, requests

r = requests.get(
    "https://ky.ax/api/v1/me",
    headers={"Authorization": f"Bearer {os.environ['KY_API_KEY']}"},
)
print(r.json())

const r = await fetch("https://ky.ax/api/v1/me", {
  headers: { Authorization: `Bearer ${process.env.KY_API_KEY}` },
});
console.log(await r.json());

curl -X POST https://ky.ax/api/v1/device/start \
  -H "Content-Type: application/json" \
  -d '{"client": "My App"}'

# open verification_url, then poll every 3 seconds:
curl -X POST https://ky.ax/api/v1/device/poll \
  -H "Content-Type: application/json" \
  -d '{"device_code": "…"}'

import time, webbrowser, requests

API = "https://ky.ax/api/v1"
start = requests.post(f"{API}/device/start", json={"client": "My App"}).json()
print("Your code:", start["user_code"])
webbrowser.open(start["verification_url"])

while True:
    time.sleep(start["interval"])
    poll = requests.post(f"{API}/device/poll", json={"device_code": start["device_code"]}).json()
    if poll["status"] != "pending":
        break
api_key = poll.get("api_key")  # only when status is "approved"

const API = "https://ky.ax/api/v1";
const post = (path, body) =>
  fetch(API + path, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  }).then((r) => r.json());

const start = await post("/device/start", { client: "My App" });
console.log("Open", start.verification_url, "and enter", start.user_code);

let poll;
do {
  await new Promise((r) => setTimeout(r, start.interval * 1000));
  poll = await post("/device/poll", { device_code: start.device_code });
} while (poll.status === "pending");
const apiKey = poll.api_key; // only when status is "approved"

# 1. declare the song
SIZE=$(wc -c < my-song.mp3 | tr -d ' ')
curl https://ky.ax/api/v1/check \
  -H "Authorization: Bearer $KY_API_KEY" \
  -H "X-Ky-Client: My App" \
  -H "Content-Type: application/json" \
  -d "{\"mode\": \"catalogue\", \"files\": [{\"name\": \"my-song.mp3\", \"size\": $SIZE}]}"

# 2. send it to the upload_url you got back
curl --upload-file my-song.mp3 \
  "https://ky.ax/api/v1/checks/c_…/items/i_…/upload" \
  -H "Authorization: Bearer $KY_API_KEY" \
  -H "Content-Type: application/octet-stream"

# 3. poll until status is done, then read each item's verdict
curl "https://ky.ax/api/v1/checks/c_…?summary=0" \
  -H "Authorization: Bearer $KY_API_KEY"

import os, time, requests

API = "https://ky.ax/api/v1"
H = {"Authorization": f"Bearer {os.environ['KY_API_KEY']}", "X-Ky-Client": "My App"}
path = "my-song.mp3"
size = os.path.getsize(path)

# 1. declare the song
r = requests.post(f"{API}/check", headers=H, json={
    "mode": "catalogue",
    "files": [{"name": path, "size": size}],
})
r.raise_for_status()
check = r.json()

# 2. send it, streamed from disk with its exact length
with open(path, "rb") as f:
    requests.put("https://ky.ax" + check["items"][0]["upload_url"], data=f, headers={
        **H, "Content-Type": "application/octet-stream", "Content-Length": str(size),
    }).raise_for_status()

# 3. poll until done, then read the verdict
while True:
    check = requests.get(f"{API}/checks/{check['id']}", headers=H,
                         params={"summary": "0"}).json()
    if check["status"] in ("done", "error"):
        break
    time.sleep(5)
for item in check["items"]:
    print(item["filename"], item["verdict"], item["headline"])
    if item["evidence_url"]:
        evidence = requests.get(item["evidence_url"], headers=H).json()

import { readFile } from "node:fs/promises";

const API = "https://ky.ax/api/v1";
const headers = { Authorization: `Bearer ${process.env.KY_API_KEY}`, "X-Ky-Client": "My App" };
const call = async (url, init = {}) => {
  const r = await fetch(url, { ...init, headers: { ...headers, ...init.headers } });
  const body = await r.json();
  if (!r.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  return body;
};

// 1. declare the song
const bytes = await readFile("my-song.mp3");
let check = await call(`${API}/check`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ mode: "catalogue", files: [{ name: "my-song.mp3", size: bytes.length }] }),
});

// 2. send it
await call("https://ky.ax" + check.items[0].upload_url, {
  method: "PUT",
  headers: { "Content-Type": "application/octet-stream" },
  body: bytes,
});

// 3. poll until done, then read the verdict
for (;;) {
  check = await call(`${API}/checks/${check.id}?summary=0`);
  if (check.status === "done" || check.status === "error") break;
  await new Promise((r) => setTimeout(r, 5000));
}
for (const item of check.items) {
  console.log(item.filename, item.verdict, item.headline);
  if (item.evidence_url) await call(item.evidence_url);
}

# declare them together, then send each one
curl https://ky.ax/api/v1/check \
  -H "Authorization: Bearer $KY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "catalogue", "files": [
        {"name": "verse-take-2.wav", "size": 31457280},
        {"name": "vocal-stem.flac", "size": 9830400}]}'

# each item in the reply carries its own upload_url
curl --upload-file verse-take-2.wav \
  "https://ky.ax/api/v1/checks/c_…/items/i_…/upload" \
  -H "Authorization: Bearer $KY_API_KEY" \
  -H "Content-Type: application/octet-stream"

paths = ["verse-take-2.wav", "vocal-stem.flac"]
r = requests.post(f"{API}/check", headers=H, json={
    "mode": "catalogue",
    "files": [{"name": p, "size": os.path.getsize(p)} for p in paths],
})
r.raise_for_status()
for path, item in zip(paths, r.json()["items"]):
    with open(path, "rb") as f:
        requests.put("https://ky.ax" + item["upload_url"], data=f, headers={
            **H, "Content-Type": "application/octet-stream",
            "Content-Length": str(os.path.getsize(path)),
        }).raise_for_status()

import { readFile, stat } from "node:fs/promises";

const paths = ["verse-take-2.wav", "vocal-stem.flac"];
const files = await Promise.all(paths.map(async (name) => ({ name, size: (await stat(name)).size })));
const check = await call(`${API}/check`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ mode: "catalogue", files }),
});
for (const [i, item] of check.items.entries()) {
  await call("https://ky.ax" + item.upload_url, {
    method: "PUT",
    headers: { "Content-Type": "application/octet-stream" },
    body: await readFile(paths[i]),
  });
}

curl https://ky.ax/api/v1/check \
  -H "Authorization: Bearer $KY_API_KEY" \
  -F "file=@verse.mid" \
  -F "file=@chorus.mid"

# or one file as the body
curl https://ky.ax/api/v1/check \
  -H "Authorization: Bearer $KY_API_KEY" \
  -H "Content-Type: audio/midi" \
  -H "X-Ky-Filename: my-song.mid" \
  --data-binary @my-song.mid

files = [("file", (name, open(name, "rb"), "audio/midi"))
         for name in ["verse.mid", "chorus.mid"]]
r = requests.post("https://ky.ax/api/v1/check", headers=H, files=files)

const form = new FormData();
for (const name of ["verse.mid", "chorus.mid"]) {
  form.append("file", new Blob([await readFile(name)], { type: "audio/midi" }), name);
}
await fetch("https://ky.ax/api/v1/check", { method: "POST", headers, body: form });

curl https://ky.ax/api/v1/checks/c_8Hq2x0VnY1aK3mPq7RtZ9w \
  -H "Authorization: Bearer $KY_API_KEY"

check = requests.get(f"{API}/checks/{check_id}", headers=H).json()
for item in check["items"]:
    if item["status"] == "done":
        print(item["verdict"], item["headline"])
        for f in item["findings"]:
            print(" ", f["work"]["title"], f["relationship"], f["proportion_of_yours"])

const check = await call(`${API}/checks/${id}`);
for (const item of check.items.filter((i) => i.status === "done")) {
  console.log(item.verdict, item.headline);
  for (const f of item.findings) console.log(" ", f.work.title, f.relationship, f.proportion_of_yours);
}

curl https://ky.ax/api/v1/check \
  -H "Authorization: Bearer $KY_API_KEY" \
  -F "mode=pairwise" \
  -F "file=@take-1.mid" \
  -F "file=@take-2.mid" \
  -F "file=@take-3.mid"

names = ["take-1.mid", "take-2.mid", "take-3.mid"]
r = requests.post(f"{API}/check", headers=H, data={"mode": "pairwise"},
                  files=[("file", (n, open(n, "rb"), "audio/midi")) for n in names])

const form = new FormData();
form.append("mode", "pairwise");
for (const n of ["take-1.mid", "take-2.mid", "take-3.mid"]) {
  form.append("file", new Blob([await readFile(n)], { type: "audio/midi" }), n);
}
await call(`${API}/check`, { method: "POST", body: form });

curl "https://ky.ax/api/v1/checks?limit=20" \
  -H "Authorization: Bearer $KY_API_KEY"

curl -X DELETE https://ky.ax/api/v1/checks/c_8Hq2x0VnY1aK3mPq7RtZ9w \
  -H "Authorization: Bearer $KY_API_KEY"

checks, cursor = [], None
while True:
    page = requests.get(f"{API}/checks", headers=H,
                        params={"limit": 100, **({"cursor": cursor} if cursor else {})}).json()
    checks += page["checks"]
    cursor = page["next_cursor"]
    if not cursor:
        break

requests.delete(f"{API}/checks/{checks[-1]['id']}", headers=H).raise_for_status()

const checks = [];
let cursor = null;
do {
  const q = new URLSearchParams({ limit: "100", ...(cursor ? { cursor } : {}) });
  const page = await call(`${API}/checks?${q}`);
  checks.push(...page.checks);
  cursor = page.next_cursor;
} while (cursor);

await call(`${API}/checks/${checks.at(-1).id}`, { method: "DELETE" });

curl https://ky.ax/api/v1/usage \
  -H "Authorization: Bearer $KY_API_KEY"

curl https://ky.ax/api/v1/billing \
  -H "Authorization: Bearer $KY_API_KEY"

usage = requests.get(f"{API}/usage", headers=H).json()
f = usage["files"]
print(f"{f['used']} files used, {f['left']} left this period")

const usage = await call(`${API}/usage`);
const { used, left } = usage.files;
console.log(`${used} files used, ${left} left this period`);

curl https://ky.ax/api/status

status = requests.get("https://ky.ax/api/status").json()
print(status["audio"]["max_bytes"], status["audio"]["daily_user"])

const status = await (await fetch("https://ky.ax/api/status")).json();
console.log(status.audio.max_bytes, status.audio.daily_user);