Call a unified operation

Calling a unified operation means naming which steps to run and how to route each service. Nothing fans out by default — that is deliberate.

From your application

const result = await sdk.unified.issues.create(
  { title: "Fix login" },
  { targets: ["github", "gitlab"], idempotencyKey: "issue-42" },
);

console.log(result.primary_id, result.title, result.provider_ids);

result = await sdk.unified.issues.create(
    {"title": "Fix login"},
    {"targets": ["github", "gitlab"], "idempotency_key": "issue-42"},
)

print(result["primary_id"], result["title"], result["provider_ids"])

In TypeScript targets is a call option; in Python it is the second argument.

Targets

targets is the exact subset of binding steps to execute. One or many are valid, and the set must be dependency-closed — if a step you name depends on another, name that one too. Dependencies are never invoked secretly on your behalf.

Property	Where	What it does
`targets`	Required call option	The dependency-closed set of binding steps to run
`idempotencyKey` / `idempotency_key`	Call option	A stable caller key; generated clients create a UUID when omitted

Selectors

Selectors are keyed by configured service, while targets is keyed by binding step. That difference matters when several steps share one service: they share the one selector for it.

Selector	TypeScript / Python	What it does
`environment`	`environment`	Chooses a declared provider environment
`endUserRef`	`end_user_ref`	Routes OAuth or OIDC steps through a connected user
`authType`	`auth_type`	Disambiguates `oauth`, `oidc`, or another declared type
`authName`	`auth_name`	Disambiguates several declared schemes of the same type
`resourceId`	`resource_id`	Chooses an already connected tenant or account UUID

const result = await sdk.unified.issues.create(
  { title: "Fix login" },
  {
    targets: ["jira"],
    selectors: {
      jira: {
        endUserRef: "user-42",
        authType: "oauth",
        authName: "OAuth2",
        resourceId: selectedResource.id,
      },
    },
  },
);

For a single selected OAuth or OIDC scheme, endUserRef alone is usually enough. One service selector is preflighted once and reused by every selected step and active rollback on that service.

Selectors carry routing identifiers only — never provider tokens or secrets. A selector keyed by an alias step is invalid unless that alias is also the real configured service key.

What preflight checks

Before any provider call, the Engine validates the dependency-closed target set, the selectors, the exact endpoints, and execution-token permission for every selected forward step and active rollback. Any preflight failure rejects the call with zero physical calls and no envelope. Inactive rollback declarations are not preflighted.

Reading the result

Without an operation-level output, you get the all-settled envelope:

{
  "results": [
    { "target": "github", "status": "success", "data": { } },
    { "target": "gitlab", "status": "error",   "error": { } }
  ],
  "rollbacks": [
    { "target": "github", "status": "success", "triggeredBy": "gitlab" }
  ]
}

Forward results preserve target order and carry success, error, or skipped. Rollbacks carry success or error plus triggeredBy / triggered_by. One provider failure never erases another result. With an operation-level output, your constructed object replaces that envelope entirely — no data wrapper, no {results, rollbacks}. A binding-level output without an operation output replaces only that target’s data inside the ordinary envelope.

When connected auth fails

Forward and rollback connected-auth failures return an authAction / auth_action so your application can complete the existing SDK auth flow and retry deliberately.

`authAction`	What it means
`connect`	This user has never connected to that service
`reconnect`	The grant lapsed or was revoked; run consent again
`select_resource`	Several tenants are reachable and none was chosen

Handle these rather than retrying blindly — a retry without the corresponding action will fail the same way.

Without the generated package

Unified operations run over REST like any other, with targets and per-service selectors in the body. Unified execution is the case where Idempotency-Key is required, not optional:

curl -X POST "$FUSED_ENGINE_URL/v1/apps/$VERSION_ID/executions" \
  -H "Authorization: Bearer $FUSED_SDK_TOKEN" \
  -H 'Idempotency-Key: issue-42' \
  -H 'Content-Type: application/json' \
  -d '{"operation":"issues.create","input":{"title":"Fix login"},"targets":["github","gitlab"]}'

For a one-off check from a terminal, fused-cli sdk invoke takes the same targets — see testing from the CLI for its flags. Unified execution never defaults to every declared target, whichever route you take. Naming them is the safeguard.

Both non-package routes bound a unified aggregate at 17 MiB and each provider document at 1 MiB. The generated package keeps its broader gRPC transport, so a large aggregate is a reason to use it rather than curl.

Pagination

Pagination is inherited from each endpoint and its effective service-version policy. Physical calls may only lower the limit, and unified calls take a target-keyed pagination map beside targets and selectors. It remains one buffered graph call. Never loop pages or pass continuation tokens yourself.

Permissions

A generated call needs the SDK identity plus an execution token authorized for every selected forward operation and active rollback. There is no separate unified scope. CLI lookup needs app.read; sdk activity also needs audit.read.

Declare a unified operation

Bindings, dependencies, rollback, and shaping the return value.

Get Started

Guides

Reference

Call a unified operation

From your application

Targets

Selectors

What preflight checks

Reading the result

When connected auth fails

Without the generated package

Permissions

Declare a unified operation

​From your application

​Targets

​Selectors

​What preflight checks

​Reading the result

​When connected auth fails

​Without the generated package

​Pagination

​Permissions

Declare a unified operation

From your application

Targets

Selectors

What preflight checks

Reading the result

When connected auth fails

Without the generated package

Pagination

Permissions