Skip to content
Floopy Docs

Node.js / TypeScript

Overview

Floopy is a zero-SDK gateway. You do not need to install a Floopy-specific library. Just point the standard OpenAI Node.js SDK at https://api.floopy.ai/v1 and use your Floopy API key. All features — caching, rate limiting, fallbacks, observability — work automatically through headers.

Installation

Terminal window
npm install openai

Configuration

import OpenAI from "openai";


const client = new OpenAI({
  baseURL: "https://api.floopy.ai/v1",
  apiKey: process.env.FLOOPY_API_KEY, // starts with fp_
});

Set FLOOPY_API_KEY in your environment. You can create one in the dashboard.

Basic Request

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "user", content: "Explain quantum computing in one sentence." },
  ],
});


console.log(response.choices[0].message.content);

Switch providers by changing the model name — no other code changes needed:

// Anthropic
const response = await client.chat.completions.create({
  model: "claude-sonnet-4-20250514",
  messages: [{ role: "user", content: "Hello!" }],
});

Streaming

const stream = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Write a short poem." }],
  stream: true,
});


for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

Custom Headers

Pass Floopy-specific headers using the second argument to any SDK method:

const response = await client.chat.completions.create(
  {
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  },
  {
    headers: {
      "Floopy-Cache": "semantic",
      "floopy-property-environment": "production",
      "floopy-property-feature": "chat",
      "floopy-fallback": "claude-sonnet-4-20250514",
    },
  },
);
HeaderDescription
Floopy-CacheCache strategy: semantic or exact
floopy-property-*Attach custom metadata for filtering in the dashboard
floopy-fallbackFallback model if the primary provider fails
floopy-session-idGroup related requests into a session
floopy-user-idAssociate requests with an end user

See the Headers Reference for the full list.