X Flatfile Flatfile API Reference
41
AI ReadinessNon-Ready (D-)41/100
Agent-ready OpenAPI document · curated by JenticData EnrichmentData Transformationhttp222 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Build and run customer data-onboarding workflows on Flatfile - workspaces, agents, actions, and exports - through a 222-endpoint REST API.
Use for: Find all Flatfile actions in the current workspace, Create a bulk action across multiple records, Retrieve the current Flatfile account, List all configured Flatfile agents
Not supported: 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.
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.
Install Jentic One Beta
Connect the Flatfile API Reference to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Flatfile API Reference, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fapi.x.flatfile.com%2Fflatfile" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fapi.x.flatfile.com%2Fflatfile" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Flatfile API Reference API.
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
Patterns agents use Flatfile API Reference API for, with concrete tasks.
★ 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.
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.
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.
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.
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.
Use Jentic to find the Flatfile bulk-action operation, execute it with the validation config, and parse the resulting reject list
Key Endpoints
222 endpoints — jentic publishes the only available openapi specification for flatfile's api, keeping it validated and agent-ready.
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
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
Jentic AI Readiness Score
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
A
API Reference
- Non-Ready (D-)41/100
31
Foundational Compliance58
Developer Experience & Jentic Compatibility29
AI-Readiness & Agent Experience42
Agent Usability60
Security100
AI DiscoverabilityPowered by JenticScoring Framework 1.0.0 | Scoring Engine 0.4.0
Show dimension breakdown
31
Foundational Compliance
Base layer of spec validity and structural soundness.
Grade: FSignals: 4
0%
Lint Results
Aggregated quality score from linter diagnostics, weighted by severity.
100%
Resolution Completeness
Percentage of `$ref` references that resolve successfully.
0%
Specification Validity
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
25%
Structural Integrity
Structural correctness score based on schema issues using logarithmic dampening.
58
Developer Experience & Jentic Compatibility
Clarity, completeness, and ingestion readiness for developers and tooling.
Grade: C+Signals: 4
0%
Example Density
How richly the API is illustrated with examples.
100%
Example Validity
Percentage of examples that conform to their schemas.
40%
Response Coverage
Percentage of operations with complete response definitions (success, client error, server error).
93%
Tooling Readiness
Health of API ingestion, bundling, and resolution within Jentic pipelines.
29
AI-Readiness & Agent Experience
Semantic breadth, depth, and agent comprehension for AI systems.
Grade: FSignals: 4
53%
Description Coverage
Coverage of descriptions across API elements.
0%
Error Standardization
Coverage of RFC 9457 Problem Details for error responses.
0%
OperationId Quality
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
63%
Summary Coverage
Coverage of summaries across operations/tags/info.
42
Agent Usability
Functional utility, complexity comfort, and AI orchestration readiness.
Grade: D-Signals: 1
42%
Complexity Comfort
Agent comfort level based on API operational and structural complexity.
60
Security
Trust, risk posture, and security compliance.
Grade: B-Signals: 1
60%
Authentication Strength
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
100
AI Discoverability
Findability, semantic richness, and reasoning readiness.
Grade: A+Signals: 1
100%
Descriptive Richness
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Flatfile API Reference API through Jentic.
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.
GET STARTED