API reference
JSON in. Selected evidence out.
Base URL: https://underpin-optimise-api.westernroseglobal.workers.dev
Send Content-Type: application/json and Authorization: Bearer YOUR_API_KEY. Keep the key server-side.
Compress source text
POST /v1/compress
| Field | What to send |
|---|---|
| text | Required source string; up to 50,000 UTF-16 units. |
| query | Required question; up to 4,000 UTF-16 units. |
| ratio | Target reduction from 1 to 20; default 5. Targets bytes, not model tokens. |
| guarded | Default true. Returns full source when certain risks or empty selection are detected. |
{
"text": "YOUR SOURCE TEXT",
"query": "What deadline applies?",
"ratio": 5,
"guarded": true
}Read the response
| Field | Meaning |
|---|---|
| text | Evidence to pass to your model. |
| spans | Original source locations: start inclusive, end exclusive; UTF-16 offsets. |
| original_bytes / bytes | UTF-8 sizes before and after selection, including returned labels. |
| fallback | true means full-source fallback was used. |
| risk_flags | Heuristic risk signals, not a guarantee of accuracy. |
| remaining_requests / resets_at | Daily account allowance remaining and its UTC reset time. |
Recover missing passages
POST /v1/retrieve uses the same original text, a focused query, exclude_spans from previous results and max_bytes (default 2,048; range 32–8,192). Up to 256 exclusion spans. Integration example →
Usage and key management
| Endpoint | Purpose |
|---|---|
| GET /v1/usage | used, remaining, daily_limit, resets_at, expires_at:null. |
| DELETE /v1/key | Revoke the API key used for this request. |
| POST /v1/feedback | category: accuracy/integration/suggestion, message (1–2,000 characters), consent:true. Three messages per key. |
Account API — usually managed through the website
Signup, login and recovery return a session token. Use that token (not your API key) for protected account endpoints. Sessions last 24 hours; API keys do not expire.
| Endpoint | JSON body / purpose |
|---|---|
| POST /v1/account/signup | email, password (12–128 characters), consent:true → session, api_key and recovery_code. Save the key and recovery code immediately. |
| POST /v1/account/login | email, password → session. |
| GET /v1/account | Session bearer → account details, usage, key status. |
| POST /v1/account/key | Session bearer, confirm:true → replacement key; revokes previous key. |
| POST /v1/account/recover | email, password (new), recovery_code → new session and recovery code; revokes old sessions and current API key. |
| POST /v1/account/logout | Session bearer → sign out. |
| DELETE /v1/account | Session bearer, confirm:true → delete account and revoke its key. |
Errors
| Status | What to do |
|---|---|
| 400 | Correct the JSON fields; do not retry unchanged input. |
| 401 | Check your key or sign in again. |
| 403 | Use underpin.cloud for browser account management. |
| 409 | Account could not be created; try sign-in or recovery. |
| 410 | Anonymous key issuance was retired; create an account. |
| 413 | Reduce the request body: processing allows 256 KiB. |
| 415 | Send Content-Type: application/json. |
| 429 | Read the message: rate limit, daily account quota or shared capacity. |
| 503 | Temporarily unavailable or paused; use a bounded retry or your original context. |
Errors return {"error":"message"}. Invalid compressor arguments after quota reservation consume an attempt. All responses use Cache-Control: no-store. GET /health checks service liveness.