Call an external API

Choose the path that matches the service and operation:

Request	Use
Public endpoint without authentication	`fetchHttp`
Unsupported operation for a supported service	A custom action with the integration’s account and authenticated API helper
Unsupported authenticated service	A custom action with a restricted credential from 1Password

Automate.ax can’t define a new platform-managed integration entirely in automation code. Managed integrations depend on server-side credential storage, authorization, account binding, and token refresh.

Call a public endpoint

fetchHttp makes a durable request and returns the status, headers, and parsed body as signals. This endpoint passes its offset query parameter to the public PokéAPI:

automations/look-up-pokemon.automation.ts

import {
  automation,
  fetchHttp,
  onHttpRequest,
  respondToHttpRequest,
} from "automate.ax"

export default automation("Look up a Pokémon", () => {
  const request = onHttpRequest()
  const pokemon = fetchHttp({
    query: {
      limit: 1,
      offset: request.query.transform((query) => query.offset ?? 0),
    },
    responseType: "json",
    url: "https://pokeapi.co/api/v2/pokemon",
  })

  respondToHttpRequest({
    body: pokemon.body,
    requestId: request.requestId,
    status: pokemon.status,
  })
})

fetchHttp registers work and returns a signal without calling the API during composition. Every input accepts compatible signals. fetchHttp serializes JSON request bodies automatically and uses responseType to read the response body.

Handle failures

HTTP error statuses return normally with ok: false. Network and response parsing failures throw, so Automate.ax retries them before recording a failed action. Use provider-supported idempotency keys for requests that create or change data. See fetchHttp for request fields, response parsing, and output details.

Protect credentials and validate responses

Literal action inputs are durable run data. Don’t put a raw API key, bearer token, or other secret in fetchHttp headers, query parameters, or the body. If Automate.ax supports the service but not the operation, define a custom action with .account(...) and use the integration’s authenticated API helper. The platform privately resolves and refreshes the selected account for the handler. For an unsupported service, store a restricted credential in 1Password, resolve it with onePassword.resolveSecret, and pass that sensitive signal directly to a custom action. Automate.ax keeps the value encrypted in storage and materializes it for the handler when it runs. A custom action also lets you validate the provider response with Zod before returning typed data to the rest of the automation:

automations/list-provider-projects.automation.ts

import { automation, defineAction, onSchedule } from "automate.ax"
import { onePassword } from "automate.ax/onepassword"
import { z } from "zod"

const projectsSchema = z.object({
  projects: z.array(z.object({ id: z.string(), name: z.string() })),
})

const listProviderProjects = defineAction("List provider projects")
  .input(z.object({ apiKey: z.string() }))
  .output(projectsSchema)
  .retry({ replaySafety: "safe" })
  .handler(async ({ input }) => {
    const response = await fetch("https://api.example.com/projects", {
      headers: { authorization: `Bearer ${input.apiKey}` },
    })

    if (!response.ok) {
      throw new Error(`Provider request failed with ${response.status}`)
    }

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

export default automation("List provider projects", () => {
  onSchedule({ schedule: "0 * * * *" })

  const apiKey = onePassword.resolveSecret({
    secretReference: "op://Automation/ExampleAPI/credential",
  })

  listProviderProjects({ apiKey })
})

Limit the provider credential and the connected 1Password service account to the required resources and permissions. Don’t return the credential, include it in an error, or write it to logs. If the action returns sensitive provider data, declare an output sensitivity policy. Store a dedicated credential at the op:// reference. Apply the provider’s scope, resource, expiration, quota, and network restrictions. Rotate the 1Password item without changing secretReference. If you can’t use 1Password, keep a restricted credential inside the custom action handler’s closure in private automation source. Anyone who can read the source can read the credential, and rotation requires a code change and deployment. Use the provider’s platform-managed integration account when Automate.ax supports it.

Deploy and call the endpoint

Deploy the project and use the printed trigger URL:

bunx automate.ax deploy
curl "YOUR_TRIGGER_URL?offset=25"

The request waits up to 55 seconds for validated JSON. The automation can continue after the caller times out.

Start

Concepts

Guides

Call a public endpoint

Handle failures

Protect credentials and validate responses

Deploy and call the endpoint

​Call a public endpoint

​Handle failures

​Protect credentials and validate responses

​Deploy and call the endpoint

Call a public endpoint

Handle failures

Protect credentials and validate responses

Deploy and call the endpoint