canonical: https://jentic.com/apis/api.x.flatfile.com/flatfile

# X Flatfile Flatfile API Reference

Jentic publishes the only available OpenAPI specification for Flatfile's API, keeping it validated and agent-ready. Flatfile is a data-onboarding platform that helps teams import, validate, and transform customer-supplied spreadsheets and CSVs at scale. The 222-endpoint API exposes accounts, actions, agents, agent exports, and the broader workspace primitives that power custom data onboarding flows. Use it to embed bring-your-own-data import experiences inside an application without writing a parsing pipeline.

## For AI agents

Build and run customer data-onboarding workflows on Flatfile - workspaces, agents, actions, and exports - through a 222-endpoint REST API.

## Scope

Does not handle hosted ETL between SaaS sources, BI dashboarding, or storage of long-term analytical data - use for customer data onboarding, validation, and transformation only.

## Capabilities

- Trigger a bulk action across imported records to apply transformations in one API call
- Manage Flatfile agents and roll back to a previous version when a deployment misbehaves
- Generate and download agent exports for offline review or downstream loading
- Inspect the current Flatfile account to confirm tenant context before issuing operations
- Retrieve a specific action by id to check its status or rerun parameters
- List the roles assigned to an agent to confirm correct permissioning before running it

## Use cases

### Embedded Data Onboarding for SaaS Customers

A B2B SaaS app needs to let customers import legacy spreadsheets without bespoke parsing. The team configures a Flatfile workspace, then an agent provisions per-customer onboarding sessions through the API, watches the actions queue for completion, and pulls the cleaned data back into the product. Importing a customer's first dataset goes from days to minutes.

Example prompt: Create a Flatfile action for the new customer dataset, watch `/actions/{actionId}` until it completes, and pull the output

### Bulk Validation and Cleanup Pipelines

Operations teams importing thousands of records at once need a single bulk action rather than per-row calls. The `/actions/bulk` endpoint runs validation and transformation across the whole import in one request. The agent reads the action result and surfaces invalid rows for human review before the data lands in production.

Example prompt: POST to `/actions/bulk` with the validation rules, then GET `/actions/{actionId}` until completion and surface invalid rows

### Versioned Flatfile Agents with Rollback

When an updated Flatfile agent introduces a regression, ops needs an immediate rollback path. `/agents/{agentId}/versions` lists prior versions and `/agents/{agentId}/versions/{agentVersionId}/revert` restores the chosen one. Bad releases are recoverable in a single API call rather than a deploy cycle.

Example prompt: List versions for the misbehaving agent, identify the last known-good version, and POST the revert endpoint

### Scheduled Export of Onboarded Data

Some customers want a nightly export of the records they imported into Flatfile. An agent triggers /agent-exports for each tracked workspace, polls `/agent-exports/{agentExportId}` for completion, then downloads the file via `/agent-exports/{agentExportId}/download.` The export ends up in object storage for downstream loading.

Example prompt: Trigger a Flatfile agent export, poll for completion, and download the resulting file to storage

### AI Agent Data Onboarding via Jentic

An AI agent embedded in a SaaS product helps customers map their messy spreadsheets to the canonical schema. The agent uses Jentic to find the right Flatfile actions and agent operations, runs validations, and reports any rejects back to the customer. The 222-endpoint surface stays out of the developer's prompt.

Example prompt: Use Jentic to find the Flatfile bulk-action operation, execute it with the validation config, and parse the resulting reject list

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/accounts/current` | Retrieve the current account context |
| GET | `/actions` | List actions in the workspace |
| POST | `/actions/bulk` | Run a bulk action across many records |
| GET | `/agents` | List configured agents |
| GET | `/agents/{agentId}/versions` | List version history for an agent |
| POST | `/agents/{agentId}/versions/{agentVersionId}/revert` | Revert an agent to a prior version |
| POST | `/agent-exports` | Create a new agent export |
| GET | `/agent-exports/{agentExportId}/download` | Download a completed export |

## Key resources

- **Accounts** — Tenant context for the calling user
- **Actions** — Single and bulk transformations applied to imported data
- **Agents** — Versioned data-handling logic with role-based permissions
- **Agent Exports** — Asynchronous exports of imported records

## Why Jentic

- **Setup:** Wiring Flatfile by hand means setting up its HTTP token auth, learning the agent and action resource shapes, and managing agent versions and exports yourself. Through Jentic you install once, import Flatfile from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Flatfile puts the agent id in the URL path (`/agents/{agentId}/versions/...`), so a rule can pin your agent to one Flatfile agent: it can read that agent's versions and nothing else. You choose the operations it may call, so reverting a version is not included unless you add it.
- **Credential handling:** Your Flatfile token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list agent versions' or 'download an agent export', and Jentic returns the matching Flatfile operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Airbyte** — Airbyte focuses on ETL between SaaS sources; Flatfile focuses on customer-supplied spreadsheet onboarding.
- **Zapier** — Zapier wires Flatfile actions into downstream CRM, spreadsheet, and notification tools without custom glue code.
- **Shopify** — Shopify is a common downstream target for Flatfile-imported product or customer records.

## FAQ

### Why is there no official OpenAPI spec for Flatfile?

Flatfile does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Flatfile API Reference via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Flatfile API use?

Flatfile uses HTTP bearer authentication. Send your Flatfile secret as a bearer token in the Authorization header. Through Jentic, the secret is held in the credential vault and injected at execution time, so the raw key never enters agent prompts.

### Can I run a bulk transformation with the Flatfile API?

Yes. POST `/actions/bulk` applies a transformation across many records in a single request. Watch the action's status with GET `/actions/{actionId}` until it completes, then read the resulting record set or rejects.

### What are the rate limits for the Flatfile API?

The spec does not declare numeric rate limits; Flatfile enforces tenant-level limits at the platform layer. Build retries with backoff on 429, and prefer bulk endpoints (such as `/actions/bulk`) over per-record calls when importing many rows.

### How do I revert a misbehaving Flatfile agent through Jentic?

Install the SDK with `pip install jentic`. Search Jentic for `revert flatfile agent version`, load the schema for POST `/agents/{agentId}/versions/{agentVersionId}/revert`, and execute it with the agent id and the version id you want to restore.

### Can I export records out of Flatfile?

Yes. POST /agent-exports to create a new export job, poll `/agent-exports/{agentExportId}` for completion, and call `/agent-exports/{agentExportId}/download` to fetch the resulting file.

### Can I limit what my agent is allowed to do with the Flatfile API?

Yes. Because you run Jentic One yourself, your own rules decide which Flatfile operations and credentials the agent may use. Since Flatfile carries the agent id in the URL path (`/agents/{agentId}/versions/...`), you can pin the agent to a single Flatfile agent so it only reads that agent's versions and nothing else. You pick the exact operations it may call, so a destructive step like POST `/agents/{agentId}/versions/{agentVersionId}/revert` is excluded unless you explicitly allow it.