Documentation by ClonePartner

Start typing to search.

Connector Reference

Truto

View Markdown

Configure the truto connector, choose between unified and proxy API methods, target integrated accounts, and stream paginated results.

Truto

The truto connector reads and writes SaaS application data through the Truto platform, using either the normalized unified API or the integration's native proxy API.

When to use it

Use truto when the source or destination is a SaaS app connected through Truto (helpdesks, CRMs, and similar). Prefer unified methods when a unified model covers the fields you need; use proxy methods for integration-specific fields and endpoints the unified model does not expose.

Configuration

Key Type Required Default Description
api_token string Yes — Truto API token (stored as a secret)
base_url string No — Truto API base URL (optional)

Integrated accounts

Every data method requires an integrated_account_id — the Truto connected account (one tenant's authorization for one integration) the call runs against. The token is environment-wide, so one Connector can serve many accounts; which account to use is per-call data, not connector config. Pass it through task arguments and fix it at job creation with template arguments when appropriate.

Methods

Unified API

unified_model selects the Truto unified model (for example ticketing, crm); resource is the unified resource name within it.

Method Arguments Returns Behavior
list resource, integrated_account_id, unified_model (all required), query array Streams all pages of a unified resource, following next_cursor to the end
get resource, id, integrated_account_id, unified_model (all required), query object Gets a single resource by ID
create resource, data, integrated_account_id, unified_model (all required), query object Creates a resource
update resource, id, data, integrated_account_id, unified_model (all required), query object Updates a resource
delete resource, id, integrated_account_id, unified_model (all required), query void Deletes a resource

Proxy API

Proxy methods call the integration's native endpoints as exposed by Truto; resource is the native resource/endpoint name.

Method Arguments Returns Behavior
proxy_list resource, integrated_account_id (required), query array Streams all pages from the native list endpoint
proxy_get resource, id, integrated_account_id (required), query object Gets a single native resource by ID
proxy_create resource, data, integrated_account_id (required), query object Creates via the native endpoint
proxy_update resource, id, data, integrated_account_id (required), query object Updates via the native endpoint
proxy_delete resource, id, integrated_account_id (required), query void Deletes via the native endpoint
proxy_custom resource, method, integrated_account_id (required), data, query object Calls a custom HTTP method (e.g. POST, PATCH) on a proxy resource
proxy_download resource, method, integrated_account_id (required), query object Downloads raw binary content from a proxy custom download method

Custom API

Custom API methods hit an arbitrary path on the integration's API (/custom/<path>), for endpoints Truto has not modeled. Mutating calls must include a methodConfig object in data with the HTTP method and a body_format (json, form, multipart, raw, xml) — without body_format, Truto omits the upstream request body.

Method Arguments Returns Behavior
custom_request path, method, integrated_account_id (required), data, query object Arbitrary HTTP call to a custom path
custom_create path, integrated_account_id, data (required), query object POST to a custom path; data carries fields plus methodConfig: { method: POST, body_format: json }
custom_update path, integrated_account_id, data (required), query object PATCH to a custom path; data carries fields plus methodConfig: { method: PATCH, body_format: json }
custom_upsert create_path, update_path, integrated_account_id, data (required), id, query object PATCHes update_path when id is set, otherwise POSTs create_path

Discovery

Method Arguments Returns Behavior
list_integrated_accounts limit, cursor, q, integration, environment_integration_id object Lists integrated accounts one page at a time (accounts + next_cursor), with server-side search and integration filters
capabilities integrated_account_id (required), type, methods, include_undescribed object Lists the listable unified and proxy resources for an account
query_schema resource, integrated_account_id (required), unified_model, method object Fetches the filterable query schema for a resource

Example

name: export_helpdesk_tickets
arguments:
  account_id:
    type: string
    required: true
connectors:
  source:
    type: truto
steps:
  - name: list_tickets
    type: call_method
    config: |
      {
        "connector": "source",
        "method": "list",
        "args": {
          "resource": "tickets",
          "unified_model": "ticketing",
          "integrated_account_id": arguments.account_id
        }
      }

The matching connectors.yaml entry for CLI runs:

source:
  type: truto
  config:
    api_token: ${TRUTO_TOKEN}

Behavior notes

  • list and proxy_list are streaming methods: they follow next_cursor across every page and yield records one at a time with backpressure. Do not buffer their output unless the dataset is known to be small.
  • Retries: 429 responses are always retried; 5xx responses are retried only for read-only methods (writes are not blindly repeated). Backoff is exponential, honoring Retry-After when present, up to 5 attempts.
  • Use capabilities and query_schema to discover what an account exposes before authoring steps — resources and filters vary by integration and plan.
  • Data Explorer uses list_integrated_accounts, capabilities, and query_schema to drive its pickers for Truto Connectors. See Data Explorer.