How It Works
The concepts behind every surface — the same model whether you call over HTTP, the CLI, or MCP.
The broker model
Glasser buys provider APIs wholesale and resells them per call. The unit of sale is an endpoint: one provider operation with a published price, a provider-native input schema, and a version. One Key covers the whole catalog; there are no per-vendor accounts and no monthly floor. The flow is always the same three verbs: search the catalog, inspect the contract, run the call.
The price is part of the contract
inspect returns the exact price before you spend: a rule (flat, or per-result with a cap) plus a charge clause for every outcome — NO_RESULT, PROVIDER_ERROR, TIMED_OUT, INTERNAL. What you see is what settles. Money is always an exact decimal string (e.g. "0.005"), never a float: do no float arithmetic on it.
A run's life
Admission checks the policy, quotes the price, and reserves a hold — all before dispatch. A refusal (bad input, insufficient balance, policy) creates no run and charges nothing. After dispatch the run settles: the hold is released and the charge lands per the published clause.
QUEUEDAccepted, not yet dispatched to the providerRUNNINGDispatched, the provider has not answered yetCOMPLETEDTerminal — the provider answered. Its answer may still be a “not found”FAILEDTerminal — no usable provider answer; the failure block says whySTOPPEDTerminal — stopped before dispatch. Dispatch wins the race: a run already sent to the provider completes and is chargedTwo indicators, never one: status and charge
A run's status and its charge are independent facts. COMPLETED means the provider answered — a provider 404 (“person not found”) is a normal COMPLETED run carrying that outcome in provider_response, charged by the endpoint's NO_RESULT clause. A FAILED run can carry a non-zero charge when its clauses say so. Always read both.
Idempotency: a retry is a read
Every run carries an idempotency key you choose. Sending the same key again returns the original run instead of buying a second one — the answer is marked replayed and nothing new is charged. On any ambiguous failure (a timeout, a dropped connection), retry with the SAME key. The same key with a different request body is refused with a conflict.
Keys and policy
A Key belongs to a Workspace, and the Workspace's balance is what runs spend. The effective policy is the intersection of the Workspace's policy and the Key's own: an endpoint outside it does not exist for that Key — search never lists it, and inspect answers not-found rather than forbidden, so existence is not leaked.
One model, four surfaces
Everything above holds identically on the HTTP API, the CLI, the MCP server, and the agent Skill — they are one implementation behind four doors, and a Workspace's budget and policy do not care which door a call came through.