> ## 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.

# Changelog

> API version history and breaking-change log

FileFeed uses date-based API versions. Every entry below is a version you
can pin to via the `FileFeed-Version` header. Existing integrations stay on
their pinned version forever (until that version's sunset date) — bumping
is opt-in.

See the [API introduction](/api-reference/introduction#versioning) for how
versioning works and the [migration guides](#migration-guides) below for
upgrade walkthroughs.

***

## `2026-05-25`  <sub>Latest</sub>

The "Connection" rename.

### Added

* New canonical endpoints under `/connections/*` mirroring the existing
  `/clients/*` routes one-for-one.
* `FileFeed-Version` response header on every reply so clients can audit
  which shape the server applied.
* `Deprecation` / `Sunset` / `Link` response headers on legacy `/clients`
  routes when accessed with this version (per
  [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) and
  [draft-ietf-httpapi-deprecation-header](https://www.ietf.org/archive/id/draft-ietf-httpapi-deprecation-header-08.html)).
* `@filefeed/sdk@2.0.0` published with:
  * `filefeed.connections.*` namespace
  * `FileFeedConfig.apiVersion` override
  * `FileFeedConfig.onDeprecation` callback
* Outbound uploads accept `outputFilename` and `outputFormat` (`csv` |
  `json` | `xml`) to control the delivered file's name and serialization.
* Pipeline run status `delivered` — the terminal success state for
  **outbound** runs (output written to its destination). Inbound runs still
  use `completed`.
* `@filefeed/sdk@2.1.0`: outbound output options, self-hosted SFTP connection
  fields, `delivered` status.
* `@filefeed/sdk@2.2.0`: `filefeed.connections.getByName(name)` — resolve a
  connection (and its `awsUserName`) by its workspace-unique name.

### Changed

* The entity formerly called `Client` is now called `Connection`. The
  database row, IDs, and JSON shape are unchanged — only the name moved.
* Connection names are unique per workspace.
* TypeScript types `Client`, `CreateClientParams`, `UpdateClientParams` are
  now aliases for `Connection`, `CreateConnectionParams`,
  `UpdateConnectionParams`. Source-compatible — existing code keeps
  compiling.

### Deprecated

* HTTP: all `/clients/*` routes when called with `FileFeed-Version:
  2026-05-25`. They keep working but emit `Deprecation: true`.
* SDK: `filefeed.clients.*` methods. They proxy to `connections.*` and emit
  one warning per method per process.
* Method rename: `filefeed.clients.testConnection(id)` → `filefeed.connections.test(id)`.

### Security

* Connection responses no longer return stored credentials
  (`sftpPassword` / `sftpPrivateKey` / `sftpPassphrase` / `awsPassword`).
  They are write-only: set via create/update, never read back.

### Sunset

* API version `2024-09-01` is scheduled for sunset on **2027-05-25**.

#### Additive updates (no version bump)

These shipped within `2026-05-25` and are backwards compatible:

* Outbound uploads accept `connectionName` (the connection's human-readable
  name) on `POST /outbound/uploads`. Connection resolution now matches the
  connection `name` — the same path for hosted and self-hosted SFTP — so the
  name you created the connection with now works for self-hosted delivery.
  The legacy `clientName` field still works (resolved by name) but is
  deprecated; `connectionName` is also returned on the upload status response.
* `/pipelines` and `/pipeline-runs` list endpoints accept a `connectionName`
  filter (alias of the deprecated `clientName` filter).
* Fixed: outbound `outputFormat: "csv"` / `"xml"` without an explicit
  `outputFilename` now delivers the file in the requested format instead of
  silently falling back to JSON.
* `@filefeed/sdk@2.3.0` published with `connectionName` support.
* **Static-value field mappings.** A pipeline field mapping can now be a static
  constant `{ target, value }` (no `source`) that writes a fixed value into a
  column on every row, alongside the existing sourced `{ source, target,
  transform? }` mappings. `@filefeed/sdk@2.3.1`.
* **Email connections.** Create a connection with `type: "EMAIL"` to ingest
  files mailed as attachments to a dedicated inbound address
  (`connection.emailInbox.inboundAddress`). Configure `emailAllowedFormats`
  (required, non-empty), `emailAllowedSenders`, and `emailSubjectFilter`.
  Workspace registration is restricted to company email domains.
  `@filefeed/sdk@2.4.0`.
* **Documents API** (`/documents/*`). A connection-scoped S3 file manager:
  `browse`, `metadata`, `download`, presigned single/multipart upload,
  folder create/move/rename, and object/folder/bulk delete. Pipeline-backed
  folders are protected (override requires `force` + admin).
* **Per-connection notification preferences**
  (`GET`/`PUT /notifications/preferences/:connectionId`). Deliver
  `PIPELINE_RUN_FAILED` / `PIPELINE_RUN_SUCCEEDED` alerts over `EMAIL` /
  `SLACK` / `SMS`.
* **Direct file access.** `GET /files/json` fetches a processed JSON file by
  name; `POST /files/search` searches rows across processed files.
* **Zapier pipeline-run subscriptions.**
  `POST`/`DELETE /webhooks/zapier/pipeline-run-events/{subscribe,unsubscribe}`
  register a workspace-level `PIPELINE_RUN_EVENT` webhook for Zapier.
* **Schemas** are defined by a JSON Schema `definition` object (the SDK's
  legacy `fields` array is ignored by the API). Schema responses always include
  `isActive`. Webhook signing secrets are returned only once on create and
  never on reads.
* `@filefeed/sdk@2.5.0` published with the `documents`, `notifications`, and
  `files` resources, Zapier webhook methods, `Schema.definition`,
  `Pipeline.webhooks`, and `PipelineRun.client` / `isPipelineDeleted`.
* **Pipeline run delta.** New endpoint `GET /pipeline-runs/delta` compares the
  processed files of two runs of the **same** pipeline (for example yesterday vs
  today) and returns the records added and removed, with summary counts and a
  paginated `changes` list. The diff is a whole-record set difference — there is
  no record-identity key, so a changed row appears as one removed plus one
  added. Available as
  `filefeed.pipelineRuns.delta({ baseRunId, compareRunId })` in
  `@filefeed/sdk@2.7.0`.
* **Aggregated field mappings** <sub>limited availability</sub>. A pipeline
  field mapping can now combine **multiple** source columns into one target —
  `{ sources, target, delimiter? }` — joined in order by `delimiter` (default a
  single space), skipping empty values; a `transform`, if set, runs on the
  joined result. Provide `sources` instead of `source`, alongside the existing
  sourced and static-value mappings. Gated per workspace: until the feature is
  enabled for you, saving a pipeline that uses `sources` returns `400`. Contact
  [support@filefeed.io](mailto:support@filefeed.io) to enable it.

[Read the migration guide →](/migration/v1-to-v2)

***

## `2024-09-01`  <sub>Deprecated · sunsets 2027-05-25</sub>

Baseline. This is the version every workspace was created on prior to the
`2026-05-25` release. No prior changelog entries exist — this is the first
version where date-based versioning was introduced; we backdated the
baseline label to the date of GA so we have a coherent timeline.

### Endpoints

* `/clients/*`, `/schemas/*`, `/pipelines/*`, `/pipeline-runs/*`,
  `/webhooks/*`, `/outbound/*`

### Sunset behaviour

On **2027-05-25**, requests sent with `FileFeed-Version: 2024-09-01` will
receive `410 Gone`:

```json theme={null}
{
  "error": "api_version_sunset",
  "message": "API version 2024-09-01 was sunset on 2027-05-25. Upgrade to 2026-05-25.",
  "migration_url": "https://docs.filefeed.io/migration/v1-to-v2"
}
```

***

## Migration guides

* [Upgrade to 2026-05-25](/migration/v1-to-v2) — Client → Connection rename