DocsIntegrationsOther Frameworks

Other Frameworks

Actify is a plain HTTP API — it works with any stack that can make a POST request. The integration pattern is always the same: fire the Actify call in parallel with your own logic, then attach _commerce_layer to your response when it is present. This guide shows what that looks like in portable terms.

The API call

Every integration reduces to a single authenticated POST /v1/match. The snippet below uses the native fetch API (available in Node 18+, Deno, Bun, and every modern browser runtime) — swap it for the HTTP client your framework already uses.

const ACTIFY_BASE = process.env.ACTIFY_BASE_URL ?? 'https://actify-api.vercel.app';
const ACTIFY_API_KEY = process.env.ACTIFY_API_KEY;

const ACTIFY_TIMEOUT_MS = Number(process.env.ACTIFY_TIMEOUT_MS ?? 1500);

async function fetchActifyMatch(taskQuery) {
  try {
    const res = await fetch(`${ACTIFY_BASE}/v1/match`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${ACTIFY_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ task_query: taskQuery }),
      signal: AbortSignal.timeout(ACTIFY_TIMEOUT_MS),
    });
    if (!res.ok) return null;
    const data = await res.json();
    return data._commerce_layer ?? null;
  } catch {
    return null;  // fail-open — never block your core logic
  }
}

Generic integration pattern

Start the Actify call before awaiting your own work, so both run concurrently. Merge the result into your response only if it arrived in time.

async function handleRequest(userQuery) {
  // 1. Fire both tasks concurrently
  const commercePromise = fetchActifyMatch(userQuery);
  const corePromise     = yourExistingLogic(userQuery);

  // 2. Await your core result first — it is never delayed by Actify
  const result   = await corePromise;
  const commerce = await commercePromise;

  // 3. Attach only when a match was found
  if (commerce) {
    result._commerce_layer = commerce;
  }

  return result;
}

Rules

Always run the Actify call concurrently — never await it before starting your own work.
Set a finite client-side timeout via `ACTIFY_TIMEOUT_MS` (default ~1.5 s in examples). Tune to your time-to-response — too short misses cold paths; unbounded waits break fail-open.
Pass the user's raw query in task_query — not a summarised or rephrased version of it.
Forward recommendation URLs verbatim; do not rewrite or shorten them (attribution depends on the tracked redirect).
If the call times out or returns an error, return your response without a commerce block — fail-open.
On HTTP 429 (rate limit), skip the Actify call and retry with exponential backoff on the next request.

← MCP Server API reference →