Call APIs and run transforms

Use an API when the user needs a result now, such as an order lookup or a saved decision. Use a transform when they start background work, such as recalculating a dataset. Both are selected by their registered project resource names.

Call an API from an interactionCopy Anchor Link

Inside a component under VortexifyProvider:

import { useState } from "react";
import { useVortexify } from "@vortexify/react";

export function NormalizeForm() {
  const { client, ready } = useVortexify();
  const [value, setValue] = useState("");
  const [result, setResult] = useState<{ value: string; length: number } | null>(null);
  const [busy, setBusy] = useState(false);
  const [error, setError] = useState<string | null>(null);

  async function submit() {
    if (!ready || busy) return;
    setBusy(true); setError(null); setResult(null);
    try {
      setResult(await client.runApi<{ value: string; length: number }>("normalize", { value }));
    } catch (failure) {
      setError(failure instanceof Error ? failure.message : "Request failed");
    } finally { setBusy(false); }
  }

  return <form onSubmit={event => { event.preventDefault(); void submit(); }}>
    <label>Text <input value={value} onChange={event => setValue(event.target.value)} /></label>
    <button disabled={!ready || busy}>{busy ? "Processing…" : "Normalize"}</button>
    {error && <p role="alert">{error}</p>}
    {result && <p>{result.value} ({result.length} characters)</p>}
  </form>;
}

This assumes the normalize API from backend operations exists and its runtime is ready. runApi unwraps the execution envelope and returns the API's JSON value. The generic type describes what your component expects; the API still needs to return that shape.

Inputs are a mapping of strings, numbers, and booleans matching Python Input declarations. Managed tables, secrets, and database connections resolve on the backend. The client supplies project context and authentication; call normalize, not the Python function name or decorator route.

Start and observe background workCopy Anchor Link

Starting a transform returns a job ID. Wait for that same job, inspect its terminal status, and then fetch the result your screen needs:

import type { VortexifyClient } from "@vortexify/react";

async function refreshOrders(client: VortexifyClient) {
  const { job_id } = await client.startTransform("refresh_orders", {});
  const job = await client.pollTransform("refresh_orders", job_id, {
    onProgress: snapshot => console.log(snapshot.status),
  });
  if (job.status !== "success") throw new Error(`Refresh ${job.status}`);
  return client.runApi("customer_orders", { customer_id: "123" });
}

Show progress and retain job_id in component/application state so a user can inspect existing work after a request fails. getTransformJob(name, jobId) reads a snapshot once; pollTransform repeats until terminal. Statuses created, pending, queued, and running are nonterminal; success, failed, and stopped are terminal.

Polling does not return published rows automatically. The example fetches them through an API after the run. In the platform, inspect the same run's Output and Processing views, and use its table publication to inspect schema and relationships when relevant.

Preview and productionCopy Anchor Link

The configured SDK mode applies to API and transform execution. Local development and hosted previews use committed preview resources. Published apps use production resources. Run required upstream producers and check their output before invoking consumers; see configuration.

The current platform Playground submits committed preview runs. Starting a production transform from a published app uses the production execution path. A preview run does not activate production schedules.

Errors, waiting, and retriesCopy Anchor Link

React SDK 0.1.1 preserves the server's JSON message on HTTP failures, with the HTTP status and decoded response available on VortexifyError. Non-JSON responses fall back to HTTP <status>. For example, “API runtime is not ready; build it through the CLI” means the server correctly rejected an unprepared runtime: run vortexify build api NAME --wait and inspect that build before invoking it again.

Methods accept RequestOptions with signal and timeoutMs. The request timeout defaults to the configured value or 60 seconds. PollOptions also accepts intervalMs (default 1,000) and onProgress; the total polling timeout defaults to five minutes.

A browser timeout, canceled request, or closed screen does not stop submitted backend work. Reuse the existing job ID when possible. An API may already have written data before its response is lost, so choose a deliberate retry/idempotency strategy for write operations.

See API contracts, transforms, and React configuration.