API

Make raw HTTP requests to Treasure AI APIs, similar to gh api from GitHub CLI. Useful for inspecting endpoints during SDK or CLI design, or for calling APIs that tdx does not yet wrap.

Disabled by default

tdx api is disabled by default since v2026.7 to prevent AI assistants from making misconfigured requests that bypass tdx's structured commands. See API command safety for the rationale and how to enable it.

Enabling

tdx api is enabled only via a config file — there is no environment variable, on purpose (a one-line VAR=1 tdx api ... would let an AI session bypass the gate).

1. Global config (recommended) — add enable_api_command to ~/.config/tdx/tdx.json:

{
  "enable_api_command": true
}

2. Project config — add the same field to a tdx.json in your project directory. This scopes the opt-in to one repo, but an AI editing the project can also flip it; prefer global config when safety matters.

When disabled, tdx api is hidden from tdx --help. Running it explicitly prints a guarded message that points at the safety guide.

Usage

tdx api <endpoint> [options]

Arguments

Argument	Description
<endpoint>	API path starting with /, e.g. /v3/database/list

Options

Option	Description
-X, --method <method>	HTTP method (GET, POST, PUT, DELETE, PATCH). Defaults to GET.
--data <json>	Request body as a JSON string
-f, --file <path>	Read the request body from a file
-H, --header <header>	Custom header in Key: Value format. Repeatable.
--type <api_type>	Which TD API to target (td, cdp, workflow, trino, llm). Defaults to td.

Examples

# List databases
tdx api /v3/database/list

# Inspect a CDP parent segment
tdx api /entities/parent_segments --type cdp

# Issue a query
tdx api -X POST --data '{"query":"SELECT 1"}' /v3/job/issue/hive/mydb

Prefer structured commands

Most use cases are better served by tdx's typed commands — they validate inputs, resolve names to IDs, and protect against the kinds of misconfiguration that motivated disabling tdx api by default.

Instead of	Use
tdx api /v3/database/list	tdx db list
tdx api /v3/table/list/<db>	tdx table list <db>
tdx api -X POST --data '{"query":…}' /v3/job/issue/…	tdx query "<sql>"
tdx api /entities/parent_segments --type cdp	tdx ps list / tdx ps view
tdx api /api/workflows --type workflow	tdx workflow list

Reach for tdx api when you are intentionally exploring an endpoint that tdx does not yet wrap, or debugging an API response shape.