> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filefeed.io/llms.txt
> Use this file to discover all available pages before exploring further.
# API Library
> TypeScript SDK for programmatic access to FileFeed
## 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
Explore endpoints with the API Playground.
Fetch processed data and acknowledge runs.
Retry patterns and structured error handling.
## Installation
```bash theme={null}
npm install @filefeed/sdk
```
```bash theme={null}
yarn add @filefeed/sdk
```
```bash theme={null}
pnpm add @filefeed/sdk
```
## Requirements
* Node.js >= 18
* TypeScript >= 5 (for TS projects)
## Initialize the client
```ts theme={null}
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](/api-reference/introduction)
## Resources and methods
For endpoint details and payload schemas, see the API Reference.
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
```ts theme={null}
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);
```
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
```ts theme={null}
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' } });
```
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](/automated-flows/sftp).
| 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
```ts theme={null}
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);
```
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
```ts theme={null}
// 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 }
```
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
```ts theme={null}
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 });
```
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).
```ts theme={null}
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](/automated-flows/outbound) for the full walkthrough.
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). |
```ts theme={null}
const page = await filefeed.documents.browse({ connectionId: 'conn_1' });
console.log(page.folders, page.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. |
```ts theme={null}
const results = await filefeed.files.search({
pipelineRunIds: ['run_1', 'run_2'],
searchTerm: 'john@example.com',
});
```
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). |
```ts theme={null}
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
```ts theme={null}
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);
}
```