Call Pomerado from a backend

Call the REST API from your backend with an API key. This guide runs a Google Flights search, follows its job and receives a webhook when the job finishes.

Set up

Create an API key on the Dashboard under Settings, then API keys, and load it into POMERADO_API_KEY from your secret manager.

const api = "https://api.pomerado.ai/v1";
const headers = {
  Authorization: `Bearer ${process.env.POMERADO_API_KEY}`,
  "Content-Type": "application/json",
};

Find the tool

const tools = await fetch(
  `${api}/tools?query=search+flights&site_url=google.com`,
  { headers },
);
const toolId = (await tools.json()).data[0].id;

Run it

const run = await fetch(`${api}/runs/read-only`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    tool_id: toolId,
    input: { origin: "SFO", destination: "JFK", departure_date: "2026-11-20" },
  }),
});
const { id: jobId } = await run.json(); // 202, with the job

For a write tool, use POST /v1/runs with an Idempotency-Key header, so a retry never acts on the site twice.

Follow the job

Read the job until it finishes or asks a question, waiting Retry-After seconds between reads:

async function follow(id: string) {
  for (;;) {
    const res = await fetch(`${api}/jobs/${id}`, { headers });
    const job = await res.json();
    if (job.status !== "queued" && job.status !== "running") return job;
    const seconds = Number(res.headers.get("retry-after") ?? 2);
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  }
}

const job = await follow(jobId);
if (job.status === "succeeded") console.log(job.result);

A job with status needs_input waits on a person: send them its input_request.answer_url.

Receive a webhook

Instead of polling, create a webhook once:

curl https://api.pomerado.ai/v1/webhooks \
  -H "Authorization: Bearer $POMERADO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/pomerado/events", "events": ["job.needs_input", "job.succeeded", "job.failed"]}'

Store the secret in the answer; it’s shown once. Verify each delivery with a Standard Webhooks library, answer with a 2xx within 10 seconds, then read the job, since events never carry a result:

import { Webhook } from "standardwebhooks";

const webhook = new Webhook(process.env.POMERADO_WEBHOOK_SECRET!);

app.post(
  "/pomerado/events",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const event = webhook.verify(
      req.body,
      req.headers as Record<string, string>,
    ) as any;
    res.sendStatus(204);
    if (event.type === "job.succeeded") {
      const job = await (
        await fetch(`${api}/jobs/${event.data.job_id}`, { headers })
      ).json();
      console.log(job.result);
    }
  },
);

Details

A result is kept until its first read, and at most 60 minutes after the job ends. Only the API key that started the job can read it; include_result=false checks the job without using up the result.
An event can arrive more than once. Drop repeats by its id.
More in webhooks, wait for a result and the API reference.

Get started

Example guides

Guides

Call Pomerado from a backend

Set up

Find the tool

Run it

Follow the job

Receive a webhook

​Set up

​Find the tool

​Run it

​Follow the job

​Receive a webhook

Set up

Find the tool

Run it

Follow the job

Receive a webhook