API Reference

All endpoints are prefixed with https://api.ziptoken.ai. Requests require Authorization: Bearer <key>.

POST/api/v1/compress

Compress a single text input. Returns the compressed text, token counts, savings ratio, and a quality score.

Request body

Parameter	Type	Required	Description
`text`	string	required	The prompt text to compress. Max length depends on your plan.
`mode`	string	optional	"conservative" \| "balanced" \| "aggressive". Default: "balanced".
`model`	string	optional	Target LLM: "gpt-4o" \| "claude-3-5" \| "gemini". Used for tokenizer selection.
`preserveCode`	boolean	optional	Keep code blocks unchanged. Default: true.

Response

json

{
  "compressed":      "string — the compressed prompt",
  "originalTokens":  1024,
  "compressedTokens": 512,
  "savedTokens":     512,
  "ratio":           0.5,
  "qualityScore":    4,    // 1–5 scale
  "mode":            "balanced",
  "model":           "rule-based"
}

POST/api/v1/batch

Compress up to 100 texts in a single request. Available on Starter and above.

Request body

Parameter	Type	Required	Description
`texts`	string[]	required	Array of prompt texts to compress. Max 100 items.
`mode`	string	optional	Applied to all items. Default: "balanced".
`preserveCode`	boolean	optional	Default: true.

Response

json

{
  "results": [
    {
      "compressed":      "...",
      "originalTokens":  200,
      "compressedTokens": 110,
      "savedTokens":     90,
      "ratio":           0.45,
      "qualityScore":    4
    }
  ],
  "totalSavedTokens": 900,
  "averageRatio":     0.45
}

GET/api/v1/usage

Retrieve token usage for the current billing period.

Response

json

{
  "plan":             "starter",
  "tokensUsed":       1_450_000,
  "tokensLimit":      2_000_000,
  "periodStart":      "2025-04-01T00:00:00Z",
  "periodEnd":        "2025-05-01T00:00:00Z",
  "resetAt":          "2025-05-01T00:00:00Z"
}

Error codes

Status	Code	Meaning
400	`invalid_request`	Missing or malformed body.
401	`invalid_key`	API key is missing or invalid.
402	`quota_exceeded`	Monthly token quota reached. Upgrade or wait for reset.
413	`text_too_long`	Input exceeds the plan's max token limit.
429	`rate_limit`	Too many requests. Respect the Retry-After header.
500	`internal_error`	Something went wrong on our end. Retry with backoff.