# 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](/treasure-code/guide/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`:

```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](/treasure-code/guide/api-command-safety).

## Usage

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

```bash
# 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.