GET STARTED / HOSTED API

Quick start

Call our API with your text and a question. Use the returned text in your existing AI call.

POSThttps://underpin-optimise-api.westernroseglobal.workers.dev/v1/compress

Using n8n, Make, VS Code or ComfyUI? Choose your setup →

1. Get your API key

Create a free account and copy your key. Save it as OPTIMISE_API_KEY in your server’s environment variables or secrets settings. There is no Optimise package to install and nothing to host.

Testing locally? Set your key in your terminal

Replace YOUR_API_KEY with the key from your account. Keep it out of source control and public frontend code.

PowerShell

$env:OPTIMISE_API_KEY = "YOUR_API_KEY"

Shell

export OPTIMISE_API_KEY="YOUR_API_KEY"

2. Call Optimise from your code

Choose your language. These examples make a real HTTP request to our hosted API.

Node.js 18+. Paste into optimise.mjs and run node optimise.mjs. Or copy the function into your existing server code.

JavaScript

// Node.js 18+ — add this function to your server code.
async function optimise(text, query) {
  const response = await fetch('https://underpin-optimise-api.westernroseglobal.workers.dev/v1/compress', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: 'Bearer ' + process.env.OPTIMISE_API_KEY
    },
    body: JSON.stringify({ text, query, ratio: 5, guarded: true }),
    signal: AbortSignal.timeout(20000)
  });
  const result = await response.json();
  if (!response.ok) throw new Error(result.error);
  return result.text;
}

const context = await optimise(
  'Payment is due in 30 days. Delivery is on Tuesday.',
  'When is payment due?'
);
console.log(context);

Install the HTTP client once: python -m pip install requests. Paste into optimise.py and run python optimise.py.

Python

import os
import requests

def optimise(text, query):
    response = requests.post(
        'https://underpin-optimise-api.westernroseglobal.workers.dev/v1/compress',
        headers={'Authorization': 'Bearer ' + os.environ['OPTIMISE_API_KEY']},
        json={'text': text, 'query': query, 'ratio': 5, 'guarded': True},
        timeout=20,
    )
    response.raise_for_status()
    return response.json()['text']

context = optimise(
    'Payment is due in 30 days. Delivery is on Tuesday.',
    'When is payment due?',
)
print(context)

Run in a Bash-compatible terminal, such as macOS, Linux or Git Bash.

cURL

curl 'https://underpin-optimise-api.westernroseglobal.workers.dev/v1/compress' \
  -H "Authorization: Bearer $OPTIMISE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "text": "Payment is due in 30 days. Delivery is on Tuesday.",
    "query": "When is payment due?",
    "ratio": 5,
    "guarded": true
  }'

3. Use the result in your existing AI call

context is the text Optimise selected. Put it where your application currently sends the full document to its model. Keep your question and system instructions the same.

JavaScript

// In your existing app, documentText and question are your own inputs.
const context = await optimise(documentText, question);
// Replace documentText with context in your existing model request.

You send: text = your document or tool result; query = the question your agent needs to answer.
You receive: JSON containing text = the selected context. The helpers above return that field directly.

Optimise does not call your model. Your existing model client, model-provider key and billing stay in your application.

What do ratio and guarded mean?

ratio:5 targets roughly one fifth of the source bytes. guarded:true allows the API to return the full text when it detects a risk or cannot select evidence. A short sample may return the full source. Neither setting guarantees answer accuracy or a particular token saving.

Errors and daily limits

401: check the API key. 429: read the error message; a daily allowance or a short rate limit has been reached. Timeout: the attempt may have completed; check account usage before retrying.

100 requests/account/day, resetting at midnight UTC. Keys do not expire. Shared testing capacity also applies. The examples surface errors and make no automatic retries.

Need more detail? API fields and responses → · Retrieve missing passages →