# 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`:

```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:

```json
{
  "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](/treasure-code/guide/marketing-as-code).

| 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](/treasure-code/commands/api)
- [Proxy configuration](/treasure-code/guide/proxy)
- [Profile management](/treasure-code/guide/profile-management)