Skip to main content
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;
  service_tier: ServiceTier;
}
Fields:
​
is_safe
boolean
required
Indicates whether the content is safe. false means prompt injection was detected.
​
categories
DetectedCategory[]
required
Array of detected threat categories with confidence levels. Empty array when is_safe is true.
​
request_id
string
required
Unique identifier for this scan request. Use this for tracking and support inquiries.
​
api_key_id
string
required
The ID of the API key used for this request.
​
request_units
number
required
Number of request units consumed by this scan operation.
​
service_tier
ServiceTier
required
The service tier associated with your API key.
Example: 
{
  "is_safe": false,
  "categories": [
    {
      "code": "role_manipulation",
      "confidence": "high"
    },
    {
      "code": "behavioral_override_low",
      "confidence": "medium"
    }
  ],
  "request_id": "req_abc123xyz",
  "api_key_id": "key_def456uvw",
  "request_units": 1,
  "service_tier": "standard"
}

​
DetectedCategory

Represents a detected threat with its confidence level. 
interface DetectedCategory {
  code: ThreatCategory;
  confidence: ConfidenceLevel;
}
Fields:
​
code
ThreatCategory
required
The type of threat detected. See Threat Categories below.
​
confidence
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 =
  | "behavioral_override_low"
  | "role_manipulation"
  | "context_injection"
  | "instruction_hierarchy_manipulation"
  | "output_manipulation"
  | "data_exfiltration"
  | "external_actions"
  | "safety_bypass";
CategoryDescription
behavioral_override_lowAttempts to override system behavior or instructions
role_manipulationAttempts to manipulate the AI’s role or identity
context_injectionInjection of malicious context or instructions
instruction_hierarchy_manipulationManipulation of instruction priority or hierarchy
output_manipulationAttempts to control output format or content
data_exfiltrationAttempts to extract sensitive data
external_actionsAttempts to trigger external actions or API calls
safety_bypassAttempts to bypass safety measures or content filters

​
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 = "free" | "standard" | "premium" | "enterprise";

​
Client Configuration

​
Constructor Options

interface CentureClientOptions {
  apiKey?: string;
  baseUrl?: string;
  fetch?: typeof fetch;
  fetchOptions?: RequestInit;
}
Options:
​
apiKey
string
Your Centure API key. If not provided, the client reads from the CENTURE_API_KEY environment variable.
​
baseUrl
string
default:"https://api.centure.ai"
The base URL for the Centure API. Override this for testing or custom deployments.
​
fetch
typeof fetch
Custom fetch implementation. Use this to provide a different fetch function (e.g., node-fetch for older Node.js versions).
​
fetchOptions
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 ClassHTTP StatusDescription
MissingApiKeyErrorN/ANo API key provided in options or environment
UnauthorizedError401Invalid or expired API key
BadRequestError400Invalid request format or parameters
PayloadTooLargeError413Image 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})`);
    });
  }
}

​
Next Steps

Quickstart

Return to the quickstart guide for installation and basic usage

MCP Integration

Secure Model Context Protocol applications with the SDK