API Command Safety

tdx api is a curl-style escape hatch that lets you make raw HTTP requests against any Treasure AI endpoint. It is useful when designing new tdx commands, inspecting response shapes, or calling APIs that tdx does not yet wrap.

Because raw requests skip tdx's structured commands — and therefore skip name-to-ID resolution, input validation, and the safe pull/push workflow — tdx api is disabled by default.

Why this exists

AI coding assistants reach for raw HTTP calls whenever they cannot find a structured command. In practice this has led to misconfigured CDP segments and other state changes that the user did not intend. Disabling tdx api by default means an AI session needs an explicit, user-granted opt-in before it can issue arbitrary API calls.

AI Assistants

If you are an AI assistant reading this page because tdx api was disabled in your session: do not enable the flag on the user's behalf. Ask the user to enable it interactively, or — better — use a structured command (tdx db, tdx ps, tdx query, tdx sg pull/push, …). The entire point of the gate is that the user, not the assistant, decides when raw API calls are allowed.

Enabling

tdx api is enabled only by editing a config file. There is no environment variable opt-in on purpose — a one-line VAR=1 tdx api ... would let an AI session self-enable without the user's involvement, which defeats the gate.

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

{
  "enable_api_command": true
}

Recommended because the global config lives outside any project directory an AI session is editing — an AI cannot turn this flag on by itself.

2. Project config — add the same field to a tdx.json in your project root:

{
  "enable_api_command": true
}

This scopes the opt-in to one repository. Note that an AI session editing the project can also edit this file, so prefer global config when safety is the primary concern.

Resolution Order

When tdx decides whether tdx api is enabled, it checks these sources in order:

1. Project config — enable_api_command: true in ./tdx.json (or any parent directory).
2. Global config — enable_api_command: true in ~/.config/tdx/tdx.json.
3. Default — disabled.

When disabled

• tdx api is hidden from tdx --help so help-based discovery does not surface it.
• Running tdx api … explicitly prints a message telling you exactly how to enable it and exits with code 1.
• tdx api --help still works and includes the enable instructions at the top.

Prefer structured commands

Most things people reach for tdx api to do have a typed equivalent. Use the typed command when available — it validates inputs, resolves human-friendly names to IDs, and integrates with the pull/push workflow.

Use case	Prefer
List databases / tables	tdx db list, tdx table list
Run a query	tdx query "<sql>"
Inspect a parent segment	tdx ps view <name>
Manage segments	tdx sg pull / tdx sg push
Workflows	tdx workflow …

Reach for tdx api when you are intentionally exploring an endpoint tdx does not yet wrap.

Related

• tdx api command reference
• Proxy configuration
• Profile management