Node.js SDK Reference

This page documents the types, methods, and configuration options available in the @centure/node-sdk package.

Client Methods

scanText

Scans text content for prompt injection attempts.

async scanText(text: string): Promise<ScanResponse>

Parameters:

text (string) - The text content to scan

Returns: Promise<ScanResponse> Throws:

BadRequestError - Invalid request format
UnauthorizedError - Invalid or missing API key
MissingApiKeyError - No API key provided

scanImage

Scans images for text-based prompt injection attempts.

async scanImage(image: string | Buffer): Promise<ScanResponse>

Parameters:

image (string | Buffer) - Base64-encoded image string or Buffer object

Returns: Promise<ScanResponse> Throws:

BadRequestError - Invalid image format
UnauthorizedError - Invalid or missing API key
PayloadTooLargeError - Image exceeds size limit
MissingApiKeyError - No API key provided

Response Types

ScanResponse

The response object returned by all scan methods.

interface ScanResponse {
  is_safe: boolean;
  categories: DetectedCategory[];
  request_id: string;
  api_key_id: string;
  request_units: number;
  billed_request_units: number;
  service_tier: ServiceTier;
}

Fields:

boolean

required

Indicates whether the content is safe. false means prompt injection was detected.

DetectedCategory[]

required

Array of detected threat categories with confidence levels. Empty array when is_safe is true.

string

required

Unique identifier for this scan request. Use this for tracking and support inquiries.

string

required

The ID of the API key used for this request.

number

required

Number of request units consumed by this scan operation.

number

required

Number of request units billed for this scan. May differ from request_units when discounts apply.

ServiceTier

required

The service tier associated with your API key.

Example:

{
  "is_safe": false,
  "categories": [
    {
      "code": "context_injection",
      "confidence": "high"
    },
    {
      "code": "output_manipulation",
      "confidence": "medium"
    }
  ],
  "request_id": "req_abc123xyz",
  "api_key_id": "key_def456uvw",
  "request_units": 1,
  "billed_request_units": 1,
  "service_tier": "standard"
}

DetectedCategory

Represents a detected threat with its confidence level.

interface DetectedCategory {
  code: ThreatCategory;
  confidence: ConfidenceLevel;
}

Fields:

ThreatCategory

required

The type of threat detected. See Threat Categories below.

ConfidenceLevel

required

Confidence level of the detection: "low", "medium", or "high".

Threat Categories

The SDK detects the following threat categories. Each corresponds to a specific attack pattern.

See the Risk Classifications page for detailed explanations of each category.

type ThreatCategory =
  | "output_manipulation"
  | "context_injection"
  | "data_exfiltration"
  | "unauthorized_actions";

Category	Description
`output_manipulation`	Attempts to control output format, content, or style
`context_injection`	Injection of fake context, roles, or instruction overrides
`data_exfiltration`	Attempts to extract sensitive data
`unauthorized_actions`	Attempts to trigger unauthorized actions or API calls

Confidence Levels

Confidence levels indicate the detection certainty:

type ConfidenceLevel = "low" | "medium" | "high";

high - Strong indicators of prompt injection. Block these requests.
medium - Moderate indicators. Consider additional validation or monitoring.
low - Weak indicators. May require context-specific handling.

Block all high confidence detections in production. Apply additional scrutiny to medium confidence results based on your risk tolerance.

Service Tiers

Service tiers determine rate limits and features available to your API key:

type ServiceTier = "low" | "standard" | "dedicated";

Client Configuration

Constructor Options

interface CentureClientOptions {
  apiKey?: string;
  baseUrl?: string;
  fetch?: typeof fetch;
  fetchOptions?: RequestInit;
}

Options:

string

Your Centure API key. If not provided, the client reads from the CENTURE_API_KEY environment variable.

string

default:"https://api.centure.ai"

The base URL for the Centure API. Override this for testing or custom deployments.

typeof fetch

Custom fetch implementation. Use this to provide a different fetch function (e.g., node-fetch for older Node.js versions).

RequestInit

Additional options passed to all fetch requests. Use this to set custom headers, timeouts, or other request parameters.

Configuration Examples

Custom timeout:

const client = new CentureClient({
  apiKey: "your-api-key",
  fetchOptions: {
    timeout: 30000, // 30 seconds
  },
});

Custom headers:

const client = new CentureClient({
  apiKey: "your-api-key",
  fetchOptions: {
    headers: {
      "X-Custom-Header": "value",
    },
  },
});

Custom fetch implementation:

import fetch from "node-fetch";

const client = new CentureClient({
  apiKey: "your-api-key",
  fetch: fetch as any,
});

Testing environment:

const client = new CentureClient({
  apiKey: "test-api-key",
  baseUrl: "http://localhost:3001",
});

Error Classes

The SDK provides specific error classes for different failure scenarios:

import {
  BadRequestError,
  UnauthorizedError,
  PayloadTooLargeError,
  MissingApiKeyError,
} from "@centure/node-sdk";

Error Class	HTTP Status	Description
`MissingApiKeyError`	N/A	No API key provided in options or environment
`UnauthorizedError`	401	Invalid or expired API key
`BadRequestError`	400	Invalid request format or parameters
`PayloadTooLargeError`	413	Image exceeds maximum size limit

Error handling pattern:

try {
  const result = await client.scanText(userInput);

  if (!result.is_safe) {
    // Handle unsafe content
    console.log("Threats detected:", result.categories);
  }
} catch (error) {
  if (error instanceof UnauthorizedError) {
    // Handle authentication error
  } else if (error instanceof BadRequestError) {
    // Handle validation error
  } else if (error instanceof PayloadTooLargeError) {
    // Handle size limit error
  } else {
    // Handle unexpected errors
  }
}

TypeScript Support

The SDK includes full TypeScript definitions. All types are exported for use in your application:

import type {
  ScanResponse,
  DetectedCategory,
  ThreatCategory,
  ConfidenceLevel,
  ServiceTier,
} from "@centure/node-sdk";

function handleScanResult(result: ScanResponse): void {
  if (!result.is_safe) {
    result.categories.forEach((category: DetectedCategory) => {
      console.log(`Threat: ${category.code} (${category.confidence})`);
    });
  }
}

Getting Started

API Reference

Security Concepts

SDKs

Pricing

Monitoring & Logs

Node.js SDK Reference

Client Methods

scanText

scanImage

Response Types

ScanResponse

DetectedCategory

Threat Categories

Confidence Levels

Service Tiers

Client Configuration

Constructor Options

Configuration Examples

Error Classes

TypeScript Support

Next Steps

Quickstart

MCP Integration

​Client Methods

​scanText

​scanImage

​Response Types

​ScanResponse

​DetectedCategory

​Threat Categories

​Confidence Levels

​Service Tiers

​Client Configuration

​Constructor Options

​Configuration Examples

​Error Classes

​TypeScript Support

​Next Steps

Quickstart

MCP Integration

Client Methods

scanText

scanImage

Response Types

ScanResponse

DetectedCategory

Threat Categories

Confidence Levels

Service Tiers

Client Configuration

Constructor Options

Configuration Examples

Error Classes

TypeScript Support

Next Steps