Quickstart

Before you start#

You need a Contextwaise API key (keys open at launch) and an application that sends context to an LLM: retrieved documents, search results, tool output or memory. No SDK is required for the API; any HTTP client works.

Your first request#

1. Get an API key

   API keys open at launch. Join the waitlist and we'll send yours first. A key starts with sw_live_ and is shown only once.

   Join waitlist

2. Store it as an environment variable

   Keep the key on the server, never in client-side code or in your repository.

   .envCopy

   CONTEXTWAISE_URL=https://app.contextwaise.com
   CONTEXTWAISE_API_KEY=sw_live_...

3. Send the question and its context

   Pass the user's question as query and each piece of context as a candidate. Give each candidate a source label so the dashboard can break savings down by source.

   cURLTypeScriptPython

   Copy

   curl https://app.contextwaise.com/api/v1/optimize \
     -H "Authorization: Bearer $CONTEXTWAISE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
     "query": "Why was I charged twice this month?",
     "candidates": [
       { "id": "doc-12", "text": "Duplicate charges happen when a card payment times out and is retried…", "source": "rag" },
       { "id": "doc-40", "text": "Our office hours are Monday to Friday, 9am to 6pm CET.", "source": "rag" }
     ],
     "agent": "support-assistant",
     "model": "gpt-6.1-sol"
   }'

4. Send the returned context to your model

   Use context in place of your original candidates when you build the prompt. Kept items come back in the order you sent them.

Read the response#

Every response carries the context to send and a report that explains each decision:

{
  "id": "req_8Hc2kQ0aZt1x",
  "context": [
    { "id": "doc-12", "text": "Duplicate charges happen when a card payment times out and is retried…", "source": "rag" }
  ],
  "report": {
    "tokens": { "before": 9120, "after": 2310, "saved": 6810, "savedPct": 74.67 },
    "cost": { "before": 0.0182, "after": 0.0046, "scorer": 0.0004, "avoided": 0.0132 },
    "model": "gpt-6.1-sol",
    "inputPricePerMillion": 2,
    "items": [
      { "id": "doc-12", "source": "rag", "tokens": 120, "originalTokens": 120, "score": 2.8, "kept": true, "reason": "relevant" },
      { "id": "doc-40", "source": "rag", "tokens": 14, "originalTokens": 14, "score": 0, "kept": false, "reason": "low_relevance" }
    ],
    "guard": null,
    "budget": 6000,
    "aggressiveness": "balanced",
    "threshold": 1.4,
    "conversation": null,
    "route": null,
    "latencyMs": 180,
    "timings": { "auth": 3, "project": 2, "score": 170, "select": 1 }
  }
}

• context: the items worth sending, in your order.
• report.tokens: input tokens before and after, and the share saved.
• report.items: every candidate with its relevance score (0 to 3), whether it was kept, and the reason.

The same request appears in the dashboard under Requests, where you can open it and read every kept and removed item.

Using an agent framework?#

If your app runs an agent loop, in TypeScript or Python, the Agent SDK trims every tool result the moment it returns: one line for the Vercel AI SDK, one call per turn on the Anthropic and OpenAI SDKs, or one call per tool result in any loop.

Where to go next#

• RAG and retrieved context: wire it into your retrieval step.
• Conversations and prompt caching: the one rule for chat apps.
• API reference: every field of the request and the report.