API Library

Overview

The @filefeed/sdk package provides a type-safe client for the FileFeed API.

Authentication via API key
Resources: Connections (formerly Clients), Pipelines, Schemas, Pipeline Runs, Webhooks, Outbound Uploads, Documents, Files, Notifications
Pagination helpers and typed responses

Quick links

API Reference

Explore endpoints with the API Playground.

Syncing Data

Fetch processed data and acknowledge runs.

Handling Errors

Retry patterns and structured error handling.

Installation

npm
yarn
pnpm

npm install @filefeed/sdk

yarn add @filefeed/sdk

pnpm add @filefeed/sdk

Requirements

Node.js >= 18
TypeScript >= 5 (for TS projects)

Initialize the client

import FileFeed from '@filefeed/sdk';

const filefeed = new FileFeed({ apiKey: process.env.FILEFEED_API_KEY! });
// Example usage
const runs = await filefeed.pipelineRuns.list({ status: 'completed', limit: 50 });

Next steps

Call endpoints with the API Reference

Resources and methods

For endpoint details and payload schemas, see the API Reference.

connections

Manage SFTP / Email endpoints (formerly called clients). The deprecated filefeed.clients.* namespace still works and proxies here.

Method	Signature	Description
list	`list()`	List connections.
retrieve	`retrieve(id)`	Get a connection by id.
getByName	`getByName(name)`	Get a connection by name (unique per workspace). Resolves to the connection or `undefined`.
create	`create(params)`	Create a connection (SFTP, self-hosted SFTP, or `type: 'EMAIL'`).
update	`update(id, params)`	Update connection details.
remove	`remove(id)`	Delete a connection.
test	`test(id)`	Test SFTP connectivity (returns success/message). No-op for EMAIL.

Common workflows

Provision a connection with SFTP credentials (write-only — never read back)
Create an EMAIL connection that ingests mailed attachments
Verify connectivity before onboarding
Resolve a connection by its human-readable name

const conn = await filefeed.connections.create({ name: 'Acme' });
const ok = await filefeed.connections.test(conn.id);

// Outbound uploads reference a connection by its human-readable NAME —
// pass `connectionName: 'Acme'` directly (no slug lookup needed).
// Credentials are never returned on reads.
const found = await filefeed.connections.getByName('Acme');
if (found) console.log(found.id, found.sftpUsername);

schemas

Define and validate your target data model.

Method	Signature	Description
list	`list()`	List schemas.
retrieve	`retrieve(id)`	Get a schema.
create	`create(params)`	Create a schema from a JSON Schema `definition`.
update	`update(id, params)`	Update a schema’s `definition`.
remove	`remove(id)`	Delete a schema.
validate	`validate({ schemaId, data })`	Validate a payload against a schema.

Common workflows

Define the column structure as a JSON Schema definition
Validate a sample payload pre-ingestion

const schema = await filefeed.schemas.create({
  name: 'Employees',
  definition: {
    type: 'object',
    properties: {
      email: { type: 'string' },
      name: { type: 'string' },
    },
    required: ['email', 'name'],
  },
});
const result = await filefeed.schemas.validate({ schemaId: schema.id, data: { email: 'a@b.com', name: 'Ada' } });

pipelines

Connect clients to schemas and define mappings/transforms. Field mappings support sourced entries ({ source, target, transform? }), static values ({ target, value }) that write a fixed constant into a column on every row, and aggregated entries ({ sources, target, delimiter? }) that join several input columns into one target — limited availability, see field-mapping kinds.

Method	Signature	Description
list	`list({ clientId?, connectionName? })`	List pipelines.
retrieve	`retrieve(id)`	Get a pipeline.
create	`create(params)`	Create a pipeline (mappings/transforms).
update	`update(id, params)`	Update pipeline configuration.
remove	`remove(id)`	Delete a pipeline.
toggleActive	`toggleActive(id)`	Enable/disable a pipeline.

Common workflows

Create a pipeline for a client + schema
Adjust mappings, then toggle active for go-live

const pipeline = await filefeed.pipelines.create({
  name: 'Employees',
  clientId,
  schemaId,
  mappings: {
    fieldMappings: [
      { source: 'emp_id', target: 'id' },
      { target: 'source_system', value: 'FileFeed' }, // static constant on every row
    ],
  },
});
await filefeed.pipelines.toggleActive(pipeline.id);

pipelineRuns

Manage processing jobs and retrieve processed data.

Method	Signature	Description
list	`list({ status?, clientId?, pipelineId?, pipelineName?, page?, limit? })`	Paginated runs. Filter by status/client/pipeline/ids.
retrieve	`retrieve(id)`	Get a single pipeline run.
getData	`getData({ pipelineRunId, offset?, limit? })`	Paginated processed rows (offset-based, up to 1000 per page).
ack	`ack({ pipelineRunId })`	Mark run as processed (idempotent).
reprocess	`reprocess({ pipelineRunId })`	Re-run processing for a given run.
getOriginalFileUrl	`getOriginalFileUrl({ pipelineRunId, expiresIn? })`	Presigned URL to the original file.
getProcessedFileUrl	`getProcessedFileUrl({ pipelineRunId, expiresIn? })`	Presigned URL to the processed file.
delta	`delta({ baseRunId, compareRunId, offset?, limit? })`	Compare two runs of the same pipeline; returns the records added/removed between their processed files, with summary counts and a paginated `changes` list.

Common workflows

Fetch completed runs, paginate data, then acknowledge the run
Download original or processed file for audit trails
Reprocess failed runs after fixing mapping or schema
Diff two runs of the same pipeline (e.g. yesterday vs today) to see which records changed

// Quick example
const runs = await filefeed.pipelineRuns.list({ status: 'completed', limit: 25 });
const page = await filefeed.pipelineRuns.getData({ pipelineRunId: runs.data[0].id, limit: 1000 });

// Compare the two most recent runs of the same pipeline
const diff = await filefeed.pipelineRuns.delta({
  baseRunId: runs.data[1].id,
  compareRunId: runs.data[0].id,
});
console.log(diff.summary); // { baseCount, compareCount, addedCount, removedCount }

webhooks

Receive signed notifications for pipeline events.

Method	Signature	Description
list	`list()`	List webhooks.
retrieve	`retrieve(id)`	Get a webhook.
create	`create(params)`	Create a webhook (name, URL, optional headers). eventType defaults to GENERAL and secret is server-generated.
update	`update(id, params)`	Update webhook configuration.
remove	`remove(id)`	Delete a webhook.
listDeliveries	`listDeliveries(params)`	Inspect delivery attempts and status codes.
subscribeZapierPipelineRunEvents	`({ targetUrl })`	Subscribe a Zapier URL to pipeline-run events.
unsubscribeZapierPipelineRunEvents	`({ id })`	Remove a Zapier pipeline-run subscription.

Common workflows

Create a webhook for pipeline events
Monitor delivery health and retry on failure

const hook = await filefeed.webhooks.create({ name: 'Pipeline events', url: 'https://example.com/webhooks/filefeed' });
const deliveries = await filefeed.webhooks.listDeliveries({ webhookId: hook.id, page: 1, limit: 50 });

outbound

Push JSON data into outbound pipelines via multipart uploads.

Method	Signature	Description
initUpload	`initUpload(params)`	Create an upload session.
uploadPart	`uploadPart(uploadId, partNumber, params)`	Upload one JSON array part.
completeUpload	`completeUpload(uploadId, params)`	Finalize and trigger processing.
abortUpload	`abortUpload(uploadId)`	Cancel and cleanup parts.
getUploadStatus	`getUploadStatus(uploadId)`	Check session progress.
uploadJson	`uploadJson(params)`	Convenience: chunk, upload, and complete in one call.

Common workflows

Push data from your backend into a pipeline
Chunk large datasets and upload in parts
Use uploadJson() for simple one-shot uploads
Choose the delivered file’s name and format (csv | json | xml)

Pass the connection’s human-readable name as connectionName (the legacy clientName resolves by that same name and is deprecated).

const result = await filefeed.outbound.uploadJson({
  connectionName: 'Acme Corp',
  pipelineName: 'employee-sync',
  data: [{ remoteId: 'E001', firstName: 'Alice', lastName: 'Smith' }],
  outputFilename: 'employees.csv', // optional exact name
  outputFormat: 'csv',             // optional: csv | json | xml
});

See the Outbound Flow guide for the full walkthrough.

documents

Browse and manage a connection’s file store (S3 drive). Paths are relative to the connection root; pipeline-backed folders are protected.

Method	Signature	Description
browse	`browse({ connectionId, path?, token? })`	List one page of folders/files.
getMetadata	`getMetadata({ connectionId, path })`	File size, content type, etag.
getDownloadUrl	`getDownloadUrl({ connectionId, path })`	Presigned download URL.
createUploadTicket	`createUploadTicket(params)`	Presigned single/multipart upload.
completeUpload / abortUpload	`(params)`	Finalize / cancel a multipart upload.
createFolder / move / rename	`(params)`	Folder + path operations.
deleteObject / deleteFolder / bulkDelete	`(params)`	Delete (force = admin only).

const page = await filefeed.documents.browse({ connectionId: 'conn_1' });
console.log(page.folders, page.files);

files

Direct access to processed file content (distinct from per-run access on pipelineRuns).

Method	Signature	Description
getJson	`getJson({ clientName, fileName, pipelineId, offset?, limit? })`	Fetch a processed JSON file by name.
search	`search({ pipelineRunIds, searchTerm?, ... })`	Search rows across processed files.

const results = await filefeed.files.search({
  pipelineRunIds: ['run_1', 'run_2'],
  searchTerm: 'john@example.com',
});

notifications

Per-connection notification preferences — deliver pipeline-run alerts over EMAIL / SLACK / SMS.

Method	Signature	Description
getPreferences	`getPreferences(connectionId)`	List a connection’s preferences.
setPreferences	`setPreferences(connectionId, { preferences })`	Upsert preferences (an enabled one needs recipients).

await filefeed.notifications.setPreferences('conn_123', {
  preferences: [
    { eventType: 'PIPELINE_RUN_FAILED', channel: 'EMAIL', isEnabled: true, recipients: ['ops@acme.com'] },
  ],
});

The documents, files, and notifications resources and the Zapier webhook methods require @filefeed/sdk ≥ 2.5.0.

Example: Paginate Data

const runs = await filefeed.pipelineRuns.list({ status: 'completed', limit: 50 });
for (const run of runs.data) {
  let offset: number | null = 0;
  do {
    const page = await filefeed.pipelineRuns.getData({ pipelineRunId: run.id, limit: 1000, offset });
    // process page.data
    offset = page.data.length === 1000 ? (offset ?? 0) + page.data.length : null;
  } while (offset !== null);
}

Getting Started

Embedded Importers

Automated Flows

MCP Server

Versioning

Overview

Quick links

API Reference

Syncing Data

Handling Errors

Installation

Requirements

Initialize the client

Next steps

Resources and methods

Example: Paginate Data

​Overview

​Quick links

API Reference

Syncing Data

Handling Errors

​Installation

​Requirements

​Initialize the client

​Next steps

​Resources and methods

​Example: Paginate Data

Overview

Quick links

Installation

Requirements

Initialize the client

Next steps

Resources and methods

Example: Paginate Data