Integrate Extract

Copy one of these prompts into Claude, ChatGPT, or any AI assistant to generate integration code for the /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
          | {                                             // classification key
              "labels": [ "<label>" | { "name": "<label>", "rubric": "<when it applies>" }, ... ],  // 2–26 labels
              "description": "<optional context for the decision>"  // optional
            }
      },
      "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.
  A key whose object contains a "labels" list is a classification key: it is routed to
  the classification model instead of extracted, and its "confidence" is the calibrated
  probability of the chosen label (returned as the entity "text"). Its "start"/"end"/
  "context" point at the verbatim evidence phrase backing the decision (not the label
  text, which is usually inferred and not present verbatim), falling back to 0 / "" when
  no evidence is found. A classification key with fewer than 2 or more than 26 labels
  returns 422.
- 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

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!;
  }
}

Usage:

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})`);
}

Getting Started

Compress

Summarize

Extract

Classify

Batch

Prompts

Quick integration

Production-ready

LangChain tool

What the production prompt generates

​Prompts

​Quick integration

​Production-ready

​LangChain tool

​What the production prompt generates

Prompts

Quick integration

Production-ready

LangChain tool

What the production prompt generates