Catalog Push API: reference for AI agents

[
  {
    "step": 1,
    "name": "open",
    "request": {
      "method": "POST",
      "path": "/jobs",
      "headers": {
        "Authorization": "Bearer <key>",
        "Content-Type": "application/json"
      },
      "body": {
        "mode": "replace",
        "fullSync": true
      }
    },
    "response": {
      "status": 201,
      "body": {
        "job": {
          "jobId": "<jobId>",
          "state": "open",
          "mode": "replace",
          "fullSync": true,
          "vendorId": "<vendorId>",
          "openedAt": "2026-11-01T19:24:09.196Z",
          "expiresAt": "2026-11-02T19:24:09.196Z",
          "closedAt": null,
          "finishedAt": null,
          "failureCode": null,
          "batchesReceived": 0,
          "rowsReceived": 0,
          "rowsValidated": 0,
          "rowsRefused": 0
        }
      }
    },
    "next": "Store job.jobId. Go to step 2."
  },
  {
    "step": 2,
    "name": "send batch (repeat for every batch, in order)",
    "request": {
      "method": "POST",
      "path": "/jobs/<jobId>/batches",
      "headers": {
        "Authorization": "Bearer <key>",
        "Content-Type": "application/json",
        "Idempotency-Key": "<jobId>:<batchIndex>"
      },
      "body": {
        "rows": [
          {
            "externalId": "hr-1001",
            "productHandle": "ethiopia-guji",
            "sku": "HR-GUJI-250",
            "status": "active",
            "product": {
              "title": "Ethiopia Guji"
            },
            "variant": {
              "priceMinor": 1850,
              "currency": "USD",
              "quantity": 40
            }
          }
        ]
      }
    },
    "response": {
      "status": 202,
      "body": {
        "batchId": "<batchId>",
        "sequence": 1,
        "rowsAccepted": 1,
        "rowsRefused": 0,
        "issues": []
      }
    },
    "next": "If rowsRefused > 0, record issues (index is the row position in this batch). With fullSync true a refused row makes the archive pass skip. Otherwise send the next batch, then step 3."
  },
  {
    "step": 3,
    "name": "close",
    "request": {
      "method": "POST",
      "path": "/jobs/<jobId>/close",
      "headers": {
        "Authorization": "Bearer <key>"
      },
      "body": null
    },
    "response": {
      "status": 202,
      "body": {
        "job": {
          "jobId": "<jobId>",
          "state": "closed",
          "mode": "replace",
          "fullSync": true,
          "vendorId": "<vendorId>",
          "openedAt": "2026-11-01T19:24:09.196Z",
          "expiresAt": "2026-11-02T19:24:09.196Z",
          "closedAt": "2026-11-01T19:24:10.832Z",
          "finishedAt": null,
          "failureCode": null,
          "batchesReceived": 1,
          "rowsReceived": 1,
          "rowsValidated": 1,
          "rowsRefused": 0,
          "batchesApplied": 0,
          "rowsApplied": 0,
          "rowsFailed": 0,
          "created": 0,
          "updated": 0,
          "unchanged": 0,
          "reportExpiresAt": null
        }
      }
    },
    "next": "A repeated close answers 200 with the job. Go to step 4."
  },
  {
    "step": 4,
    "name": "poll until finished",
    "request": {
      "method": "GET",
      "path": "/jobs/<jobId>",
      "headers": {
        "Authorization": "Bearer <key>"
      },
      "body": null
    },
    "response": {
      "status": 200,
      "body": {
        "job": {
          "jobId": "<jobId>",
          "state": "closed",
          "mode": "replace",
          "fullSync": true,
          "vendorId": "<vendorId>",
          "openedAt": "2026-11-01T19:24:09.196Z",
          "expiresAt": "2026-11-02T19:24:09.196Z",
          "closedAt": "2026-11-01T19:24:10.832Z",
          "finishedAt": "2026-11-01T19:24:21.409Z",
          "failureCode": null,
          "batchesReceived": 1,
          "rowsReceived": 1,
          "rowsValidated": 1,
          "rowsRefused": 0,
          "batchesApplied": 1,
          "rowsApplied": 1,
          "rowsFailed": 0,
          "created": 1,
          "updated": 0,
          "unchanged": 0,
          "reportExpiresAt": "2026-12-01T19:24:21.409Z"
        }
      }
    },
    "next": "While job.finishedAt is null, wait 5 to 10 seconds and repeat. When set, go to step 5."
  },
  {
    "step": 5,
    "name": "judge and report",
    "request": {
      "method": "GET",
      "path": "/jobs/<jobId>/errors.csv",
      "headers": {
        "Authorization": "Bearer <key>"
      },
      "body": null
    },
    "response": {
      "status": 200,
      "body": "row_number,sku,field,severity,code,message,external_id\n2,,sku,error,INVALID_ROW,This row does not match the push row format.,hr-bad\n"
    },
    "next": "Only fetch it when job.failureCode is not null or job.rowsFailed > 0 (a refused row counts in rowsFailed). Success means failureCode null and rowsFailed 0."
  }
]

// A full sync with plain fetch: the call order an agent must follow.
const BASE = 'https://catalog.usethrottle.dev/v1/catalog';
const headers = { Authorization: `Bearer ${process.env.CATALOG_VENDOR_KEY ?? ''}`, 'Content-Type': 'application/json' };

interface Row { externalId: string; productHandle: string; sku: string }

async function call(path: string, init: RequestInit & { idempotencyKey?: string } = {}) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch(`${BASE}${path}`, {
      ...init,
      headers: { ...headers, ...(init.idempotencyKey ? { 'Idempotency-Key': init.idempotencyKey } : {}) },
    });
    // 429 and 5xx: wait, then resend the SAME request with the SAME key.
    if (res.status === 429 || res.status >= 500) {
      await new Promise((r) => setTimeout(r, Number(res.headers.get('Retry-After') ?? 5) * 1000));
      continue;
    }
    const body = await res.json();
    if (!res.ok) throw new Error(`${body.error.code} ${body.error.requestId}`);
    return body;
  }
  throw new Error('GAVE_UP');
}

// batches: arrays of at most 1,000 rows; one product's rows stay together.
export async function fullSync(batches: Row[][]) {
  const { job } = await call('/jobs', { method: 'POST', body: JSON.stringify({ mode: 'replace', fullSync: true }) });
  for (const [index, rows] of batches.entries()) {
    await call(`/jobs/${job.jobId}/batches`, {
      method: 'POST',
      body: JSON.stringify({ rows }),
      idempotencyKey: `${job.jobId}:${index}`,
    });
  }
  await call(`/jobs/${job.jobId}/close`, { method: 'POST' });
  for (;;) {
    const { job: view } = await call(`/jobs/${job.jobId}`);
    if (view.finishedAt !== null) return view; // read failureCode and rowsFailed
    await new Promise((r) => setTimeout(r, 10_000));
  }
}

// Pseudo-code that type-checks: the control flow of a full sync.
type Row = { externalId: string; productHandle: string; sku: string };
type Job = { jobId: string; finishedAt: string | null; failureCode: string | null; rowsFailed: number };
type Outcome = { ok: true; job: Job } | { ok: false; reason: string };

declare function openJob(body: { mode: 'replace'; fullSync: boolean }): Promise<{ jobId: string }>;
declare function sendBatch(jobId: string, rows: Row[], idempotencyKey: string): Promise<{ rowsRefused: number }>;
declare function closeJob(jobId: string): Promise<void>;
declare function getJob(jobId: string): Promise<Job>;
declare function sleep(seconds: number): Promise<void>;
declare function chunkByProduct(rows: Row[], max: number): Row[][];

export async function fullSync(feed: Row[]): Promise<Outcome> {
  const job = await openJob({ mode: 'replace', fullSync: true });
  const batches = chunkByProduct(feed, 1000); // never split a product's rows

  let refused = 0;
  for (const [index, rows] of batches.entries()) {
    // On 429/5xx the HTTP layer waits Retry-After and resends the same key.
    const answer = await sendBatch(job.jobId, rows, `${job.jobId}:${index}`);
    refused += answer.rowsRefused;
  }
  if (refused > 0) return { ok: false, reason: 'rows refused: a refused row skips the archive for this whole job; start a new full-sync job with the corrected feed' };

  await closeJob(job.jobId);

  for (;;) {
    const view = await getJob(job.jobId);
    if (view.finishedAt !== null) {
      return view.failureCode === null && view.rowsFailed === 0
        ? { ok: true, job: view }
        : { ok: false, reason: `failureCode=${view.failureCode} rowsFailed=${view.rowsFailed}` };
    }
    await sleep(10);
  }
}