FastPII Docs
FastPII Connect

Gateway

FastPII Gateway SDK reference for OpenAI-compatible chat completions with automatic PII protection — Python and TypeScript.

Gateway

The FastPII Gateway is a transparent reverse proxy at https://gateway.fastpii.com that accepts OpenAI-compatible requests, inspects them for sensitive data, and forwards them to upstream LLM providers.

How it works

  1. Your application sends an OpenAI-compatible request to the Gateway
  2. The Gateway inspects request content for PII according to your workspace policy
  3. If the request passes inspection, it forwards it to the configured LLM provider
  4. The response is inspected for PII before being returned to you
  5. If PII is detected in responses, the Gateway can block or redact according to policy

Key points:

  • Auth: X-API-Key header (same key as the Connect API)
  • Endpoints: /v1/chat/completions, /v1/completions, /v1/embeddings
  • No /v1/models endpoint (model availability is workspace-configured)
  • PII protection is automatic and transparent (workspace-level policy)
  • Streaming uses SSE with data: {json}\n\n framing and data: [DONE]\n\n
  • Response headers: X-FastPII-Processed: true, X-FastPII-Provider, X-FastPII-Fallback

Python SDK

Synchronous

from fastpii_connect import FastPIIClient

client = FastPIIClient(api_key="fpk_your_api_key")

# Non-streaming
response = client.gateway.chat.completions(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response["choices"][0]["message"]["content"])

# Streaming
for event in client.gateway.chat.stream(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
):
    if isinstance(event, ChatCompletionChunk):
        print(event.content, end="")

Asynchronous

from fastpii_connect import AsyncFastPII, ChatCompletionChunk

async with AsyncFastPII(api_key="fpk_your_api_key") as client:
    # Non-streaming
    response = await client.gateway.chat.completions(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}],
    )
    print(response["choices"][0]["message"]["content"])

    # Streaming
    async for event in client.gateway.chat.stream(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}],
    ):
        if isinstance(event, ChatCompletionChunk):
            print(event.content, end="")

TypeScript SDK

import { FastPIIClient } from "fastpii-connect";

const client = new FastPIIClient({ apiKey: "fpk_your_api_key" });

// Non-streaming
const response = await client.gateway.chat.completions({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(response.choices[0].message.content);

// Streaming
for await (const event of client.gateway.chat.stream({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
})) {
  if ("content" in event) {
    process.stdout.write(event.content);
  }
}

Chat completions

completions()

Create a non-streaming chat completion. Sends POST /v1/chat/completions with stream: false.

Python:

response = client.gateway.chat.completions(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"},
    ],
    temperature=0.7,
    max_tokens=1000,
)

TypeScript:

const response = await client.gateway.chat.completions({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Hello!" },
  ],
  temperature: 0.7,
  max_tokens: 1000,
});

Parameters follow the OpenAI chat completions API. The model and messages fields are required. All other OpenAI-compatible parameters (temperature, max_tokens, top_p, frequency_penalty, etc.) are passed through.

Returns the raw OpenAI-format response as a dictionary (Python) or object (TypeScript).

stream()

Create a streaming chat completion. Sends POST /v1/chat/completions with stream: true.

Python:

from fastpii_connect import ChatCompletionChunk, StreamDone, StreamError

for event in client.gateway.chat.stream(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
):
    if isinstance(event, ChatCompletionChunk):
        print(event.content, end="")
    elif isinstance(event, StreamDone):
        print("\n[Stream complete]")
    elif isinstance(event, StreamError):
        print(f"\n[Stream error: {event.message}]")

TypeScript:

for await (const event of client.gateway.chat.stream({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
})) {
  if ("content" in event) {
    process.stdout.write(event.content);       // ChatCompletionChunk
  } else if ("type" in event && event.type === "done") {
    console.log("\n[Stream complete]");          // StreamDone
  } else if ("message" in event) {
    console.error(`\n[Stream error: ${event.message}`); // StreamError
  }
}

Stream event types

ChatCompletionChunk

A single content chunk from the stream.

Python:

FieldTypeDescription
contentstringText content of this chunk
finish_reasonstring or NoneWhy the stream ended (e.g., "stop", "length")
indexintChoice index
rawdictRaw OpenAI-format chunk data

TypeScript:

FieldTypeDescription
contentstringText content of this chunk
finishReasonstring | nullWhy the stream ended
indexnumberChoice index
rawRecord<string, unknown>Raw OpenAI-format chunk data

StreamDone

A stream termination sentinel. No fields beyond type: "done".

StreamError

An error embedded in the SSE stream.

FieldPython typeTypeScript typeDescription
messagestrstringError message
error_typestrstring (errorType)Error type (e.g., "pii_policy_error")
rawdictRecord<string, unknown>Raw error data

Response headers

The Gateway adds these headers to every response:

HeaderDescription
X-FastPII-Processed"true" if PII inspection was performed
X-FastPII-ProviderThe upstream LLM provider used (e.g., "openai", "anthropic")
X-FastPII-FallbackPresent if a fallback provider was used
X-Request-IDUnique request identifier for debugging

Gateway-specific errors

The Gateway can raise additional errors beyond the standard Connect API errors:

ErrorStatusWhen
PolicyBlockError403Request blocked by workspace PII policy before reaching the LLM
PIIInspectionError503LLM response blocked because PII was detected in the output
ProviderUnavailableError502Upstream LLM provider unavailable or returned an error

These errors inherit from GatewayError (which inherits from FastPIIError):

from fastpii_connect.errors import (
    GatewayError,
    PolicyBlockError,
    PIIInspectionError,
    ProviderUnavailableError,
)

try:
    response = client.gateway.chat.completions(model="gpt-4o", messages=[...])
except PolicyBlockError as e:
    print(f"Request blocked: {e.message}")
except PIIInspectionError as e:
    print(f"Response contained PII: {e.message}")
except ProviderUnavailableError as e:
    print(f"Provider unavailable: {e.message}")
except GatewayError as e:
    print(f"Gateway error: {e.message} (type={e.error_type})")
import {
  GatewayError,
  PolicyBlockError,
  PIIInspectionError,
  ProviderUnavailableError,
} from "fastpii-connect";

try {
  const response = await client.gateway.chat.completions({ model: "gpt-4o", messages: [...] });
} catch (error) {
  if (error instanceof PolicyBlockError) {
    console.log(`Request blocked: ${error.message}`);
  } else if (error instanceof PIIInspectionError) {
    console.log(`Response contained PII: ${error.message}`);
  } else if (error instanceof ProviderUnavailableError) {
    console.log(`Provider unavailable: ${error.message}`);
  } else if (error instanceof GatewayError) {
    console.log(`Gateway error: ${error.message} (type=${error.errorType})`);
  }
}

See the error handling reference for the full error hierarchy.

Using with OpenAI SDK

Since the Gateway is OpenAI-compatible, you can point the official OpenAI SDK at it:

from openai import OpenAI

client = OpenAI(
    api_key="fpk_your_api_key",
    base_url="https://gateway.fastpii.com/v1",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "fpk_your_api_key",
  baseURL: "https://gateway.fastpii.com/v1",
});

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

The Gateway will automatically inspect all requests and responses for PII according to your workspace policy.

CLI Reference

Command-line interface reference for the fastpii-connect CLI tool.

Error Handling

Complete error hierarchy for FastPII Connect — API errors, Gateway errors, and error handling patterns for Python and TypeScript.

On this page

GatewayHow it worksPython SDKSynchronousAsynchronousTypeScript SDKChat completionscompletions()stream()Stream event typesChatCompletionChunkStreamDoneStreamErrorResponse headersGateway-specific errorsUsing with OpenAI SDK