Call an external API with a custom action

Use a custom action when Automate.ax does not provide the external operation you need. The action handler can call an HTTP API with fetch, while input and output schemas keep the rest of your automation typed. Add Zod as a direct project dependency for the action schemas:

bun add zod

This example exposes a small HTTP endpoint backed by the public PokéAPI:

automations/look-up-pokemon.automation.ts

import {
  automation,
  defineAction,
  onHttpRequest,
  respondToHttpRequest,
} from "automate.ax"
import { z } from "zod"

const pokemonSchema = z.object({
  id: z.number(),
  name: z.string(),
})

const getPokemon = defineAction("Get Pokémon")
  .describe("Gets one Pokémon from PokéAPI.")
  .input(
    z.object({
      name: z.string().trim().min(1),
    }),
  )
  .output(pokemonSchema)
  .handler(async ({ input }) => {
    const response = await fetch(
      `https://pokeapi.co/api/v2/pokemon/${encodeURIComponent(input.name.toLowerCase())}`,
    )

    if (!response.ok) {
      throw new Error(`PokéAPI returned HTTP ${response.status}.`)
    }

    return pokemonSchema.parse(await response.json())
  })

export default automation("Look up a Pokémon", () => {
  const request = onHttpRequest({ waitForResponse: true })
  const pokemon = getPokemon({
    name: request.query.transform((query) => query.name ?? "pikachu"),
  })

  respondToHttpRequest({ body: pokemon })
})

Define custom actions at module scope and call them inside the automation callback. Calling getPokemon registers durable work and returns a signal; it does not call the API during composition. The handler runs later with schema-validated input, and Automate.ax validates its result before making the output available to respondToHttpRequest.

Handle provider failures

Throw when the provider does not return a usable response. Automate.ax retries execution failures before recording a failed action outcome, so use provider-supported idempotency keys for custom actions that create or change data. Parse untrusted response data with a maintained schema library. Do not cast response.json() to the expected type.

Use authenticated APIs safely

Do not hardcode API keys in source code or pass credentials through action inputs or signals. If Automate.ax supports the service but not a particular operation, declare that service with the action builder’s .account(...) method and use the authenticated API helper exported by the integration subpath. The platform then resolves and refreshes the selected account privately for the handler. If the service itself is not supported and requires credentials, request a new integration rather than embedding its secret in the automation. Credential-free endpoints, like the example above, can be called directly.

Deploy and call the endpoint

Deploy the project and use the printed trigger URL:

bunx automate.ax deploy
curl "YOUR_TRIGGER_URL?name=eevee"

The request waits up to ten seconds and returns the validated JSON output when the custom action finishes in time. The automation can continue if the caller times out.

Get started

Guides

Concepts

Reference

Call an external API with a custom action

Handle provider failures

Use authenticated APIs safely

Deploy and call the endpoint

​Handle provider failures

​Use authenticated APIs safely

​Deploy and call the endpoint

Handle provider failures

Use authenticated APIs safely

Deploy and call the endpoint