Driving Burst Desk from code

Everything the web app does is available over HTTP. The base URL is https://api.skillsafe.ai/v1/app-api, every request carries Authorization: Bearer <token>, and every response is the same envelope.

The `task` field comes first

This app has five lanes behind one endpoint. Every run body must carry a task field naming the lane - it is what the system prompt routes on. Send the wrong one and you get a valid package of the wrong kind; omit it and the model picks the closest lane and tells you which it chose.

One more shape trap: the run body is the input object. Do not wrap it in an {"input": ...} envelope - that returns 200 while hiding task from the model, which is the most confusing way this API can fail.

task Lane Fields Sections returned

plan Turn an API and its traffic into a sheet brief, known Summary, The Sheet, What It Assumes, Reasoning, Next Step

read What each limit admits, as opposed to what it says sheet, worry Summary, Verdict, Findings, Corrected Sheet, Next Step

edges The edges: the boundary, the burst, and the exact reference sheet Summary, Every Rule Against The Exact Reference, Where The Extra Requests Come From, The Test That Finds Each One, Next Step

keys The keys: what the multiplication puts in front of the backend sheet Summary, Every Rule Times Its Keys, What The Backend Sees, What Would Actually Bound It, Next Step

decide Decide what changes: the algorithm, the number, or the caller sheet, fixed Summary, A Different Algorithm Closes, A Different Number Closes, Only The Caller Closes, Nothing Closes - The Property Is The Point, Next Step

task	Lane	Fields	Sections returned
`plan`	Turn an API and its traffic into a sheet	`brief, known`	Summary, The Sheet, What It Assumes, Reasoning, Next Step
`read`	What each limit admits, as opposed to what it says	`sheet, worry`	Summary, Verdict, Findings, Corrected Sheet, Next Step
`edges`	The edges: the boundary, the burst, and the exact reference	`sheet`	Summary, Every Rule Against The Exact Reference, Where The Extra Requests Come From, The Test That Finds Each One, Next Step
`keys`	The keys: what the multiplication puts in front of the backend	`sheet`	Summary, Every Rule Times Its Keys, What The Backend Sees, What Would Actually Bound It, Next Step
`decide`	Decide what changes: the algorithm, the number, or the caller	`sheet, fixed`	Summary, A Different Algorithm Closes, A Different Number Closes, Only The Caller Closes, Nothing Closes - The Property Is The Point, Next Step

Only task and the lane’s own required fields are mandatory: sheet on read, edges, keys and decide; brief on plan. Every field is a string - there are no number fields on this app. sheet is the limit sheet itself: a header of KEY: value lines, then a LIMITS: block with one rule per line.

The header is where a rule becomes a verdict. BACKEND: is what the service behind the limits can take, as a rate - 800/s. Without it the response can compute every figure and conclude nothing. KEYS: is how many distinct keys exist, and it is the multiplier on every per-key rule: a limit of 100/min is either 1.67/s or 13,333/s depending on it. CLIENTS: takes retry, drop or queue and decides whether the rejects come back. GATE: names the one rule that fronts ALL the traffic, if there is one. WINDOW: and SERVICE: are defaults for rules that give a bare count or omit a service time.

A rule needs a name and an algorithm and then a limit= - except debounce and throttle, which need delay= instead. The algorithm word takes the aliases a real config uses: fixed/fixed-window, sliding (the log, and the only exact one), counter/sliding-window-counter, bucket/token-bucket, leaky/gcra, concurrency/in-flight/semaphore, debounce and throttle. Anything else is reported as an unknown algorithm rather than guessed at.

limit= takes 100/min, 10/s, 5/15min or a bare count. A bare count is a COUNT, not a rate - the window comes from window=, the WINDOW: header or the default, and the response says which, because guessing per-second where the config means per-minute is a sixtyfold error in the direction nobody checks. burst= is a bucket’s capacity; leave it off and it defaults to the limit, which is what every implementation does and is why the burst gets forgotten. scope= takes key, ip, global, user, tenant, endpoint, account or token, and everything except global multiplies. service= turns a concurrency limit into a rate; without it the row is undefined and is left out of every total. offered= is the traffic that arrives - without it the response says what a rule admits but not what it rejects. shape= takes steady, bursty, spiky, front or back, and decides which way a sliding counter’s error points.

Everything in the response is one comparison: what a rule SAYS against what it ADMITS. A fixed window admits exactly twice its limit at the boundary - two adjacent counters, not a margin to tune. A token bucket admits B + floor(r × elapsed), so its capacity arrives in one instant. A sliding counter is an estimate that errs both ways by up to the limit. A concurrency limit admits c/S per second. A debounce is a step at the delay. Only a sliding window log admits exactly what it says.

And the keys are the largest number on the page. A limit of N per key with K keys admits N × K, which is what the service sees. A globally-scoped rule bounds its own route; only a rule declared with GATE: bounds all the traffic, and that declaration is your claim rather than something this API can verify.

Anything the reader cannot place is listed as a problem rather than skipped: an unknown header key or an unreadable header value, a line outside a block, a rule with no algorithm or an unknown one, a missing or unreadable limit, an unknown field, extra words on the line and a duplicate name, each with its line number. A sheet with no readable rules is an error.

Rates come back in whichever unit reads best - 13,333/s, 1.67/min - counts as integers, gaps as multiples like 2×. These are ceilings, not descriptions of your traffic: no load is generated and no gateway is read, so the worst window is what the algorithm permits rather than what your callers do, and offered= is one number where real traffic has a shape.

Add $model to any body to choose the model for that run: gpt-5.6-luna, gpt-5.6-terra (the default) or gpt-5.6-sol. Luna caps output at 4,096 tokens and will fail the read, edges, keys and decide lanes rather than shorten them - a findings table, a corrected sheet, or three tables with a row per rule, is several thousand characters before the reasoning starts.

The response envelope

Success and failure have the same outer shape, so one check covers both.

{
  "ok": true,
  "data": {
    "...": "the result"
  }
}

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "seconds should be number, got string",
    "details": {}
  }
}

HTTP error.code What it means

400 VALIDATION_ERROR The body was not a JSON object, or a declared field had the wrong type. A number field sent as a string is the usual cause.

401 UNAUTHORIZED No token, or a token that has expired or been revoked. Mint a new one.

402 INSUFFICIENT_CREDITS The balance is below the run's minimum. Call /estimate first and compare hold_credits against /me.

404 NOT_FOUND Wrong path, or a job id that does not belong to this token.

409 CONFLICT An Idempotency-Key replay whose body differs from the original request.

429 RATE_LIMITED Too many requests. Back off; do not tight-loop.

503 UPSTREAM_UNAVAILABLE The model provider is unavailable. Retry with backoff.

HTTP	error.code	What it means
`400`	`VALIDATION_ERROR`	The body was not a JSON object, or a declared field had the wrong type. A number field sent as a string is the usual cause.
`401`	`UNAUTHORIZED`	No token, or a token that has expired or been revoked. Mint a new one.
`402`	`INSUFFICIENT_CREDITS`	The balance is below the run's minimum. Call /estimate first and compare hold_credits against /me.
`404`	`NOT_FOUND`	Wrong path, or a job id that does not belong to this token.
`409`	`CONFLICT`	An Idempotency-Key replay whose body differs from the original request.
`429`	`RATE_LIMITED`	Too many requests. Back off; do not tight-loop.
`503`	`UPSTREAM_UNAVAILABLE`	The model provider is unavailable. Retry with backoff.

1. Get a token

Open /tokens.html in a browser and copy the token this app already holds - no developer console needed. A guest token is minted automatically and is enough for /me and /estimate; writing a package is metered and needs a personal token, which comes from signing in on that page.

Keep it in an environment variable rather than in source:

export SKILLSAFE_TOKEN="YOUR_TOKEN"

2. Check the session and the balance

GET /me is free. It returns only three fields: subject_type, subject_id and credits. Signed-in means subject_type == "user" - there is no username or email to test.

curl -sS -X GET "https://api.skillsafe.ai/v1/app-api/me" \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN"

import json, urllib.request

TOKEN = "YOUR_TOKEN"   # from /tokens.html
BASE  = "https://api.skillsafe.ai/v1/app-api"

def call(method, path, payload=None, headers=None):
    data = json.dumps(payload).encode() if payload is not None else None
    req = urllib.request.Request(BASE + path, data=data, method=method)
    req.add_header("Authorization", "Bearer " + TOKEN)
    req.add_header("Content-Type", "application/json")
    req.add_header("Accept", "application/json")
    # A plain urllib request with no User-Agent is refused with 403.
    req.add_header("User-Agent", "burst-desk-client/1.0")
    for k, v in (headers or {}).items():
        req.add_header(k, v)
    with urllib.request.urlopen(req) as r:
        return json.loads(r.read())

out = call("GET", "/me")
print(json.dumps(out["data"], indent=2))

const TOKEN = "YOUR_TOKEN";   // from /tokens.html
const BASE  = "https://api.skillsafe.ai/v1/app-api";

async function call(method, path, payload) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "Content-Type": "application/json"
    },
    body: payload === undefined ? undefined : JSON.stringify(payload)
  });
  const json = await res.json();
  if (!res.ok || !json.ok) throw new Error(json.error?.message || res.statusText);
  return json.data;
}

const data = await call("GET", "/me");
console.log(data);

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

const base = "https://api.skillsafe.ai/v1/app-api"
const token = "YOUR_TOKEN" // from /tokens.html

func main() {
	req, _ := http.NewRequest("GET", base+"/me", nil)
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

import java.net.URI;
import java.net.http.*;

public class Main {
    static final String BASE  = "https://api.skillsafe.ai/v1/app-api";
    static final String TOKEN = "YOUR_TOKEN"; // from /tokens.html

    public static void main(String[] args) throws Exception {
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(BASE + "/me"))
            .header("Authorization", "Bearer " + TOKEN)
            .header("Content-Type", "application/json")
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();
        HttpResponse<String> res = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(res.body());
    }
}

require 'net/http'
require 'json'
require 'uri'

BASE  = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN" # from /tokens.html

uri = URI("#{BASE}/me")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{TOKEN}"
req["Content-Type"] = "application/json"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
puts JSON.pretty_generate(JSON.parse(res.body)["data"])

<?php
$base  = "https://api.skillsafe.ai/v1/app-api";
$token = "YOUR_TOKEN"; // from /tokens.html

$opts = ["http" => [
    "method"  => "GET",
    "header"  => "Authorization: Bearer $token\r\nContent-Type: application/json\r\n",
]];
$res  = file_get_contents($base . "/me", false, stream_context_create($opts));
$json = json_decode($res, true);
print_r($json["data"]);

using System.Net.Http;
using System.Text;

const string Base  = "https://api.skillsafe.ai/v1/app-api";
const string Token = "YOUR_TOKEN"; // from /tokens.html

var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", $"Bearer {Token}");

var res = await http.SendAsync(new HttpRequestMessage(new HttpMethod("GET"), Base + "/me")
{
    Content = null
});
Console.WriteLine(await res.Content.ReadAsStringAsync());

3. Price the run before making it

POST /estimate costs nothing, creates no job, and returns the worst-case cost. Compare hold_credits against the balance from step 2 before you submit: a 402 after the fact is avoidable. hold_credits is a reservation priced at the full output cap - the actual charge is usually far lower.

It also echoes model, model_alias and markup_bps, which is the authoritative check that a run is bound to the model you think it is. Estimate each lane separately: their prompts and caps differ, so their holds do.

curl -sS -X POST "https://api.skillsafe.ai/v1/app-api/estimate" \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}'

import json, urllib.request

TOKEN = "YOUR_TOKEN"   # from /tokens.html
BASE  = "https://api.skillsafe.ai/v1/app-api"

def call(method, path, payload=None, headers=None):
    data = json.dumps(payload).encode() if payload is not None else None
    req = urllib.request.Request(BASE + path, data=data, method=method)
    req.add_header("Authorization", "Bearer " + TOKEN)
    req.add_header("Content-Type", "application/json")
    req.add_header("Accept", "application/json")
    # A plain urllib request with no User-Agent is refused with 403.
    req.add_header("User-Agent", "burst-desk-client/1.0")
    for k, v in (headers or {}).items():
        req.add_header(k, v)
    with urllib.request.urlopen(req) as r:
        return json.loads(r.read())

payload = {
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}
out = call("POST", "/estimate", payload)
print(out["data"]["hold_credits"], out["data"]["model"])

const TOKEN = "YOUR_TOKEN";   // from /tokens.html
const BASE  = "https://api.skillsafe.ai/v1/app-api";

async function call(method, path, payload) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "Content-Type": "application/json"
    },
    body: payload === undefined ? undefined : JSON.stringify(payload)
  });
  const json = await res.json();
  if (!res.ok || !json.ok) throw new Error(json.error?.message || res.statusText);
  return json.data;
}

const payload = {
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
};
const data = await call("POST", "/estimate", payload);
console.log(data.hold_credits, data.model, data.model_alias);

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

const base = "https://api.skillsafe.ai/v1/app-api"
const token = "YOUR_TOKEN" // from /tokens.html

func main() {
	payload := []byte(`{
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}`)
	req, _ := http.NewRequest("POST", base+"/estimate", bytes.NewReader(payload))
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

import java.net.URI;
import java.net.http.*;

public class Main {
    static final String BASE  = "https://api.skillsafe.ai/v1/app-api";
    static final String TOKEN = "YOUR_TOKEN"; // from /tokens.html

    public static void main(String[] args) throws Exception {
        String payload = """
{
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}
""";
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(BASE + "/estimate"))
            .header("Authorization", "Bearer " + TOKEN)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();
        HttpResponse<String> res = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(res.body());
    }
}

require 'net/http'
require 'json'
require 'uri'

BASE  = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN" # from /tokens.html

payload = {
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}

uri = URI("#{BASE}/estimate")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{TOKEN}"
req["Content-Type"] = "application/json"
req.body = JSON.dump(payload)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
puts JSON.pretty_generate(JSON.parse(res.body)["data"])

<?php
$base  = "https://api.skillsafe.ai/v1/app-api";
$token = "YOUR_TOKEN"; // from /tokens.html

$payload = json_encode([
  "task" => "read",
  "sheet" => "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry" => "we get a spike on the hour that the limits should have stopped",
  "rules" => "<the working rules for this lane, sent by the app>"
]);

$opts = ["http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer $token\r\nContent-Type: application/json\r\n",
    "content" => $payload,
]];
$res  = file_get_contents($base . "/estimate", false, stream_context_create($opts));
$json = json_decode($res, true);
print_r($json["data"]);

using System.Net.Http;
using System.Text;

const string Base  = "https://api.skillsafe.ai/v1/app-api";
const string Token = "YOUR_TOKEN"; // from /tokens.html

var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", $"Bearer {Token}");

var payload = """
{
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}
""";
var content = new StringContent(payload, Encoding.UTF8, "application/json");
var res = await http.SendAsync(new HttpRequestMessage(new HttpMethod("POST"), Base + "/estimate")
{
    Content = content
});
Console.WriteLine(await res.Content.ReadAsStringAsync());

4. Write a package

POST /run submits the job. Always send an Idempotency-Key: a network blip that replays the same request must not bill twice. A replay with the same key returns the stored result and is not charged again; a replay with the same key but a different body is a 409.

The response carries output.output (the Markdown package), charged_credits and truncated. If truncated is true the balance sat between min_credits and hold_credits and the output was cut short - render what arrived and say so rather than presenting it as complete.

curl -sS -X POST "https://api.skillsafe.ai/v1/app-api/run" \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}'

import json, urllib.request

TOKEN = "YOUR_TOKEN"   # from /tokens.html
BASE  = "https://api.skillsafe.ai/v1/app-api"

def call(method, path, payload=None, headers=None):
    data = json.dumps(payload).encode() if payload is not None else None
    req = urllib.request.Request(BASE + path, data=data, method=method)
    req.add_header("Authorization", "Bearer " + TOKEN)
    req.add_header("Content-Type", "application/json")
    req.add_header("Accept", "application/json")
    # A plain urllib request with no User-Agent is refused with 403.
    req.add_header("User-Agent", "burst-desk-client/1.0")
    for k, v in (headers or {}).items():
        req.add_header(k, v)
    with urllib.request.urlopen(req) as r:
        return json.loads(r.read())

payload = {
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}
out = call("POST", "/run", payload)
print(out["data"]["output"]["output"])

const TOKEN = "YOUR_TOKEN";   // from /tokens.html
const BASE  = "https://api.skillsafe.ai/v1/app-api";

async function call(method, path, payload) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "Content-Type": "application/json"
    },
    body: payload === undefined ? undefined : JSON.stringify(payload)
  });
  const json = await res.json();
  if (!res.ok || !json.ok) throw new Error(json.error?.message || res.statusText);
  return json.data;
}

const payload = {
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
};
const data = await call("POST", "/run", payload);
console.log(data.output.output);

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

const base = "https://api.skillsafe.ai/v1/app-api"
const token = "YOUR_TOKEN" // from /tokens.html

func main() {
	payload := []byte(`{
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}`)
	req, _ := http.NewRequest("POST", base+"/run", bytes.NewReader(payload))
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

import java.net.URI;
import java.net.http.*;

public class Main {
    static final String BASE  = "https://api.skillsafe.ai/v1/app-api";
    static final String TOKEN = "YOUR_TOKEN"; // from /tokens.html

    public static void main(String[] args) throws Exception {
        String payload = """
{
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}
""";
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(BASE + "/run"))
            .header("Authorization", "Bearer " + TOKEN)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();
        HttpResponse<String> res = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(res.body());
    }
}

require 'net/http'
require 'json'
require 'uri'

BASE  = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN" # from /tokens.html

payload = {
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}

uri = URI("#{BASE}/run")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{TOKEN}"
req["Content-Type"] = "application/json"
req.body = JSON.dump(payload)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
puts JSON.pretty_generate(JSON.parse(res.body)["data"])

<?php
$base  = "https://api.skillsafe.ai/v1/app-api";
$token = "YOUR_TOKEN"; // from /tokens.html

$payload = json_encode([
  "task" => "read",
  "sheet" => "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry" => "we get a spike on the hour that the limits should have stopped",
  "rules" => "<the working rules for this lane, sent by the app>"
]);

$opts = ["http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer $token\r\nContent-Type: application/json\r\n",
    "content" => $payload,
]];
$res  = file_get_contents($base . "/run", false, stream_context_create($opts));
$json = json_decode($res, true);
print_r($json["data"]);

using System.Net.Http;
using System.Text;

const string Base  = "https://api.skillsafe.ai/v1/app-api";
const string Token = "YOUR_TOKEN"; // from /tokens.html

var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", $"Bearer {Token}");

var payload = """
{
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}
""";
var content = new StringContent(payload, Encoding.UTF8, "application/json");
var res = await http.SendAsync(new HttpRequestMessage(new HttpMethod("POST"), Base + "/run")
{
    Content = content
});
Console.WriteLine(await res.Content.ReadAsStringAsync());

5. Stream a run

POST /run-stream is the same call with a text/event-stream response. Worth knowing before you build on it: from a server or from cURL you get event: delta frames carrying the output token by token; from a browser you get event: tick heartbeats and then one event: done with the whole output. Handle both, and treat ticks as liveness rather than progress.

Frame types are job (the job id), delta ({"text": "..."}), tick ({"t": seconds}), done, and error. An idempotent replay returns plain JSON with no stream at all, so check the content type before you start reading frames.

curl -sS -N -X POST "https://api.skillsafe.ai/v1/app-api/run-stream" \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "Idempotency-Key: cbd-$(date +%s)" \
  -d '{
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}'

import json, urllib.request

TOKEN = "YOUR_TOKEN"
BASE  = "https://api.skillsafe.ai/v1/app-api"

payload = {
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}

req = urllib.request.Request(BASE + "/run-stream", data=json.dumps(payload).encode(), method="POST")
req.add_header("Authorization", "Bearer " + TOKEN)
req.add_header("Content-Type", "application/json")
req.add_header("Accept", "text/event-stream")
req.add_header("Idempotency-Key", "cbd-demo-1")
req.add_header("User-Agent", "burst-desk-client/1.0")

event, data = "message", ""
with urllib.request.urlopen(req) as r:
    for raw in r:
        line = raw.decode().rstrip("\n")
        if line.startswith("event:"):
            event = line[6:].strip()
        elif line.startswith("data:"):
            data += line[5:].strip()
        elif line == "":
            if data:
                frame = json.loads(data)
                if event == "delta":
                    print(frame.get("text", ""), end="")
                elif event == "done":
                    print("\n--- charged:", frame.get("charged_credits"))
            event, data = "message", ""

const TOKEN = "YOUR_TOKEN";
const BASE  = "https://api.skillsafe.ai/v1/app-api";

const payload = {
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
};

const res = await fetch(BASE + "/run-stream", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "cbd-demo-1"
  },
  body: JSON.stringify(payload)
});

// An idempotent replay comes back as plain JSON with no stream at all.
if (!(res.headers.get("content-type") || "").includes("text/event-stream")) {
  const json = await res.json();
  console.log(json.data.output.output);
} else {
  const reader = res.body.getReader();
  const dec = new TextDecoder();
  let buf = "";
  for (;;) {
    const { done, value } = await reader.read();
    if (done) break;
    buf += dec.decode(value, { stream: true });
    let i;
    while ((i = buf.indexOf("\n\n")) >= 0) {
      const frame = buf.slice(0, i);
      buf = buf.slice(i + 2);
      let name = "message", data = "";
      for (const line of frame.split("\n")) {
        if (line.startsWith("event:")) name = line.slice(6).trim();
        else if (line.startsWith("data:")) data += line.slice(5).trim();
      }
      if (!data) continue;
      const p = JSON.parse(data);
      if (name === "delta") process.stdout.write(p.text || "");
      if (name === "tick") console.error("still writing:", p.t + "s");
      if (name === "done") console.log("\ncharged:", p.charged_credits);
    }
  }
}

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

const base = "https://api.skillsafe.ai/v1/app-api"
const token = "YOUR_TOKEN" // from /tokens.html

func main() {
	payload := []byte(`{
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}`)
	req, _ := http.NewRequest("POST", base+"/run-stream", bytes.NewReader(payload))
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

import java.net.URI;
import java.net.http.*;

public class Main {
    static final String BASE  = "https://api.skillsafe.ai/v1/app-api";
    static final String TOKEN = "YOUR_TOKEN"; // from /tokens.html

    public static void main(String[] args) throws Exception {
        String payload = """
{
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}
""";
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(BASE + "/run-stream"))
            .header("Authorization", "Bearer " + TOKEN)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();
        HttpResponse<String> res = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(res.body());
    }
}

require 'net/http'
require 'json'
require 'uri'

BASE  = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN" # from /tokens.html

payload = {
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}

uri = URI("#{BASE}/run-stream")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{TOKEN}"
req["Content-Type"] = "application/json"
req.body = JSON.dump(payload)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
puts JSON.pretty_generate(JSON.parse(res.body)["data"])

<?php
$base  = "https://api.skillsafe.ai/v1/app-api";
$token = "YOUR_TOKEN"; // from /tokens.html

$payload = json_encode([
  "task" => "read",
  "sheet" => "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry" => "we get a spike on the hour that the limits should have stopped",
  "rules" => "<the working rules for this lane, sent by the app>"
]);

$opts = ["http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer $token\r\nContent-Type: application/json\r\n",
    "content" => $payload,
]];
$res  = file_get_contents($base . "/run-stream", false, stream_context_create($opts));
$json = json_decode($res, true);
print_r($json["data"]);

using System.Net.Http;
using System.Text;

const string Base  = "https://api.skillsafe.ai/v1/app-api";
const string Token = "YOUR_TOKEN"; // from /tokens.html

var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", $"Bearer {Token}");

var payload = """
{
  "task": "read",
  "sheet": "<BACKEND/KEYS/CLIENTS/GATE header, then a LIMITS block with one rule per line; the grammar is in /llms.txt>",
  "worry": "we get a spike on the hour that the limits should have stopped",
  "rules": "<the working rules for this lane, sent by the app>"
}
""";
var content = new StringContent(payload, Encoding.UTF8, "application/json");
var res = await http.SendAsync(new HttpRequestMessage(new HttpMethod("POST"), Base + "/run-stream")
{
    Content = content
});
Console.WriteLine(await res.Content.ReadAsStringAsync());

6. Read the result

output.output is Markdown in the envelope this app's system prompt guarantees: every section is a level-two heading spelled exactly as listed in the lane table above, in that order; tables are GitHub pipe tables with the declared columns; prompts are in fenced blocks opened with three backticks and the word text; checklists are - [x] lines.

So parsing is a split on /^## / - but do it fence-aware, because a prompt block can legitimately contain a line starting with ##. Count the sections you got against the ones the lane declares: a short list means the run was truncated, not that the contract changed.

def sections(md):
    out, name, buf, fence = {}, None, [], False
    for line in md.split("\n"):
        if line.lstrip().startswith("```"):
            fence = not fence
        if not fence and line.startswith("## "):
            if name:
                out[name] = "\n".join(buf).strip()
            name, buf = line[3:].strip(), []
            continue
        if name:
            buf.append(line)
    if name:
        out[name] = "\n".join(buf).strip()
    return out

The artifact most callers want is the fenced text block inside ## The Sheet or ## Corrected Sheet - that is a complete sheet in the grammar above, so it can be fed straight back into another lane with nothing carried alongside it. Every other section is prose and tables meant to be read.

Rate limits and good manners

/estimate and /me are free. Call them as much as you like, within reason.
A 429 means back off with a delay, not retry immediately.
Send an Idempotency-Key on every /run. Derive it from a hash of the body plus an attempt counter, so a retry of the same request reuses the key and a deliberate re-run gets a new one.
The engine in the web app is client-side only and has no endpoint. What it computes is published in full in llms.txt, and every part of it is a rule you can apply yourself. The boundary factor is 2 because two adjacent counters each admit their limit and a sliding window of the same length can contain the end of one and the start of the other - it does not depend on the window length and it is not a safety margin. A token bucket admits B + floor(r × elapsed); the floor matters at exactly the boundary that matters, because over the half-open window [0, 1000) a bucket of 50 at 10/s admits 59 rather than 60. Per-key limits multiply by N × K, and a faithful per-key limit is ceiling ÷ keys - shown so you can see why it is not an option. A concurrency limit is c/S per second, which is why it tightens on its own when the backend slows and why it cannot be compared with a rate limit at face value. A debounce is a step at the delay, not a ratio. Every one of those closed forms is checked in this app’s harness against a DISCRETE-EVENT SIMULATOR that walks a request stream through each limiter and counts the admissions, sharing no code and no formula with the arithmetic - which is where a simulation belongs. It reads a SHEET, not a gateway: no load is generated, no config is inspected and no metrics are read, so every figure is a consequence of the numbers you send. The worst window is a CEILING - what the algorithm permits, not what your callers do; a client that never synchronises with a window edge never reaches it and a cron fleet reaches it every time. offered= is one number for a whole window and real traffic has a shape, which is why a sliding counter’s error direction is a hint rather than a calculation. The key count is the load-bearing assumption, it is usually the number nobody owns, and “keys that exist” and “keys that called this hour” differ by an order of magnitude in most systems. A GATE: is your claim that a rule fronts everything - if an internal caller, a second route or a cache-miss path bypasses it, the bound it provides is imaginary and every verdict resting on it is wrong. And it does not model queuing, priority, fairness between keys under contention, or anything downstream of admission: a limiter admitting within the ceiling can still produce a latency problem. Every rule with its worst window, its product and its gap, and every caller figure, are sent with each run as prescan, and the system prompt requires answering them.