Skip to content

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).

# 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]

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.

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:

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

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:

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

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

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

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

Next steps