/extract endpoint. Start with the quick integration prompt to get something working fast, or use the production-ready prompt if you’re building for a live environment.
Prompts
Quick integration
Paste this prompt to generate a minimal TypeScript function - useful for prototyping or one-off scripts.Quick integration prompt
Write a TypeScript async function `extractEntities` that calls the ScaleDown entity
extraction API and returns the parsed response.
API details:
- Endpoint: POST https://api.scaledown.xyz/extract
- Auth: HTTP header `x-api-key: <your key>`
- Request body (JSON):
{
"text": "<the document or passage to search>", // optional if document is provided
"document": "<base64-encoded file>", // optional; image or PDF
"document_mime_type": "image/jpeg", // required when document is set
"instruction": "<optional global instruction>", // optional; prepended before the text
"entities": {
"<EntityTypeName>": "<plain English description of what to look for>"
// values can also be nested objects or arrays - see structured extraction below
}
}
Either "text" or "document" must be provided. If both are given, OCR text is appended
after the plain text before extraction. The keys in "entities" are names you choose
(e.g. "Name", "Email", "Company"). The values are descriptions of what each key should match.
The optional "instruction" field is prepended before the text and applies globally across
all entity types - use it for deduplication rules, ranking constraints, or output format requirements.
- Success response (JSON):
{
"entities": [
{
"text": "<the exact matched span from the input>",
"type": "<EntityTypeName matching a key you defined>",
"confidence": 1.0,
"start": 0,
"end": 10,
"context": "<up to 500 characters of surrounding text on each side>"
}
],
"structured_result": null, // populated when nested/array entity schemas are used
"ocr_text": null // populated when a document was processed
}
- Error responses: 422 (bad body, neither text nor document, or OCR failure),
500 (server error), 504 (timeout)
Function signature:
extractEntities(
payload: { text?: string; document?: string; document_mime_type?: string;
entities: Record<string, unknown> },
apiKey: string
): Promise<{ entities: Array<{ text: string; type: string; confidence: number;
start: number; end: number; context: string }>;
structured_result: Record<string, unknown> | null;
ocr_text: string | null }>
Requirements:
- Use the native fetch API (Node 18+).
- Throw an Error that includes the HTTP status code and response body text on
any non-2xx response.
- Return the full parsed response on success.
Production-ready
Paste this prompt to generate a fully typed TypeScript service class with error handling, retries, and environment-variable-based configuration.Production-ready prompt
Write a production-quality TypeScript module for integrating the ScaleDown entity
extraction API.
API details:
- Endpoint: POST https://api.scaledown.xyz/extract
- Auth: HTTP header `x-api-key: <your key>`
- Request body (JSON):
{
"text": "<document or passage to search>", // optional if document is provided
"document": "<base64-encoded file>", // optional; image or PDF
"document_mime_type": "application/pdf", // required when document is set
"instruction": "<optional global instruction>", // optional; prepended before the text
"entities": {
"<TypeName>": "<description string>"
| {
"description": "<what to look for>",
"threshold": 0.0–1.0, // optional, overrides global threshold for this type
"top_n": number // optional, max results for this type; 0 = unlimited
}
| { "<field>": "<description>", ... } // nested object schema
| [{ "<field>": "<description>", ... }] // array-of-objects schema
},
"threshold": 0.5, // optional global confidence cutoff, default 0.5
"top_n": 0 // optional global max results per type, default 0 (unlimited)
}
Either "text" or "document" must be provided. If both are given, the OCR text is
appended after the plain text before extraction. The optional "instruction" field is
prepended before the text and applies globally across all entity types.
- Success response (JSON):
{
"entities": [
{
"text": "<matched span>",
"type": "<TypeName>",
"confidence": 1.0,
"start": 0,
"end": 10,
"context": "<up to 500 chars of surrounding text on each side>"
}
],
"structured_result": { // present when nested/array schemas are used
"<TypeName>": <value> | { ... } | [ ... ] | null
} | null,
"ocr_text": "<raw OCR text>" | null
}
Scalar entity results are in "entities"; nested object and array results are in
"structured_result". Results within each scalar type are ranked by confidence
descending before top_n is applied.
- Error responses: 422 (malformed body, neither text nor document, or OCR failure),
500 (server error), 504 (timeout)
Apply these programming principles:
1. Environment configuration - Load the API key from process.env.SCALEDOWN_API_KEY.
Throw a clear Error at construction time if the variable is undefined or empty,
with a message that tells the developer exactly which variable to set.
2. TypeScript interfaces - Define the following:
EntityDefinition: string
| { description: string; threshold?: number; top_n?: number }
| Record<string, unknown>
| Array<Record<string, unknown>>
ExtractOptions: { threshold?: number; top_n?: number }
ExtractedEntity: { text: string; type: string; confidence: number;
start: number; end: number; context: string }
ExtractResult: {
entities: ExtractedEntity[];
structured_result: Record<string, unknown> | null;
ocr_text: string | null;
}
3. Custom error class - Define ScaleDownError extending Error with fields
status: number and body: string, setting name = "ScaleDownError".
4. Single-responsibility client - Implement a ScaleDownExtractClient class with one
public async method:
extract(
payload: {
text?: string;
document?: string;
document_mime_type?: string;
entities: Record<string, EntityDefinition>;
},
options?: ExtractOptions
): Promise<ExtractResult>
No global state; the API key is stored as a private readonly field.
5. Retry with exponential backoff - On HTTP 5xx or 504 status, wait 2 000 ms
before retry 1, 4 000 ms before retry 2, 8 000 ms before retry 3.
Throw ScaleDownError after all three retries are exhausted.
Throw ScaleDownError immediately on 422 (not retriable).
6. Use fetch (Node 18+ built-in). No external HTTP dependencies. Full type annotations.
LangChain tool
Paste this prompt to generate a LangChain Tool that makes the Extract endpoint available to an AI agent.LangChain tool prompt
Write a Python LangChain Tool subclass called ScaleDownExtractTool that wraps the
ScaleDown entity extraction API so it can be used as a tool inside a LangChain agent.
ScaleDown API details:
- Endpoint: POST https://api.scaledown.xyz/extract
- Auth: HTTP header `x-api-key: <your key>`
- Request body (JSON):
{
"text": "<document or passage to search>", // optional if document is provided
"document": "<base64-encoded file>", // optional; image or PDF
"document_mime_type": "image/jpeg", // required when document is set
"entities": {
"<TypeName>": "<description string>"
| { "description": str, "threshold": float, "top_n": int }
},
"threshold": 0.5, // optional, global confidence cutoff, default 0.5
"top_n": 0 // optional, max results per type, 0 = unlimited, default 0
}
Either "text" or "document" must be provided.
- Success response (JSON):
{
"entities": [
{ "text": str, "type": str, "confidence": float,
"start": int, "end": int, "context": str }
],
"structured_result": dict | None,
"ocr_text": str | None
}
- Error responses: 422 (bad body, neither text nor document, or OCR failure),
500 (server error), 504 (timeout)
Requirements:
1. Environment configuration - Load SCALEDOWN_API_KEY from os.environ in __init__.
Raise ValueError with a clear message at init time if the variable is absent.
2. Tool metadata - Set:
name = "extract_entities"
description = a clear sentence explaining that the tool extracts named entities
from text (or a base64-encoded document) using a plain-English schema, and
describing the expected input format.
3. Input format - The tool's _run method accepts a single JSON string with keys:
{
"text": str, // optional if document is provided
"document": str, // optional base64-encoded file
"document_mime_type": str, // required when document is set
"entities": { "TypeName": "desc" }, // required
"threshold": float, // optional, default 0.5
"top_n": int // optional, default 0
}
Parse it with json.loads; return a JSON error string if parsing fails.
4. Return format - Return a JSON-encoded string of the full response (entities,
structured_result, ocr_text) on success. On any API error (network failure,
non-2xx status, unexpected response shape), return a JSON string
{ "error": "<message>" } rather than raising an exception, so the agent can
handle the failure gracefully.
5. Async version - Implement _arun as an async version of _run using aiohttp.
Reuse the same request-building and response-parsing logic.
6. Usage example - Include a short code snippet at the bottom showing how to
instantiate the tool and add it to a LangChain agent's tools list.
What the production prompt generates
The production-ready prompt instructs the AI to apply six programming principles. Here is an example of the code it produces:Principles encoded in the production-ready prompt: environment-variable config, full TypeScript interfaces, custom error class, single-responsibility service client, retry with exponential backoff, no external HTTP dependencies.
Show Example output from the production-ready prompt
Show Example output from the production-ready prompt
type EntityDefinition =
| string
| { description: string; threshold?: number; top_n?: number };
interface ExtractOptions {
threshold?: number;
top_n?: number;
}
interface ExtractedEntity {
text: string;
type: string;
confidence: number;
start: number;
end: number;
context: string;
}
interface ExtractResult {
entities: ExtractedEntity[];
}
class ScaleDownError extends Error {
constructor(public status: number, public body: string) {
super(`ScaleDown API error ${status}: ${body}`);
this.name = "ScaleDownError";
}
}
class ScaleDownExtractClient {
private static readonly BASE_URL = "https://api.scaledown.xyz/extract";
private readonly apiKey: string;
constructor() {
const key = process.env.SCALEDOWN_API_KEY;
if (!key) {
throw new Error(
"SCALEDOWN_API_KEY environment variable is missing or empty. " +
"Set it with: export SCALEDOWN_API_KEY=your_key_here"
);
}
this.apiKey = key;
}
async extract(
text: string,
entitySchema: Record<string, EntityDefinition>,
options?: ExtractOptions
): Promise<ExtractResult> {
const body = { text, entities: entitySchema, ...options };
const retryDelays = [2000, 4000, 8000];
let lastError: ScaleDownError | undefined;
for (let attempt = 0; attempt <= retryDelays.length; attempt++) {
if (attempt > 0) {
await new Promise((r) => setTimeout(r, retryDelays[attempt - 1]));
}
const response = await fetch(ScaleDownExtractClient.BASE_URL, {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-key": this.apiKey,
},
body: JSON.stringify(body),
});
if (response.ok) {
return response.json() as Promise<ExtractResult>;
}
const bodyText = await response.text();
if (response.status === 429 || response.status >= 500) {
lastError = new ScaleDownError(response.status, bodyText);
continue; // retry
}
// 400, 401: not retriable
throw new ScaleDownError(response.status, bodyText);
}
throw lastError!;
}
}
const client = new ScaleDownExtractClient(); // reads SCALEDOWN_API_KEY from env
const result = await client.extract(
"Henry Wang is a CS student from the SF Bay Area. Twitter: @henryw",
{
Name: "Full name of the person",
Twitter: { description: "Twitter or X handle", threshold: 0.8, top_n: 1 },
},
{ threshold: 0.5 }
);
for (const entity of result.entities) {
console.log(`${entity.type}: "${entity.text}" (confidence: ${entity.confidence})`);
}