SaveToken API

Overview

The API is REST over HTTPS. It accepts JSON request bodies, returns JSON responses, and uses standard HTTP status codes.

POST /v1/optimize does the work. GET /v1/health, POST /v1/keys/free, GET /v1/keys/{transaction_id}, and POST /v1/support need no key; every other endpoint does. Send the key from a server you control — never embed a tsk_ key in browser or mobile-app code.

Quickstart

Step 1 — Get a key

Mint a free key. No account, no card.

curl -X POST https://api.savetoken.org/v1/keys/free

{
  "key": "tsk_9f2c7b1e8a4d6053c1e2f4a6b8d0c3e5",
  "api_key": "tsk_9f2c7b1e8a4d6053c1e2f4a6b8d0c3e5",
  "key_id": "b0a1c2d3-e4f5-6789-abcd-0123456789ef",
  "daily_quota": 100,
  "note": "store this now — it is never shown again (hashed at rest)"
}

Step 2 — Send a request

Pass the text you would otherwise send to your model. The call shape is the same in every language.

curl -X POST https://api.savetoken.org/v1/optimize \
  -H "Authorization: Bearer tsk_9f2c7b1e8a4d6053c1e2f4a6b8d0c3e5" \
  -H "Content-Type: application/json" \
  -d '{"text": "2026-09-08T11:04:22Z INFO  db pool acquired conn=17 ..."}'

import requests

resp = requests.post(
    "https://api.savetoken.org/v1/optimize",
    headers={"Authorization": "Bearer tsk_9f2c7b1e8a4d6053c1e2f4a6b8d0c3e5"},
    json={"text": "2026-09-08T11:04:22Z INFO  db pool acquired conn=17 ..."},
)
result = resp.json()
print(result["verdict"], result["tokens_in"], result["tokens_out"])

const resp = await fetch("https://api.savetoken.org/v1/optimize", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tsk_9f2c7b1e8a4d6053c1e2f4a6b8d0c3e5",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "2026-09-08T11:04:22Z INFO  db pool acquired conn=17 ..." }),
});
const result = await resp.json();
console.log(result.verdict, result.tokens_in, result.tokens_out);

Step 3 — Read the response

{
  "request_id": "b3f1a09c-4e77-4b2a-9c1d-2f6e8a0d5b41",
  "optimized": "2026-09-08T11:04:22Z INFO db pool acquired conn=17 ...",
  "mode": "frame_filter",
  "tokens_in": 1139,
  "tokens_out": 630,
  "dollars_saved": 0.0031,
  "verdict": "WIN",
  "warnings": []
}

Send optimized to your LLM provider in place of the original text. verdict is WIN only when optimized is smaller than the input and was verified equivalent to it — that is the only case where dollars_saved is above zero. REDUCED means the token count genuinely dropped and a structural safety check passed, but this exact content hasn't been run through reference-model verification yet — dollars_saved stays $0 (billed savings are verified-only), but estimated_savings shows the real, unverified figure so a genuine reduction never reads as "nothing happened." NEUTRAL means no reduction happened at all for this input; fall back to the original text. PASS_THROUGH means there was nothing to reduce — for example, the entire input was held as a stable prefix.

Authentication

Send your API key on every authenticated request, in either header:

Keys are hashed with SHA-256 at rest. SaveToken cannot display a key after it is issued — store it when you create it. Revoke a key from the dashboard.

Optimize a tool result

Reduce a noisy tool or function result before it re-enters an agent's prompt.

Prerequisite: an API key.

1. Take the raw tool output — a web-search payload, an API response, a file dump.
2. Send it as text to POST /v1/optimize.
3. Use optimized from the response as the tool message content.
4. If verdict is NEUTRAL or REDUCED, an agent pipeline should still treat it cautiously — REDUCED means a real drop that isn't reference-model verified for this exact content, not a guarantee it's safe for automated consumption.

Optimize a conversation history

Keep a long chat inside the context window by reducing older turns.

Prerequisite: an API key.

1. Send the conversation as messages instead of text.
2. Set stable_prefix_message_count to the number of leading messages to leave byte-identical — this keeps a provider prompt-cache prefix intact.
3. Send the returned optimized string as the context for your next model call.

{
  "messages": [
    {"role": "system", "content": "You are a support agent."},
    {"role": "user", "content": "My deploy fails with exit code 137."},
    {"role": "assistant", "content": "Exit 137 is an out-of-memory kill. Raise the container memory limit and redeploy."}
  ],
  "stable_prefix_message_count": 1
}

Reduce the input tokens in a block of text or a message array. Requires authentication.

Request body

* Provide exactly one of text or messages. Sending both, or neither, returns BAD_REQUEST.

options object

Response body

Errors

Mint a free, rate-limited API key. No authentication. No request body.

Response body

Errors

Retrieve the key minted for a completed checkout. No authentication. Polled by the checkout page after payment.

Response body

404 means the key is not minted yet, or has already been retrieved once. A second request never re-reveals a key.

List recent calls made with your key, newest first. Requires authentication.

Query parameters

Response body

Return the running cost total for your key. Requires authentication.

Response body

Return service status. No authentication. Response is {"status": "ok"}.

File an issue. No authentication — usable by a human via the help center's form, or directly by an agent that just received an error and wants to report it with context attached.

Request body

curl -X POST https://api.savetoken.org/v1/support \
  -H "Content-Type: application/json" \
  -d '{"message": "getting 500 on every call today", "request_id": "b3f1a09c-4e77-4b2a-9c1d-2f6e8a0d5b41"}'

Response body

Errors

Errors

Every error response has the same shape:

{
  "request_id": "b3f1a09c-4e77-4b2a-9c1d-2f6e8a0d5b41",
  "error": true,
  "code": "BAD_REQUEST",
  "message": "exactly one of text or messages must be set"
}

Rate limits

A request past any limit returns 429 RATE_LIMIT with a message naming the limit reached.

Roadmap

• Official Python and TypeScript SDKs — in progress.
• Framework helpers for LangChain, LangGraph, and LlamaIndex — planned.
• Key-management API endpoints — planned. Use the dashboard to revoke a key today.