Extract

Extract

curl --request POST \
  --url https://api.scaledown.xyz/extract \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "text": "<string>",
  "entities": {},
  "threshold": 0.5,
  "top_n": 0
}
'

import requests

url = "https://api.scaledown.xyz/extract"

payload = {
    "text": "<string>",
    "entities": {},
    "threshold": 0.5,
    "top_n": 0
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({text: '<string>', entities: {}, threshold: 0.5, top_n: 0})
};

fetch('https://api.scaledown.xyz/extract', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.scaledown.xyz/extract",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'text' => '<string>',
    'entities' => [
        
    ],
    'threshold' => 0.5,
    'top_n' => 0
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.scaledown.xyz/extract"

	payload := strings.NewReader("{\n  \"text\": \"<string>\",\n  \"entities\": {},\n  \"threshold\": 0.5,\n  \"top_n\": 0\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.scaledown.xyz/extract")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"<string>\",\n  \"entities\": {},\n  \"threshold\": 0.5,\n  \"top_n\": 0\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.scaledown.xyz/extract")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"text\": \"<string>\",\n  \"entities\": {},\n  \"threshold\": 0.5,\n  \"top_n\": 0\n}"

response = http.request(request)
puts response.read_body

{
  "entities": [
    {
      "text": "<string>",
      "type": "<string>",
      "confidence": 123,
      "start": 123,
      "end": 123,
      "context": "<string>"
    }
  ]
}

POST

extract

Extract

curl --request POST \
  --url https://api.scaledown.xyz/extract \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "text": "<string>",
  "entities": {},
  "threshold": 0.5,
  "top_n": 0
}
'

import requests

url = "https://api.scaledown.xyz/extract"

payload = {
    "text": "<string>",
    "entities": {},
    "threshold": 0.5,
    "top_n": 0
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({text: '<string>', entities: {}, threshold: 0.5, top_n: 0})
};

fetch('https://api.scaledown.xyz/extract', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.scaledown.xyz/extract",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'text' => '<string>',
    'entities' => [
        
    ],
    'threshold' => 0.5,
    'top_n' => 0
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.scaledown.xyz/extract"

	payload := strings.NewReader("{\n  \"text\": \"<string>\",\n  \"entities\": {},\n  \"threshold\": 0.5,\n  \"top_n\": 0\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.scaledown.xyz/extract")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"<string>\",\n  \"entities\": {},\n  \"threshold\": 0.5,\n  \"top_n\": 0\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.scaledown.xyz/extract")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"text\": \"<string>\",\n  \"entities\": {},\n  \"threshold\": 0.5,\n  \"top_n\": 0\n}"

response = http.request(request)
puts response.read_body

{
  "entities": [
    {
      "text": "<string>",
      "type": "<string>",
      "confidence": 123,
      "start": 123,
      "end": 123,
      "context": "<string>"
    }
  ]
}

Overview

The /extract endpoint runs Named Entity Recognition (NER) over a block of text. Unlike standard NER, you define the entity types you want in plain English - the model uses your descriptions to find matching spans, returning each one with a confidence score and surrounding context. Every result includes surrounding text on each side of the matched span, so you can validate or use the extracted value without going back to the source. The amount of context returned is controlled by the context_chars parameter (default: 500 characters per side).

Request

string

The input text to extract entities from. Can be a full document, web page content, article, or any plain text string. Either text or document must be provided. If both are given, the OCR text is appended after text.

string

A base64-encoded file to extract entities from. Supported formats: JPEG, PNG, TIFF, single-page PDF, multi-page PDF. The file is processed via AWS Textract OCR and the extracted text is used as input. Either text or document must be provided.

string

MIME type of the document (e.g. "image/jpeg", "application/pdf"). Required when document is provided.

string

Optional global instruction prepended to the text before extraction. Use this to provide rules that apply across all entity types - for example, deduplication logic, ranking constraints, or output format requirements. This is separate from per-entity descriptions.

number

default:500

Number of characters of surrounding text to include on each side of a matched entity span in the context response field. Set to 0 to omit context entirely, or increase for wider windows on long documents.

object

required

A mapping of entity type names to their definition. Each value can be one of:

A plain string - a description of what to look for
An object - with optional description, threshold, and top_n fields
A nested object - defining a structured sub-schema (object with named fields)
An array of objects - defining a repeated structured schema (e.g. a list of line items)
A classification key - an object with a labels list, routed to the classifier (see below)

Show Entity object fields

string

What this entity type represents. Used as the model’s search criteria.

number

Per-entity confidence cutoff (0–1). Overrides the global threshold for this type only.

number

Per-entity result limit. Overrides the global top_n for this type only.

Show Classification key fields

A key whose object contains a labels list is treated as a classification key. Rather than copying a value out of the text, its value is decided by choosing among your labels using our classification model - which is purpose-built for categorical and boolean decisions and is more accurate on them than the extraction model. The response still includes the evidence span and surrounding context. See Classification keys for details.

array

required

The candidate values to choose between (2–26). Each label is either a plain string (the value to return) or an object with name and rubric fields, where rubric describes when that label applies. Providing rubrics improves accuracy.

string

Optional context about the decision being made for this key. Prepended to the combined rubric.

number

Global confidence threshold (0–1). Entities below this score are filtered out. Can be overridden per entity type.

number

default:0

Global limit on how many results to return per entity type, ranked by confidence descending. 0 returns all results above the threshold. Can be overridden per entity type.

Response

array

List of extracted scalar entities, sorted by confidence descending within each type. For nested or array entity types, values appear in structured_result instead.

Show Entity object

string

The exact text span extracted from the input.

string

The entity type name, matching a key from your entities request field.

number

Model confidence score between 0 and 1. For classification keys, this is the calibrated probability of the chosen label.

number

Character offset of the start of the entity in the input text.

number

Character offset of the end of the entity in the input text.

string

Surrounding text around the entity span. The window size is controlled by the context_chars request parameter (default: 500 characters per side).

object | null

Present when any entity in the request uses a nested object or array schema. Contains the full structured extraction result keyed by entity name. Scalar fields from the same request also appear here alongside their nested counterparts. null for flat extraction requests.

string | null

The raw text extracted from the document via OCR. null if no document was provided.

Error responses

Status	Meaning
`422 Unprocessable Entity`	Malformed request body, neither `text` nor `document` provided, a classification key with fewer than 2 or more than 26 labels, or OCR failed.
`500 Internal Server Error`	Inference service unavailable.
`504 Gateway Timeout`	Extraction request timed out.

Authentication

Include your API key in every request using the x-api-key header.

-H "x-api-key: <your-api-key>"

Examples

Basic extraction

curl -X POST https://api.scaledown.xyz/extract \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "text": "Henry Wang is a CS student from the SF Bay Area. You can find him on Twitter at @henryw and Instagram at @b0i.",
    "entities": {
      "Name": "Full name of the person",
      "Twitter": "Twitter or X handle",
      "Instagram": "Instagram username"
    }
  }'

import requests

response = requests.post(
    "https://api.scaledown.xyz/extract",
    headers={"x-api-key": "<your-api-key>"},
    json={
        "text": "Henry Wang is a CS student from the SF Bay Area. You can find him on Twitter at @henryw and Instagram at @b0i.",
        "entities": {
            "Name": "Full name of the person",
            "Twitter": "Twitter or X handle",
            "Instagram": "Instagram username",
        },
    },
)
print(response.json())

const response = await fetch("https://api.scaledown.xyz/extract", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<your-api-key>",
  },
  body: JSON.stringify({
    text: "Henry Wang is a CS student from the SF Bay Area. You can find him on Twitter at @henryw and Instagram at @b0i.",
    entities: {
      Name: "Full name of the person",
      Twitter: "Twitter or X handle",
      Instagram: "Instagram username",
    },
  }),
});
const data = await response.json();

Response:

{
  "entities": [
    {
      "text": "Henry Wang",
      "type": "Name",
      "confidence": 0.994,
      "start": 0,
      "end": 10,
      "context": "Henry Wang is a CS student from the SF Bay Area. You can find him on Twitter at @henryw and Instagram at @b0i."
    },
    {
      "text": "@henryw",
      "type": "Twitter",
      "confidence": 0.976,
      "start": 79,
      "end": 86,
      "context": "Henry Wang is a CS student from the SF Bay Area. You can find him on Twitter at @henryw and Instagram at @b0i."
    },
    {
      "text": "@b0i",
      "type": "Instagram",
      "confidence": 0.978,
      "start": 104,
      "end": 108,
      "context": "Henry Wang is a CS student from the SF Bay Area. You can find him on Twitter at @henryw and Instagram at @b0i."
    }
  ]
}

Extracting from an image (OCR)

Extract works directly on photos and scans, not just plain text. Pass a base64-encoded image (or PDF) in the document field - we run OCR via AWS Textract, then extract your entities from the recovered text. This is the path to use for receipts, invoices, IDs, forms, business cards, and any photographed or scanned page. The raw OCR output is returned as ocr_text so you can audit exactly what the model read.

Supported formats: JPEG, PNG, TIFF, and single- or multi-page PDF. document_mime_type is required whenever document is set - use the file’s real MIME type (e.g. image/jpeg, image/png, application/pdf) so Textract decodes the bytes correctly. You can also send text and document together; the OCR output is appended after your text.

The example below extracts fields from a photographed receipt:

DOCUMENT=$(base64 -b 0 -i receipt.jpg)

curl -X POST https://api.scaledown.xyz/extract \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "document": "'"$DOCUMENT"'",
    "document_mime_type": "image/jpeg",
    "entities": {
      "merchant": "Name of the store or merchant",
      "total": "Total amount paid, including currency",
      "date": "Date of the transaction"
    }
  }'

import base64
import requests

with open("receipt.jpg", "rb") as f:
    document = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://api.scaledown.xyz/extract",
    headers={"x-api-key": "<your-api-key>"},
    json={
        "document": document,
        "document_mime_type": "image/jpeg",
        "entities": {
            "merchant": "Name of the store or merchant",
            "total": "Total amount paid, including currency",
            "date": "Date of the transaction",
        },
    },
)
data = response.json()
print(data["entities"])
print(data["ocr_text"])  # raw text recovered from the image

import fs from "fs";

const document = fs.readFileSync("receipt.jpg").toString("base64");

const response = await fetch("https://api.scaledown.xyz/extract", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<your-api-key>",
  },
  body: JSON.stringify({
    document,
    document_mime_type: "image/jpeg",
    entities: {
      merchant: "Name of the store or merchant",
      total: "Total amount paid, including currency",
      date: "Date of the transaction",
    },
  }),
});
const data = await response.json();
console.log(data.ocr_text); // raw text recovered from the image

Response:

{
  "entities": [
    { "text": "Blue Bottle Coffee", "type": "merchant", "confidence": 0.98, "start": 0, "end": 18, "context": "Blue Bottle Coffee ..." },
    { "text": "$12.50", "type": "total", "confidence": 0.95, "start": 38, "end": 44, "context": "... TOTAL $12.50" },
    { "text": "03/14/2026", "type": "date", "confidence": 0.97, "start": 19, "end": 29, "context": "Blue Bottle Coffee 03/14/2026 ..." }
  ],
  "structured_result": null,
  "ocr_text": "Blue Bottle Coffee\n03/14/2026\n1x Latte  $5.00\n1x Croissant  $7.50\nTOTAL $12.50"
}

Extracting from a PDF

PDFs (single- or multi-page) work the same way - just set document_mime_type to application/pdf.

DOCUMENT=$(base64 -b 0 -i contract.pdf)

curl -X POST https://api.scaledown.xyz/extract \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "document": "'"$DOCUMENT"'",
    "document_mime_type": "application/pdf",
    "entities": {
      "party_name": "Name of a party to the contract",
      "effective_date": "The date the contract takes effect",
      "governing_law": "The jurisdiction or governing law clause"
    }
  }'

import base64
import requests

with open("contract.pdf", "rb") as f:
    document = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://api.scaledown.xyz/extract",
    headers={"x-api-key": "<your-api-key>"},
    json={
        "document": document,
        "document_mime_type": "application/pdf",
        "entities": {
            "party_name": "Name of a party to the contract",
            "effective_date": "The date the contract takes effect",
            "governing_law": "The jurisdiction or governing law clause",
        },
    },
)
print(response.json())

import fs from "fs";

const document = fs.readFileSync("contract.pdf").toString("base64");

const response = await fetch("https://api.scaledown.xyz/extract", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<your-api-key>",
  },
  body: JSON.stringify({
    document,
    document_mime_type: "application/pdf",
    entities: {
      party_name: "Name of a party to the contract",
      effective_date: "The date the contract takes effect",
      governing_law: "The jurisdiction or governing law clause",
    },
  }),
});
const data = await response.json();

Structured (nested) extraction

For more complex documents, you can define nested schemas to extract structured objects or arrays of objects. Use a nested object to extract a single structured group of fields, or an array of objects to extract a repeated structure such as invoice line items. The full structured output is returned in the structured_result field. Scalar fields in the same request are also included there, alongside any nested values. Nested object example - extract a single structured address:

curl -X POST https://api.scaledown.xyz/extract \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "text": "Ship to: Jane Smith, 42 Maple Street, Springfield, IL 62701.",
    "entities": {
      "recipient": "The full name of the recipient",
      "address": {
        "street": "Street address including number",
        "city": "City name",
        "state": "Two-letter state code",
        "zip": "ZIP or postal code"
      }
    }
  }'

import requests

response = requests.post(
    "https://api.scaledown.xyz/extract",
    headers={"x-api-key": "<your-api-key>"},
    json={
        "text": "Ship to: Jane Smith, 42 Maple Street, Springfield, IL 62701.",
        "entities": {
            "recipient": "The full name of the recipient",
            "address": {
                "street": "Street address including number",
                "city": "City name",
                "state": "Two-letter state code",
                "zip": "ZIP or postal code",
            },
        },
    },
)
print(response.json())

const response = await fetch("https://api.scaledown.xyz/extract", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<your-api-key>",
  },
  body: JSON.stringify({
    text: "Ship to: Jane Smith, 42 Maple Street, Springfield, IL 62701.",
    entities: {
      recipient: "The full name of the recipient",
      address: {
        street: "Street address including number",
        city: "City name",
        state: "Two-letter state code",
        zip: "ZIP or postal code",
      },
    },
  }),
});
const data = await response.json();

Response:

{
  "entities": [
    {
      "text": "Jane Smith",
      "type": "recipient",
      "confidence": 1.0,
      "start": 9,
      "end": 19,
      "context": "Ship to: Jane Smith, 42 Maple Street, Springfield, IL 62701."
    }
  ],
  "structured_result": {
    "recipient": "Jane Smith",
    "address": {
      "street": "42 Maple Street",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701"
    }
  },
  "ocr_text": null
}

Array schema example - extract invoice line items:

curl -X POST https://api.scaledown.xyz/extract \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "text": "Invoice: 1x Widget A @ $10.00, 3x Widget B @ $5.00, 1x Shipping @ $8.50",
    "entities": {
      "vendor": "The name of the vendor or supplier",
      "line_items": [
        {
          "description": "Description or name of the line item",
          "quantity": "Quantity ordered",
          "unit_price": "Price per unit"
        }
      ]
    }
  }'

import requests

response = requests.post(
    "https://api.scaledown.xyz/extract",
    headers={"x-api-key": "<your-api-key>"},
    json={
        "text": "Invoice: 1x Widget A @ $10.00, 3x Widget B @ $5.00, 1x Shipping @ $8.50",
        "entities": {
            "vendor": "The name of the vendor or supplier",
            "line_items": [
                {
                    "description": "Description or name of the line item",
                    "quantity": "Quantity ordered",
                    "unit_price": "Price per unit",
                }
            ],
        },
    },
)
print(response.json())

const response = await fetch("https://api.scaledown.xyz/extract", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<your-api-key>",
  },
  body: JSON.stringify({
    text: "Invoice: 1x Widget A @ $10.00, 3x Widget B @ $5.00, 1x Shipping @ $8.50",
    entities: {
      vendor: "The name of the vendor or supplier",
      line_items: [
        {
          description: "Description or name of the line item",
          quantity: "Quantity ordered",
          unit_price: "Price per unit",
        },
      ],
    },
  }),
});
const data = await response.json();

Response:

{
  "entities": [],
  "structured_result": {
    "vendor": null,
    "line_items": [
      { "description": "Widget A", "quantity": "1", "unit_price": "$10.00" },
      { "description": "Widget B", "quantity": "3", "unit_price": "$5.00" },
      { "description": "Shipping", "quantity": "1", "unit_price": "$8.50" }
    ]
  },
  "ocr_text": null
}

When using array schemas, array fields appear only in structured_result. The entities array contains only scalar fields from the same request that could be matched to a span in the text.

Classification keys

Some of the fields you want are not really extraction targets - they are decisions. “Is this account past due?” or “Is this an electric or gas meter?” have no verbatim span to pull; they require judging the text against a fixed set of options. The extraction model is tuned to copy spans out of the source, so it is a poor fit for these, and mixing them into an extraction call drags down accuracy for every key. To handle these, mark the key as a classification key by giving it a labels list. Any key whose object contains labels is split out of the extraction call and routed to our classification model instead - a model purpose-built for categorical and boolean decisions, using constrained decoding over your labels with calibrated confidence scores. The rest of the request extracts as normal, and classified values are merged back into the same response so nothing changes on your side. Labels can be plain strings, or objects with a name and a rubric describing when that label applies. Rubrics meaningfully improve accuracy - prefer them over bare strings for anything non-obvious. An optional per-key description adds context about the decision.

curl -X POST https://api.scaledown.xyz/extract \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "text": "Account for Jane Doe. Balance is 90 days past due. Service: natural gas line.",
    "entities": {
      "account_holder": "Full name of the account holder",
      "is_delinquent": {
        "description": "Whether the account is behind on payments",
        "labels": [
          { "name": "delinquent", "rubric": "Balance is past due, in collections, or 30+ days overdue" },
          { "name": "current", "rubric": "Account is paid up to date, with no past-due balance" }
        ]
      },
      "meter_type": {
        "labels": ["electric", "gas"]
      }
    }
  }'

import requests

response = requests.post(
    "https://api.scaledown.xyz/extract",
    headers={"x-api-key": "<your-api-key>"},
    json={
        "text": "Account for Jane Doe. Balance is 90 days past due. Service: natural gas line.",
        "entities": {
            "account_holder": "Full name of the account holder",
            "is_delinquent": {
                "description": "Whether the account is behind on payments",
                "labels": [
                    {"name": "delinquent", "rubric": "Balance is past due, in collections, or 30+ days overdue"},
                    {"name": "current", "rubric": "Account is paid up to date, with no past-due balance"},
                ],
            },
            "meter_type": {"labels": ["electric", "gas"]},
        },
    },
)
print(response.json())

const response = await fetch("https://api.scaledown.xyz/extract", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<your-api-key>",
  },
  body: JSON.stringify({
    text: "Account for Jane Doe. Balance is 90 days past due. Service: natural gas line.",
    entities: {
      account_holder: "Full name of the account holder",
      is_delinquent: {
        description: "Whether the account is behind on payments",
        labels: [
          { name: "delinquent", rubric: "Balance is past due, in collections, or 30+ days overdue" },
          { name: "current", rubric: "Account is paid up to date, with no past-due balance" },
        ],
      },
      meter_type: { labels: ["electric", "gas"] },
    },
  }),
});
const data = await response.json();

Response:

{
  "entities": [
    {
      "text": "Jane Doe",
      "type": "account_holder",
      "confidence": 1.0,
      "start": 12,
      "end": 20,
      "context": "Account for Jane Doe. Balance is 90 days past due. Service: natural gas line."
    },
    {
      "text": "delinquent",
      "type": "is_delinquent",
      "confidence": 0.94,
      "start": 33,
      "end": 49,
      "context": "Account for Jane Doe. Balance is 90 days past due. Service: natural gas line."
    },
    {
      "text": "gas",
      "type": "meter_type",
      "confidence": 0.88,
      "start": 60,
      "end": 76,
      "context": "Account for Jane Doe. Balance is 90 days past due. Service: natural gas line."
    }
  ],
  "structured_result": null,
  "ocr_text": null
}

The classified value is returned as the entity text, and confidence is the calibrated probability of the chosen label. The label itself is usually not a verbatim span in the source (it was inferred), so start/end and context instead point at the evidence the model used for the decision - here, "90 days past due" for is_delinquent, not the word “delinquent”. If no relevant evidence is found, start/end fall back to 0 and context is empty. In a structured (nested) request, classified values also appear in structured_result under their key.

A classification key still counts as part of your single /extract call - one request in, one response out, billed as one extract call. Each classification key needs at least 2 and at most 26 labels; outside that range the request returns 422.

To locate the evidence span, each classification key runs a brief follow-up pass that pulls the verbatim phrase backing the decision. This is transparent - the span and context are populated for you - but it does add to the token usage reported for the call. If you don’t need spans for a boolean/categorical field, you can ignore start/end/context on those entities.

With per-entity overrides

Use per-entity threshold and top_n when different entity types need different precision, or when you only want the single best match for a given type.

curl -X POST https://api.scaledown.xyz/extract \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "text": "...",
    "entities": {
      "Name": {
        "description": "Full name of a person",
        "threshold": 0.3,
        "top_n": 1
      },
      "Company": {
        "description": "Company or organization name",
        "threshold": 0.7
      },
      "Email": "Email address"
    },
    "threshold": 0.5,
    "top_n": 5
  }'

import requests

response = requests.post(
    "https://api.scaledown.xyz/extract",
    headers={"x-api-key": "<your-api-key>"},
    json={
        "text": "...",
        "entities": {
            "Name": {"description": "Full name of a person", "threshold": 0.3, "top_n": 1},
            "Company": {"description": "Company or organization name", "threshold": 0.7},
            "Email": "Email address",
        },
        "threshold": 0.5,
        "top_n": 5,
    },
)
print(response.json())

const response = await fetch("https://api.scaledown.xyz/extract", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<your-api-key>",
  },
  body: JSON.stringify({
    text: "...",
    entities: {
      Name: { description: "Full name of a person", threshold: 0.3, top_n: 1 },
      Company: { description: "Company or organization name", threshold: 0.7 },
      Email: "Email address",
    },
    threshold: 0.5,
    top_n: 5,
  }),
});
const data = await response.json();

In this example:

Name uses threshold 0.3 and returns at most 1 result
Company uses threshold 0.7 and returns up to 5 results (global top_n)
Email uses the global threshold 0.5 and returns up to 5 results

Writing good entity labels

The entity name and description are both used as part of the model’s search criteria - wording them well is the biggest lever you have on extraction quality. Use lowercase or Title Case. The model was trained with lowercase labels. Keeping your entity names lowercase (e.g. person, company) or Title Case (e.g. Person, Company) produces better results than ALL_CAPS or other conventions. Be specific with names, and test synonyms. The entity name itself influences what the model looks for. person and full name will find slightly different things. If results are missing or noisy, try rephrasing the name - person name, individual, or full name may all behave differently on your data. Labels can be descriptive phrases, not just single words. Instead of city, use capital city and population center. The extra context helps the model distinguish between entity types that might otherwise overlap. Descriptions can be full instructions. Rather than "Name of the person", write "Find the first and last name of the person mentioned in the text". Instruction-style descriptions consistently outperform short noun phrases on complex or ambiguous entities. Avoid mixing overlapping granularities in the same call. If you include both location and city, the model has to decide which label to assign to a city - and will often split results unpredictably between them. Pick one level of granularity per concept. Examples:

Instead of	Use
`CITY`	`city` or `City`
`city` + `location` in the same call	just `city` or just `location`
`"Name"`	`"Find the first and last name of the person in the text"`
`"city"` (when you want capitals specifically)	`"capital city and population center"`

Notes

Results within each entity type are ranked by confidence descending before top_n is applied.
The context field is always derived from the original text input - it is not generated by the model.
Character offsets (start, end) refer to byte positions in the original text string.
There is no fixed limit on the number of entity types you can define in a single request.
Classification keys (any entity object with a labels list) are routed to the classification model rather than extracted. Use them for boolean or categorical fields - keeping them out of the extraction path improves accuracy for both.
threshold and top_n do not apply to classification keys - the value is a single chosen label, always returned.

Authorizations

x-api-key

string

header

required

Body

application/json

text

string

required

The input text to extract entities from.

entities

object

required

A mapping of entity type names to their definition.

Show child attributes

threshold

number

default:0.5

Global confidence threshold (0–1).

top_n

number

default:0

Global limit on results per entity type. 0 returns all above threshold.

Response

Successful extraction

entities

object[]

Show child attributes

Overview Integrate Extract

Getting Started

Compress

Summarize

Classify

Batch

Extract

Overview

Request

Response

Error responses

Authentication

Examples

Basic extraction

Extracting from an image (OCR)

Extracting from a PDF

Structured (nested) extraction

Classification keys

With per-entity overrides

Writing good entity labels

Notes

Authorizations

Body

Response

​Overview

​Request

​Response

​Error responses

​Authentication

​Examples

​Basic extraction

​Extracting from an image (OCR)

​Extracting from a PDF

​Structured (nested) extraction

​Classification keys

​With per-entity overrides

​Writing good entity labels

​Notes

Authorizations

Body

Response

Overview

Request

Response

Error responses

Authentication

Examples

Basic extraction

Extracting from an image (OCR)

Extracting from a PDF

Structured (nested) extraction

Classification keys

With per-entity overrides

Writing good entity labels

Notes