← Interface Desk / API
Tokens

Drive Interface Desk from your own code

The page does its free work in the browser: it reads the brief against the design-an-interface skill's five requirement questions, lists the key operations, counts the entry points and parameters of every signature and assigns each design its constraint. Its two paid lanes are available over HTTP. You send one JSON object with task set to "designs" or "compare", and the model replies with one JSON object. The easiest way to build the input is the page itself: IfaceKit.buildInput(IfaceKit.analyze({module, language, brief, sketch, designs, count, paradigm}), lane) in ifacekit.js, which also runs under Node; Recon.reconcile(reply, {A, K: IfaceKit, lane, sent}) in recon.js runs the page's checks on a normalised reply.

Base URL: https://api.skillsafe.ai/v1/app-api. Every call sends Content-Type: application/json and, once you have a token, Authorization: Bearer <token>. Both lanes run on gpt-terra with a 10% publisher markup. A run needs a signed-in (user) token and is metered: the platform holds the estimate's hold_credits while the run is in flight and then charges only what it used (charged_credits). /estimate is free. A plain-text summary is at /llms.txt.

The response envelope

Every response is {"data": ..., "error": null} on success or {"data": null, "error": {"code", "message"}} on failure.

Error codes

HTTPcodemeaning
400VALIDATION_ERRORThe body is not a JSON object, a required field is missing, or a field is the wrong type. Every field of the run input is a string.
401UNAUTHORIZEDNo token, or an expired one: get a new one (step 2).
402INSUFFICIENT_CREDITSThe balance is below the run's minimum. Top up at skillsafe.ai/account/billing/.
403FORBIDDENA guest token tried a metered run: sign in for a personal token.
404NOT_FOUNDUnknown job id.
429RATE_LIMITEDBack off and retry with the same Idempotency-Key.

The task field

Two lanes, in the order a person meets them:

Input fields (all strings)

fieldwhencontent
taskrequireddesigns or compare
modulerequiredThe module's name, e.g. rate limiter.
languagerequiredOne of TypeScript, JavaScript, Python, Go, Rust, Java, C#, Kotlin, Swift.
briefrequiredThe module brief, up to 8,000 characters (the page cuts lines from the middle beyond that and marks the cut).
sketchdesigns, optionalYour own first interface idea, up to 4,000 characters - context, never one of the designs.
designscompare onlyA JSON string: [{id, name, constraint, signature[], usage[], hides[], tradeoffs[]}], at most 14,000 characters.
factsrequiredA JSON string: brief{answered[], missing[], operations[], callers[], constraints[], hidden[]}, assign[{id, constraint}] (designs), metrics (per design for compare: {entry_points[], params, max_params, flag_params, types[], implemented[]} - implemented lists methods of an injected interface, which the caller implements and which are not entry points; for designs, the sketch's), clip.
retry_noteoptionalOnly on a reformat retry: what was wrong with the previous reply.

The reply contract

designs: task, task_note, requirements{problem, callers[], operations[], constraints[], hidden[], assumed[]}, designs[{id, name, constraint, signature[], usage[], hides[], tradeoffs[], covers[{operation, via}]}] (one per facts.assign, in order), headline, summary.

compare: task, task_note, criteria[{criterion: simplicity|general_purpose|efficiency|depth|misuse, discussion, favours}] (exactly five, in that order; favours a design id or tie), divergence[], synthesis{base, borrowed[{from, element, why}], signature[], usage[], rationale}, questions[], headline, summary. Code is always an array of lines. Neither lane states a measurement: the page counts.

Worked examples

These are the page's own bundled examples (invented modules and callers), with the input as app.js builds it and the saved model reply the page replays for free - two for designs, one for compare.

designs: a rate limiter for an API gateway, TypeScript, three designs

Input (the brief shown separately, facts shortened here):

{
 "task": "designs",
 "module": "rate limiter",
 "language": "TypeScript",
 "brief": "(a string - shown below)",
 "sketch": "",
 "facts": "(a JSON string; decoded: 5 of 5 questions answered, 4 key operations; assigns A: Minimize method count - aim for 1-3 methods max; B: Maximize flexibility - support many use cases; C: Optimize for the most common case)"
}

brief:

# Rate limiter for the Quillmere API gateway

Problem: one noisy tenant can starve every other tenant on the shared gateway. We need a per-tenant rate limiter that the
gateway consults before it forwards a request, and that the admin console can query.

Callers:
- the HTTP middleware in the gateway, once per incoming request (hot path)
- the admin console, to show a tenant's remaining quota and to lift a limit after a plan upgrade
- integration tests, which need to advance time without sleeping

Operations:
- check whether a request may proceed, and if not, how long the caller should wait
- report the remaining quota for a tenant
- reset a tenant's usage after a plan upgrade
- change a tenant's limits without restarting the gateway

Constraints:
- the check must add well under a millisecond on the hot path
- state lives in memory on one node today; a shared Redis store is planned for next quarter, and callers must not change when it arrives
- the gateway code base is TypeScript on Node 22 and uses async/await throughout
- some routes cost more than others: a bulk export counts as 10 ordinary requests

Hidden:
- the token-bucket arithmetic and refill timing
- where the counters are stored (memory now, Redis later)
- clock handling, so tests can control time

Reply:

{
 "task": "designs",
 "task_note": "",
 "requirements": {
  "problem": "One noisy tenant can starve every other tenant on the shared Quillmere API gateway. The module is a per-tenant rate limiter that the gateway consults before forwarding a request and that the admin console can query.",
  "callers": [
   "the HTTP middleware in the gateway, once per incoming request (hot path)",
   "the admin console, to show a tenant's remaining quota and to lift a limit after a plan upgrade",
   "integration tests, which need to advance time without sleeping"
  ],
  "operations": [
   "check whether a request may proceed, and if not, how long the caller should wait",
   "report the remaining quota for a tenant",
   "reset a tenant's usage after a plan upgrade",
   "change a tenant's limits without restarting the gateway"
  ],
  "constraints": [
   "the check must add well under a millisecond on the hot path",
   "state lives in memory on one node today; a shared Redis store is planned for next quarter, and callers must not change when it arrives",
   "the gateway code base is TypeScript on Node 22 and uses async/await throughout",
   "some routes cost more than others: a bulk export counts as 10 ordinary requests"
  ],
  "hidden": [
   "the token-bucket arithmetic and refill timing",
   "where the counters are stored (memory now, Redis later)",
   "clock handling, so tests can control time"
  ],
  "assumed": [
   "Every call is async (returns a Promise) even with the in-memory store, so callers need not change when the Redis store arrives.",
   "A tenant's limit can be expressed as a capacity plus a refill rate per second; the brief names token buckets but not the exact limit fields.",
   "Route cost is known by the gateway at check time, either as a number or as a route name looked up in a cost table."
  ]
 },
 "designs": [
  {
   "id": "A",
   "name": "Factory plus two verbs: admit and adjust",
   "constraint": "Minimize method count - aim for 1-3 methods max",
   "signature": [
    "type TenantId = string;",
    "",
    "interface Limits { capacity: number; refillPerSecond: number }",
    "",
    "interface LimiterConfig {",
    "  defaults: Limits;",
    "  store?: { kind: \"memory\" } | { kind: \"redis\"; url: string };",
    "  clock?: \"system\" | \"manual\";",
    "}",
    "",
    "interface Decision {",
    "  allowed: boolean;",
    "  remaining: number;",
    "  retryAfterMs: number;",
    "}",
    "",
    "type Change =",
    "  | { kind: \"reset\" }",
    "  | { kind: \"limits\"; limits: Limits }",
    "  | { kind: \"advanceClock\"; ms: number };",
    "",
    "interface Limiter {",
    "  admit(tenant: TenantId, cost: number): Promise<Decision>;",
    "  adjust(tenant: TenantId, change: Change): Promise<Decision>;",
    "}",
    "",
    "declare function createLimiter(config: LimiterConfig): Limiter;"
   ],
   "usage": [
    "const limiter = createLimiter({ defaults: { capacity: 100, refillPerSecond: 10 } });",
    "",
    "const d = await limiter.admit(tenantId, route === \"/export\" ? 10 : 1);",
    "if (!d.allowed) res.setHeader(\"Retry-After\", Math.ceil(d.retryAfterMs / 1000));",
    "",
    "// admin console: cost 0 peeks without consuming",
    "const { remaining } = await limiter.admit(tenantId, 0);",
    "await limiter.adjust(tenantId, { kind: \"limits\", limits: { capacity: 500, refillPerSecond: 50 } });",
    "await limiter.adjust(tenantId, { kind: \"reset\" });",
    "",
    "// tests, created with clock: \"manual\"",
    "await limiter.adjust(tenantId, { kind: \"advanceClock\", ms: 60_000 });"
   ],
   "hides": [
    "the token-bucket arithmetic and refill timing behind a single Decision value",
    "the choice of counter store, selected once in the config and invisible to admit and adjust",
    "clock handling: the manual clock exists only as a config switch and one Change variant",
    "every admin mutation behind one adjust entry point keyed by a discriminated union"
   ],
   "tradeoffs": [
    "Only three things to learn (createLimiter, admit, adjust); new admin actions become new Change variants, not new methods.",
    "Reporting remaining quota by admitting with cost 0 is a convention a reader must know;
... (shortened here; the page shows it whole)

designs: a feature-flag client in Python with a first sketch, four designs

Input (the brief and the sketch shown separately):

{
 "task": "designs",
 "module": "feature-flag client",
 "language": "Python",
 "brief": "(a string - shown below)",
 "sketch": "(a string - shown below)",
 "facts": "(a JSON string; decoded: 5 of 5 questions answered, 4 key operations; assigns A: Minimize method count - aim for 1-3 methods max; B: Maximize flexibility - support many use cases; C: Optimize for the most common case; D: Take inspiration from Python's logging module (named loggers in a dotted hierarchy))"
}

brief:

# Feature-flag client for the Fernhollow billing service

Problem: the billing service decides at runtime whether new behaviour is on for a customer - a new invoice layout, a
changed proration rule - and today it reads environment variables scattered through the code. We want one small client
module that answers "is this on for this customer?" consistently.

Callers:
- request handlers in the billing service (Django), many times per request
- nightly batch jobs that loop over every customer account
- unit tests, which must force a flag on or off without a network call

Operations:
- ask whether a boolean flag is on for a given customer
- get the chosen variant of a multi-variant experiment for a customer
- force a flag's value inside a test, and undo it afterwards
- list every flag the service evaluated during a request, for the audit log

Constraints:
- flag definitions come from a remote flag service; that service may be down, and a sensible default must apply
- evaluation must not make a network call per check - definitions are refreshed in the background every 30 seconds
- the code base is Python 3.12 with type hints checked by mypy in strict mode
- percentage rollouts must give a customer the same answer on every call

Hidden:
- the refresh loop and the cache of flag definitions
- the hashing that buckets customers into rollout percentages
- the HTTP client used to talk to the flag service

sketch:

class FlagClient:
    def __init__(self, service_url: str, api_key: str, refresh_seconds: int = 30) -> None: ...
    def is_enabled(self, flag: str, customer_id: str, default: bool = False) -> bool: ...
    def get_variant(self, flag: str, customer_id: str, default: str = "control") -> str: ...
    def override(self, flag: str, value: bool) -> None: ...
    def clear_override(self, flag: str) -> None: ...
    def evaluated_flags(self) -> list[str]: ...

Reply:

{
 "task": "designs",
 "task_note": "",
 "requirements": {
  "problem": "The Fernhollow billing service needs one small client that answers consistently whether new behaviour (a flag or an experiment variant) is on for a given customer, replacing environment variables scattered through the code.",
  "callers": [
   "request handlers in the billing service (Django), many times per request",
   "nightly batch jobs that loop over every customer account",
   "unit tests, which must force a flag on or off without a network call"
  ],
  "operations": [
   "ask whether a boolean flag is on for a given customer",
   "get the chosen variant of a multi-variant experiment for a customer",
   "force a flag's value inside a test, and undo it afterwards",
   "list every flag the service evaluated during a request, for the audit log"
  ],
  "constraints": [
   "flag definitions come from a remote flag service; that service may be down, and a sensible default must apply",
   "evaluation must not make a network call per check - definitions are refreshed in the background every 30 seconds",
   "the code base is Python 3.12 with type hints checked by mypy in strict mode",
   "percentage rollouts must give a customer the same answer on every call"
  ],
  "hidden": [
   "the refresh loop and the cache of flag definitions",
   "the hashing that buckets customers into rollout percentages",
   "the HTTP client used to talk to the flag service"
  ],
  "assumed": [
   "The service URL and API key are supplied once at process start-up (A, B, D); the brief does not say where they come from.",
   "A Django request carries an authenticated user from which the customer id can be read, and per-flag fallback defaults live in Django settings (C).",
   "Flag keys can be named as dotted paths such as 'billing.invoices.new_layout' (D).",
   "Each request is evaluated in its own context (thread or contextvar), so a per-request audit trail does not mix requests (A, C)."
  ]
 },
 "designs": [
  {
   "id": "A",
   "name": "Typed flag values + one evaluate() + one scope()",
   "constraint": "Minimize method count - aim for 1-3 methods max",
   "signature": [
    "from collections.abc import Iterator, Mapping",
    "from contextlib import contextmanager",
    "from dataclasses import dataclass",
    "from typing import Generic, TypeVar",
    "",
    "T = TypeVar('T', bool, str)",
    "",
    "@dataclass(frozen=True)",
    "class Flag(Generic[T]):",
    "    key: str",
    "    default: T",
    "",
    "def configure(service_url: str, api_key: str) -> None: ...",
    "",
    "def evaluate(flag: Flag[T], customer_id: str) -> T: ...",
    "",
    "@contextmanager",
    "def scope(pins: Mapping[str, bool | str] | None = None) -> Iterator[list[str]]: ..."
   ],
   "usage": [
    "NEW_INVOICE_LAYOUT = Flag('new-invoice-layout', default=False)",
    "PRORATION = Flag('proration-rule', default='control')",
    "",
    "with scope() as evaluated:",
    "    if evaluate(NEW_INVOICE_LAYOUT, customer.id):",
    "        render_new_layout(invoice)",
    "    rule = evaluate(PRORATION, customer.id)",
    "audit_log.record(flags=evaluated)",
    "",
    "def test_new_layout() -> None:",
    "    with scope(pins={'new-invoice-layout': True}):",
    "        assert evaluate(NEW_INVOICE_LAYOUT, 'cust-1') is True"
   ],
   "hides": [
    "the refresh loop and the cache of flag definitions, started by configure()",
    "the hashing that buckets customers into rollouts, inside evaluate()",
    "the HTTP client used to talk to the flag service",
    "the fallback to Flag.default when the flag service is down or the key is unknown",
    "how scope() tracks evaluations and pins per request context"
   ],
   "tradeoffs": [
    "Three callables cover all four operations: the boolean and variant checks share evaluate(), whose return type mypy infers from the Flag's default.",
    "Defaults are declared once with the flag, not at every call site as in the sketch's default= parameters, so two call sites cannot disagree on a default.",
    "scope() does double duty (audit trail and test pins), which is compact but means a reader has to learn that one context manager serves two different callers.",
... (shortened here; the page shows it whole)

compare: the rate limiter's three designs

Input (the designs are the first example's reply, handed over by the page):

{
 "task": "compare",
 "module": "rate limiter",
 "language": "TypeScript",
 "brief": "(a string - shown below)",
 "designs": "(a JSON string: 3 designs - A Factory plus two verbs: admit and adjust, B Pluggable engine: store, clock and policy resolver injected, C Hot-path function returning a wait time, admin functions beside it)",
 "facts": "(a JSON string; decoded: 5 of 5 questions answered, 4 key operations; metrics for A 3 entry points, B 9 entry points, C 8 entry points)"
}

brief:

# Rate limiter for the Quillmere API gateway

Problem: one noisy tenant can starve every other tenant on the shared gateway. We need a per-tenant rate limiter that the
gateway consults before it forwards a request, and that the admin console can query.

Callers:
- the HTTP middleware in the gateway, once per incoming request (hot path)
- the admin console, to show a tenant's remaining quota and to lift a limit after a plan upgrade
- integration tests, which need to advance time without sleeping

Operations:
- check whether a request may proceed, and if not, how long the caller should wait
- report the remaining quota for a tenant
- reset a tenant's usage after a plan upgrade
- change a tenant's limits without restarting the gateway

Constraints:
- the check must add well under a millisecond on the hot path
- state lives in memory on one node today; a shared Redis store is planned for next quarter, and callers must not change when it arrives
- the gateway code base is TypeScript on Node 22 and uses async/await throughout
- some routes cost more than others: a bulk export counts as 10 ordinary requests

Hidden:
- the token-bucket arithmetic and refill timing
- where the counters are stored (memory now, Redis later)
- clock handling, so tests can control time

Reply:

{
 "task": "compare",
 "task_note": "",
 "criteria": [
  {
   "criterion": "simplicity",
   "discussion": "A is the smallest surface by a wide margin: 3 entry points (createLimiter, admit, adjust), 5 parameters in total and at most 2 on any call, so a new caller learns one factory and two verbs. C has 8 entry points and 8 parameters with at most 2 per call, and each function name says exactly what it does, which makes it easy to read even though there is more of it. B has 9 entry points and 13 parameters with up to 3 on one call, and on top of that the caller must supply or understand four implemented methods (load, save, now, resolve) before the first evaluate. A is the easiest to learn, with the caveat that its compactness comes from packing admin actions into one Change union.",
   "favours": "A"
  },
  {
   "criterion": "general_purpose",
   "discussion": "B is the most general: the store, clock, policy source and cost rule are all injected, and LimitKey already carries an optional scope, so a Redis CounterStore, per-route limits or a new cost rule arrive without touching callers. The risk is over-generalisation, since the brief names only one concrete future change (the Redis store next quarter) and B pays for many futures it does not mention. A covers that same Redis change through a store variant in its config and absorbs new admin actions as new Change variants, which is general enough for this brief. C's module-level state and fixed set of functions mean one limiter per process, so it is the least able to grow.",
   "favours": "B"
  },
  {
   "criterion": "efficiency",
   "discussion": "The hot path must add well under a millisecond, so the shape of the per-request call matters most. A's admit returns allowed, remaining and retry time in one awaited call, with the store and limits fixed at creation, which leaves nothing extra to look up per request. C's waitBeforeForward is equally lean, but because it returns only a wait time, middleware that wants to send remaining-quota headers must make a second call to remainingQuota. B's evaluate awaits a PolicyResolver and runs a CostFunction on every request and also dispatches events, and the shape does not force the resolver to cache, so it is the one most likely to push latency onto the hot path.",
   "favours": "A"
  },
  {
   "criterion": "depth",
   "discussion": "A is the deepest: behind 3 entry points it hides the token-bucket arithmetic, the store choice and clock handling, which is exactly the hidden list in the brief. C also hides route-cost lookup, which A leaves to the caller, but it spreads that across 8 entry points, including test-only advance, release and freezeTime in the same public surface. B is the shallowest relative to what it hides, because it publishes CounterStore and BucketState, which puts the storage boundary the brief wants hidden into the public types.",
   "favours": "A"
  },
  {
   "criterion": "misuse",
   "discussion": "C is the hardest to misuse on the hot path: the middleware passes a tenant id and a route and gets one number back, and the bulk-export weight never leaves the module. Its weak points are that configureLimits must run before the first check, an ordering rule the types cannot enforce, and that module-wide frozen time does not suit parallel tests. A relies on conventions that are easy to get wrong: reading quota by admitting with cost 0, computing route cost in gateway code, and an advanceClock variant that a system-clock limiter can only reject at run time. B gives a caller many ways to assemble a limiter wrongly, such as a resolver that does not cache or a store that leaks state.",
   "favours": "C"
  }
 ],
 "divergence": [
  "The designs differ most in where the route cost and the clock live: C keeps the bulk-export weight inside the module and swaps time module-wide, A makes the caller pass a numeric cost and puts clock control in a production Change variant, and B injects both as replaceable parts.",
  "This matters because the brief asks for both a sub-millisecond hot path and clock handling hidden from production callers, and only a design that fixes cost rules and the clock at construction time gets both without leak
... (shortened here; the page shows it whole)

The page re-checks the reply; the API does not

The page holds every reply to account (recon.js). Designs: one design per assigned constraint, in order, the constraint copied; declarations only, no function bodies, loops or return statements; every key operation covered by every design through a name that is in that design's signature; the fewest-methods design within three entry points by the page's count; no two designs near-clones and none a renamed copy of the sketch. Compare: the five criteria in order, each favouring a real design or a tie, discussed in prose with no tables, with any entry-point count it quotes equal to the page's; a synthesis based on a real design, borrowing only from the others; at least one question back. Both: no percentage the brief does not contain. Over the API you get the model's reply as it is; run the same checks yourself with Recon.reconcile in recon.js, or paste the same brief into the page.

Step 1 — a tiny client helper

One function that sends JSON and unwraps the envelope.

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="paste-your-token-here"   # from https://interface-desk.skillsafe.ai/tokens.html
api() { # api METHOD PATH [JSON-BODY]
  curl -s -X "$1" "$BASE$2" -H "Content-Type: application/json" \
    ${TOKEN:+-H "Authorization: Bearer $TOKEN"} ${3:+--data "$3"}
}

Step 2 — a token

A guest token is enough for /me and /estimate. A run is metered, so it needs a personal token: sign in on /tokens.html and copy it from there.

# a guest token (enough for /me and /estimate); a run needs your personal token from /tokens.html
TOKEN=$(curl -s -X POST "$BASE/guest" -H "Content-Type: application/json" -d '{"slug":"interface-desk"}' | jq -r '.data.token')

Step 3 — GET /me

Who the token is (subject_type: user or guest) and the credit balance.

api GET /me | jq '.data | {subject_type, credits}'

Step 4 — POST /estimate

Free. The body is the run input itself (not wrapped in {"input": ...}). hold_credits is a reservation, not the price; min_credits is what the balance must cover; model reads gpt-5.6-terra and model_alias gpt-terra.

# input.json: the run input object - {"task": "designs", "module": "...", "language": "...", "brief": "...", "facts": "..."}
api POST /estimate "$(cat input.json)" | jq '.data | {hold_credits, min_credits, model, model_alias, markup_bps, warnings}'

Step 5 — POST /run, then poll the job

Send an Idempotency-Key built from the lane and the input: a retry with the same key never bills twice. The page uses interface-desk:<lane>:<inputHash>:a<attempt>. The job's output.output is the reply text; truncated: true means the balance cut it short.

KEY="interface-desk:designs:$(shasum -a 256 input.json | cut -c1-16):a1"
JOB=$(curl -s -X POST "$BASE/run" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $KEY" --data @input.json | jq -r '.data.job_id')
while :; do
  J=$(api GET "/jobs/$JOB"); S=$(echo "$J" | jq -r '.data.status')
  case "$S" in succeeded|failed|cancelled) break;; esac; sleep 2
done
echo "$J" | jq -r '.data.output.output' > reply.json   # one JSON object, the lane's contract
echo "$J" | jq '.data | {charged_credits, truncated}'

Step 6 — POST /run-stream

The same run as Server-Sent Events. compare.json is a compare-lane run input, built like input.json.

# Server-Sent Events: tick/delta events while the job runs, then a final event with the job
curl -N -s -X POST "$BASE/run-stream" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: interface-desk:compare:$(shasum -a 256 compare.json | cut -c1-16):a1" --data @compare.json