Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/arjunkshah/supercompress/llms.txt

Use this file to discover all available pages before exploring further.

The key management endpoints let you create and administer the API keys used to authenticate calls to /v1/compress. All six endpoints require a Firebase ID token — not an API key — because they operate on behalf of a signed-in user and are the same routes the dashboard UI calls.

​
Authentication

All requests on this page must include: 
Authorization: Bearer <firebase_id_token>
In dev mode (SC_AUTH_DEV=1) you can pass a synthetic token such as dev:my-uid:me@dev.local instead of a real Firebase token.

​
GET /api/me

Returns the Firebase uid and email address for the currently authenticated user. This is a lightweight liveness check for the auth layer and is also used by the dashboard on first load.

​
Example request

curl https://your-api-host/api/me \
  -H "Authorization: Bearer <firebase_id_token>"

​
Response fields

​
uid
string
The Firebase user ID.
​
email
string
The email address associated with the Firebase account. May be null for anonymous or OAuth-only accounts.

​
Example response

{
  "uid": "Xk9mR3pLqZVt2nOeD7cF",
  "email": "alice@example.com"
}

​
GET /api/keys

Lists all active (non-revoked) API keys for the authenticated user, together with a per-key usage summary.

​
Example request

curl https://your-api-host/api/keys \
  -H "Authorization: Bearer <firebase_id_token>"

​
Example response

{
  "keys": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Production",
      "prefix": "sc_live_aBcDeFgH",
      "created_at": "2024-11-01T10:00:00+00:00",
      "last_used_at": "2024-11-15T14:32:01+00:00",
      "revoked": false
    }
  ],
  "usage": {
    "3fa85f64-5717-4562-b3fc-2c963f66afa6": {
      "total_requests": 142,
      "total_tokens_in": 589000,
      "total_tokens_out": 206150,
      "total_tokens_saved": 382850,
      "by_day": {
        "2024-11-15": {
          "key_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "requests": 12,
          "tokens_in": 49200,
          "tokens_out": 17220,
          "tokens_saved": 31980
        }
      }
    }
  }
}

​
POST /api/keys

Creates a new API key for the authenticated user. Returns the key record and the full secret value. The secret is derived from a cryptographically random 24-byte token and is shown only once — it is not stored, only its SHA-256 hash is.

​
Body parameters

​
name
string
default:"Production"
A human-readable label for the key. Maximum 80 characters. Whitespace-only names are stored as "Untitled key".

​
Example request

curl -X POST https://your-api-host/api/keys \
  -H "Authorization: Bearer <firebase_id_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production"}'

​
Example response

{
  "key": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Production",
    "prefix": "sc_live_aBcDeFgH",
    "created_at": "2024-11-15T09:00:00+00:00",
    "last_used_at": null,
    "revoked": false
  },
  "secret": "sc_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345"
}
The secret field contains the full sc_live_… key and is returned exactly once. Copy it to a secrets manager immediately. If you lose it, you must create a replacement key and revoke the old one.

​
PATCH /api/keys/

Renames an existing key. Only the display name is changed; the key secret, prefix, and usage history are unaffected.

​
Path parameter

ParameterTypeDescription
key_idstringUUID of the API key

​
Body parameters

​
name
string
required
New display name. Between 1 and 80 characters. Whitespace-only values are ignored and the existing name is preserved.

​
Example request

curl -X PATCH https://your-api-host/api/keys/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer <firebase_id_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Staging"}'

​
Example response

{
  "key": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Staging",
    "prefix": "sc_live_aBcDeFgH",
    "created_at": "2024-11-15T09:00:00+00:00",
    "last_used_at": "2024-11-15T14:32:01+00:00",
    "revoked": false
  }
}
Returns 404 if the key does not exist or does not belong to the authenticated user.

​
DELETE /api/keys/

Permanently revokes an API key. The key is immediately removed from the hash lookup index, so any in-flight requests using it will start failing with 401 within milliseconds.

​
Path parameter

ParameterTypeDescription
key_idstringUUID of the API key

​
Example request

curl -X DELETE https://your-api-host/api/keys/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer <firebase_id_token>"

​
Example response

{
  "key": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Production",
    "prefix": "sc_live_aBcDeFgH",
    "created_at": "2024-11-15T09:00:00+00:00",
    "last_used_at": "2024-11-15T14:32:01+00:00",
    "revoked": true
  }
}
Revocation is permanent and immediate. The key hash is removed from the lookup index, and the key record is marked "revoked": true. There is no undo — create a new key if access needs to be restored.
Returns 404 if the key does not exist or does not belong to the authenticated user.

​
GET /api/keys//usage

Returns a usage snapshot for a single key, broken down by calendar day (UTC).

​
Path parameter

ParameterTypeDescription
key_idstringUUID of the API key

​
Example request

curl https://your-api-host/api/keys/3fa85f64-5717-4562-b3fc-2c963f66afa6/usage \
  -H "Authorization: Bearer <firebase_id_token>"

​
Response fields

​
total_requests
integer
Total number of successful /v1/compress calls made with this key.
​
total_tokens_in
integer
Cumulative input token count across all requests (tokens before compression).
​
total_tokens_out
integer
Cumulative output token count across all requests (tokens after compression).
​
total_tokens_saved
integer
Cumulative tokens saved: total_tokens_in − total_tokens_out. This directly maps to KV-cache reduction.
​
by_day
object
A map from UTC date strings ("YYYY-MM-DD") to per-day usage records. Each record contains key_id, requests, tokens_in, tokens_out, and tokens_saved for that day.

​
Example response

{
  "total_requests": 142,
  "total_tokens_in": 589000,
  "total_tokens_out": 206150,
  "total_tokens_saved": 382850,
  "by_day": {
    "2024-11-14": {
      "key_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "requests": 130,
      "tokens_in": 539800,
      "tokens_out": 188930,
      "tokens_saved": 350870
    },
    "2024-11-15": {
      "key_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "requests": 12,
      "tokens_in": 49200,
      "tokens_out": 17220,
      "tokens_saved": 31980
    }
  }
}
Returns 404 if the key does not exist or does not belong to the authenticated user.

Build docs developers (and LLMs) love

Get started for freeTalk to us