Developer Utility APIs | Thousand API

Distance

Calculates distance between two points.

MCP tool: calculate_distance

GET /v1/distance

Parameters:

Parameter	Type	Required	Description
p1	string	✓	Point 1 lat,lon (e.g. 35.681236,139.767125)
p2	string	✓	Point 2 lat,lon (e.g. 34.702485,135.495951)

Request example:

curl "https://api.thousand-api.com/v1/distance?p1=35.681236,139.767125&p2=34.702485,135.495951" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "p1": { "lat": 35.681236, "lon": 139.767125 },
  "p2": { "lat": 34.702485, "lon": 135.495951 },
  "distance_km": 402.3
}

Convert coordinates between WGS84 (GPS), Tokyo Datum (legacy Japanese geodetic system), JGD2011, and GSI/OSM/Google XYZ map tile coordinates. No external libraries; uses Molodensky approximation parameters.

MCP tool: utility.convert_coordinates

WGS84 is the standard GPS coordinate system. Tokyo Datum (tokyo) was used on legacy GSI maps and government systems and can differ from WGS84 by up to about 450 m. JGD2011 (jgd2011) is practically identical to WGS84 but is accepted as a separate datum for future parameter updates. For tile conversion (to=tile), coordinates are normalized to WGS84 before Web Mercator XYZ tile calculation.

GET /v1/geo/convert

Parameters:

Parameter	Type	Required	Description
lat	number	✓	Latitude (-90 to 90)
lng	number	✓	Longitude (-180 to 180)
from	string	✓	Source datum: wgs84 / tokyo / jgd2011
to	string	✓	Target datum: wgs84 / tokyo / jgd2011 / tile
zoom	integer	-	Required when to=tile. Zoom level (integer 0–25)

Response fields:

When converting between datums (to is wgs84 / tokyo / jgd2011), output contains:

Parameter	Description
lat	Converted latitude (rounded to 8 decimal places)
lng	Converted longitude (rounded to 8 decimal places)

When to is tile, output contains:

Parameter	Description
zoom	Zoom level from the request
x	Tile X index (longitude axis, zero-based)
y	Tile Y index (latitude axis; smaller values are farther north)

Request example:

Example 1: WGS84 → Tokyo Datum (convert GPS to legacy Japanese datum)

curl "https://api.thousand-api.com/v1/geo/convert?lat=35.6812&lng=139.7671&from=wgs84&to=tokyo" \
  -H "x-api-key: YOUR_API_KEY"

{
  "from": "wgs84",
  "to": "tokyo",
  "input": { "lat": 35.6812, "lng": 139.7671 },
  "output": { "lat": 35.68109304, "lng": 139.76727453 }
}

Example 2: Tokyo Datum → WGS84 (legacy data to GPS coordinates)

curl "https://api.thousand-api.com/v1/geo/convert?lat=35.68109304&lng=139.76727453&from=tokyo&to=wgs84" \
  -H "x-api-key: YOUR_API_KEY"

{
  "from": "tokyo",
  "to": "wgs84",
  "input": { "lat": 35.68109304, "lng": 139.76727453 },
  "output": { "lat": 35.6812, "lng": 139.7671 }
}

Example 3: WGS84 → tile coordinates (zoom=15, GSI-style XYZ)

curl "https://api.thousand-api.com/v1/geo/convert?lat=35.6812&lng=139.7671&from=wgs84&to=tile&zoom=15" \
  -H "x-api-key: YOUR_API_KEY"

{
  "from": "wgs84",
  "to": "tile",
  "input": { "lat": 35.6812, "lng": 139.7671 },
  "output": { "zoom": 15, "x": 29105, "y": 12903 }
}

Color Palette

Generates color palettes (complementary, analogous, triadic, tetradic, shades) from a base hex color. No external dependencies; uses HSL color space for mathematically accurate results.

MCP tool: utility.generate_color_palette

GET /v1/color/palette

Parameters:

Parameter	Type	Required	Description
color	string	✓	Base color in #RRGGBB format
type	string	-	complementary / analogous / triadic / tetradic / shades

Request example:

curl "https://api.thousand-api.com/v1/color/palette?color=%231976D2&type=complementary" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "base": "#1976D2",
  "type": "complementary",
  "palette": [
    {
      "hex": "#1976D2",
      "rgb": "rgb(25, 118, 210)",
      "hsl": "hsl(211, 79%, 46%)",
      "name": "base"
    },
    {
      "hex": "#D27619",
      "rgb": "rgb(210, 118, 25)",
      "hsl": "hsl(31, 79%, 46%)",
      "name": "complement"
    }
  ]
}

Color Space Conversion

Converts colors between HEX, RGB, HSL, HSV, and CMYK. All conversions use RGB as an intermediate for consistent results. No external dependencies; pure conversion formulas only.

MCP tool: convert.color

Pass the returned hex values to utility.calc_color_contrast as foreground/background to verify accessibility of colors obtained from HSL or CMYK. Combine with utility.generate_color_palette for palette generation → format conversion → contrast checking workflows.

GET /v1/color/convert

Parameters:

Parameter	Type	Required	Description
color	string	✓	Source color value (format depends on from)
from	string	✓	Source format: hex / rgb / hsl / hsv / cmyk
color (hex)	string	-	#1976D2 / 1976D2 / #FFF / FFF (3-digit shorthand)
color (rgb)	string	-	25,118,210 / 25, 118, 210 / rgb(25, 118, 210) / {"r":25,"g":118,"b":210}
color (hsl)	string	-	210,79,46 / 210, 79, 46 / hsl(210, 79%, 46%)
color (hsv)	string	-	210,88,82 / 210, 88, 82
color (cmyk)	string	-	88,44,0,18 / 88, 44, 0, 18

Response fields:

Parameter	Description
input.format	Input format (hex / rgb / hsl / hsv / cmyk)
input.value	Original input color string (echoed back)
hex	Normalized HEX (uppercase #RRGGBB)
rgb.r / g / b	RGB components (0–255)
hsl.h	Hue (0–360)
hsl.s / l	Saturation and lightness (0–100)
hsv.h	Hue (0–360)
hsv.s / v	Saturation and value (0–100)
cmyk.c / m / y / k	Ink components (0–100)

Request example:

Example 1: Convert HEX to all formats (#1976D2)

curl "https://api.thousand-api.com/v1/color/convert?color=%231976D2&from=hex" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "input": { "format": "hex", "value": "#1976D2" },
  "hex": "#1976D2",
  "rgb": { "r": 25, "g": 118, "b": 210 },
  "hsl": { "h": 210, "s": 79, "l": 46 },
  "hsv": { "h": 210, "s": 88, "v": 82 },
  "cmyk": { "c": 88, "m": 44, "y": 0, "k": 18 }
}

Example 2: Convert HSL to RGB and HEX (CSS variable use case)

curl "https://api.thousand-api.com/v1/color/convert?color=hsl(210%2C%2079%25%2C%2046%25)&from=hsl" \
  -H "x-api-key: YOUR_API_KEY"

{
  "input": { "format": "hsl", "value": "hsl(210, 79%, 46%)" },
  "hex": "#1975D2",
  "rgb": { "r": 25, "g": 117, "b": 210 },
  "hsl": { "h": 210, "s": 79, "l": 46 },
  "hsv": { "h": 210, "s": 88, "v": 82 },
  "cmyk": { "c": 88, "m": 44, "y": 0, "k": 18 }
}

Example 3: Convert CMYK to web color (print data)

curl "https://api.thousand-api.com/v1/color/convert?color=88%2C44%2C0%2C18&from=cmyk" \
  -H "x-api-key: YOUR_API_KEY"

{
  "input": { "format": "cmyk", "value": "88,44,0,18" },
  "hex": "#1975D1",
  "rgb": { "r": 25, "g": 117, "b": 209 },
  "hsl": { "h": 210, "s": 79, "l": 46 },
  "hsv": { "h": 210, "s": 88, "v": 82 },
  "cmyk": { "c": 88, "m": 44, "y": 0, "k": 18 }
}

WCAG Color Contrast

Calculates the WCAG 2.1 contrast ratio between a foreground and background color and returns AA/AAA compliance flags plus a recommendation string. No external dependencies; uses the official relative luminance algorithm.

MCP tool: utility.calc_color_contrast

WCAG 2.1 thresholds: AA normal text 4.5:1, AA large text / UI 3:1, AAA normal text 7:1, AAA large text 4.5:1. Large text means 18pt+ or 14pt+ bold.

Pair palette hex values from utility.generate_color_palette as foreground/background and call this API to filter down to accessible combinations in agent workflows.

GET /v1/color/contrast

Parameters:

Parameter	Type	Required	Description
foreground	string	✓	Foreground HEX (#RRGGBB, RRGGBB, or 3-digit shorthand)
background	string	✓	Background HEX (#RRGGBB, RRGGBB, or 3-digit shorthand)

Request example:

curl "https://api.thousand-api.com/v1/color/contrast?foreground=%23FFFFFF&background=%231976D2" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

Example 1: Sufficient contrast (#FFFFFF / #1976D2)

{
  "foreground": "#FFFFFF",
  "background": "#1976D2",
  "contrast_ratio": 4.6,
  "wcag_aa_normal": true,
  "wcag_aa_large": true,
  "wcag_aaa_normal": false,
  "wcag_aaa_large": true,
  "recommendation": "AA normal + AAA large: good for most use cases (ratio: 4.6:1)"
}

Example 2: Insufficient contrast (Fail)

{
  "foreground": "#777777",
  "background": "#888888",
  "contrast_ratio": 1.26,
  "wcag_aa_normal": false,
  "wcag_aa_large": false,
  "wcag_aaa_normal": false,
  "wcag_aaa_large": false,
  "recommendation": "Fail: insufficient contrast for any WCAG level (ratio: 1.26:1)"
}

Response fields:

Parameter	Description
foreground	Normalized foreground color (uppercase #RRGGBB)
background	Normalized background color (uppercase #RRGGBB)
contrast_ratio	WCAG contrast ratio (2 decimal places)
wcag_aa_normal	Passes AA for normal text (>= 4.5:1)
wcag_aa_large	Passes AA for large text / UI (>= 3:1)
wcag_aaa_normal	Passes AAA for normal text (>= 7:1)
wcag_aaa_large	Passes AAA for large text (>= 4.5:1)
recommendation	Highest compliance level summary (English)

Math Expression Eval

Safely evaluate mathematical expressions. Supports arithmetic, trigonometry, statistics, unit conversion, and variable bindings. Does not use JavaScript eval — runs in a mathjs sandbox with dangerous functions (import, parse, etc.) disabled. A 100ms timeout blocks oversized computations.

MCP tool: utility.calc_expression

POST /v1/math/eval

Parameters:

Parameter	Type	Required	Description
expression	string	required	Expression to evaluate (max 500 characters)
variables	object	-	Variable bindings (values must be number / string / boolean)
precision	integer	-	Decimal places for numeric results (0–15, omit for no limit)

Response fields:

Parameter	Description
expression	Echo of the input expression
variables	Variables used (null when omitted)
result	Evaluation result (number / string / boolean)
result_str	String form of result
precision	Precision applied (null when omitted)

Tax-inclusive calculation example:

Request example:

curl -X POST "https://api.thousand-api.com/v1/math/eval" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expression": "(100000 + 50000) * 1.1"
  }'

Response example:

{
  "expression": "(100000 + 50000) * 1.1",
  "variables": null,
  "result": 165000,
  "result_str": "165000",
  "precision": null
}

Compound interest with variable bindings:

Request example:

curl -X POST "https://api.thousand-api.com/v1/math/eval" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expression": "principal * (1 + rate)^years",
    "variables": {
      "principal": 1000000,
      "rate": 0.05,
      "years": 10
    },
    "precision": 0
  }'

Response example:

{
  "expression": "principal * (1 + rate)^years",
  "variables": {
    "principal": 1000000,
    "rate": 0.05,
    "years": 10
  },
  "result": 1628895,
  "result_str": "1628895",
  "precision": 0
}

Math function (Pythagorean theorem) example:

Request example:

curl -X POST "https://api.thousand-api.com/v1/math/eval" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expression": "sqrt(x^2 + y^2)",
    "variables": {
      "x": 3,
      "y": 4
    }
  }'

Response example:

{
  "expression": "sqrt(x^2 + y^2)",
  "variables": {
    "x": 3,
    "y": 4
  },
  "result": 5,
  "result_str": "5",
  "precision": null
}

Consumption Tax Calc

Calculates Japanese consumption tax (standard 10%, reduced 8%, or any custom rate). Supports exclusive↔inclusive conversion, rounding modes (floor / ceil / round), and multi-item totals. Uses integer yen arithmetic to avoid floating-point errors.

MCP tool: utility.calc_tax

POST /v1/math/tax

Parameters:

Parameter	Type	Required	Description
amount	number	-	Single amount in yen (mutually exclusive with items; one required)
rate	number	-	Tax rate in percent (default: 10, range 0–100)
rounding	string	-	Rounding: floor / ceil / round (default: floor)
direction	string	-	exclusive_to_inclusive (net→gross, default) or inclusive_to_exclusive (gross→net)
items	array	-	Line items; when set, top-level amount/rate ignored. item.rate falls back to top-level rate (then 10)

Response fields:

Parameter	Description
direction	Conversion direction
net	Tax-exclusive amount (single mode)
tax	Tax amount (single mode)
gross	Tax-inclusive amount (single mode)
rate	Applied tax rate (single mode)
items	Per-line net / tax / gross / rate (multi-item mode)
total_net	Total tax-exclusive (multi-item mode)
total_tax	Total tax (multi-item mode)
total_gross	Total tax-inclusive (multi-item mode)
rounding	Rounding mode used

Single amount (exclusive → inclusive):

Request example:

curl -X POST "https://api.thousand-api.com/v1/math/tax" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "rate": 10,
    "rounding": "floor"
  }'

Response example:

{
  "direction": "exclusive_to_inclusive",
  "net": 1000,
  "tax": 100,
  "gross": 1100,
  "rate": 10,
  "rounding": "floor"
}

Multiple items (10% + 8% mixed rates):

Request example:

curl -X POST "https://api.thousand-api.com/v1/math/tax" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "amount": 1000, "rate": 10 },
      { "amount": 500, "rate": 8 }
    ],
    "rounding": "floor"
  }'

Response example:

{
  "direction": "exclusive_to_inclusive",
  "items": [
    { "net": 1000, "tax": 100, "gross": 1100, "rate": 10 },
    { "net": 500, "tax": 40, "gross": 540, "rate": 8 }
  ],
  "total_net": 1500,
  "total_tax": 140,
  "total_gross": 1640,
  "rounding": "floor"
}

Inclusive → exclusive reverse calculation:

Request example:

curl -X POST "https://api.thousand-api.com/v1/math/tax" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1100,
    "rate": 10,
    "rounding": "floor",
    "direction": "inclusive_to_exclusive"
  }'

Response example:

{
  "direction": "inclusive_to_exclusive",
  "net": 1000,
  "tax": 100,
  "gross": 1100,
  "rate": 10,
  "rounding": "floor"
}

Loan / Interest Calc

Calculates equal-payment (fixed installment) and equal-principal loan repayments: monthly payment, total payment, and total interest. Compound interest and yen rounding are common LLM failure modes — this API rounds each month with Math.round and forces a final-month clearance so the schedule totals match the principal.

MCP tool: utility.calc_loan

POST /v1/math/loan

Parameters:

Parameter	Type	Required	Description
principal	number	required	Loan principal in yen (must be positive)
annual_rate	number	required	Annual interest rate in percent (e.g. 3.5 means 3.5% per year, not 0.035)
term_months	integer	required	Repayment term in months (1–600; 50 years max)
method	string	-	equal_payment (default) or equal_principal
include_schedule	boolean	-	When true, include the amortization schedule (default: false)

Response fields:

Parameter	Description
method	Repayment method applied
monthly_payment	Fixed monthly payment for equal_payment; null for equal_principal (varies by month)
total_payment	Sum of all payments (yen)
total_interest	Total interest (total_payment − principal)
schedule	Amortization rows when include_schedule is true: month / payment / principal / interest / balance

Equal payment (equal_payment) — fixed monthly installment:

Request example:

curl -X POST "https://api.thousand-api.com/v1/math/loan" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": 1000000,
    "annual_rate": 3,
    "term_months": 12,
    "method": "equal_payment"
  }'

Response example:

{
  "method": "equal_payment",
  "monthly_payment": 84694,
  "total_payment": 1016325,
  "total_interest": 16325
}

Equal principal (equal_principal) — compare total cost under the same terms:

Request example:

curl -X POST "https://api.thousand-api.com/v1/math/loan" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": 1200000,
    "annual_rate": 3,
    "term_months": 12,
    "method": "equal_principal"
  }'

Response example:

{
  "method": "equal_principal",
  "monthly_payment": null,
  "total_payment": 1219500,
  "total_interest": 19500
}

Amortization schedule (include_schedule: true):

Request example:

curl -X POST "https://api.thousand-api.com/v1/math/loan" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": 1000000,
    "annual_rate": 3,
    "term_months": 12,
    "method": "equal_payment",
    "include_schedule": true
  }'

Response example:

{
  "method": "equal_payment",
  "monthly_payment": 84694,
  "total_payment": 1016325,
  "total_interest": 16325,
  "schedule": [
    { "month": 1, "payment": 84694, "principal": 82194, "interest": 2500, "balance": 917806 },
    { "month": 12, "payment": 84691, "principal": 84480, "interest": 211, "balance": 0 }
  ]
}

Pagination Calc

Calculate all pagination values from total_items, current page, and per_page in one call. Returns offset / limit (0-based, ready for SQL or API skip/take) and from / to (1-based for UI display), plus has_prev / has_next, prev_page / next_page, and page_range.

MCP tool: utility.calc_pagination (use current_page instead of page)

GET /v1/pagination/calc

Parameters:

Parameter	Type	Required	Description
total_items	integer	Required	Total item count (0 or greater)
page	integer	Required	Current page number (1-based)
per_page	integer	-	Items per page (default: 20, max: 1000)
window_size	integer	-	Number of pages in page_range (default: 5, max: 20)

Response fields:

Parameter	Description
total_items	Input total item count
page	Current page number (1-based)
per_page	Items per page
total_pages	Total page count (0 when total_items is 0)
offset	Zero-based offset (equivalent to SQL OFFSET)
limit	Fetch size (same as per_page; equivalent to SQL LIMIT)
from	First displayed item number (1-based)
to	Last displayed item number (1-based; equals total_items on the last page)
has_prev	Whether a previous page exists
has_next	Whether a next page exists
prev_page	Previous page number (null when has_prev is false)
next_page	Next page number (null when has_next is false)
page_range	Array of page numbers for UI pagination controls

Basic (total_items=234, page=3):

Request example:

curl "https://api.thousand-api.com/v1/pagination/calc?total_items=234&page=3" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "total_items": 234,
  "page": 3,
  "per_page": 20,
  "total_pages": 12,
  "offset": 40,
  "limit": 20,
  "from": 41,
  "to": 60,
  "has_prev": true,
  "has_next": true,
  "prev_page": 2,
  "next_page": 4,
  "page_range": [1, 2, 3, 4, 5]
}

Last page (page=12, has_next: false):

Request example:

curl "https://api.thousand-api.com/v1/pagination/calc?total_items=234&page=12" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "total_items": 234,
  "page": 12,
  "per_page": 20,
  "total_pages": 12,
  "offset": 220,
  "limit": 20,
  "from": 221,
  "to": 234,
  "has_prev": true,
  "has_next": false,
  "prev_page": 11,
  "next_page": null,
  "page_range": [8, 9, 10, 11, 12]
}

Semver Version Compare

Compare, sort, and validate semantic version strings (semver). Correctly handles cases like 1.10.0 > 1.9.0 that string comparison gets wrong. Supports prerelease versions and range satisfaction checks (e.g. ^1.0.0, >=2.0.0-beta).

MCP tool: utility.compare_versions

POST /v1/version/compare

Parameters:

Parameter	Type	Required	Description
versions	string[]	-	List of versions to sort and find latest from (max 100 items)
compare	string	-	Source version for comparison (must be paired with against)
against	string	-	Target version for comparison (must be paired with compare)
include_prerelease	boolean	-	Include prerelease versions in sorted/latest (default: false)
satisfies	object	-	Map of range pattern to version to check (key=range, value=version)

Response fields:

Parameter	Type	Description
compare	string	Request compare value (when specified)
against	string	Request against value (when specified)
result	number	Comparison result: 1=compare is newer / 0=equal / -1=compare is older (when specified)
result_label	string	Text form of result: greater / equal / less (when specified)
sorted	string[]	Versions sorted ascending (when versions specified)
latest_stable	string \| null	Newest stable version (when versions specified)
satisfies	object	Whether each range is satisfied (when satisfies specified)

Compare two versions:

Request example:

curl -X POST "https://api.thousand-api.com/v1/version/compare" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "compare": "1.10.0",
    "against": "1.9.0"
  }'

Response example:

{
  "compare": "1.10.0",
  "against": "1.9.0",
  "result": 1,
  "result_label": "greater"
}

Combined sort, compare, and range check:

Request example:

curl -X POST "https://api.thousand-api.com/v1/version/compare" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "versions": ["1.9.0", "1.10.0", "2.0.0-beta.1", "2.0.0"],
    "compare": "2.0.0",
    "against": "1.10.0",
    "include_prerelease": false,
    "satisfies": {
      "^1.9.0": "1.10.0",
      ">=2.0.0": "2.0.0-beta.1"
    }
  }'

Response example:

{
  "compare": "2.0.0",
  "against": "1.10.0",
  "result": 1,
  "result_label": "greater",
  "sorted": ["1.9.0", "1.10.0", "2.0.0"],
  "latest_stable": "2.0.0",
  "satisfies": {
    "^1.9.0": true,
    ">=2.0.0": false
  }
}

Batch Execute

Run multiple API calls in a single request sequentially. Before chaining multiple MCP tools, consider data.execute_batch first. Use tools:[{id,tool,args}] with MCP tool names and pass prior step results via {{stepId.field}} dot notation.

MCP tool name: data.execute_batch

MCP presets (pass directly to data.execute_batch)

The same JSON is available in the tool-catalog MCP Resource (thousand-api://catalog/tools) under execute_batch_presets.

Today → holiday check → exchange rate

Get current datetime, check if today is a holiday, then fetch USD/JPY exchange rate.

{
  "tools": [
    {
      "id": "now",
      "tool": "datetime.get_current_datetime",
      "args": {
        "timezone": "Asia/Tokyo"
      }
    },
    {
      "id": "holiday",
      "tool": "datetime.is_holiday",
      "args": {
        "country": "JP",
        "date": "{{now.date}}"
      }
    },
    {
      "id": "rate",
      "tool": "network.get_exchange_rate",
      "args": {
        "from": "USD",
        "to": "JPY",
        "amount": 100
      }
    }
  ]
}

JSON validate → merge → stats

Validate JSON, merge with defaults, then compute stats on numeric values in one round trip.

{
  "tools": [
    {
      "id": "validate",
      "tool": "data.validate_json",
      "args": {
        "json_str": "{\"scores\":[10,20,30,40]}"
      }
    },
    {
      "id": "merge",
      "tool": "data.merge_json",
      "args": {
        "mode": "merge",
        "base": "{{validate.json}}",
        "patch": {
          "meta": {
            "source": "batch"
          }
        }
      }
    },
    {
      "id": "stats",
      "tool": "data.calc_stats",
      "args": {
        "values": [
          10,
          20,
          30,
          40
        ]
      }
    }
  ]
}

Slug → Base64 → HMAC signature

Generate a slug, encode it as Base64, and create an HMAC signature sequentially.

{
  "tools": [
    {
      "id": "slug",
      "tool": "text.generate_slug",
      "args": {
        "text": "Hello World API"
      }
    },
    {
      "id": "b64",
      "tool": "convert.base64",
      "args": {
        "data": "{{slug.slug}}",
        "direction": "encode"
      }
    },
    {
      "id": "hmac",
      "tool": "security.generate_hmac",
      "args": {
        "mode": "sign",
        "algorithm": "sha256",
        "message": "{{b64.output}}",
        "secret": "my-secret-key"
      }
    }
  ]
}

POST /v1/batch/execute

Parameters:

Parameter	Type	Required	Description
tools	object[]	-	MCP tool-name based steps (max 10). Alternative to steps
tools[].id	string	required	Step ID (alphanumeric, hyphens, underscores; max 32 chars)
tools[].tool	string	required	MCP tool name (e.g. datetime.get_current_datetime)
tools[].args	object	required	Arguments matching the target tool inputSchema (supports {{}} refs)
steps	object[]	-	HTTP path based steps (max 10). Alternative to tools
steps[].id	string	required	Step ID (alphanumeric, hyphens, underscores; max 32 chars; reference key)
steps[].method	string	required	HTTP method: GET / POST / PUT / PATCH / DELETE
steps[].path	string	required	API path starting with /v1/ (max 200 chars)
steps[].query	object	-	Query parameters (supports {{}} references)
steps[].body	object	-	Request body for POST etc. (supports {{}} references)
stop_on_error	boolean	-	true (default): skip remaining steps after first failure / false: continue

Response fields:

Parameter	Type	Description
results	object[]	Per-step execution results
results[].id	string	Step ID
results[].status	number	HTTP status (0 when skipped)
results[].body	unknown	Response body (JSON)
results[].skipped	boolean	Skipped due to stop_on_error
results[].error	string	Error message when status >= 400
total_steps	number	Total steps in the request
executed_steps	number	Steps actually executed
failed_step	string \| null	First failed step ID
timed_out	boolean	Whether the 28s batch timeout fired

Step references (dot notation)

Use {{stepId.path.to.field}} in string query/body fields. When the entire value is {{...}}, the original type (number, boolean, etc.) is preserved. Partial embedding converts to string.

Blocked endpoints in batch

Example 1: Chained steps (current time → holiday check → exchange rate)

Request example:

curl -X POST "https://api.thousand-api.com/v1/batch/execute" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      {
        "id": "now",
        "method": "GET",
        "path": "/v1/datetime/now",
        "query": { "timezone": "Asia/Tokyo" }
      },
      {
        "id": "holiday",
        "method": "GET",
        "path": "/v1/calendar/is-holiday",
        "query": { "country": "JP", "date": "{{now.date}}" }
      },
      {
        "id": "rate",
        "method": "GET",
        "path": "/v1/exchangerate",
        "query": { "from": "USD", "to": "JPY", "amount": "100" }
      }
    ]
  }'

Response example:

{
  "results": [
    { "id": "now", "status": 200, "body": { "date": "2026-06-09", "time": "12:00:00" }, "skipped": false },
    { "id": "holiday", "status": 200, "body": { "datetime.is_holiday": false }, "skipped": false },
    { "id": "rate", "status": 200, "body": { "rate": 156.2 }, "skipped": false }
  ],
  "total_steps": 3,
  "executed_steps": 3,
  "failed_step": null,
  "timed_out": false
}

Example 1b: tools format (MCP tool names)

Request example:

curl -X POST "https://api.thousand-api.com/v1/batch/execute" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": [
      {
        "id": "now",
        "tool": "datetime.get_current_datetime",
        "args": { "timezone": "Asia/Tokyo" }
      },
      {
        "id": "holiday",
        "tool": "datetime.is_holiday",
        "args": { "country": "JP", "date": "{{now.date}}" }
      },
      {
        "id": "rate",
        "tool": "network.get_exchange_rate",
        "args": { "from": "USD", "to": "JPY", "amount": 100 }
      }
    ]
  }'

Example 2: Independent steps with stop_on_error: false

Request example:

curl -X POST "https://api.thousand-api.com/v1/batch/execute" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stop_on_error": false,
    "steps": [
      { "id": "hash", "method": "GET", "path": "/v1/hash/generate", "query": { "text": "a", "algorithm": "sha256" } },
      { "id": "uuid", "method": "GET", "path": "/v1/uuid/generate" },
      { "id": "distance", "method": "GET", "path": "/v1/distance", "query": { "p1": "35.68,139.76", "p2": "35.65,139.74" } }
    ]
  }'

Response example:

{
  "results": [
    { "id": "hash", "status": 200, "body": { "hash": "..." }, "skipped": false },
    { "id": "uuid", "status": 200, "body": { "uuids": ["..."] }, "skipped": false },
    { "id": "distance", "status": 200, "body": { "distance_meters": 3500 }, "skipped": false }
  ],
  "total_steps": 3,
  "executed_steps": 3,
  "failed_step": null,
  "timed_out": false
}

Health

Lightweight health check for MCP self-diagnostics. No authentication and no quota consumption.

MCP tool: utility.diagnose_mcp (uses this internally)

GET /v1/health

Response example:

{
  "status": "ok",
  "timestamp": "2026-06-19T10:00:00.000Z"
}

Diagnose MCP

MCP self-diagnostics: API connectivity (/v1/health), API key validity, and disabled tool list in one call. None of these checks consume quota.

MCP tool name: utility.diagnose_mcp

Response example:

{
  "api_health": "ok",
  "api_key_valid": true,
  "disabled_tools_count": 2,
  "disabled_tools": ["network.dns_lookup", "utility.calc_expression"],
  "checked_at": "2026-06-19T10:00:00.000Z"
}

Developer utilities

Distance

GET /v1/distance

Coordinate conversion

GET /v1/geo/convert

Color Palette

GET /v1/color/palette

Color Space Conversion

GET /v1/color/convert

WCAG Color Contrast

GET /v1/color/contrast

Math Expression Eval

POST /v1/math/eval

Consumption Tax Calc

POST /v1/math/tax

Loan / Interest Calc

POST /v1/math/loan

Semver Version Compare

POST /v1/version/compare

Batch Execute

Today → holiday check → exchange rate

JSON validate → merge → stats

Slug → Base64 → HMAC signature

POST /v1/batch/execute

Health

GET /v1/health

Diagnose MCP