smoltext API Quickstart: Your First Compressed Payload

What You Will Build

By the end of this tutorial you will have compressed a small JSON payload, stored the compact form, and decompressed it back to the original — all through the smoltext edge API.

Prerequisites

You need a terminal with curl and an API key. The base URL for every call is https://api.smoltext.sprapp.com.

Step One: Compress

Send a small payload to the compress endpoint:

curl -X POST https://api.smoltext.sprapp.com/v1/compress \
  -H "Authorization: Bearer $SMOLTEXT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data":"{\"u\":4821,\"e\":\"signup\"}"}'

The response returns the compressed bytes (base64-encoded in the JSON body) and the original and compressed sizes so you can see the ratio immediately.

Step Two: Inspect the Ratio

The response includes a size summary. For a small structured payload like this, expect a meaningful reduction. If the ratio is near 1.0 or worse, your payload is either too small to compress or too high-entropy — both expected outcomes the API reports honestly.

Step Three: Decompress

Round-trip it back:

curl -X POST https://api.smoltext.sprapp.com/v1/decompress \
  -H "Authorization: Bearer $SMOLTEXT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data":"<base64-from-step-one>"}'

You should get your original JSON back, byte for byte. smoltext is lossless — decompression always reproduces the exact input.

Step Four: Wire It Into Code

In an application, the pattern is: compress before write, decompress after read. Keep a small wrapper so the rest of your code never sees the compressed form:

async function compress(data) {
  const r = await fetch("https://api.smoltext.sprapp.com/v1/compress", {
    method: "POST",
    headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ data }),
  });
  return (await r.json()).compressed;
}

Where to Apply It

The best first target is your highest-volume small-record path: analytics events, KV writes, or log lines. Compress a representative sample, confirm the ratio, then roll it into the write path.

A Note on Latency

Compression runs at the Cloudflare edge in sub-millisecond time. For most workloads the network round trip dominates, so co-locate your call with the edge where possible, or batch many records into one request.

What's Next

Once the round trip works, explore batch compression to amortize request overhead across many small records, and read the deep dives on the semantic JSON codec to understand exactly where your savings come from.