REST API Integration

Use PromptCacheAI from any backend

Call /chat before your model provider. If PromptCacheAI returns a cached response, use it. If it misses, call your provider and save the final response with /cache/save.

1. Create an API key

Create a key in Settings - API Keys. Every request must include the X-API-Key header.

Keep your PromptCacheAI API key server-side. Do not expose it in browser code, mobile apps, or public client bundles.

2. Check the cache with /chat

Send the prompt, namespace, provider, and model to PromptCacheAI before your model call. The response includes a prompt_hash that you use later when saving a new model response.

curl https://api.prompt-cache.ai/v1/chat \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "support-bot",
    "provider": "openai",
    "model": "gpt-4o-mini",
    "prompt": "How do I reset my password?"
  }'

Response shapes

Cache miss

{
  "cached": false,
  "prompt_hash": "abc123...",
  "response": "",
  "cache_mode": "live",
  "cache_decision": "miss_no_candidate",
  "save_recommended": true
}

Cache hit

{
  "cached": true,
  "prompt_hash": "abc123...",
  "response": "To reset your password...",
  "cache_mode": "live",
  "cache_decision": "exact_hit",
  "save_recommended": false
}

Test-mode would-hit

{
  "cached": false,
  "prompt_hash": "def456...",
  "response": "",
  "cache_mode": "test",
  "cache_decision": "test_validator_would_hit",
  "canonical_prompt_hash": "abc123...",
  "save_recommended": false
}

3. Call your model on a miss

When cached is false, call your provider as usual. PromptCacheAI is provider agnostic, so your app keeps its existing model call, retries, streaming, and safety filters.

4. Save the model response

After your model returns a final answer, save it with the same prompt_hash and namespace. Do not save whensave_recommended is false.

curl https://api.prompt-cache.ai/v1/cache/save \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_hash": "<PROMPT_HASH_FROM_CHAT_RESPONSE>",
    "namespace": "support-bot",
    "response": "To reset your password, click ..."
  }'

Production-safe manual pattern

Treat PromptCacheAI as an optimization layer. If a cache check does not complete or does not return a reusable response, your app should call the model normally.

import OpenAI from "openai";

const API_BASE = "https://api.prompt-cache.ai/v1";
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });
type ChatResult = {
  cached?: boolean;
  response?: string;
  prompt_hash?: string;
  save_recommended?: boolean;
};

export async function answerWithCache(namespace: string, prompt: string) {
  const apiKey = process.env.PROMPTCACHEAI_KEY!;
  let chatRes: ChatResult | null = null;

  try {
    const res = await fetch(`${API_BASE}/chat`, {
      method: "POST",
      headers: {
        "X-API-Key": apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        namespace,
        provider: "openai",
        model: "gpt-4o-mini",
        prompt,
      }),
    });
    if (!res.ok) throw new Error(`PromptCacheAI /chat failed: ${res.status}`);
    chatRes = await res.json();
  } catch (err) {
    console.warn("PromptCacheAI cache check failed; calling model directly", err);
  }

  if (chatRes?.cached) {
    return { source: "cache", text: chatRes.response };
  }

  const completion = await openai.responses.create({
    model: "gpt-4o-mini",
    input: prompt,
  });
  const text = completion.output_text || "";

  try {
    if (chatRes?.prompt_hash && chatRes.save_recommended !== false) {
      await fetch(`${API_BASE}/cache/save`, {
        method: "POST",
        headers: {
          "X-API-Key": apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          prompt_hash: chatRes.prompt_hash,
          namespace,
          response: text,
        }),
      });
    }
  } catch (err) {
    console.warn("PromptCacheAI cache save failed", err);
  }

  return { source: "provider", text };
}

Prefer the shortest Node integration?

Use the Quickstart with SDK guide if you are building in Node or TypeScript.