API Library

Overview

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

Authentication via API key
Resources: Pipeline Runs, Clients, Schemas, Pipelines, Webhooks
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

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.

clients

Manage SFTP clients and connection details.

Method	Signature	Description
list	`list()`	List clients.
retrieve	`retrieve(id)`	Get a client.
create	`create(params)`	Create a client with credentials.
update	`update(id, params)`	Update client details.
remove	`remove(id)`	Delete a client.
testConnection	`testConnection(id)`	Test SFTP connectivity (returns success/message).

Common workflows

Provision a client with SFTP credentials
Rotate credentials, manage allowlists
Verify connectivity before onboarding

const client = await filefeed.clients.create({ name: 'Acme' });
const ok = await filefeed.clients.testConnection(client.id);

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 (fields, validation).
update	`update(id, params)`	Update schema details.
remove	`remove(id)`	Delete a schema.
validate	`validate({ schemaId, data })`	Validate a payload against a schema.

Common workflows

Define required fields and validation rules
Validate a sample payload pre-ingestion

const schema = await filefeed.schemas.create({ name: 'Employees', fields: [
  { name: 'email', type: 'string', required: true },
  { name: 'name', type: 'string', required: true }
] });
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.

Method	Signature	Description
list	`list({ clientId?, clientName? })`	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: {} });
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.

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

// 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 });

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 (URL, event type, secret).
update	`update(id, params)`	Update webhook configuration.
remove	`remove(id)`	Delete a webhook.
listDeliveries	`listDeliveries(params)`	Inspect delivery attempts and status codes.

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', eventType: 'GENERAL' });
const deliveries = await filefeed.webhooks.listDeliveries({ webhookId: hook.id, page: 1, limit: 50 });

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

Overview

Quick links

API Reference

Syncing Data

Handling Errors

Installation

Requirements

Initialize the client

Next steps

Resources and methods

Example: Paginate Data

Getting Started

Embedded Importers

Automated Flows

​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