API reference

Playground API

POST /v1/playground/compare — fire the same prompt twice in parallel: once raw, once with mintoken rules injected. Get both responses, both token counts, and the savings number in one call. Same engine the dashboard playground uses.

Endpoint

Base URL: https://api.mintoken.in
Path: POST /v1/playground/compare

Two upstream calls per request

Each call to /comparesends two requests to the underlying provider concurrently — one untouched (the “normal” arm) and one with the mintoken system prompt prepended. Both burn provider tokens against the key you pass inprovider_key.

Basic example

curl https://api.mintoken.in/v1/playground/compare \
  -H "Authorization: Bearer mt_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Explain how a database connection pool works.",
    "provider": "anthropic",
    "provider_key": "sk-ant-xxxxx",
    "model": "claude-haiku-4-5",
    "intensity": "full"
  }'

Request headers

Header	Required	Description
`Authorization`	Yes	`Bearer mt_live_…` — your mintoken API key.
`Content-Type`	Yes	`application/json`

provider_key goes in the body, not a header

Unlike the proxy endpoints (which expect X-Provider-Key as a header), the playground accepts the upstream provider key as a JSON field. It is used in-flight for the two upstream calls and is never persisted.

Request body

Field	Type	Required	Description
`prompt`	string	Yes	The user message. Sent verbatim to both arms; mintoken rules are injected as a system prompt only on the mintoken arm.
`provider`	string	No	Provider id. Defaults to `anthropic`. Any id from `GET /v1/playground/providers`, or the literal string `custom` for a BYO endpoint.
`provider_key`	string	Yes	Your own API key for the chosen provider (e.g. `sk-ant-…`, `sk-proj-…`). Used in-flight, never stored.
`model`	string \| null	No	Model id. Falls back to the provider's default. Required when `provider="custom"`.
`intensity`	string	No	Compression level. `lite`, `full` (default), or `ultra`. See Intensity levels.
`custom_base_url`	string \| null	Conditional	OpenAI-compatible base URL (without the trailing `/chat/completions`). Required when `provider="custom"`.

Response shape

200 OK with a JSON body containing the outputs and usage from both arms. Either side may have populated text and a null error, an error string and empty text, or partial output. Inspect both errors before assuming the run succeeded.

Field	Type	Description
`normal_response`	string	Provider output without mintoken rules.
`normal_tokens`	integer	Output tokens reported by the provider for the normal arm.
`normal_error`	string \| null	Friendly error message if the normal call failed; otherwise null.
`normal_ms`	integer	Wall-clock latency of the normal call in milliseconds.
`mintoken_response`	string	Provider output with mintoken rules injected.
`mintoken_tokens`	integer	Output tokens for the mintoken arm.
`mintoken_error`	string \| null	Friendly error message if the mintoken call failed; otherwise null.
`mintoken_ms`	integer	Wall-clock latency of the mintoken call in milliseconds.
`savings_percent`	number	`round(100 * (normal - mintoken) / normal, 1)`. Zero if either arm returned zero tokens.
`intensity`	string	Echo of the intensity that ran (lite / full / ultra).

Listing providers and models

GET /v1/playground/providers returns the full provider catalogue plus default models — useful for building your own playground UI or picking a model id programmatically.

curl https://api.mintoken.in/v1/playground/providers \
  -H "Authorization: Bearer mt_live_xxxxx"

Custom OpenAI-compatible endpoints

Set provider to custom and supply custom_base_url + model to point the playground at any OpenAI-compatible endpoint (self-hosted vLLM, LM Studio, an internal gateway, etc.).

curl https://api.mintoken.in/v1/playground/compare \
  -H "Authorization: Bearer mt_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Summarise the SOLID principles.",
    "provider": "custom",
    "provider_key": "sk-your-endpoint-key",
    "custom_base_url": "https://your-llm.example.com/v1",
    "model": "your-model-id",
    "intensity": "full"
  }'

Error responses

The endpoint returns 200 OK for partial failures (the response body carries normal_error and mintoken_error). Hard errors use the following status codes:

Status	When
400	Empty `prompt`, unknown `provider`, or `provider="custom"` without `custom_base_url` / `model`.
401	Missing or invalid `Authorization` header.
429	Monthly token quota exceeded on your mintoken plan.

Every run is recorded

Successful, partial, and broken runs all land in the dashboard's usage table tagged endpoint=playground/compare. Token columns tell you whether a run was clean (both > 0), partial (one side 0), or broken (both 0).

When to use the playground API

Building a savings calculator into your own dashboard or sales tool.
Running offline benchmarks across providers and intensity levels — point a script at /compare and log savings_percent per prompt.
Debugging compression behaviour on a single prompt without wiring up the proxy in your real app first.

For real production traffic, use the proxy endpoints — see OpenAI proxy, Anthropic proxy, and Google Gemini proxy. The playground is for evaluation, not the hot path.

← Previous

Google Gemini proxy

Streaming