# Data plane

> Source: https://truto.one/docs/cli/data-plane/

Data-plane commands call third-party services **through** Truto using credentials on an integrated account. Every call requires an account ID via `-a, --account` (except `capabilities` when targeting an integration).

## Unified API

Normalized resources across integrations (consistent field names).

```bash
# List CRM contacts
truto unified crm contacts -a <account-id>

# Get one record
truto unified crm contacts <contact-id> -m get -a <account-id>

# Create
truto unified crm contacts -m create -a <account-id> -b '{"first_name":"Jane"}'

# Query params (comma-separated key=value, or JSON object)
truto unified crm contacts -a <account-id> -q "limit=10,status=active"
truto unified crm contacts -a <account-id> --query-json '{"limit":10}'

# Stdin body
echo '{"first_name":"Test"}' | truto unified crm contacts -m create -a <account-id> --stdin
```

**Arguments:** `<model>` (e.g. `crm`, `ats`), `<resource>` (e.g. `contacts`), optional `[id]`

:::callout{type="info"}
Use **unified** when you want Truto's normalized schema across vendors. Use **proxy** for integration-specific fields or APIs not in the unified model.
:::

## Proxy API

Raw integration resources without normalization.

```bash
truto proxy tickets -a <account-id>
truto proxy tickets T-42 -m get -a <account-id>
truto proxy tickets -m create -a <account-id> -b '{"subject":"Bug report"}'

# Custom method → POST /proxy/tickets/custom-action
truto proxy tickets -m custom-action -a <account-id> -b '{"key":"value"}'
```

## Custom API

User-defined custom endpoints on Truto:

```bash
truto custom /my-endpoint -a <account-id>
truto custom /my-endpoint -m POST -a <account-id> -b '{"key":"value"}'
truto custom /my-endpoint -a <account-id> -H "X-Custom-Header=value"
```

## Batch

Multiple operations in one request (same resource format as sync jobs):

```bash
truto batch requests.json

truto batch -b '{"integrated_account_id":"<id>","resources":[
  {"resource":"contacts","method":"list"},
  {"resource":"companies","method":"list"}
]}'

cat batch.json | truto batch --stdin
```

Each entry: `resource`, `method`, optional `query`, `body`, `id`, `persist` (set `persist: true` on proxy resources to include results in the response).

## Test mapping locally

Evaluate a `response_mapping` JSONata expression against a sample raw API response — no integrated account or third-party call:

```bash
# Inline mapping + sample file
truto unified test-mapping \
  --mapping '$map(results, function($r) { $merge([$r, {"id": $string($r.id)}]) })' \
  --input sample-response.json

# Fetch mapping from the platform, then evaluate
truto unified test-mapping \
  --model crm --resource contacts --integration salesforce \
  --method list \
  --input sample-response.json

# Overlay environment-specific overrides
truto unified test-mapping \
  --model crm --resource contacts --integration salesforce \
  --with-overrides <env-unified-model-id> \
  --input sample-response.json \
  --show-mapping

cat sample-response.json | truto unified test-mapping \
  --mapping-file expr.jsonata --stdin
```

Pass query context into the mapping as `$query` / `$rawQuery` with `-q`, `--query-json`, or `--query-file` (same as live unified calls). Operator-based mappings cannot be evaluated locally yet — the CLI prints the resolved mapping for inspection.

## Capabilities

Discover proxy and unified methods for an integration or account:

```bash
truto capabilities hubspot
truto capabilities <account-id> --methods list,get --resource contacts
truto capabilities hubspot --has-description
```

See [Admin resources — Capabilities](/docs/cli/admin-resources#capabilities) for `--type`, `--target`, and AI readiness details.

## Discovering methods on an account

Before calling unified or proxy, list what an account supports:

```bash
truto accounts tools <account-id>
truto accounts tools <account-id> --methods list --tags contacts,deals
```

## Next steps

- [Power features](/docs/cli/power-features) — bulk `export`, `diff`
- [Examples](/docs/cli/examples) — proxy and unified walkthroughs