The Chain.io File API lets you deliver files from a Chain.io Flow to a secure, Chain.io-hosted data store and make those files available to your trading partners through a simple HTTPS GET request. It is designed for cases where you need to expose structured data or documents through a lightweight API without standing up infrastructure.

What the File API Does

When you send data through a Flow and select File API as the destination connection, Chain.io:

1. Writes the final output file from your Flow into a secure, Chain.io-managed storage location.

2. Makes that file available at a URL that your trading partner can call via HTTPS.

3. Requires an API key (that you control) to securely retrieve the file.

This allows you to build simple, partner-specific APIs based entirely on Chain.io Flows.

Files are available in the API for one year after they are posted.  Updating a file resets the timer.

Key Concepts

File Output from a Flow

The file created at the end of your Flow—after mapping, JSON creation, post-processing, or any other steps—is the file that the File API exposes.

• Whatever filename the Flow produces is the filename used in the retrieval URL.

• You can generate filenames dynamically using Flow features, making it easy to use shipment numbers, reference numbers, job numbers, etc.

Namespaces

Namespaces create logical sub-paths within your File API URL.
Use them to:

• Group multiple Flows under the same customer-facing API.

• Isolate different customers or business units.

• Support multiple partner-specific APIs without creating separate connections.

Example:
/fp/{company-uid}/{namespace}/{filename}

Each namespace has its own API key list, allowing full separation of partner access.

API Keys

You add API keys in the File API destination configuration.
These keys:

• Are securely stored by Chain.io.

• Must be included by your trading partner in the x-api-key header of their GET request.

• Control access at the namespace level.

Retrieving a File

Your trading partner retrieves files via:

GET https://webhooks.chain.io/fp/{company-uid}/{namespace}/{filename} x-api-key: {their-api-key}

• company-uid is your unique company identifier inside Chain.io.

• namespace is configured in the File API destination.

• filename is whatever your Flow outputs.

All files are stored with a one-year time-to-live (TTL).

Creating Partner-Specific APIs

Because the File API is the output of a Flow, you can shape the data however you need:

• Build JSON payloads with Chain.io’s JSON builder.

• Map incoming EDI or flat files to clean partner-specific schemas.

• Use post-processors to finalize formatting.

This means every partner can have:

• A unique API endpoint.

• A custom namespace.

• A custom data structure.

• A key-based URL path that uses their reference numbers.

Using Filenames as API Keys

If you pull a reference number from your input data (e.g., House BOL, shipment ID, job number) and use it as the filename

https://webhooks.chain.io/fp/{company}/{namespace}/{house-bol}

For more information on customizing file name, see our Output Filename Format (specifally the JSON & XPath Options)

For example, to convert a file to use the forwarder_reference field in Chain.io Standard Shipment JSON, you would enter this as the output file name.

{{jsonata "shipments[0].forwarder_reference"}}

You effectively expose a RESTful endpoint that retrieves exactly one shipment’s data by its reference number.

Partners can now call an API like:

GET /fp/abc123/shipment-api/47839201

Typical Use Cases

• Create a Shipment lookup API for a customer with only the fields they need based on files pushed from your TMS

• Provide customers with an on-demand status endpoint keyed by reference numbers.

• Expose structured data from legacy EDI pipelines in a modern API format.

• Convert product masters into a lookup API available for AI classification tools