Actions (deprecated)

Compatibility reference for existing action functions and asynchronous action callers.

Actions are deprecated. For new development, use Tools. Existing actions remain callable. See Migrate from actions to tools before changing an existing integration.

Existing action definitions

Legacy actions use createAction from nango. Keep the original input and output schemas and read input from the second exec argument:

import { createAction } from 'nango';
import * as z from 'zod';

export default createAction({
    description: 'Reads a GitHub issue',
    input: z.object({ owner: z.string(), repo: z.string(), issueNumber: z.number() }),
    output: z.object({ title: z.string() }),
    exec: async (nango, input) => {
        const response = await nango.get({
            endpoint: `/repos/${input.owner}/${input.repo}/issues/${input.issueNumber}`
        });
        return { title: response.data.title };
    }
});

Keep importing the file from your project’s index.ts. Existing projects can dry run actions with nango dryrun <name> <connection-id> --input '<JSON>' and deploy one with nango deploy <environment> <integration>/actions/<file>.ts.

Synchronous calls

Prefer calling the action through the tool-call API. Existing callers can continue to use nango.triggerAction(integrationId, connectionId, actionName, input) or POST /action/trigger.

Legacy HTTP calls send Connection-Id, Provider-Config-Key, and Content-Type: application/json headers, with { "action_name": "<ACTION-NAME>", "input": {} } as the body. Authenticate with a Nango Environment API key from Environment Settings > API Keys, sent as Authorization: Bearer <NANGO-API-KEY>. Scoped keys need environment:tools:call.

Asynchronous calls

Existing async workflows can continue using the legacy API:

const { id, statusUrl } = await nango.triggerActionAsync(
    '<INTEGRATION-ID>',
    '<CONNECTION-ID>',
    '<ACTION-NAME>',
    { title: 'Example' }
);
const result = await nango.getAsyncActionResult({ id });

For HTTP, send the same request to POST /action/trigger with X-Async: true. Optionally set X-Max-Retries from 0 to 5; the default is 0. Use retries only when the operation is safe to repeat.

The response contains an id and statusUrl. Poll GET /action/<ACTION-ID>: 404 means the execution is still running, 200 returns the output, and 500 returns the execution error. Use the same authentication and scope as the trigger request.

Async actions are processed sequentially per environment; completion time depends on queue length and execution time. To receive completion events instead of polling, enable Async action completed in your webhook configuration.

Calling an action from a function

Existing sync or action functions can call await nango.triggerAction('<ACTION-NAME>', input). This helper is deprecated and is not available on the tool SDK.

Action errors

Existing actions can throw new nango.ActionError({ message: 'Example' }) to return an action_script_failure with the supplied payload. This is a legacy action error contract.

Completion webhook

Enable Async action completed in the Environment Settings webhook configuration. Nango sends the completion payload to your configured webhook URL. Keep your existing handler and its payload contract while migrating synchronous callers to tools. See webhook verification and retries.

The completion webhook identifies the execution to poll:

{
    "from": "nango",
    "type": "async_action",
    "connectionId": "<CONNECTION-ID>",
    "providerConfigKey": "<INTEGRATION-ID>",
    "payload": {
        "id": "<ACTION-ID>",
        "statusUrl": "/action/<ACTION-ID>"
    }
}

Fetch the result from payload.statusUrl with your Environment API key. Verify the webhook signature before processing it.