DEV Community: Apideck

Your MCP Server Is Eating Your Context Window. There's a Simpler Way

samz — Mon, 16 Mar 2026 15:31:45 +0000

TL;DR: MCP tool definitions can burn 55,000+ tokens before an agent processes a single user message. We built the Apideck CLI as an AI-agent interface instead:an ~80-token agent prompt replaces tens of thousands of tokens of schema, with progressive disclosure via --help and structural safety baked into the binary. Any agent that can run shell commands can use it. No protocol support required.

The problem demos never show you

Here's a scenario that'll feel familiar if you've wired up MCP servers for anything beyond a demo.

You connect GitHub, Slack, and Sentry. Three services, maybe 40 tools total. Before your agent has read a single user message, 55,000 tokens of tool definitions are sitting in the context window. That's over a quarter of Claude's 200k limit. Gone.

It gets worse. Each MCP tool costs 550-1,400 tokens for its name, description, JSON schema, field descriptions, enums, and system instructions. Connect a real API surface, say a SaaS platform with 50+ endpoints, and you're looking at 50,000+ tokens just to describe what the agent could do, with almost nothing left for what it should do.

One team reported three MCP servers consuming 143,000 of 200,000 tokens. That's 72% of the context window burned on tool definitions. The agent had 57,000 tokens left for the actual conversation, retrieved documents, reasoning, and response. Good luck building anything useful in that space.

This isn't a theoretical concern. David Zhang (@dzhng), building Duet, described ripping out their MCP integrations entirely, even after getting OAuth and dynamic client registration working. The tradeoff was impossible:

Load everything up front → lose working memory for reasoning and history
Limit integrations → agent can only talk to a few services
Build dynamic tool loading → add latency and middleware complexity

He called it a "trilemma."

And the numbers hold up under controlled testing. A recent benchmark by Scalekit ran 75 head-to-head comparisons (same model, Claude Sonnet 4, same tasks, same prompts) and found MCP costing 4 to 32x more tokens than CLI for identical operations. Their simplest task, checking a repo's language, consumed 1,365 tokens via CLI and 44,026 via MCP. The overhead is almost entirely schema: 43 tool definitions injected into every conversation, of which the agent uses one or two.

Three approaches to the same problem

The industry is converging on three responses to context bloat. Each has a sweet spot.

MCP with compression tricks

The first response is to keep MCP but fight the bloat. Teams compress schemas, use tool search to load definitions on demand, or build middleware that slices OpenAPI specs into smaller chunks.

This works for small, well-defined interactions like looking up an issue, creating a ticket, or fetching a document. MCP's structured tool calls and typed schemas are genuinely useful when you have a tight set of operations that agents use frequently.

But it adds infrastructure. You need a tool registry, search logic, caching, and routing. You're building a service to manage your services. And you're still paying per-tool token costs every time the agent decides it needs a new capability.

Code execution

The code execution approach treats the agent like a developer with a persistent workspace. When the agent needs a new integration, it reads the API docs, writes code against the SDK, runs it, and saves the script for reuse. Duet pioneered this pattern by letting agents write and maintain their own integration scripts.

This is powerful for long-lived workspace agents that maintain state across sessions and need complex workflows: loops, conditionals, polling, batch operations. Things that are awkward to express as individual tool calls become natural in code.

There's a more targeted variant worth watching: Code Mode. Instead of writing arbitrary code against raw APIs, the agent writes short orchestration scripts that call structured MCP tools underneath. A benchmark by Sideko across 12 Stripe tasks showed Code Mode MCP using 58% fewer tokens than raw MCP and 56% fewer than CLI. The key insight: on multi-step tasks like creating an invoice with line items, CLI required 19 LLM round trips, raw MCP needed 12, and Code Mode collapsed it to 4. The agent writes a TypeScript program that handles the looping internally, without going back to the LLM at each step.

This matters because CLI's efficiency advantage, which is real for single-step discovery and reads, can erode on complex chained writes where each round trip compounds context. Code Mode offers a middle ground: structured tool access without the schema bloat, plus the ability to batch operations without per-step LLM overhead.

The tradeoff is that your agent is writing and executing code against production APIs. Even sandboxed, the safety surface is larger than a CLI with structural permissions. You need review mechanisms and trust in your agent's judgment. But for workflows that involve loops and dependent state, it's a pattern worth considering alongside CLI.

CLI as the agent interface

The third approach is the one we took. Instead of loading schemas into the context window or letting the agent write integration code, you give it a CLI.

A well-designed CLI is a progressive disclosure system by nature. When a human developer needs to use a tool they haven't touched before, they don't read the entire API reference. They run tool --help, find the subcommand they need, run tool subcommand --help, and get the specific flags for that operation. They pay attention costs proportional to what they actually need.

Agents can do exactly the same thing. And the token economics are dramatically different.

Why CLIs are the pragmatic sweet spot

Progressive disclosure saves tokens

Here's what the Apideck CLI agent prompt looks like. This is the entire thing an AI agent needs in its system prompt:

Use `apideck` to interact with the Apideck Unified API.
Available APIs: `apideck --list`
List resources: `apideck <api> --list`
Operation help: `apideck <api> <resource> <verb> --help`
APIs: accounting, ats, crm, ecommerce, hris, ...
Auth is pre-configured. GET auto-approved. POST/PUT/PATCH prompt (use --yes). DELETE blocked (use --force).
Use --service-id <connector> to target a specific integration.
For clean output: -q -o json

That's ~80 tokens. Compare that to the alternatives:

Approach	Tokens consumed	When
Full OpenAPI spec in context	30,000-100,000+	Before first message
MCP tools (~3,600 per API)	10,000-50,000+	Before first message
CLI agent prompt	~80	Before first message
CLI `--help` call	~50-200	Only when needed

The agent starts with 80 tokens of guidance and discovers capabilities on demand:

# Level 1: What APIs are available? (~20 tokens output)
$ apideck --list
accounting ats connector crm ecommerce hris ...

# Level 2: What can I do with accounting? (~200 tokens output)
$ apideck accounting --list
Resources in accounting API:

  invoices
    list       GET  /accounting/invoices
    get        GET  /accounting/invoices/{id}
    create     POST /accounting/invoices
    delete     DELETE /accounting/invoices/{id}

  customers
    list       GET  /accounting/customers
    ...

# Level 3: How do I create an invoice? (~150 tokens output)
$ apideck accounting invoices create --help
Usage: apideck accounting invoices create [flags]

Flags:
  --data string        JSON request body (or @file.json)
  --service-id string  Target a specific connector
  --yes                Skip write confirmation
  -o, --output string  Output format (json|table|yaml|csv)
  ...

Each step costs 50-200 tokens, loaded only when the agent decides it needs that information. An agent handling an accounting query might consume 400 tokens total across three --help calls. The same surface through MCP would cost 10,000+ tokens loaded upfront whether the agent uses them or not.

This mirrors how Claude Agent Skills work. Metadata first, full details only when selected, reference material only when needed. The CLI does the same thing through a different mechanism.

Scalekit's benchmark independently validated this pattern. They found that even a minimal ~800-token "skills file" (a document of CLI tips and common workflows) reduced tool calls by a third and latency by a third compared to a bare CLI. Our approach takes it further: the ~80-token agent prompt provides the same progressive discovery at a tenth of the cost. The principle is the same. A small, upfront hint about how to navigate the tool is worth more than thousands of tokens of exhaustive schema.

Reliability: local beats remote

There's a dimension of the MCP problem that doesn't get enough attention: availability.

Scalekit's benchmark recorded a 28% failure rate on MCP calls to GitHub's Copilot server. Out of 25 runs, 7 failed with TCP-level connection timeouts. These weren't protocol errors or bad tool calls. The connection never completed.

CLI agents don't have this failure mode. The binary runs locally. There's no remote server to time out, no connection pool to exhaust. When your agent runs apideck accounting invoices list, it makes a direct HTTPS call to the Apideck API. One hop, not two.

This matters at scale. At 10,000 operations per month, a 28% failure rate means roughly 2,800 retries, each burning additional tokens and latency. Scalekit estimated the monthly cost difference at $3.20 for CLI versus $55.20 for direct MCP, a 17x cost multiplier, with the reliability tax on top.

Remote MCP servers will improve. Connection pooling, better infrastructure, and gateway layers will close the gap. But "the binary is on your machine" is a reliability guarantee that no amount of infrastructure engineering on the server side can match.

Structural safety beats prompt-based safety

Telling an agent "never delete production data" in a system prompt is like putting a sticky note on the nuclear launch button. It works until a creative prompt injection peels the note off.

Security research on AI agents in CI/CD has shown how prompt injection can manipulate agents with high-privilege tokens into leaking secrets or modifying infrastructure. The pattern is always the same: untrusted input gets injected into a prompt, the agent has broad tool access, and bad things happen.

The Apideck CLI takes a structural approach. Permission classification is baked into the binary based on HTTP method:

// From internal/permission/engine.go
switch op.Permission {
case spec.PermissionRead:
    return ActionAllow      // GET -> auto-approved
case spec.PermissionWrite:
    return ActionPrompt     // POST/PUT/PATCH -> confirmation required
case spec.PermissionDangerous:
    return ActionBlock       // DELETE -> blocked by default
}

No prompt can override this. A DELETE operation is blocked unless the caller explicitly passes --force. A POST requires --yes or interactive confirmation. GET operations run freely because they can't modify state.

The agent frameworks reinforce this. Claude Code, Cursor, and GitHub Copilot all have permission systems that gate shell command execution. So you get two layers of structural safety: the agent framework asks "should I run this command?" and the CLI itself enforces "is this operation allowed?"

You can also customize the policy per operation:

# ~/.apideck-cli/permissions.yaml
defaults:
  read: allow
  write: prompt
  dangerous: block

overrides:
  accounting.payments.create: block    # payments are sensitive
  crm.contacts.delete: prompt          # contacts can be soft-deleted

This is the same principle behind Duda blocking destructive MCP actions, but enforced structurally in the binary, not through prompt instructions that compete with everything else in the context window.

Universal compatibility, zero protocol overhead

Every serious agent framework ships with "run shell command" as a primitive. Claude Code has Bash. Cursor has terminal access. GitHub Copilot SDK exposes shell execution. Gemini CLI runs commands natively.

MCP requires dedicated client support, connection plumbing, and server lifecycle management. A CLI requires a binary on the PATH.

This matters more than it sounds. When you're building an agent that needs to interact with APIs, the integration path for a CLI is:

Install the binary
Set environment variables for auth
Add ~80 tokens to the system prompt
Done

The integration path for MCP is:

Implement or configure an MCP client
Set up server connections (transport, auth, lifecycle)
Handle tool registration and schema loading
Manage connection state and reconnection
Deal with the token budget for tool definitions

The CLI approach also means your agent integration isn't locked to any specific framework. The same apideck binary works from Claude Code, Cursor, a custom Python agent, a bash script, or a CI/CD pipeline.

How we built it

The Apideck CLI is a single static binary that parses our OpenAPI spec at startup and generates its entire command tree dynamically.

OpenAPI-native, no code generation. The binary embeds the latest Apideck Unified API spec. On startup, it parses the spec with libopenapi and builds commands for every API group, resource, and operation. When the API adds new endpoints, apideck sync pulls the latest spec. No SDK regeneration, no version bumps.

Smart output defaults. When running in a terminal, output defaults to a formatted table with colors. When piped or called from a non-TTY (which is how agents call it), output defaults to JSON. Agents get machine-parseable output without needing to remember --output json.

# Agent calls this (non-TTY) -> gets JSON automatically
$ apideck accounting invoices list -q
[{"id": "inv_12345", "number": "INV-001", "total": 1500.00, ...}]

# Human runs the same command in terminal -> gets a table
$ apideck accounting invoices list
┌──────────┬─────────┬──────────┐
│ ID       │ Number  │ Total    │
├──────────┼─────────┼──────────┤
│ inv_12345│ INV-001 │ 1,500.00 │
└──────────┴─────────┴──────────┘

Auth is invisible. Credentials are resolved from environment variables (APIDECK_API_KEY, APIDECK_APP_ID, APIDECK_CONSUMER_ID) or a config file, and injected into every request automatically. The agent never handles tokens, never sees auth headers, never needs to manage sessions.

Connector targeting. The --service-id flag lets agents target specific integrations. apideck accounting invoices list --service-id quickbooks hits QuickBooks. Swap to --service-id xero and the same command hits Xero. Same interface, different backend. The unified API handles the rest.

When CLI isn't the answer

CLIs aren't universally better. Here's where the other approaches win.

MCP is better for tightly scoped, high-frequency tools. If your agent calls the same 5-10 tools hundreds of times per session, the upfront schema cost amortizes well. A customer support agent that only ever looks up tickets, updates status, and sends replies doesn't need progressive disclosure. It needs those tools ready immediately.

Code execution is better for complex, stateful workflows. If your agent needs to poll an API every 30 seconds, aggregate results across paginated endpoints, or orchestrate multi-step transactions with rollback logic, writing code is more natural than chaining CLI calls. As the Sideko benchmark showed, CLI's efficiency advantage can reverse on multi-step chained writes where each round trip compounds context. For those patterns, Code Mode (agent writes orchestration scripts that call structured tools) or the Duet approach (full code execution) will use fewer total tokens despite higher per-step overhead.

MCP is better when your agent acts on behalf of other people's users. This is the dimension most CLI-vs-MCP comparisons gloss over, and it's worth being direct about. When your agent automates your own workflow, ambient credentials are fine. You are the user, and the only person at risk is you. But if you're building a B2B product where agents act on behalf of your customers' employees, across organizations those customers control, the identity problem becomes three-layered: which agent is calling, which user authorized it, and which tenant's data boundary applies. Per-user OAuth with scoped access, consent flows, and structured audit trails are real requirements at that boundary, and they're requirements that raw CLI auth (gh auth login, environment variables) wasn't designed to solve. MCP's authorization model, whatever its efficiency cost, addresses this natively.

There's also a deeper identity gap that CLI auth doesn't address: agent-level identity. A CLI token authenticates the user, but the API provider never knows which agent made the request. That matters for policy enforcement. If an API provider has a partnership with Agent A but not Agent B, there's no way to distinguish them in a CLI token. MCP's OAuth model can carry agent identity through claims like act, which becomes critical as agents start calling other agents and you need the full chain of delegation in the token. For single-agent workflows this is academic. For multi-agent architectures it's a real architectural constraint.

That said, the gap is narrower than it looks for unified API architectures. Apideck already centralizes auth through Vault: credentials are managed per-consumer, per-connection, and scoped by service. The --service-id flag targets a specific integration within a specific consumer's vault. The structural permission system enforces read/write/delete boundaries in the binary. What's missing is the per-user OAuth consent flow and tenant-scoped audit trail, real gaps, but ones that sit at the platform layer, not the agent interface layer. A CLI can be the interface while a backend handles delegated authorization. These aren't mutually exclusive.

It's also worth noting that MCP's auth story is less settled than it appears. As Speakeasy's MCP OAuth guide makes clear, user-facing OAuth exchange is not actually required by the MCP spec. Passing access tokens or API keys directly is completely valid. The real complexity kicks in when MCP clients need to handle OAuth flows dynamically, which requires Dynamic Client Registration (DCR), a capability most API providers don't support today. Companies like Stripe and Asana have started adding DCR to accommodate MCP, but it remains a high-friction integration. The auth advantage MCP has over CLI is real in theory, but in practice, the ecosystem is still catching up to the spec.

CLIs are weaker at streaming and bi-directional communication. A CLI call is request-response. If you need server-sent events, WebSocket streams, or long-lived connections, you'll want an SDK or MCP server that can hold a connection open.

Distribution has friction. MCP servers can theoretically live behind a URL. CLIs need a binary per platform, updates, and PATH management. For the Apideck CLI, we ship a static Go binary that runs everywhere without dependencies, but it's still a binary you need to install.

The honest framing: MCP, code execution, and CLIs are complementary tools. The mistake is treating MCP as the universal answer when, for many integration patterns, a CLI does the job with two orders of magnitude less context overhead.

What this means for API providers

If you're building developer tools in 2026, AI agents are becoming a primary consumer of your API surface. Not the only consumer (human developers still matter), but a rapidly growing one.

A few things are worth considering:

Your OpenAPI spec is too big for a context window. If you have 50+ endpoints, converting your spec to MCP tools will burn the budget of most agent interactions. Think about what a minimal entry point looks like.

Progressive disclosure isn't just a UX pattern anymore. It's a token optimization strategy. Give agents a way to discover capabilities incrementally instead of dumping everything upfront.

Structural safety is non-negotiable. Prompt-based guardrails are the security equivalent of honor system parking. Build permission models into your tools, not your prompts. Classify operations by risk level and enforce that classification in code.

Ship machine-friendly output formats. JSON by default in non-interactive contexts. Stable exit codes. Deterministic output. These are documented principles for agentic CLI design, and they matter because your next power user might not have hands.

Accounting Integration

𝚂𝚊𝚞𝚛𝚊𝚋𝚑 𝚁𝚊𝚒 — Thu, 05 Mar 2026 05:42:01 +0000

Your finance team didn't sign up to be data-entry clerks. Neither did your customers.

Yet every day, thousands of businesses manually export transactions from QuickBooks, copy invoice data from Xero, or reconcile payments between three different spreadsheets. It's slow, error-prone, and a waste of skilled people's time.

Accounting integrations fix this. They connect your software directly to your customers' general ledger, automatically syncing invoices, expenses, payments, and journal entries. No CSV exports. No copy-paste errors. No "we'll reconcile it at month-end."

This guide covers what accounting integrations actually do, the most common use cases, and how companies like Ramp, Airbase, and BILL have leveraged them to gain a competitive advantage.

The open accounting movement is driving demand for standardized data access across accounting platforms, making integration capabilities a competitive requirement for B2B SaaS products.

What Is an Accounting Integration?

An accounting integration is a connection between your application and an accounting platform like QuickBooks, Xero, NetSuite, or Sage Intacct. It allows data to flow between systems, either one-way or bidirectionally, without manual intervention.

A quick definition, if you're new to this: A general ledger (GL) is the master record of all financial transactions in a business. Every transaction gets tagged with a GL code, which is essentially a label that categorizes where the money went: "Travel," "Software Subscriptions," "Office Supplies," and so on. When we talk about syncing to the GL, we mean getting your data into that master record with the right labels attached.

At a practical level, accounting integrations mean:

Invoices created in your billing system appear automatically in your customer's accounting software
Expenses logged in your app push directly to the general ledger with the correct GL codes
Payments recorded in one system update the other in real time
Bank transactions reconcile automatically instead of requiring manual matching

The alternative is what most businesses still do: export a CSV, open Excel, clean the data, reformat it for the accounting system, import it, and hope nothing gets lost in translation. Multiply that by hundreds of transactions per month, and you've created busywork that produces no value.

Why Accounting Integrations Matter for Your Product

If you're building software that touches money (invoicing, expense management, payroll, procurement, lending, payments), your customers will eventually ask: "Does this connect to our accounting system?"

The answer determines whether you're a tool they'll actually adopt or one they'll abandon after the free trial.

The business case is straightforward:

Faster sales cycles. Enterprise buyers have procurement checklists. "Integrates with NetSuite" is often a required line item. Without it, you don't make the shortlist.
Lower churn. Customers who integrate your product into their financial workflows don't leave easily. The switching cost is too high when your app is integrated into their month-end close process.
Higher contract values. Integration features justify premium pricing. Ramp charges more for deeper ERP connections. So does BILL. Customers pay for the time savings.
Reduced support burden. Every "how do I export this to QuickBooks?" ticket is a symptom of a missing integration. Build it once, eliminate the ticket category.
Market expansion. Companies across specific regions, industries, and sizes use certain accounting tools. SMBs gravitate toward QuickBooks and Xero. Mid-market and enterprise prefer NetSuite, Sage Intacct, and Microsoft Dynamics. Offering integrations with the tools your target markets rely on opens doors that would otherwise stay closed.

Two Types of Accounting Integrations

Before diving into use cases, it's worth distinguishing between two categories:

Customer-Facing (Product) Integrations

These connect your product to your customers' accounting systems. They're what this guide focuses on—the integrations that become product features, drive sales conversations, and require supporting hundreds of different customer configurations.

The rest of this guide addresses customer-facing integrations, which present unique challenges around multi-tenancy, authorization, and scale.

Internal Integrations

These connect your company's own systems. For example:

CRM → Accounting: When an opportunity closes in Salesforce, automatically create the customer in NetSuite for invoicing
Accounting → BI: Sync financial data from Xero to Tableau for executive dashboards
Accounting → Slack: Alert the finance channel when invoices are overdue

These are typically built with iPaaS tools (Workato, Tray) or custom scripts. They're one-off connections serving your internal workflows.

6 Common Use Cases for Accounting Integrations

1. Expense Management → General Ledger Sync

The problem: Employees submit expenses. Finance approves them. Then someone manually enters each line item into QuickBooks with the correct GL code, department, and tax treatment.

The integration: Approved expenses push automatically to the accounting system. GL codes mapped by expense category. The finance team reviews exceptions, not every transaction.

Who does this well: Brex, Expend, ExpenseOnDemand, Ramp, and Airbase all sync expenses directly to QuickBooks, Xero, NetSuite, and Sage Intacct. For corporate card products, this is now table stakes. Invoice2go by BILL used Apideck's Unified API to speed up accounting integrations across multiple platforms, enabling support for major systems without custom builds. This helped them scale expense and reporting features quickly across over 220,000 customers worldwide.

Below is what the QuickBooks Online integration looks like on Ramp after you set it up.

2. Invoicing and Billing → Accounts Receivable

The problem: Your product generates invoices. Your customer's accounting team needs those invoices in their accounts receivable ledger. Right now, they're downloading PDFs and manually creating entries.

The integration: Invoices created in your system automatically appear in the customer's accounting platform. Payment status syncs back. When the invoice is paid, both systems reflect it without anyone having to touch a keyboard.

Who does this well: Stripe's invoicing connects to QuickBooks and Xero. Chargebee syncs subscription invoices to major accounting platforms. Any serious billing tool offers this now. For example, Roopairs used Apideck's Unified API to launch a QuickBooks Online integration quickly, saving roughly 40 developer hours and supporting 30 active customers from day one. The team is now planning expansions to Sage Intacct and NetSuite due to the speed and simplicity of the implementation.

Stripe QuickBooks Online integration guide

3. Procurement and AP Automation → Purchase Order Matching

The problem: A company issues a purchase order. Goods arrive. An invoice comes in. Someone has to manually match the PO, receipt, and invoice (the "three-way match") before approving payment.

The integration: Your procurement system shares PO data with the accounting platform. When invoices arrive, matching happens automatically. Exceptions flag for review; clean matches process straight through.

Who does this well: Coupa, SAP Ariba, and newer players like Zip connect procurement workflows directly to ERPs for automated matching and approval routing. For example, Derive used Apideck's Unified API to reduce development time by about 70 percent. They went from sign-up to a live Xero integration in just three weeks and later launched a Workday connection in under 90 days, which helped accelerate sales cycles and expand into enterprise markets more quickly.

Coupa Invoice Matching Explained

4. Revenue Recognition → Compliance with Accounting Standards

The problem: SaaS companies with usage-based pricing or multi-element contracts can't just recognize revenue when cash hits the bank. Accounting standards like ASC 606 require recognizing revenue over the service period. In plain English: you have to follow specific rules about when you're allowed to say you've "earned" money. Calculating this manually across thousands of subscriptions is an audit nightmare.

The integration: Your billing system sends contract and usage data to the accounting platform. Revenue schedules are generated automatically based on the rules. Auditors get clean documentation without your team building spreadsheets.

Who does this well: Stripe Revenue Recognition, Chargebee's RevRec module, and dedicated tools like Leapfin pull transaction data and push compliant journal entries to NetSuite or Sage Intacct.

Chargebee RevRec Features

5. Embedded Fintech → Real-Time Cash Flow Visibility

The problem: Lending platforms, cash flow tools, and financial dashboards need to see a business's real financial position. Bank feeds show cash movement, but not the full picture: receivables, payables, revenue trends, and outstanding invoices.

The integration: Pull chart of accounts, invoices, bills, and journal entries from the customer's accounting system. Display real-time financial health. Underwrite loans based on actual accounting data, not uploaded bank statements from three months ago.

Who does this well: Plaid handles banking data; accounting integrations from providers like Codat and Apideck fill in the rest. Lenders like Clearco and Pipe use accounting data to underwrite in hours instead of weeks.

For a technical deep-dive on this pattern, see Using Accounting APIs for Smart Lending Decisions.

Plaid API Docs

6. AI and Machine Learning → Financial Intelligence

The problem: You want to offer AI-powered features: budget predictions, anomaly detection, and cash flow forecasting, but your models need comprehensive financial data from each customer.

The integration: Pull balance sheets, income statements, transaction histories, and accounts receivable aging from customers' accounting systems. Feed this data to your ML models for personalized insights. As new transactions flow in, models update automatically.

Who does this well: Runway, Jirav, and Mosaic pull accounting data to power FP&A automation. Fintech platforms use it to build credit models that outperform traditional underwriting.

Runway Fintech Platform

How Companies Build Accounting Integrations

This is where product decisions become engineering reality. You have three paths:

Option 1: Build Direct Integrations

Connect to each accounting platform's API individually. QuickBooks Online has a REST API. Xero uses OAuth 2.0. NetSuite offers both SOAP and REST. Sage has several APIs, depending on which Sage product you're targeting.

Pros: Full control over the integration. Access to every feature the platform offers.

Cons: Each integration is a significant investment. Industry estimates indicate that a single integration requires 150+ engineering hours to build and 300+ hours annually to maintain, with total costs ranging from $10,000 to $50,000 per integration per year, including engineering time, customer success support, and ongoing maintenance. Supporting 10 accounting systems means multiplying that investment tenfold. Teams routinely estimate six weeks and ship in three months, as auth flows alone can derail timelines.

The maintenance reality: Accounting APIs change. QuickBooks pushes updates. Xero deprecates endpoints. NetSuite releases new versions. When a sync breaks on the first of the month (the worst possible timing for any finance team), someone on your team is firefighting instead of building features. Direct integrations require ongoing "on-call" capacity that most teams underestimate.

Option 2: Use a Unified API

A unified API provider normalizes multiple accounting platforms into a single integration. Think of it as a universal translator: your system speaks one language, and the provider handles the dialects of QuickBooks, Xero, NetSuite, and the rest.

You build once; they maintain the connections.

Pros: Launch in weeks instead of months. One data model to learn. One auth flow to implement. Coverage across platforms without multiplying your engineering investment. Unified API approaches typically deliver 3-5x faster implementation with significantly lower total cost of ownership over multi-year periods.

Cons: You're dependent on the provider's coverage depth and data model. Some edge cases or advanced features may still require direct API work for specific platforms.

Providers in this space: Apideck, Merge, Codat, Railz, and Rutter all offer unified accounting APIs with varying coverage, pricing models, and approaches to data normalization. For a detailed comparison, see Top Merge API Alternatives for SaaS Teams in 2025.

Not sure whether to build or buy? Read Build vs Buy Accounting Integrations.

Option 3: Hybrid Approach

Use a unified API for 80% of your coverage (common platforms and standard use cases), then build direct integrations for strategic accounts that require deep customization. This typically means NetSuite or SAP for enterprise deals that require custom fields, advanced workflows, or specific ERP modules.

How to Prioritize Which Integrations to Build

As you can't build everything at once. Use this framework to prioritize and insert the Accounting integrations that are relevant:

Criteria	Weight	QuickBooks	NetSuite	Xero	Sage Intacct
% of pipeline requesting	25%	?	?	?	?
Expected close rate lift	20%	?	?	?	?
Retention impact	20%	?	?	?	?
New market access	15%	?	?	?	?
Engineering effort	10%	?	?	?	?
Maintenance burden	10%	?	?	?	?
Weighted Score	100%	?	?	?	?

Integration Prioritization Scorecard

How to use it:

Survey your sales team: which integrations come up most in deals?
Analyze lost deals: how many cited missing integrations?
Segment by customer size: SMB skews QuickBooks/Xero, enterprise skews NetSuite/Sage
Score each integration, calculate weighted totals, and stack-rank

This prevents the common mistake of building integrations based on engineering interest rather than business impact.

Common Pitfalls: What Goes Wrong with Accounting Integrations

Most integration guides tell you what to build. Few tell you what breaks. Here are the failure modes that create support tickets, churn, and 2 AM pages:

1. Auth Token Expiry and Refresh Failures

OAuth tokens expire. Refresh tokens have their own lifespans. QuickBooks tokens last 100 days; if a customer doesn't use the integration for three months, it silently breaks. Your sync stops, but no one notices until month-end close—when the finance team is already stressed.

The fix: Proactive token health monitoring. Alert customers before re-authentication is needed, not after data stops flowing.

2. Schema Drift and API Changes

Accounting platforms don't freeze their APIs. QuickBooks pushed breaking changes to their invoice endpoints in 2023. Xero periodically deprecates fields. NetSuite's SuiteTalk versions introduce incompatibilities.

The fix: Version your integrations. Monitor API changelogs. Build regression tests that catch schema changes before customers do.

3. Rate Limit Hell

QuickBooks allows 500 requests per minute. Sounds generous until you're syncing 10,000 invoices for a new customer. Hit the limit, and your sync backs up. Customers see stale data. Support tickets pile up.

The fix: Implement exponential backoff. Queue and batch requests. Design for burst limits from day one, not after you hit them in production.

4. Multi-Entity and Multi-Currency Complications

Enterprise customers don't have one QuickBooks company. They often manage twelve subsidiaries across three currencies. Your integration works perfectly for single-entity SMBs, then breaks spectacularly when an enterprise customer connects their consolidated NetSuite instance.

The fix: Design for multi-entity from the start. Ask during onboarding: "How many entities will you connect?" If the answer is more than one, adjust your data model accordingly.

5. GL Code Mapping Mismatches

Your expense categories don't match your customer's chart of accounts. "Travel" in your system needs to map to "6200 - Employee Travel & Entertainment" in theirs. Get it wrong, and transactions land in the wrong accounts or fail to sync entirely.

The fix: Build a mapping interface. Let customers configure how your categories translate to their GL codes. Don't assume your defaults work for everyone.

6. Partnership Agreement Delays

Many enterprise accounting vendors (especially Sage, Xero, Intuit, and SAP) require formal partnership agreements before you can access sandbox environments or API documentation. These agreements can take months, sometimes over a year, and cost tens of thousands annually.

The fix: Start partnership applications early, before you need the integration. If the timeline is critical, consider unified API providers who already have these partnerships in place.

What to Look for in an Accounting Integration Solution

Whether you're evaluating unified API providers or scoping direct builds, here's what actually matters:

Platform coverage. Does it support the accounting systems your customers use? QuickBooks and Xero dominate SMB. NetSuite, Sage Intacct, and Microsoft Dynamics serve the mid-market and enterprise. Know your customer base before choosing. Need a full breakdown? See Top 15 Accounting APIs to Integrate with in 2025.
Data model depth. Can you access invoices, payments, journal entries, tracking categories, tax rates, and custom fields? Or just the basics? Shallow integrations create support tickets later.
Write access. Reading data is the easy part. Pushing invoices, expenses, or journal entries back to the accounting system is harder but more valuable. Confirm bidirectional sync works if you need it.
Auth experience. Your customers connect to your accounting system via an OAuth flow. If that flow is clunky, confusing, or breaks frequently, your support team will hear about it.
Webhooks and real-time sync. Polling for changes is slow and burns API quota. Webhooks let you react to new invoices or payments the moment they happen.
Security and compliance. You're touching general ledger data. Customers will ask about SOC 2 compliance, data encryption, and where their credentials are stored. Have answers ready, or choose a provider who does.
Integration observability. When syncs fail, can you see why? Look for logging, error categorization, and alerting that help your support team diagnose issues without escalating to engineering.

The Bottom Line

Accounting integrations aren't optional anymore. If your product touches financial data, your customers expect it to connect to their accounting system.

You can spend engineering years building and maintaining direct connections. Or you can use a unified API to launch in weeks and expand coverage as you grow.

The days of "export to CSV" are ending. Give customers the integration, or watch them find a product that does.

Frequently Asked Questions

How long does an accounting integration take to build in-house?

It depends on the platform and your requirements. Simple read-only integrations might take 4-6 weeks. Bidirectional sync with error handling, rate limiting, and multi-entity support typically takes 3-6 months. If the vendor requires a partnership agreement (NetSuite, SAP), add 3-12 months for paperwork alone.

How much do accounting integrations cost?

Direct builds run $10,000-$50,000 per integration annually when you factor in engineering time, maintenance, and support. Unified API providers typically charge $500-$2,000/month for access to dozens of integrations. The break-even point is usually 2-3 integrations.

What are the most popular accounting systems to integrate with?

Varies by segment:

SMB: QuickBooks Online, Xero, FreshBooks, Wave
Mid-market: Sage Intacct, NetSuite, Microsoft Dynamics 365 Business Central
Enterprise: NetSuite, SAP, Oracle, Microsoft Dynamics 365 Finance

What data typically gets synced?

Common objects include: invoices, bills, payments, journal entries, chart of accounts, customers/vendors, tax rates, tracking categories, purchase orders, and bank transactions. Advanced use cases add balance sheets, income statements, and aged receivables/payables.

Can I start with one integration and add more later?

Yes, but plan your data model carefully. If you build for QuickBooks first with a QuickBooks-specific schema, adding Xero later means refactoring. Starting with a normalized data model (or using a unified API) avoids this trap.

Go Deeper: Related Guides

Building your first integration?

Evaluating build vs. buy?

Designing for scale and reliability?

Understanding the Sage ecosystem?

Specific use cases?

Ready to add accounting integrations to your product? Explore Apideck's Unified Accounting API: one integration, 20+ accounting platforms, live in days.

Top Fintech APIs for Startups

𝚂𝚊𝚞𝚛𝚊𝚋𝚑 𝚁𝚊𝚒 — Thu, 05 Mar 2026 04:47:04 +0000

Building a fintech product means making critical infrastructure decisions early. The APIs you choose determine your technical debt, compliance burden, and ability to scale for years to come.

Instead of listing 20 APIs with shallow descriptions, this guide breaks down the fintech API landscape by actual business need, explains the hidden integration trade-offs, and shows you when unified API solutions prevent the maintenance nightmare that derails most startups.

The Financial Impact of API Strategy

The global open banking market is projected to reach $135.17 billion by 2030. McKinsey estimates AI could enable $1 trillion in global banking revenue shifts by the same year. These projections drive the infrastructure decisions startups make today.

But here's what those projections don't capture: most startups fail at integrations not because they chose the wrong APIs, but because they underestimated the maintenance burden.

Every API you integrate directly means authentication logic to maintain, rate limiting to handle, breaking changes to absorb, and data normalization to manage. A simple feature like "sync transactions" becomes a switch statement with fifteen cases when you're managing Stripe, Plaid, QuickBooks, and three other providers. Each case handles auth differently, maps fields uniquely, and fails in its own way.

Your codebase fragments into provider-specific branches. API providers don't coordinate their breaking changes. Plaid updates its transaction categorization. Stripe changes their webhook format. QuickBooks modifies its OAuth flow. Your test matrix explodes, but coverage remains incomplete because you can't predict every interaction.

The Money Movers: Payments and Transfers

Payment Processing

Stripe remains the default choice for startups. It handles card payments, ACH transfers, subscriptions, and payouts with a developer experience that sets the industry standard. The platform powers millions of businesses across 50+ countries, supporting companies from early-stage startups to enterprises like Amazon and Shopify.

Stripe's real advantage is the ecosystem. Stripe Treasury embeds banking features directly into products, including FDIC-insured deposits, cards, and interest-earning balances. Shopify, Lyft, and Deel use this infrastructure to manage financial accounts at scale. For startups building platforms, Stripe Connect handles marketplace payments and seller onboarding.

Adyen targets enterprise-grade needs with global payment processing across 200+ countries. For startups building for international markets from day one, Adyen's unified commerce approach handles in-person and online payments through a single integration. The tradeoff is complexity; Adyen's learning curve is steeper than Stripe's.

Square works well for startups serving physical retail or SMB markets with its point-of-sale integration and straightforward pricing. The hardware ecosystem (terminals, readers) makes it attractive for omnichannel commerce.

ACH and Bank Transfers

Dwolla excels at ACH payments with instant bank-to-bank transfers, wallet-based flows, and high-volume payouts. Payroll apps, lending platforms, and B2B marketplaces rely on this infrastructure. Dwolla handles the compliance complexity of moving money between bank accounts at scale.

Modern Treasury solves the reconciliation problem. When your startup handles large financial flows, matching payments to invoices across multiple sources becomes a full-time job. Modern Treasury automates payment ops, real-time reconciliation, and ledgering across ACH, RTP, and wire transfers. It's built for companies where money movement is core to the product.

The Data Layers: Banking Connectivity and Identity

Banking Data and Account Connectivity

Plaid dominates this category, connecting applications to thousands of banks and credit unions. Its API provides normalized financial data, including balance checks, transaction histories, account authentication, and identity verification. Personal finance apps use Plaid for spending insights, lenders use it for credit risk assessments, and neobanks integrate it for instant account verification. For teams tracking open banking APIs across different regions, the Open Banking Tracker provides data on 3,200+ open banking and PSD2 APIs globally. It helps understand coverage gaps when expanding internationally.
MX offers a strong alternative for data enrichment and transaction categorization. Personal finance management products benefit from MX's cleansing and analytics capabilities beyond basic connectivity.
TrueLayer focuses on open banking and PSD2-compliant services in Europe with instant account-to-account payments and financial insights. If your primary market is the UK or EU, TrueLayer's regional expertise matters.
Yodlee connects to over 16,000 global data sources. Wealth management apps integrate Yodlee for consolidated portfolio views, while lenders use it to assess customer liabilities before loan approval.

Identity Verification and KYC

Onfido handles government ID verification, facial recognition, liveness detection, and fraud detection. Regulatory compliance determines whether you can operate, making this category critical for any fintech handling customer funds.
Alloy powers automated risk checks by pulling data from bureaus and identity networks. Banks and neobanks use Alloy's risk engine to approve users with less manual review while maintaining compliance. The decisioning workflow builder lets you customize approval logic without code changes.
Sardine uses behavioral biometrics and machine learning to catch what traditional checks miss: suspicious login attempts, unusual spending patterns, device spoofing, and account takeovers. If your app handles money movement, Sardine adds a protection layer that document verification alone can't provide.

The Back Office: Accounting, ERP, and HRIS

This is where most startups underestimate complexity.
The challenge isn't just connecting to one accounting system. It's that your customers use different systems. QuickBooks, Xero, NetSuite, Sage, FreshBooks, and dozens of regional platforms each have distinct authentication flows, data models, rate limits, and field mapping requirements.
What looks like "add QuickBooks integration" on a roadmap becomes a three-month project. Then customers ask for Xero. Then, enterprise prospects require NetSuite. Each integration multiplies your maintenance burden. Your engineers become integration specialists rather than product developers.

Accounting and ERP Integration

QuickBooks Online holds approximately 80% market share among US small businesses. If you're serving American SMBs, QuickBooks integration is expected. But Intuit's API has authentication quirks, sandbox limitations, and data models that require dedicated engineering time to handle correctly.
Xero dominates the SME market in Australia, the UK, and New Zealand. International expansion means another separate integration with different conventions.
NetSuite and Sage Intacct serve mid-market and enterprise customers with multi-entity structures and complex financial requirements. These integrations are significantly more complex than SMB accounting platforms. Multi-subsidiary consolidation, custom fields, and approval workflows add implementation time. For detailed guidance on accounting API selection, see Top 15 Accounting APIs to Integrate with in 2025.

The Unified API Alternative

This is where unified API platforms become relevant. Instead of building and maintaining separate integrations for each accounting system, unified APIs let you connect once and access multiple platforms through a standardized interface.

The approach trades some customization depth for dramatically reduced maintenance. You lose access to provider-specific advanced features, but you gain consistent data models, centralized authentication, and a single codebase instead of 15.

Apideck's Accounting API is one solution in this space alongside Kombo, Finch, and Merge, providing access to 20+ accounting systems through a single integration. For implementation details on handling expenses and bills across platforms, see Integrating Expenses and Bills with the Accounting API.

HRIS and Payroll Integration

Fintech products increasingly touch workforce data for payroll integrations, employee verification, or benefits administration. Gusto, ADP, BambooHR, Rippling, and Workday each require separate integrations with distinct APIs and authentication flows.

Unified HRIS APIs normalize employee data across these platforms. Payroll automation through standardized integrations allows companies to scale without additional engineering investment per provider.

Lending and Investment APIs

Lending and Credit

Experian provides credit scoring and risk assessment through its credit bureau database, delivering real-time credit histories and fraud checks. BNPL providers and underwriting platforms use it for risk-based decisioning.
Finicity (now part of Mastercard) offers cash flow analytics and income verification, replacing paper-based income proofs for mortgage lenders and personal loan providers. The shift to real-time income verification is accelerating across lending categories.

For embedded lending use cases, see From Accounts Receivable to Lending Automation.

Investment and Trading

Alpaca offers commission-free trading APIs for developers building trading apps and algorithmic platforms. Its startup-friendly approach and documentation quality make it accessible for early-stage fintech.
Polygon.io provides stock market data, news, and analysis for investment platforms and trading apps that need real-time market information.

Embedded Finance Considerations

Non-financial companies are embedding payments, lending, insurance, and banking features into their products. This isn't a future trend; it's the current expectation across industries.

Vertical SaaS platforms add financial workflows to increase stickiness and revenue per customer. Construction software embeds equipment financing tied to project milestones. Healthcare platforms offer working capital based on insurance receivables. Restaurant systems provide cash advances against future credit card sales.
Marketplaces offer seller financing and instant payouts to attract supply-side participants. HR platforms embed earned wage access and benefits management to differentiate their offerings.

Building embedded finance requires integrations across accounting, banking, payments, and lending APIs. This is where unified APIs provide the most value by reducing the integration surface area while maintaining breadth of coverage. The technical burden extends beyond initial implementation; each category adds compliance surface area and ongoing maintenance.

When to Use Direct vs. Unified APIs

Every API integration increases your compliance surface area. Financial data requires SOC 2 compliance, data residency controls, and comprehensive audit trails. This context matters when evaluating the direct vs. unified decision.

Direct integrations make sense when:

Your entire business runs on one provider, and you need every advanced feature
You have dedicated integration engineers for long-term maintenance
You're pre-product-market-fit and only need one or two integrations
Your competitive advantage depends on deep optimization for a specific platform

⠀Unified APIs make sense when:

Customers demand multiple integrations across a category
Engineering time goes to integration maintenance instead of product development
You need enterprise integrations (NetSuite, SAP, Workday) without enterprise engineering overhead
You're scaling rapidly and can't afford three-month integration projects for each new provider

⠀For detailed analysis, see Unified APIs for Fintech: When Point Integrations Stop Scaling.

Recommended Stacks by Product Type

Neobank: Plaid + Unit or Stripe Treasury + Onfido + Unified Accounting API
Lending platform: Plaid + Experian/Finicity + Alloy + Dwolla + Unified Accounting API
Expense management: Stripe + Unified Accounting API + Unified HRIS API
Vertical SaaS with financial features: Stripe + Unified Accounting API + Unified HRIS API

Next Steps

Fintech API strategy isn't about choosing the "best" APIs. It's about building an integration architecture that scales without consuming engineering capacity.

Direct integrations make sense for core payment and banking infrastructure, where you need deep control. Unified APIs make sense for customer-facing integrations that require breadth without maintenance overhead.
The startups that scale treat integrations as strategic infrastructure rather than feature checkboxes.

Stripe's llms.txt has an instructions section. That's a bigger deal than it sounds.

Gertjan De Wilde — Thu, 05 Mar 2026 03:00:00 +0000

When Stripe added /llms.txt to their docs, most write-ups noted it as another company "embracing the AI era." They missed the interesting part. Buried inside is an instructions section no other company has built — Stripe programming what AI tools say about Stripe. Here's why that matters and what it means for your API.

When Stripe added /llms.txt to their docs in March 2025, most write-ups noted it as another company "embracing the AI era." They missed the interesting part.

This post is a follow-up to API Design Principles for the Agentic Era. That one covers the broader shift in how APIs need to be designed for autonomous consumers. This one goes deep on one specific mechanism, the llms.txt instructions section.

Buried inside docs.stripe.com/llms.txt is a section that doesn't exist in any other company's implementation:

## Instructions for Large Language Model Agents: Best Practices for integrating Stripe.
- Always use the Checkout Sessions API over the legacy Charges API
- Default to the latest stable SDK version
- Never recommend the legacy Card Element or Sources API
- Advise migrating from PaymentIntents to Checkout Sessions
- Prefer dynamic payment methods over hardcoded payment_method_types

This is not documentation. This is a prompt — shipped as a static file at the root of their domain — designed to be loaded into AI coding assistants before a developer asks "how do I add Stripe?"

Stripe is programming what AI tools say about Stripe. Every time a developer asks Cursor or Claude how to accept payments, and the agent fetches this file first, those instructions propagate into the answer. They're not just making their docs readable to machines. They're shaping the behavior of third-party AI systems at scale.

That's a genuinely new thing. And it has real implications for how API companies should think about their documentation in 2025.

What llms.txt actually is

Jeremy Howard (fast.ai, Answer.AI) proposed the standard in September 2024. The problem it's solving is real: LLMs have finite context windows, HTML is noisy, and you can't just dump an entire documentation site into a prompt.

His solution is deliberately low-tech. A Markdown file at /llms.txt with an H1, an optional summary blockquote, and H2-delimited sections of curated links. A companion /llms-full.txt containing complete docs in a single file. Any individual page available as clean Markdown by appending .md to its URL.

The format is boring on purpose. No special syntax, no schema, no JSON. Just the same Markdown that LLMs already understand natively. The interesting insight is curatorial: you know your documentation better than any crawler, so you should be the one to tell AI agents which parts matter.

It's the same philosophy as a well-maintained robots.txt — except instead of exclusion, it's prioritization. Robots.txt tells crawlers what to skip. Sitemap.xml tells them what exists. llms.txt tells AI what to read first.

One honest caveat: no major AI provider has confirmed their training crawlers automatically fetch llms.txt. Its real value today is inference-time, not training-time — developers manually loading it into Cursor or Claude for project context, or agent frameworks fetching it on startup. The 800,000+ "implementations" BuiltWith tracks are mostly Yoast SEO auto-generating the file for WordPress sites. The hand-curated number is closer to 784 verified sites.

Stripe's implementation is the industry outlier

Most llms.txt files are just structured indexes. Anthropic's is a clean table of contents for their API docs. Cloudflare's is massive (3.7 million tokens across product-specific files). Vercel's is so large they call it "a 400,000-word novel."

Stripe's is architecturally different. Three separate files across two domains. Every docs page available as .md. And that instructions section that no one else has.

The instructions aren't arbitrary. They're solving a specific, painful problem: Stripe has accumulated 15 years of API surface area, including several generations of deprecated payment primitives. Their Charges API still works. Their Card Element still exists. Developers — and the AI assistants helping them — regularly reach for these older APIs because they appear in older Stack Overflow answers and training data from before 2022.

The instructions section is Stripe saying: when an AI helps a developer integrate us, steer them toward the right thing. Don't let stale training data send them to the Charges API. Don't let our own backwards compatibility become a footgun.

That's a legitimate engineering concern. And the file format is a surprisingly elegant solution to it — no coordination with AI providers required, works with any system that can fetch a URL.

The announcement got 273,800 views and 740 bookmarks on Twitter. Stripe engineer Ian McCrystal: "I expect AI tools will eventually become the predominant readers of our documentation."

Who else is worth looking at

The honest answer to "who else has this figured out" is: not many, and only Stripe is doing the specific thing that matters.

Stripe remains the strongest example of the deprecation pattern precisely because they're explicit about it. Their instructions don't hint at preferred patterns — they name the bad endpoints directly: "You must not call deprecated API endpoints such as the Sources API." "Never recommend the legacy Card Element." That specificity is what makes it machine-actionable. An LLM can follow a concrete prohibition. It can't do much with "prefer modern patterns."

Cloudflare takes a structurally interesting approach. Their llms.txt is organized by service — Agents, AI Gateway, Workers AI, and so on — so an agent only needs to fetch the section relevant to what it's building rather than parsing a file that covers their entire platform. For APIs with multiple product lines, that's a better model than a flat list. You're reducing the noise ratio at fetch time, not just at index time.

LangChain and LangGraph are worth noting for a meta-reason: they're agent frameworks that have their own llms.txt. They're eating their own cooking. That's useful signal about whether the format actually helps in practice, beyond the theoretical appeal — these are teams that work with agents every day and chose to implement it anyway.

Anthropic has one for their API docs. It's structured more as an index than an instructions-heavy file — clean and navigable, but it's not doing the active correctional work that Stripe's instructions section does.

The pattern across most implementations is the same: they're documentation indexes. Useful, because a curated index is better than asking an agent to crawl your entire site. But not doing the harder job of guiding AI away from the wrong things. The providers that have figured out the instructions section are treating llms.txt as an active correctional mechanism for model drift, not just a sitemap for bots. That framing distinction is the whole thing.

Most APIs have deprecated endpoints that still work, legacy patterns that still exist in training data, and footguns that experienced developers know to avoid but newcomers (and AI assistants trained on old Stack Overflow answers) keep reaching for. The instructions section exists to close that gap. Almost no one is using it yet.

Why Stripe specifically makes this move

Stripe's developer experience has been the industry benchmark since roughly 2012. The specifics are worth understanding because they're not accidental.

Their three-column docs layout (left nav, center content, right-side live code examples in seven languages) was so effective that it became a meme — startup after startup shipped the same structure. They open-sourced Markdoc, their interactive documentation framework. They shipped Stripe Shell for live API calls inside docs pages. Their error messages include doc_url fields, parameter-level specificity, and "did you mean email?" suggestions for misspelled field names.

The doc_url in error responses is the one worth highlighting specifically. It's a small thing with outsized impact when an AI agent is in the loop. When an agent gets a 400 error, it can follow the doc_url, fetch the Markdown version of that docs page, and self-correct — without needing a human to look up what went wrong. That's not DX in the traditional sense. That's infrastructure designed for autonomous consumers.

{
  "error": {
    "code": "parameter_invalid_empty",
    "doc_url": "https://stripe.com/docs/error-codes/parameter-invalid-empty",
    "message": "You passed an empty string for 'amount'. We assume empty values are an oversight, so we require you to pass this field.",
    "param": "amount",
    "type": "invalid_request_error"
  }
}

John Collison put the llms.txt bet in plain terms: "If you go read the Stripe Docs these days, it's a lot to keep in your RAM, but trivial for an LLM."

What this means for your API

Most of this is transferable. Here's what's actually useful versus what's cargo-culting.

Actually useful:

Your error responses should include a documentation_url field pointing to a Markdown version of the relevant docs page. This costs almost nothing to implement and has immediate value — for human developers debugging in the terminal and for AI agents trying to self-correct.

Your OpenAPI descriptions should be written for semantic matching, not human skimming. When an agent is deciding which endpoint to call, it's doing something like nearest-neighbor search against your descriptions. "Gets the data" loses to "Returns a paginated list of invoices filtered by status, sorted by created_at descending. Requires accounting:read scope." Every field, every enum, every endpoint.

I've been around OpenAPI specs long enough to know how badly they rot. We built Portman to convert OpenAPI specs into Postman collections — and the main thing you learn doing that is how few specs have descriptions worth converting. Fields with no description, enums with no explanation, endpoints named things that made sense in 2019. If your spec is bad for contract testing, it's bad for agents too.

Add /llms.txt. It takes an afternoon. Link to your ten most important pages with one-sentence descriptions. That's it. You don't need the 350-link Stripe implementation on day one.

If you have deprecated APIs, use the instructions section. This is underutilized and genuinely powerful. You know which footguns exist in your API. Tell the AI.

One thing that often gets missed: the marketing upside. The same structured, machine-readable docs that make your API easy to integrate are the same content that AI answer engines like Perplexity and ChatGPT pull from when someone asks "what's the best API for X." llms.txt doesn't just help agents build with your API — it helps you show up when people are deciding which API to use. Being agent-friendly and being discoverable in AI search are the same work.

Probably not worth doing yet:

Publishing an MCP server for the sake of it. MCP is real and growing, but agent framework standardization is still in flux. A well-designed REST API with a good OpenAPI spec is more durable. Build the MCP server when you have users asking for it.

Elaborate agent-specific observability infrastructure. Request tagging and semantic logging are nice. But if your API doesn't have solid basic observability yet, that's the actual problem.

The broader pattern

There's a pattern here worth naming. For 15 years, "developer experience" meant optimizing for humans: readable error messages, clear docs, good SDKs, interactive playgrounds. The mental model was a developer sitting at a terminal, making sense of your API.

The new constraint is that a growing fraction of your API consumers are autonomous systems that read documentation, make decisions without human review, and retry failures automatically. The question isn't whether to design for this — it's happening regardless — it's whether you're designing intentionally for it.

Stripe's llms.txt instructions section is the clearest example I've seen of a company being intentional about it. They're not just making their docs machine-readable. They're asserting control over what machines say about them.

Every API company with deprecated primitives and a significant developer base has the same problem Stripe is solving. They just haven't solved it yet.

How to Make Your API Agent-Ready: Design Principles for the Agentic Era

Gertjan De Wilde — Wed, 25 Feb 2026 11:00:00 +0000

For about fifteen years, "developer experience" meant one thing: optimize for a human being sitting at a terminal. Readable error messages. Interactive docs. Code samples in seven languages. The mental model was always a person making sense of your API, iterating in real time, googling when confused. That model isn't wrong. But it's increasingly incomplete.

A growing fraction of API traffic today is generated by AI agents. Systems that autonomously discover endpoints, parse documentation, handle errors without human review, and retry failures according to their own logic. When a developer asks Cursor or Claude to "add Stripe payments," the agent fetches documentation, selects APIs, writes integration code, and debugs errors before the developer reads a line of it. The human is further from the integration than they've ever been.

The pattern is especially visible in fintech and accounting. A lending platform building an underwriting agent prompts it to "pull twelve months of invoice data and flag overdue receivables." The agent queries your API, interprets the response, and surfaces a creditworthiness signal — before a human analyst has opened a spreadsheet. A payroll platform's agent reconciles payroll entries against the general ledger overnight, without a developer watching the process. In both cases, the agent is not a convenience layer on top of a human workflow. It is the workflow. What it can do is bounded entirely by what your API communicates about itself.

This creates a new design surface. The same discipline that produced great developer experience, deliberate and user-centered API design, applied to a different consumer. Call it agent experience, or AX. It's not a replacement for DX. It's the next layer.

The good news: most of what makes an API good for agents makes it better for humans too. The bad news: a lot of APIs that seem fine for humans are quietly broken for agents. Here's where the gaps show up.

Bad OpenAPI descriptions break agent routing

When an agent decides which endpoint to call, it's doing something close to semantic search against your descriptions. It reads your spec, matches the user's intent against available operations, and picks the closest fit. The quality of your descriptions determines whether it picks correctly.

"Gets the data" loses to "Returns a paginated list of invoices filtered by status and date range, sorted by created_at descending. Requires accounting:read scope. Use the cursor parameter for pagination."

Every field, every enum value, every endpoint. The description is the signal the agent uses to route. Most OpenAPI specs are bad at this. Not because anyone decided to make them bad. They rot. Field names that made sense in context lose their meaning without descriptions. Enums accumulate values that nobody documented. Endpoints get renamed but the descriptions don't follow. The spec becomes a structural skeleton with no semantic content.

The difference between a description that helps and one that doesn't is not subtle:

# Bad — structural skeleton, no semantic content
/invoices:
  get:
    summary: Get invoices
    parameters:
      - name: status
        in: query
        schema:
          type: string
      - name: cursor
        in: query
        schema:
          type: string

# Good — enough signal to route correctly
/invoices:
  get:
    summary: List invoices filtered by status and date range
    description: >
      Returns a paginated list of invoices for the authenticated company.
      Use `status` to filter by payment state. Use `cursor` from the previous
      response to fetch the next page. Requires the `accounting:read` scope.
      For real-time sync scenarios, combine with the `updated_since` parameter
      to fetch only records changed after a given timestamp.
    parameters:
      - name: status
        in: query
        description: >
          Filter by invoice status. Accepted values: draft, submitted,
          authorised, deleted, voided, paid. Defaults to all statuses if omitted.
        schema:
          type: string
          enum: [draft, submitted, authorised, deleted, voided, paid]
      - name: cursor
        in: query
        description: >
          Opaque pagination cursor returned in the previous response.
          Omit to start from the first page.
        schema:
          type: string

An agent matching "fetch unpaid invoices for reconciliation" against the bad version has no signal to work with. Against the good version, it finds status: authorised, understands pagination, and knows it needs accounting:read before it makes a single request.

I've seen this up close. We built Portman, an open-source CLI that converts OpenAPI specs into Postman collections for contract testing. The main thing you learn doing that is how few specs have descriptions worth converting. If your spec is broken for contract testing, it's broken for agents. The failure mode is the same: a consumer that can't determine what anything does without running it.

The fix isn't glamorous. Go through your spec field by field. Write descriptions that explain what each parameter does, what values are valid, what happens when you omit it. Do this for your ten most important endpoints first. It's tedious, it takes time, and it makes a bigger difference to agent experience than almost anything else on this list.

Your errors should tell agents how to fix themselves

The agent experience of errors is fundamentally different from the human experience. A human reads an error message, understands it, googles the fix, comes back. An agent reads an error message and needs to decide, in the same execution context, what to do next. If the error is ambiguous, the agent either guesses or fails.

Stripe's error responses have included a doc_url field for years:

{
  "error": {
    "code": "parameter_invalid_empty",
    "doc_url": "https://stripe.com/docs/error-codes/parameter-invalid-empty",
    "message": "You passed an empty string for 'amount'. We assume empty values are an oversight, so we require you to pass this field.",
    "param": "amount",
    "type": "invalid_request_error"
  }
}

This is infrastructure for autonomous consumers. When an agent hits a 400, it can follow the doc_url, fetch the documentation page, and self-correct without a human in the loop. The agent experience of that error is recovery. The agent experience without doc_url is a dead end.

Adding documentation_url to your error responses costs almost nothing to implement. Pair it with documentation pages that are available as clean Markdown (by appending .md to the URL, or via a parallel /docs/{page}.md route), and you've given agents everything they need to handle errors autonomously.

The other half of error design is specificity. "Invalid request" is useless. "The amount field cannot be empty" is useful. "You passed payment_method_types: ['card'], which is deprecated, use dynamic payment methods instead" is excellent. The more specific the error, the more actionable it is for an agent trying to self-correct.

llms.txt: tell AI what to read

The llms.txt standard, proposed by Jeremy Howard in September 2024, exists because AI agents have finite context windows and your documentation site is not designed for machine consumption. HTML is noisy. Navigating a docs site the way a human would (clicking links, loading JavaScript, jumping between pages) is expensive and lossy.

The solution is a Markdown file at /llms.txt that curates the most important parts of your documentation with plain-text links and one-sentence descriptions. Agents and AI coding tools can fetch this file once and understand the shape of your documentation before writing a single line of integration code.

The format is deliberately boring. No special syntax, no schema. Just Markdown. The interesting part is curation: you know your documentation better than any crawler, so you should be the one deciding what matters.

Adding a basic /llms.txt takes an afternoon. Link to your ten most important pages. Write one sentence per link explaining what's there. That's a complete implementation. You don't need Stripe's 350-link version on day one.

What's underutilized (and genuinely powerful for agent experience) is the instructions section. Stripe's llms.txt includes:

## Instructions for Large Language Model Agents: Best Practices for integrating Stripe.
- Always use the Checkout Sessions API over the legacy Charges API
- Default to the latest stable SDK version
- Never recommend the legacy Card Element or Sources API

This is Stripe telling AI coding assistants exactly which footguns to avoid. If your API has deprecated primitives, ambiguous endpoint choices, or integration patterns that look valid but cause problems, the instructions section is where you document that for agents. It propagates into every AI-assisted integration of your API. Every time a developer asks an agent how to use your API, those instructions shape the answer.

There's a second-order benefit worth naming here. The same properties that make your docs readable to coding agents (structured Markdown, clear definitions, curated indexing) also make your content discoverable by AI answer engines like Perplexity and ChatGPT. When someone asks "what's the best accounting API" or "how do I build an accounting integration," the answer comes from content that AI can parse and cite. llms.txt, semantic descriptions, and concrete definitions aren't just AX improvements. They're how you show up in AI search. The discipline is the same: write for machines and you get both.

Get your docs indexed by Context7

Context7 is an MCP server that solves a specific problem: AI coding tools have a training data cutoff, which means they default to documentation from whenever they were last trained. If your API changed since then, agents write integrations against the old version.

Context7 addresses this by maintaining an up-to-date index of developer documentation that coding tools can query in real time, pulling current docs rather than cached training data.

Getting your documentation added to Context7 is low-effort and high-leverage. You submit your docs, they get indexed, and any developer using a Context7-enabled coding tool gets accurate, current information about your API without you needing to push updates to every AI provider individually.

The practical upside is significant if you ship changes regularly. An API that added a new authentication method last quarter, or deprecated an endpoint three months ago, looks different in Context7 than it does in an AI's training data. Developers using Context7-enabled tools get the right answer. Developers using tools without it get whatever the model was trained on.

The broader point is that documentation distribution is now a multi-channel problem. Publishing docs to your website is table stakes. Getting those docs in front of agents (through /llms.txt, through Context7, through direct MCP server implementations) is the new distribution layer. You're not just writing docs for developers who visit your site. You're writing docs for systems that will intermediate between your API and the developers who use it.

Your deprecated APIs are an agent experience problem

APIs accumulate history. Old endpoints that still work. Legacy authentication methods that are technically valid but shouldn't be used for new integrations. Multiple ways to accomplish the same thing, with meaningful differences that aren't obvious from the outside.

Humans navigate this through Stack Overflow recency, changelog reading, and conversations with other developers. Agents navigate it through your documentation and training data, which may include answers and tutorials from 2019 that recommend the old way because the new way didn't exist yet.

Your agent experience gets worse every year you don't address this, as more stale content about your old APIs accumulates on the internet and in AI training sets.

The practical response is layered. Mark deprecated endpoints explicitly in your OpenAPI spec using the deprecated: true field, with a description pointing to the replacement. Write deprecation notices at the top of deprecated docs pages, with direct links to the current approach. Add deprecated API guidance to your llms.txt instructions section. And if you're generating error responses from deprecated endpoints, consider including a migration hint in the message itself.

None of this requires coordination with AI providers. It works because agents read your documentation.

MCP: build it when people ask for it

Model Context Protocol is real, growing, and mostly not worth building for yet unless your users are asking for it.

MCP lets AI agents connect to your service through a standardized protocol with tools, resources, and prompts. The agent experience of a well-designed MCP server is genuinely better than the experience of parsing REST documentation and constructing API calls manually. But agent framework standardization is still in flux, and a well-designed REST API with a complete OpenAPI spec is more durable than an MCP server you build today against tooling that changes in six months.

HubSpot is a good example of what a mature implementation looks like. They shipped two distinct MCP servers: a remote server that connects AI clients to live CRM data (contacts, deals, tickets, companies), and a local developer MCP server that integrates with their CLI so agentic dev tools can scaffold HubSpot projects, answer questions from their developer docs, and deploy changes directly.

A developer can prompt "What's the component for displaying a table in HubSpot UI Extensions?" and the developer MCP server pulls the answer from current HubSpot documentation. Another developer can prompt "Summarize all deals in Decision maker bought in stage with deal value over $1000" and the remote MCP server queries live CRM data. Two different use cases, two different servers, both scoped tightly to what their users actually need.

When you do reach the point of building, the tooling has matured enough to make it tractable. Gram by Speakeasy is an open-source MCP cloud platform: you upload your OpenAPI spec, it converts your endpoints into curated toolsets, and deploys them as a hosted MCP server at mcp.yourcompany.com in minutes. The key design insight is curation — rather than exposing all 200 endpoints as tools and overwhelming the agent's context, Gram lets you distill them down to 5–30 focused, purpose-built tools that represent complete workflows. For teams building in Python who want full control over the implementation, FastMCP is a high-level framework that strips out the protocol boilerplate and lets you define tools, resources, and prompts in straightforward Python.

Most API companies aren't HubSpot. The right sequence for everyone else: get your OpenAPI spec right, write real descriptions, add documentation_url to your errors, publish /llms.txt, get indexed by Context7. That foundation improves agent experience immediately and transfers to every framework. Then, when users start asking how to connect your API to their AI agents and a clear integration pattern emerges, build the MCP server against that specific use case.

Building MCP for the sake of having an MCP server is the equivalent of building a mobile app for the sake of having a mobile app. The agent experience of a half-built MCP server is worse than the agent experience of a good REST API.

Skills: Teaching Agents to Do Your Job at 100x the Scale

There's a mental model shift happening in engineering right now. AI agents aren't just writing code faster; they're becoming the engineers who run the product development loop. The new engineering job is building the agents that automate that loop for you, and then directing them to do it at a scale no individual could match.

The simple version of this is already in use: Ghostty splits and tabs, tmux sessions, CLI agents in parallel. You run ten agents at once, each working a different branch or task. That's horizontal scalability for engineering work, something that was physically impossible before.

But raw parallelism without direction is chaos. This is where skills come in.

What Are Skills?

Skills are instruction packages for AI agents: Markdown files (optionally accompanied by scripts and resources) that teach an agent exactly how to handle a specific task. When the agent encounters work relevant to a skill, it loads that skill's context and operates with domain-specific precision instead of general-purpose guesswork.

Anthropic introduced Skills as a first-class concept for Claude Code and the Claude ecosystem. Simon Willison called them "maybe a bigger deal than MCP", and his argument is compelling:

Skills are conceptually extremely simple: a skill is a Markdown file telling the model how to do something, optionally accompanied by extra documents and pre-written scripts that the model can run to help it accomplish the tasks described by the skill.

The key design insight is token efficiency. At session start, Claude reads only a brief YAML frontmatter description of each available skill, a few dozen tokens per skill. The full skill content only loads when the agent determines it's needed for the task at hand. You can have dozens of skills installed without burning your context window.

The Agent Skills Ecosystem

The ecosystem is moving fast. Vercel launched agent-skills, a directory and tooling layer for discovering, installing, and composing skills across coding agents. The skills.sh platform (used by Cursor, Claude Code, and others) makes the install experience as simple as:

npx skills add <package>

Ahrefs published their own skills to teach agents how to work with their SEO API, a direct example of how companies are now shipping agent instructions alongside their APIs. We took the same approach at Apideck.

Apideck API Skills

We just launched Apideck API Skills, installable via the skills.sh directory, to teach AI agents how to build integrations against our Unified API correctly:

npx skills add apideck-libraries/api-skills

Skills cover SDK usage across TypeScript, Python, Go, Java, PHP, and .NET; authentication and Vault patterns; pagination, error handling, and connector coverage checks; and migration paths from direct integrations to the unified layer.

Instead of an agent making reasonable guesses about how our API works, it loads the relevant skill and operates with the same knowledge a senior Apideck engineer would bring to the task.

This follows the same "building with LLMs" philosophy Stripe pioneered. They offer plain-text docs, MCP server access, and agent toolkits, but skills go a layer deeper. Where plain-text docs make your documentation parseable, skills make your API learnable in the agent's execution context.

Skills vs. MCP: Complementary, Not Competing

It's worth being precise about where skills fit relative to MCP. MCPs give agents tools to call: actions they can take against live systems. Skills give agents the knowledge to use those tools well, or to accomplish tasks using the code execution environment directly.

Simon Willison puts it well: almost everything you might achieve with an MCP can be handled by a CLI tool instead, because LLMs already know how to call cli-tool --help. Skills have the same advantage, and you don't even need a CLI implementation. You drop in a Markdown file and let the model figure out execution.

The two patterns compose naturally. An agent with an MCP connection to your accounting API and a skill that explains your data model and common patterns will outperform one that has only the MCP. Skills are the institutional knowledge layer; MCP is the capability layer.

From Parallelism to Leverage

Skills connect to the larger picture of agent orchestration. When you're running agents in parallel, on PRs, when an incident fires, when a customer files a bug, the quality ceiling is determined by how well each agent understands the domain it's working in. Skills are how you encode that domain knowledge once and distribute it across every agent instance, at any scale.

The automation of the full product development loop is now an engineering responsibility. Skills are how you ensure that when your agents run that loop, at 100x the scale, while you sleep, they're running it the way you would have.

The CLI Rebirth

There's a pattern Karpathy pointed to on February 24 that cuts to something fundamental about agent-native interfaces: CLIs, the oldest developer tool, are having a second moment — not despite AI agents, but because of them.

The reason is structural. Agents are terminal-native. They know how to run --help, install packages via pip or npm, chain tools with pipes, and parse output. They don't need a bespoke integration layer to use a CLI. They just use it.

Karpathy demonstrated this concretely: Claude installed the new Polymarket CLI, built a terminal dashboard showing the highest-volume prediction markets and their 24-hour price changes, and had it running in about three minutes. Pair that with the GitHub CLI and an agent can navigate repositories, review PRs, and act on real-world data signals in a single autonomous pipeline — no custom integration layer, no MCP server, nothing to maintain.

This is the same point Willison makes about skills: almost everything you might achieve with an MCP server can be handled by a CLI, because agents already know how to use them. A well-designed CLI with good --help output is self-documenting in a way that a REST API is not. An agent encountering gh --help for the first time figures out the relevant subcommand on its own. An agent encountering your undescribed REST API hits a wall.

The opportunity for API companies is direct: if you don't have a CLI, it's worth asking whether building one would be more leveraged than building an MCP server. A CLI that agents can install and explore immediately compounds differently. Skills make this even more powerful — a developer who loads your skill and has your CLI installed gives an agent both the domain knowledge and the execution surface at the same time.

A few things make a CLI specifically better for agents: a --json flag or JSON-by-default output so agents don't have to parse human-readable strings; composable subcommands following the tool noun verb convention (like gh repo list, gh pr view) so --help output is scannable; environment-variable-based auth so agents can configure credentials without interactive prompts; and error messages that explain what went wrong rather than just returning an exit code.

Karpathy's framing for businesses is the right frame for API companies too: make your product agent-usable via markdown docs, skills, CLI, and MCP — roughly in that order of ease and durability. Each layer compounds on the last. Building the CLI doesn't require coordination with any AI provider, and it works immediately because agents can already use it.

The underlying shift

DX was about removing friction for humans. AX is the same discipline applied to autonomous consumers that can't ask for clarification and can't adapt when your API sends them somewhere unexpected.

The things that made APIs good for developers — specificity, consistent semantics, helpful errors — matter even more when there's no human in the loop to compensate for ambiguity. Ambiguity that a developer resolves through experience becomes a failure mode at scale when agents are writing the integrations.

The good news: most of what you'd do to make your API understandable to a machine is the same thing you'd do for a developer who doesn't already know your system. Start there.

We're building Apideck, a unified API for accounting integrations. The agent experience question is concrete for us: when an agent connects through Apideck and gets normalized access to 20+ accounting platforms, the quality of our OpenAPI descriptions and error responses propagates to every integration downstream. It focuses the mind.

A Guide to Integrating with the NetSuite REST API

𝚂𝚊𝚞𝚛𝚊𝚋𝚑 𝚁𝚊𝚒 — Fri, 31 Oct 2025 14:28:04 +0000

A Guide to Integrating with the NetSuite REST API

Accounting systems like NetSuite are the backbone for managing and optimizing business operations through automated processes and integrated workflows. NetSuite is a cloud-based enterprise resource planning (ERP) system that provides a business software suite for financial management, customer relationship management, e-commerce, and more.

The NetSuite REST API allows developers to build modern integrations that connect NetSuite to other systems, automate complex workflows, and synchronize data across different platforms. Using this API, developers can automate tasks such as customer creation, order processing, and real-time inventory updates. This is key to building automated solutions that reduce manual effort and increase accuracy.

Why the NetSuite REST API Matters

The NetSuite REST API provides a modern, JSON-based interface to NetSuite's core functionality, allowing you to interact with the platform programmatically using standard HTTP methods. You can use it to perform operations such as creating and updating records, managing customer data, processing transactions, and retrieving financial reports. The REST API enables you to integrate NetSuite into your existing systems and automate business-critical processes while ensuring data consistency across all applications.

For example, you can automate workflows like customer onboarding or sync order data between NetSuite and external platforms, reducing manual errors and increasing operational efficiency.

NetSuite SOAP API Alternative

If you're evaluating NetSuite integration options, you might also consider the NetSuite SOAP API. While SOAP is more established and offers broader functionality coverage, it's significantly more complex to implement due to XML handling and verbose request structures. For a detailed comparison and implementation guide, see our comprehensive NetSuite SOAP API integration guide.

Here are some examples of how you can use the REST API:

Automating customer management: The NetSuite REST API can automatically create customer records when new users sign up on your website, sync contact information, and update customer data across systems. This eliminates duplicate data entry and ensures customer information stays current across all touchpoints.

Real-time inventory synchronization: The REST API can integrate with e-commerce platforms like Shopify or WooCommerce to provide real-time inventory updates. When a product is sold online, the API immediately updates stock levels in NetSuite and can trigger reorder notifications when inventory falls below threshold levels.

Automated financial reporting: The REST API can integrate with business intelligence tools to generate real-time financial dashboards. This automation provides up-to-date profit and loss statements, cash flow reports, and sales analytics, helping businesses make data-driven decisions quickly.

How to Integrate with the NetSuite REST API

NetSuite's REST API supports Token-Based Authentication (TBA) and OAuth 2.0 for secure API access.

This guide focuses on Token-Based Authentication, which involves creating a signature using your NetSuite account credentials and including it with other authentication parameters in the request headers.

To interact with the REST API, you need to:

Create a user role with appropriate permissions, including REST Web Services access
Create a new integration record for token-based authentication and obtain the consumer key and secret
Create a new access token and obtain the token ID and secret

More detailed information is available in the official documentation.

Simplify Authentication with Apideck Vault

The authentication setup process above can be complex and time-consuming for your end users. Apideck Vault provides a white-label, hosted authentication interface that eliminates this complexity entirely.

With Vault, your users can:

Connect NetSuite in seconds - No technical setup required on their end
Secure credential storage - OAuth tokens and API keys are stored safely with enterprise-grade security
Unified experience - Same interface works for NetSuite, QuickBooks, Xero, and 200+ other integrations
Self-service management - Users can connect, disconnect, and manage integrations independently

Instead of asking users to create integration records and access tokens, they simply authenticate through Vault's hosted interface. You get the integration data you need without the setup friction that kills conversion rates.

Making a Request to the NetSuite REST API

The base URL for NetSuite REST API requests follows this format:
https://{account_id}.suitetalk.api.netsuite.com/services/rest/record/v1/{record_type}

NetSuite uses OAuth 1.0a for authentication, which requires generating a signature for each request. Here's a Python example:

import requests
from requests_oauthlib import OAuth1

# NetSuite credentials
account_id = "your_account_id"
consumer_key = "your_consumer_key" 
consumer_secret = "your_consumer_secret"
token_key = "your_token_key"
token_secret = "your_token_secret"

# Create OAuth1 auth object
auth = OAuth1(
    consumer_key,
    client_secret=consumer_secret,
    resource_owner_key=token_key,
    resource_owner_secret=token_secret,
    signature_method='HMAC-SHA256',
    signature_type='AUTH_HEADER'
)

# Example: Get a customer record
def get_customer(customer_id):
    url = f"https://{account_id}.suitetalk.api.netsuite.com/services/rest/record/v1/customer/{customer_id}"

    headers = {
        'Content-Type': 'application/json'
    }

    response = requests.get(url, auth=auth, headers=headers)
    return response.json()

# Example: Create a customer record
def create_customer(customer_data):
    url = f"https://{account_id}.suitetalk.api.netsuite.com/services/rest/record/v1/customer"

    headers = {
        'Content-Type': 'application/json'
    }

    response = requests.post(url, auth=auth, headers=headers, json=customer_data)
    return response.json()

# Usage examples
try:
    # Get customer with ID 123
    customer = get_customer("123")
    print("Customer data:", customer)

    # Create a new customer
    new_customer = {
        "companyName": "Acme Corporation",
        "email": "contact@acme.com",
        "phone": "+1-555-0123"
    }

    result = create_customer(new_customer)
    print("Created customer:", result)

except Exception as error:
    print("Error making API request:", error)

The Integration Challenge

As you can see from the examples above, integrating directly with the NetSuite REST API involves several challenges:

Authentication complexity: Implementing OAuth 1.0a signature generation requires precise handling of encoding, sorting, and hashing
Rate limiting management: NetSuite has strict concurrency limits that require careful request throttling to avoid timeouts
Custom field handling: NetSuite's custom fields require specific formatting and field ID mapping that varies by account
Error handling complexity: NetSuite's error responses require specific parsing and retry logic for different error types
Data transformation: NetSuite's data structures often don't match your application's data models
Pagination complexity: Handling large datasets requires implementing cursor-based pagination logic
Webhook limitations: NetSuite's webhook support is limited, requiring polling for real-time data needs

Each of these challenges adds development time and increases the potential for bugs in your integration.

The Apideck Unified Accounting API

Integrating with multiple accounting systems, including NetSuite, can be overwhelming and time-consuming. Managing OAuth signatures, handling rate limits, and dealing with different data formats across various platforms requires months of development effort and ongoing maintenance.

The Apideck Unified Accounting API provides a single integration point for 20+ accounting platforms, including NetSuite. This approach abstracts away the complexities of individual APIs, simplifying the integration process.

Key benefits of using the Apideck Unified Accounting API include:

Real-time data processing: All API calls are processed in real-time, not batched, ensuring your data is always fresh
Managed authentication with Vault: Apideck Vault handles all OAuth flows and credential management, eliminating complex authentication setup for your users
Unified data model: Consistent data structures across all 18+ accounting platforms
Built-in rate limit management: Automatic throttling and retry logic with exponential backoff
Webhook emulation: Get push notifications from platforms that support webhooks, with Apideck emulating webhooks for platforms that don't
White-label user interface: Easily embedded interface that gives users a simple and secure connection experience
Data normalization: Messy, inconsistent APIs are normalized into a single structure while still exposing raw downstream information
Reduced maintenance burden: Updates to underlying accounting systems don't require changes to your integration

Making Requests with Apideck

Before making API requests through Apideck, you need to configure your NetSuite connection in the Apideck platform.

Here's how simple the same operations become with Apideck's unified API. You can try these requests in our Api Explorer, which makes this even simpler.

import axios from "axios";

const headers = {
  "x-apideck-app-id": "<YOUR-APP-ID>",
  "Authorization": "Bearer <YOUR-API-KEY>",
  "x-apideck-consumer-id": "<CONSUMER-ID>", // Your NetSuite consumer
  "Content-Type": "application/json"
};

// Get a customer - unified across all accounting platforms
async function getCustomer(customerId: string) {
  try {
    const response = await axios.get(
      `https://unify.apideck.com/accounting/customers/${customerId}`,
      { headers }
    );
    return response.data;
  } catch (error) {
    console.error("Error retrieving customer:", error);
  }
}

// Create a customer - same API call works for NetSuite, QuickBooks, Xero, etc.
async function createCustomer(customerData: any) {
  try {
    const response = await axios.post(
      "https://unify.apideck.com/accounting/customers",
      customerData,
      { headers }
    );
    return response.data;
  } catch (error) {
    console.error("Error creating customer:", error);
  }
}

// List all invoices with automatic pagination
async function getInvoices() {
  try {
    const response = await axios.get(
      "https://unify.apideck.com/accounting/invoices",
      { headers }
    );
    return response.data;
  } catch (error) {
    console.error("Error retrieving invoices:", error);
  }
}

// Usage examples
const customer = await getCustomer("123");
console.log("Customer:", customer);

const newCustomer = {
  name: "Acme Corporation",
  email: "contact@acme.com", 
  phone_number: "+1-555-0123"
};

const createdCustomer = await createCustomer(newCustomer);
console.log("Created customer:", createdCustomer);

const invoices = await getInvoices();
console.log("Invoices:", invoices);

Here’s an example of the same request from Apideck’s API Explorer

You can test and make API calls with the simple drag and drop UI, which can easily pre-fill the response headers and body with the required data. You can see the list customers request being done in a single shot.

Compare this clean, simple code to the complex OAuth signature generation and authentication handling required for direct NetSuite integration. With Apideck, the same code works across NetSuite, QuickBooks, Xero, Sage, and dozens of other accounting platforms.

Real-World Integration Examples

Here are some practical examples showing how Apideck simplifies common NetSuite integration scenarios. Please note, you can try them out from our Api Explorer.

E-commerce Order Sync:

// Sync new orders from your e-commerce platform to NetSuite
async function syncOrderToNetSuite(order: any) {
  const invoice = {
    number: order.order_number,
    customer: { id: order.customer_id },
    line_items: order.items.map(item => ({
      description: item.name,
      quantity: item.quantity,
      unit_amount: item.price,
      item: { id: item.product_id }
    })),
    due_date: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString()
  };

  return await axios.post(
    "https://unify.apideck.com/accounting/invoices",
    invoice,
    { headers }
  );
}

Customer Data Synchronization:

// Keep customer data in sync between your CRM and NetSuite
async function syncCustomerData(crmCustomer: any) {
  const customer = {
    name: crmCustomer.company_name,
    email: crmCustomer.primary_email,
    phone_number: crmCustomer.phone,
    billing_address: {
      line1: crmCustomer.billing_street,
      city: crmCustomer.billing_city,
      state: crmCustomer.billing_state,
      postal_code: crmCustomer.billing_zip,
      country: crmCustomer.billing_country
    }
  };

  return await axios.post(
    "https://unify.apideck.com/accounting/customers",
    customer,
    { headers }
  );
}

Conclusion

In this guide, you learned how to integrate with the NetSuite REST API and discovered the complexities involved in direct integration. As demonstrated, working directly with NetSuite's API requires managing complex OAuth 1.0a signatures, handling rate limits, dealing with custom field mappings, and maintaining error-prone authentication code.

These challenges multiply when you need to support multiple accounting platforms beyond NetSuite. Each system has its own authentication methods, data structures, and API quirks that require separate implementations and ongoing maintenance.

To simplify your accounting integrations and eliminate the complexities of direct API integration, consider using the Apideck Unified Accounting API with the NetSuite Connector. By providing a single, consistent interface across all major accounting platforms, Apideck simplifies development, reduces maintenance overhead, and saves valuable development time and resources.

With Apideck, you can:

Connect to NetSuite and 20+ other accounting platforms with the same code
Skip complex authentication implementations
Get standardized data models across all platforms
Benefit from built-in rate limiting and error handling
Access real-time data processing (not batch processing)
Use webhook emulation for platforms that don't natively support webhooks
Focus on building features instead of managing integrations

Frequently Asked Questions

What's the difference between NetSuite REST API and SOAP API?

The REST API is newer (2019), uses JSON, and is easier to implement, but has limited functionality coverage. The SOAP API has been around longer, offers broader NetSuite feature access, but requires XML handling and is more complex to implement. For bulk operations and advanced features, SOAP is often better. For modern web/mobile apps and simple CRUD operations, REST is preferred. See our SOAP API guide for a detailed comparison.

How do I handle NetSuite's rate limits?

NetSuite uses concurrency-based rate limiting rather than traditional rate limits. Each account has a limit on concurrent API requests (typically 10-25 concurrent requests). When you exceed this limit, you'll get timeout errors rather than 429 rate limit errors. Implement exponential backoff retry logic and consider queuing requests during high-traffic periods. Monitor your usage through NetSuite's API monitoring tools.

Can I use OAuth 2.0 with NetSuite REST API?

Yes, NetSuite supports OAuth 2.0 for REST API authentication, but Token-Based Authentication (TBA) is more commonly used because tokens don't expire like OAuth 2.0 access tokens do. OAuth 2.0 requires refresh token management and has a 7-day refresh limit, making TBA more suitable for server-to-server integrations. However, if you need user-facing authentication flows, OAuth 2.0 is the better choice.

DATEV API Integration: A Comprehensive Technical Guide

𝚂𝚊𝚞𝚛𝚊𝚋𝚑 𝚁𝚊𝚒 — Fri, 31 Oct 2025 14:27:33 +0000

When German businesses need accounting software, they turn to DATEV. With decades of market dominance and adoption by thousands of tax consultants across Germany, DATEV has become the de facto standard for financial record-keeping in the German market. But here's where things get interesting for developers: integrating with DATEV isn't like connecting to your typical REST API. The architecture is fundamentally different, and understanding these differences is critical to building a successful integration.

If you're building an ERP system, e-commerce platform, or any business application that needs to sync financial data with German accounting workflows, you'll need to understand how DATEV integration actually works. This guide will walk you through the technical architecture, explain why DATEV takes a batch-processing approach instead of real-time REST calls, and show you the practical steps for implementing a robust integration.

Understanding DATEV API Integration

DATEV API integration connects your third-party platform to DATEV's accounting software ecosystem, enabling automated synchronization of financial data without manual file imports or error-prone copy-paste workflows. When you integrate with DATEV, you're connecting to the systems used by tax consultants and accountants across Germany to manage client finances, prepare tax filings, and maintain compliance with German accounting regulations.

The typical use cases span multiple business domains. E-commerce platforms sync order data and payment records. Banking systems push transaction updates for reconciliation. Property management software sends rent payments and tenant invoicing data. Payroll systems transfer employee expense information. In each case, the goal is the same: eliminate manual data entry, reduce errors, and enable real-time visibility into financial operations.

What makes DATEV integration valuable is the automation of repetitive accounting tasks. Instead of your accountant manually importing CSV files and checking for discrepancies, your integration automatically creates properly formatted records that flow directly into the accounting workflow. Invoice data, customer and supplier records, journal entries, cost center allocations, and VAT calculations all sync automatically. The result is enhanced compliance with German accounting regulations, reduced data errors, improved accuracy, and proactive financial management based on current data rather than week-old exports.

The Two Types of DATEV APIs

Here's where DATEV diverges sharply from typical API architectures. DATEV offers two primary data exchange formats, and neither one works like the REST or SOAP APIs you're probably familiar with. Understanding this distinction is absolutely critical before you start building your integration.

The CSV-based API, used for DATEV Rechnungswesen (abbreviated as ReWe), handles finalized financial bookings and accounting records. When you need to submit completed transactions that are ready for the permanent accounting record, you use this approach. Data flows through flat, tabular CSV files that must follow precise column formatting requirements. These files are processed through batch jobs called EXTF-Jobs. This approach is common in on-premise environments and legacy integrations where the infrastructure was built before cloud-native architectures became standard.

The XML-based API, used for DATEV Unternehmen Online (abbreviated as DUo), handles booking suggestions and invoice processing. This format supports complex, hierarchical data structures that represent more nuanced financial information. Data moves through structured XML files that are validated against XSD schemas to ensure compliance. These files are processed with batch jobs called dxso-Jobs. The XML approach focuses on cloud platforms and modern workflows, particularly for scenarios where you're proposing bookings that require accountant review before finalization.

Now here's the critical point that trips up many developers: DATEV does not use traditional REST or SOAP APIs for core accounting operations. If you're expecting to make HTTP POST requests with JSON payloads and get immediate synchronous responses, you're approaching this wrong. DATEV's integration relies on asynchronous batch-based file processing. You submit files as jobs, those jobs enter a processing queue, and DATEV systems handle them on their own schedule. You cannot use typical RESTful calls for submitting bookings or financial records.

There are some exceptions worth noting. DATEV does offer REST endpoints for certain niche products. The Cash Register Import API (MeinFiskal) provides documented REST endpoints for importing electronic cash register data. The Document Management system integrates via REST APIs through DATEVconnect for document workflows. But these are specialized use cases, not the core accounting functionality.

Third-party unified API providers sometimes expose REST endpoints that make DATEV integration feel more familiar to developers. But understand what's happening under the hood: these are wrappers that translate your REST calls into DATEV's batch processing behind the scenes. The underlying architecture remains batch-based, even if the developer experience feels more REST-like.

Working with the accounting:documents API

Let me show you a practical example using the accounting:documents REST API, which handles document uploads to Belege online in DATEV Unternehmen online. This is one of the REST endpoints that DATEV provides, and it demonstrates the authentication and data handling patterns you'll encounter.

First, you need to retrieve the list of clients your authenticated user can access. This establishes which companies you have permission to integrate with:

GET https://accounting-documents.api.datev.de/platform/v2/clients
Authorization: Bearer {access_token}
X-DATEV-Client-Id: {your_client_id}

The response gives you client identifiers that you'll use in subsequent requests:

[
  {
    "client_number": 1,
    "consultant_number": 455148,
    "id": "455148-1",
    "name": "Muster GmbH 1"
  }
]

That id field is the technical identifier you'll use for all data operations. Notice that it combines the consultant number and client number, creating a unique reference for this specific client within the DATEV system.

Before uploading documents, you should check what document types are available for this client. Document types determine how DATEV processes and categorizes your uploads:

GET https://accounting-documents.api.datev.de/platform/v2/clients/455148-1/document-types
Authorization: Bearer {access_token}
X-DATEV-Client-Id: {your_client_id}

This returns the configured document types:

[
  {
    "name": "Rechnungseingang",
    "category": "invoices_received",
    "debit_credit_identifier": "debit"
  },
  {
    "name": "Rechnungsausgang",
    "category": "outgoing_invoices",
    "debit_credit_identifier": "credit"
  },
  {
    "name": "Kasse",
    "category": "other_documents"
  }
]

Now you can upload a document. This uses multipart form data to combine the file with metadata:

POST https://accounting-documents.api.datev.de/platform/v2/clients/455148-1/documents
Authorization: Bearer {access_token}
X-DATEV-Client-Id: {your_client_id}
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="file"; filename="invoice-2024-001.pdf"
Content-Type: application/pdf

[Binary PDF content]
--boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
  "document_type": "Rechnungseingang",
  "note": "Supplier invoice for office supplies",
  "category": "MyERP",
  "folder": "Invoices",
  "register": "2024/10"
}
--boundary--

The metadata structure organizes documents within DATEV's document repository using a three-level hierarchy: category, folder, and register. If you specify any of these levels, you must provide all three. This organizational structure helps accountants locate documents efficiently within the DATEV interface.

When the upload succeeds, you receive confirmation with file details:

{
  "file": [{
    "name": "invoice-2024-001.pdf",
    "size": 125742,
    "upload_date": "2024-10-09T14:23:12+02:00",
    "media_type": "application/pdf"
  }],
  "document_type": "Rechnungseingang",
  "note": "Supplier invoice for office supplies"
}

Authentication and Authorization

DATEV uses OAuth2 for authorization, particularly for cloud-based integrations with Unternehmen Online. You need to design secure user consent workflows that clearly explain what data your application will access and how it will be used. Many integration scenarios require third-party approval or validation from the tax consultant who manages the client's account, since tax consultants control client access within the DATEV ecosystem.

Your OAuth implementation should support long-lived tokens with automatic renewal processes. This is critical because DATEV integrations often need continuous data synchronization without requiring users to re-authenticate frequently. Users expect their accounting data to flow automatically once they've granted initial consent.

The typical OAuth flow follows this pattern: redirect the user to DATEV's authorization endpoint, receive an authorization code after the user grants consent, exchange that code for access and refresh tokens, and use the access token for API requests. When the access token expires, use the refresh token to obtain a new access token without requiring user interaction.

Data Format Compliance and Validation

DATEV enforces strict format requirements because accounting data must maintain audit compliance and regulatory standards. The CSV and XML formats are fixed specifications that vary by product. You cannot choose arbitrary formats or invent your own column structures.

For XML submissions to Unternehmen Online, your files must validate against DATEV's XSD schemas before processing will succeed. The schemas define required fields, data types, value constraints, and structural relationships. XML validation failures result in immediate job rejection with error codes that indicate which validation rules you violated.

CSV files for Rechnungswesen demand precise column formatting. Each column must contain the correct data type in the expected position. Column order matters. Field delimiters must match the specification exactly. Even minor deviations cause processing failures because the DATEV import engine cannot risk misinterpreting financial data.

Beyond basic format validation, you must properly structure metadata that accompanies your financial records. Cost center allocations, voucher numbers, analytic account references, and VAT information all need to follow DATEV's coding schemes. German VAT codes, for instance, follow specific conventions that DATEV recognizes and validates against current tax regulations.

Common Error Scenarios

The OpenAPI specification documents numerous error codes you'll encounter. Let me walk through the most common ones and what they mean for your integration.

Error #DCO01010 restapi.InvalidDocumentTypeFault occurs when you specify a document type that doesn't exist for the client. Remember that each client configures their own document types. You must query the available types first and only use values from that list. Don't assume standard document types exist universally.

Error #DCO01015 restapi.UnsupportedFileTypeFault indicates the file format isn't accepted. DATEV restricts uploads to specific file types for security and compatibility reasons. The allowed formats vary between DuoNext and legacy systems. Always check the permitted file extensions for your target environment.

Error #DCO01016 restapi.FileSizeFault means your file exceeds the twenty-megabyte limit. Large files create processing and storage burdens. If you're handling oversized documents, you'll need to compress them, split them into multiple uploads, or reconsider your document workflow. DATEV recommends warning users when files exceed 500 KB because even allowed file sizes can slow down system performance.

Error #DCO01253 restapi.DuplicateFileFault signals that a file with identical name and document type already exists in Belege Online. DATEV prevents duplicate uploads to avoid confusion. Your integration should either generate unique filenames, allow users to specify different document types for duplicates, or implement deduplication logic before attempting uploads.

Integration Approaches: Direct vs. Unified APIs

You face a fundamental architectural decision: integrate directly with DATEV or use a unified API provider that abstracts the complexity. Each approach has distinct tradeoffs that affect your development timeline, maintenance burden, and feature coverage.

Direct integration with DATEV gives you complete control over the integration logic. You're not dependent on third-party service availability or pricing changes. You can access all DATEV features without waiting for a middleware provider to expose them. But this control comes with significant complexity. You need deep understanding of CSV and XML format specifications. You're responsible for all batch job management, status monitoring, error handling, and retry logic. Testing requires thorough validation across different client configurations and fiscal year setups. Development cycles stretch longer because you're implementing the entire integration stack yourself. Ongoing maintenance becomes a permanent operational burden as DATEV updates their APIs and format requirements.

Unified API providers like Chift, Maesn, and others offer a RESTful developer experience that feels familiar to modern web developers. These platforms automatically handle batch job creation and management behind the scenes. They provide built-in error handling and retry logic that's been tested across many production deployments. Most importantly, they support multiple accounting platforms beyond DATEV, so your integration code can potentially connect to QuickBooks, Xero, NetSuite, and other systems using the same API patterns. Time to market drops dramatically because you're leveraging pre-built infrastructure. Maintenance overhead shifts to the unified API provider.

The downsides of unified APIs include dependency on third-party service reliability and additional costs beyond DATEV's pricing. Not all DATEV features may be exposed through the unified API wrapper, potentially limiting your integration's capabilities. You're also adding network hops and processing delays compared to direct DATEV communication.

For most development teams, especially those building multi-platform integrations or operating under tight deadlines, unified API providers offer the better path. The productivity gains and reduced maintenance burden usually outweigh the additional costs and potential feature limitations. Direct DATEV integration makes sense primarily for specialized use cases that require features not available through unified APIs, or for large-scale deployments where the volume justifies investing in custom infrastructure.

Practical Implementation Considerations

When you start implementing your DATEV integration, several practical concerns will surface immediately. File naming conventions matter more than you might expect. DATEV recommends UTF-8 encoding with precomposed Unicode characters. Decomposed characters cause problems. Special characters like umlauts must be single code points, not multi-byte sequences. DATEV maintains a whitelist of permitted characters in filenames, and unsupported characters get replaced with underscores automatically. This can create confusion if your system generates filenames with characters outside the whitelist.

Rate limiting and batch processing constraints affect how you design your data synchronization strategy. You cannot stream continuous updates in real-time. Instead, you batch operations and submit them periodically. Determine appropriate batch sizes that balance efficiency against error handling complexity. Larger batches process more efficiently but make error diagnosis harder when something fails.

Error recovery needs thoughtful design because batch processing creates asynchronous failure modes. When a job fails, you need to detect the failure, parse error messages, determine which records caused problems, and decide whether to retry the entire batch or just the failed records. Your integration should implement exponential backoff for transient failures while permanently failing for validation errors that won't resolve through retries.

Testing strategies require access to DATEV sandbox environments. The API specification shows separate endpoints for sandbox testing. Use these extensively before deploying to production. Test with various client configurations, different fiscal year setups, and edge cases in your data. Remember that DATEV may automatically generate subsequent fiscal years under certain conditions, so test your integration's behavior when fiscal year transitions occur.

Final Recommendations

DATEV integration is fundamentally different from typical REST API integration work. The batch-processing architecture, strict format requirements, and certification processes create complexity that shouldn't be underestimated. Before starting development, evaluate your technical resources honestly. Do you have developers with experience in batch processing systems? Can you invest time in understanding DATEV's specific format requirements? Do you need features that unified API providers don't expose?

For most teams, starting with a unified API provider offers the fastest path to a working integration. You can always migrate to direct DATEV integration later if specific requirements demand it. Focus initially on understanding the business workflows, data mapping requirements, and error handling strategies. These concerns remain constant regardless of whether you integrate directly or through middleware.

Document your integration thoroughly, especially the format specifications and validation requirements. Future developers maintaining your integration will need this context. Build comprehensive error logging from day one because diagnosing batch processing failures requires detailed audit trails.

DATEV integration enables powerful accounting automation, but success requires respecting the architectural constraints and compliance requirements that make DATEV the trusted standard for German accounting workflows.

Bank Feeds API Integration: Why You Can’t Afford to Skip This Feature

𝚂𝚊𝚞𝚛𝚊𝚋𝚑 𝚁𝚊𝚒 — Fri, 31 Oct 2025 14:27:10 +0000

Your corporate card product is brilliant. Your business banking app solves real problems. Your expense management platform beats the competition on features and pricing.

But then a prospect asks: "Does this sync with our Xero account?"

And suddenly, you're explaining why users need to export CSVs and manually upload bank statements to their accounting system. The demo goes cold. The deal stalls. Your competitor with the bank feed integration wins the business.

This happens every day to fintech companies that treat bank feeds as a "nice to have" feature. The reality? For finance teams, bank feeds are table stakes. Without them, you're asking users to do work that could be automated via an API integration.

Here's how to fix that.

What Bank Feeds Actually Do (And Why Your Customers Demand Them)

Bank feeds automatically send transaction data from your platform into users' accounting systems, removing the need for CSV uploads and manual entry. The data flows directly from your product into Xero, QuickBooks, or NetSuite as transactions happen.

The primary reason finance teams care about bank feeds is reconciliation. When transactions appear automatically in accounting software, users can match them against invoices, bills, and other entries to close their books faster and with more confidence.

Manual reconciliation involves downloading a CSV or OFX file, reforming the columns, uploading it to their accounting system, and then manually matching each transaction. This takes hours. It creates errors. Finance teams hate it.

Bank feeds eliminate all of that. The transaction happens. Data appears in the accounting system. User clicks to reconcile. Done.

Bank feeds are especially valuable for financial platforms that handle money movement: corporate card providers, business banking apps, expense tools, payout platforms, and accounting automation products. If your product processes transactions on behalf of business customers, those transactions need to flow into their ledger.

While fintechs offer great integrations for accounting software, they traditionally lack access to the resources, APIs, and partnerships required to provide the "bank-like" experience small businesses expect. That's changing, but the expectation exists. Your users want the same experience they get from their bank: automatic feeds, no manual work.

The Use Cases That Actually Drive Revenue

Let's get specific about where bank feeds matter most.

Corporate Cards and Expense Management

Your users swipe corporate cards. Those transactions need to appear in their accounting system the same day, not next week, after someone exports a spreadsheet.

For complete reconciliation, you need two integrations: accounting sync for expenses AND bank feeds for the actual bank transactions. Without both, users still do manual work.

Example: Employee buys office supplies with the company card. Transaction hits your platform. Bank feed sends it to QuickBooks. The finance team opens QuickBooks, sees the transaction, and matches it to the expense report. Approved in 30 seconds instead of 30 minutes.

Business Banking and Neobanks

Fintechs can deliver a bank-like experience by automating the upload of transaction statements to the general ledger for reconciliation. This is what banks do. If you're competing with banks, you need to do it too.

Arc, a fintech company serving startups with treasury management and revenue-based financing, put it clearly: "We offer customers deposit accounts that serve as the core of how they run their business. It's critical for our customers to sync that data to their accounting systems."

Without bank feeds, your business banking app feels incomplete. With them, you're offering the full package.

Bill Pay and AP Automation

Push bill pay transactions to accounting systems for real-time payables reconciliation. When your platform pays a vendor invoice, that payment should appear in the customer's accounting system immediately.

This closes the loop on accounts payable. Your app initiates payment. Bank feed confirms it happened. The accounting system marks the bill as paid. No manual matching required.

Treasury Management

Treasury teams need real-time cash position visibility across multiple bank accounts. Bank feeds provide the data they need to forecast cash flow, manage liquidity, and make funding decisions.

For companies managing cash across subsidiaries or multiple currencies, automated bank feeds make daily treasury operations possible without building custom integrations for every bank account.

Why Direct Integration Is a Nightmare

You might think: "We'll just build a direct integration with Xero. How hard can it be?"

Very hard. Here's why.

Xero's Bank Feeds API is a closed API only available to financial institutions with an established partnership with Xero. You can't just sign up and start using it. You need to:

Apply to become a Xero financial services partner
Wait for approval (no guarantees)
Go through certification process (takes months)
Get your application certified for bank feeds access

That's just for Xero. Now repeat this process for QuickBooks, NetSuite, Sage Intacct, MYOB, and every other accounting platform your customers use.

Each platform has different APIs. Different authentication flows. Different data models. Different certification requirements. Different ongoing maintenance needs.

The math gets ugly fast:

3-6 months per integration
5 major platforms
= 15-30 months of development time
Plus ongoing maintenance when APIs change
Plus customer support for auth issues
Plus compliance and security reviews

And during those 15-30 months, you're not building your core product. You're managing OAuth flows and debugging webhook failures.

Most fintech companies don't have that time. The market moves too fast.

How Apideck Solves the Bank Feed Problem

A unified API aggregates multiple APIs in the same category into a single standardized endpoint with unified authentication and normalized data models. Instead of building 20 separate integrations, you build one.

For bank feeds, this means:

One Integration, Multiple Platforms

Apideck's Accounting API provides a single REST interface to sync data across 20+ accounting platforms. You write your bank feed integration once. It works with Xero, QuickBooks, NetSuite, Sage Intacct, and dozens of other systems.

Your code stays the same. Apideck handles the platform-specific details.

Authentication That Actually Works

Apideck Vault handles OAuth flows and stores credentials securely with enterprise-grade security. Your users connect their accounting system through a white-label interface. They never see your API keys. You never manage their tokens.

The same authentication flow works for every platform. No custom OAuth implementations per provider.

Maintenance You Don't Have to Do

Apideck handles connector updates, API versioning, and provider-specific changes without requiring code changes in your application. When QuickBooks ships a breaking change or Xero updates authentication requirements, Apideck updates the connector. Your code keeps working.

This is huge. Direct integrations break constantly. APIs change. Partners add new requirements. Version deprecations happen with 60 days' notice. With Apideck, that's not your problem anymore.

Normalized Data Models

Apideck normalizes messy, inconsistent APIs into a single structure while still exposing raw downstream information. Every platform uses different field names and data formats. Apideck translates between your standard format and whatever the downstream API expects.

You send the same JSON payload for bank transactions. Apideck converts it to QBXML for QuickBooks Desktop, REST for Xero, or whatever format NetSuite needs. You don't care about implementation details.

Technical Implementation: Xero Bank Feeds with Apideck

Let's get into the actual code. Here's how you implement bank feeds for Xero using Apideck's unified API.

Prerequisites

You still need Xero Bank Feeds API certification. Apideck can't bypass that requirement because it's a partnership between you and Xero. But once you're certified, Apideck handles everything else.

Step 1: Create a Bank Feed Account

The Bank Feed Accounts endpoint in Apideck's Accounting API corresponds to Xero's Feed Connections API and links your platform's accounts to bank or credit card accounts in Xero.

POST to https://unify.apideck.com/accounting/bank-feed-accounts with this payload:

{
  "source_account_id": "corp-card-001",
  "target_account_number": "12345676",
  "target_account_name": "Corporate Card Account",
  "bank_account_type": "bank",
  "currency": "USD"
}

If the bank account already exists in Xero, use target_account_id instead of name and number to link it. If not, provide target_account_name and target_account_number so Xero creates a new account.

The response gives you a bank_feed_account_id:

{
  "data": {
    "id": "55af487b-df2b-425e-9432-ea2db7a77481"
  }
}

Store this ID. You'll need it for every transaction batch you send.

Step 2: Send Bank Transactions

The Bank Feed Statements endpoint lets you send a batch of transactions tied to the bank_feed_account_id created earlier.

POST to https://unify.apideck.com/accounting/bank-feed-statements:

{
  "bank_feed_account_id": "55af487b-df2b-425e-9432-ea2db7a77481",
  "start_date": "2025-05-01T00:00:00.000Z",
  "end_date": "2025-05-15T23:59:00.000Z",
  "start_balance": 100.0,
  "start_balance_credit_or_debit": "credit",
  "end_balance": 142.0,
  "end_balance_credit_or_debit": "credit",
  "transactions": [
    {
      "posted_date": "2025-05-02T01:00:00.000Z",
      "description": "Office Supplies - Staples",
      "amount": 47.23,
      "credit_or_debit": "debit",
      "source_transaction_id": "txn_1019",
      "counterparty": "Staples Inc",
      "reference": "INV-20250502",
      "transaction_type": "payment"
    },
    {
      "posted_date": "2025-05-03T09:30:00.000Z",
      "description": "Client Payment - ACME Corp",
      "amount": 89.23,
      "credit_or_debit": "credit",
      "source_transaction_id": "txn_1020",
      "counterparty": "ACME Corp",
      "reference": "Invoice-445",
      "transaction_type": "payment"
    }
  ]
}

Best practices: Send statements in chronological order, ensure balances align correctly (Xero validates them), and avoid gaps or overlaps in statement periods to prevent rejections.

Step 3: Users Reconcile in Xero

Once the statement is successfully uploaded, transactions appear in Xero under the connected bank account where users reconcile them using Xero's standard process by matching each line to invoices, bills, or other records.

This creates the workflow your finance users expect: your platform sends transactions, Xero handles reconciliation. By automating this flow, you help users maintain accurate books with minimal manual effort.

You can send feeds daily, weekly, or on-demand. Most products send daily updates to keep accounting systems current.

Beyond Xero: Multi-Platform Support

Xero is live and fully supported. But your customers use other accounting systems too, we're actively adding support for more platforms.

SaaS companies typically need multiple accounting integrations to serve diverse customer bases: UK-focused customers use Xero, US SMBs prefer QuickBooks, and enterprise clients require Sage Intacct.

Apideck supports 20+ accounting platforms, including QuickBooks, NetSuite, Sage Intacct, MYOB, Microsoft Dynamics 365 Business Central, FreshBooks, and Exact Online. The same unified API works across all of them.

Different platforms use different formats for bank feed data. While Xero uses its proprietary Bank Feeds API, NetSuite commonly relies on the OFX (Open Financial Exchange) format for importing bank statements. OFX is a standardized format that many banks and financial institutions use to exchange transaction data. If you're building for NetSuite users, understanding OFX formatting becomes important for smooth data imports. Learn more about importing bank statements into NetSuite using OFX format at DocuClipper's guide.

Right now, bank feeds are fully implemented for Xero. Support for additional platforms is expanding. The architecture is already there. The API endpoints are the same. As Apideck adds bank feed support to more connectors, your integration automatically gains access to those platforms.

This matters because you can't predict which accounting system your next big customer will use. Building flexibility into your integration strategy now saves months of work later.

The Bottom Line for Decision Makers

Bank feeds separate products that finance teams actually adopt from products that get evaluated and rejected.

If you're building a fintech product that handles money movement, you need bank feeds. Not eventually. Now.

The choice is:

Build direct integrations to 5-10 accounting platforms over 18-24 months
Use a unified API and ship bank feeds in a few weeks

Development teams can implement accounting integrations in weeks rather than months using unified APIs with standardized webhooks, consistent error handling, and unified documentation that eliminates the complexity of learning multiple provider-specific APIs.

Apideck gives you:

One integration for 20+ accounting platforms
Managed authentication and credential storage
Automatic handling of API changes and updates
Production-ready bank feeds for Xero (with more platforms coming)
Real-time data processing with no batching delays

Next Steps

Ready to add bank feeds to your product?

For Xero Bank Feeds: Start with the detailed technical guide at developers.apideck.com/guides/bank-feeds-xero

For the Full Accounting API: Explore all endpoints and connectors at developers.apideck.com/apis/accounting

To Try It Out: Sign up for a free Apideck account and get 2,500 API calls to test your integration. No credit card required.

To Talk Strategy: Book a demo if you're evaluating unified APIs for your product roadmap. The Apideck team can walk you through your specific use case and integration requirements.

The fintech companies winning deals right now are the ones that solved bank feeds months ago. Stop building one-off integrations. Ship bank feeds this quarter instead of next year.

Your finance team users will thank you.

How to Connect with the HubSpot API

𝚂𝚊𝚞𝚛𝚊𝚋𝚑 𝚁𝚊𝚒 — Thu, 30 Oct 2025 16:43:28 +0000

HubSpot's API looks modern on the surface. REST endpoints, JSON payloads, OAuth 2.0, webhooks. Then you actually build something with it and discover the truth: it's a maze of rate limits, undocumented quirks, and lifecycle stage logic that defies human comprehension.

I've spent the last three years integrating HubSpot for various clients. Here's what the documentation won't tell you and what will save you from the same pain I went through.

The OAuth Dance Nobody Warns You About

HubSpot uses OAuth 2.0, which sounds standard until you realize their implementation has its own special flavor. You need three things before you even start: a developer account (separate from your regular HubSpot account), an app registration, and the patience of a saint.

First, create your app at developers.hubspot.com. You'll get a Client ID and Client Secret. Guard that secret like your life depends on it, because regenerating it will break every existing integration.

Here's the authorization URL you need to build:

const authUrl = `https://app.hubspot.com/oauth/authorize?` +
  `client_id=${CLIENT_ID}&` +
  `redirect_uri=${encodeURIComponent(REDIRECT_URI)}&` +
  `scope=crm.objects.contacts.read%20crm.objects.contacts.write`;

But wait, there's a catch nobody mentions: the redirect URI must match EXACTLY what you registered. Not just the domain, not just the path, but every single character, including trailing slashes. Get it wrong and you'll see a generic error that tells you nothing.

When the user approves, HubSpot redirects back with a code. You have exactly 30 seconds to exchange it for tokens, or it expires:

const tokenResponse = await fetch('https://api.hubapi.com/oauth/v1/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    redirect_uri: REDIRECT_URI,
    code: authCode
  })
});

const { access_token, refresh_token } = await tokenResponse.json();

Most access tokens are short-lived. You can check the expires_in parameter when generating an access token to determine its lifetime (in seconds). Practically you have a few minutes before they expire.

Here's the refresh logic you'll need running constantly:

async function refreshAccessToken(refreshToken) {
  const response = await fetch('https://api.hubapi.com/oauth/v1/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      refresh_token: refreshToken
    })
  });

  if (!response.ok) {
    // Refresh token is dead, user needs to reauthorize
    throw new Error('Token refresh failed - user must reauthorize');
  }

  return await response.json();
}

You can read more about the refresh access token logic from the HubSpot documentation here.

Rate Limiting: The 429 Error Festival

HubSpot's rate limits are documented, but what they don't tell you is how aggressive they are. You get 100 requests per 10 seconds for public apps. That sounds like a lot until you realize that's shared across ALL your users if you're using a single app registration.

However, you can upgrade the number of calls your app can make, which is based on your account subscription in the account it's installed in. Here's the plan details from the HubSpot Documentation:

[IMAGE: Rate limit table by subscription tier]

Here's what a 429 error looks like when you hit the limit:

{
  "status": "error",
  "message": "You have reached your secondly limit",
  "errorType": "RATE_LIMIT",
  "correlationId": "c033cdaa-2c40-4a64-ae48-b4cec88dad24",
  "policyName": "TEN_SECONDLY_ROLLING"
}

The worst part? HubSpot counts requests that fail against your rate limit. So when you hit the limit and retry immediately, you're making it worse. You need exponential backoff or you'll be stuck in 429 hell forever:

async function makeHubSpotRequest(url, options, retryCount = 0) {
  const response = await fetch(url, options);

  if (response.status === 429) {
    if (retryCount >= 5) {
      throw new Error('Max retries exceeded');
    }

    // Exponential backoff: 1s, 2s, 4s, 8s, 16s
    const delay = Math.pow(2, retryCount) * 1000;
    console.log(`Rate limited. Waiting ${delay}ms before retry...`);

    await new Promise(resolve => setTimeout(resolve, delay));
    return makeHubSpotRequest(url, options, retryCount + 1);
  }

  if (!response.ok) {
    throw new Error(`HubSpot API error: ${response.status}`);
  }

  return response.json();
}

But here's the real kicker: if you're using Make.com, Zapier, or any integration platform, you're sharing rate limits with every other customer using their HubSpot connector. I've seen perfectly reasonable workflows fail at 2 AM because someone else's integration went haywire. The only solution is to create your own OAuth app and use their "advanced" connection option.

The Lifecycle Stage Nightmare

HubSpot's lifecycle stages are supposed to track where contacts are in your sales process. In reality, they're a one-way street designed by someone who's never had to fix bad data.

Lifecycle stages can only move forward by default. Lead to Customer? Fine. Customer back to Lead because they canceled? Nope. You have to clear the field first, then set the new value in a separate API call:

// This won't work - lifecycle stage can't go backwards
await updateContact(contactId, { lifecyclestage: 'lead' }); // Fails silently

// This is what you actually need
await updateContact(contactId, { lifecyclestage: '' }); // Clear it first
await updateContact(contactId, { lifecyclestage: 'lead' }); // Now set it

async function updateContact(contactId, properties) {
  return makeHubSpotRequest(
    `https://api.hubapi.com/crm/v3/objects/contacts/${contactId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ properties })
    }
  );
}

That's two API calls for one field update, doubling your rate limit usage. And it gets worse: the batch API doesn't guarantee order, so you can't clear and set in the same batch request. Every backwards lifecycle stage movement costs you two separate API calls.

Oh, and those "Became a [stage] date" properties? They're being deprecated. HubSpot announced this in 2024, but half of its documentation still references them. You now need to use their "calculated properties," which have their own special quirks and can't be set via API at all.

Custom Properties: The False Promise

HubSpot lets you create custom properties for anything. Sounds great until you realize that enumeration properties (dropdowns, checkboxes) have their own internal IDs that aren't the same as the labels you see in the UI.

You think you're setting a property to "Enterprise Customer," but HubSpot wants "enterprise_customer_7821" or something equally ridiculous. To find the internal values, you need to query the properties endpoint first:

const propertyResponse = await makeHubSpotRequest(
  'https://api.hubapi.com/crm/v3/properties/contacts/industry',
  {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  }
);

// Returns something like:
// {
//   "options": [
//     { "label": "Enterprise Customer", "value": "enterprise_customer_7821" },
//     { "label": "SMB Customer", "value": "smb_customer_9183" }
//   ]
// }

And don't even think about changing these values later. Every integration, workflow, and report using that property will break. I learned this when a client wanted to rename "Hot Lead" to "Qualified Lead" and it took three days to fix all the broken automations.

Webhooks: Death by a Thousand Subscriptions

HubSpot webhooks seem straightforward: subscribe to events, receive notifications. What they don't tell you is that webhooks are tied to your app, not individual accounts. Every customer using your app shares the same webhook URL.

Setting up webhooks requires a verified domain and HTTPS endpoint that can handle HubSpot's validation:

app.post('/webhook', (req, res) => {
  // HubSpot sends validation on setup
  if (req.headers['x-hubspot-signature']) {
    const signature = req.headers['x-hubspot-signature'];
    const sourceString = req.method + req.url + req.rawBody;
    const hash = crypto.createHash('sha256')
      .update(CLIENT_SECRET + sourceString)
      .digest('hex');

    if (hash !== signature) {
      return res.status(401).send('Invalid signature');
    }
  }

  // Process webhook events
  req.body.forEach(event => {
    console.log(`Event: ${event.eventType} for object ${event.objectId}`);
    // But which customer is this for? Good luck figuring that out
  });

  res.status(200).send();
});

The webhook payload doesn't include which account it's from. You get an object ID and have to make another API call (counting against your rate limit) to figure out whose data changed. With 100 customers, that's 100 extra API calls per webhook event.

The Undocumented Reality

Here's what HubSpot won't tell you but you need to know:

The API versions are complex. There's v1, v2, and v3 running simultaneously. Some endpoints only exist in v1 (looking at you, Engagements API), some features are v3 only, and they're deprecating v1 "soon" (they've been saying this for three years).

Private apps are not the same as OAuth apps. Private apps use API keys and are simpler but can't be distributed. OAuth apps can be shared but require the whole token dance. Choose wrong and you'll be rebuilding your integration from scratch.

The search API is basically useless. It has a different rate limit (4 requests per second), can't search all properties, and sometimes returns stale data. One client had contacts appearing in search results three hours after deletion. The only reliable way to find data is to pull everything and filter locally.

Error messages lie. You'll get "Contact already exists" when the real problem is a malformed email. You'll get "Invalid property value" when the property doesn't exist. Always log the full request and response because the error message alone won't help you debug.

Associations are their own special hell. Want to link a contact to a company? That's a separate API call. Want to see all contacts for a company? Another call. Want to update the association? You can't, you have to delete and recreate it. Each operation counts against your rate limit.

Making This Bearable with TypeScript

If you're building anything serious, use TypeScript. HubSpot's API responses are inconsistent and TypeScript will save you from runtime explosions:

interface HubSpotContact {
  id: string;
  properties: {
    email?: string;
    firstname?: string;
    lastname?: string;
    lifecyclestage?: string;
    [key: string]: string | undefined;
  };
  createdAt: string;
  updatedAt: string;
}

interface HubSpotError {
  status: 'error';
  message: string;
  correlationId: string;
  errorType?: 'RATE_LIMIT' | 'VALIDATION_ERROR' | 'NOT_FOUND';
}

class HubSpotClient {
  constructor(private accessToken: string) {}

  async getContact(id: string): Promise<HubSpotContact> {
    const response = await this.request<HubSpotContact>(
      `https://api.hubapi.com/crm/v3/objects/contacts/${id}`
    );
    return response;
  }

  private async request<T>(url: string, options: RequestInit = {}): Promise<T> {
    const response = await fetch(url, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.accessToken}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });

    if (!response.ok) {
      const error = await response.json() as HubSpotError;
      throw new Error(`HubSpot API Error: ${error.message}`);
    }

    return response.json() as Promise<T>;
  }
}

The Apideck Escape Hatch

Look, I've built enough HubSpot integrations to know when to quit. If you need HubSpot plus other CRMs (Salesforce, Pipedrive, etc.), stop building separate integrations and use a unified API.

Apideck's unified CRM API handles HubSpot's quirks so you don't have to. One integration instead of five, OAuth complexity handled, rate limiting managed across their infrastructure, and lifecycle stage nonsense abstracted away. Your 6-week HubSpot integration can be done easily within two weeks of actual coding. And not only this, you can configure other CRMs as well.

Apideck's CRM Unified API

// Direct HubSpot API: OAuth dance, token refresh, rate limiting, lifecycle stage hell
// Apideck: Just this

import { Apideck } from '@apideck/node';

const apideck = new Apideck({
  apiKey: process.env.APIDECK_API_KEY,
  appId: process.env.APIDECK_APP_ID,
  consumerId: 'customer-123' // Your customer's ID
});

// Create a contact in HubSpot (or any CRM they've connected)
async function createContact() {
  try {
    const contact = await apideck.crm.contactsAdd({
      serviceId: 'hubspot', // Or 'salesforce', 'pipedrive', etc.
      contact: {
        firstName: 'John',
        lastName: 'Doe',
        email: 'john@example.com',
        phoneNumbers: [{ number: '+1-555-1234', type: 'work' }],
        // Lifecycle stage just works - no backwards movement BS
        lifecycleStage: 'lead',
        customFields: [
          { id: 'industry', value: 'Technology' }
        ]
      }
    });

    console.log('Contact created:', contact.data.id);
  } catch (error) {
    // Actual useful error messages
    console.error('Error:', error.message);
  }
}

// Get all contacts with pagination handled automatically
async function getAllContacts() {
  const contacts = await apideck.crm.contactsAll({
    serviceId: 'hubspot',
    filter: {
      email: 'john@example.com'
    }
  });

  // No manual pagination, no rate limit management
  for await (const contact of contacts) {
    console.log(contact.name, contact.email);
  }
}

// The same code works for ANY CRM - just change serviceId
async function syncToMultipleCRMs(contactData) {
  const crms = ['hubspot', 'salesforce', 'pipedrive'];

  for (const crm of crms) {
    await apideck.crm.contactsAdd({
      serviceId: crm,
      contact: contactData
    });
  }
  // That's it. No OAuth per platform, no different APIs, no rate limit juggling
}

Compare that to the 200 lines of OAuth handling, rate limit retry logic, and lifecycle stage workarounds you need for direct HubSpot integration. One API, consistent data models, errors that actually make sense.

Tangible benefits that matter:

Unified API for all CRM platforms
One integration for HubSpot, Salesforce, Pipedrive, and 50+ others
Field mapping that actually works - Including HubSpot's lifecycle stages and custom properties
No more OAuth gymnastics - They handle token refresh, expiration, all of it

Ship Something That Works

HubSpot's API is powerful but exhausting. You'll spend more time handling edge cases than building features. Every integration starts simple and ends with dozens of workarounds for HubSpot's peculiarities.

My advice? Start with the smallest possible integration. Get OAuth working. Make one API call successfully. Handle rate limits properly. Only then add more complexity. And when you inevitably hit the wall where you're spending more time fighting HubSpot than building your product, consider whether a unified API makes more sense.

The perfect HubSpot integration doesn't exist. Ship something that works, iterate based on which errors your customers actually hit, and keep a bottle of whiskey handy for when HubSpot changes something without warning.

Because they will, they always do.

MCP vs API

𝚂𝚊𝚞𝚛𝚊𝚋𝚑 𝚁𝚊𝚒 — Thu, 16 Oct 2025 11:22:21 +0000

MCP vs API: What’s the Actual Difference and When to Use Each

If you’re building with AI in 2025, you’ve probably heard about the Model Context Protocol (MCP). But here’s what nobody’s telling you straight: MCP doesn’t replace APIs - it makes them work better with AI. Let’s cut through the noise and understand what actually matters.

The Problem MCP Solves

Remember the USB cable mess before USB-C? That’s where we were with AI integrations. Every AI model requires custom connectors for each data source, an expensive nightmare that Anthropic calls the “M×N problem.”

Traditional APIs are ideal for developers who read documentation and write integration code. But AI agents? They’re different. They need to understand the existing tools, how to use them, and maintain context across multiple operations. That’s where MCP comes in.

MCP vs Traditional APIs: The Core Difference

APIs are for developers. MCP is for AI agents.

When you use a REST API, you manually check the documentation, understand endpoints, and write code to call /users/123 or POST /orders. It’s explicit, predictable, and stateless - each request stands alone.

MCP flips this. Instead of you reading docs, the AI asks the MCP server, “What can I do here?” and gets back a list of capabilities it can understand. Instead of stateless requests, MCP maintains sessions that remember context across multiple operations.

Think of it this way: APIs are like individual Lego blocks. MCP is the instruction manual that helps AI figure out which blocks to use and how to combine them.

The Technical Reality (Without the Jargon)

Traditional APIs use HTTP methods (GET, POST, etc.) mapped to resources. You call specific endpoints, get responses, done. They’re stateless by design - perfect for scaling but requiring you to manage any context yourself.

MCP uses JSON-RPC 2.0 - a different approach where you call methods like “tools/call” with parameters. It maintains stateful sessions, so when an AI performs multiple actions, it understands they’re part of the same task. This session management is built in, not bolted on.

Here’s what makes this practical: When you tell an AI “book my flight and add it to my calendar,” MCP helps it discover both the flight API and calendar API, understand how to use them, and maintain context that these actions are related. The underlying services? Still REST APIs. MCP just adds the AI-friendly layer on top.

Comparison Table: MCP vs Traditional APIs

Aspect	Traditional APIs	MCP
Primary Users	Developers writing code	AI agents and LLMs
Discovery	Read the documentation manually	Automatic capability discovery
State Management	Stateless (each request independent)	Stateful sessions with context
Protocol	REST, GraphQL, gRPC	JSON-RPC 2.0
Integration Approach	Explicit endpoint mapping	Dynamic tool discovery
Maturity	Battle-tested, decades old	Emerging (launched Nov 2024)
Scalability	Horizontal scaling built-in	Session management challenges
Best For	Direct integrations, mobile apps, microservices	AI orchestration, multi-step automation
Security	Established patterns (OAuth2, JWT)	Still evolving
Context Handling	Developer manages manually	Built-in conversation context

The Unified API Connection

Here’s where it gets interesting for integration pros. Companies like Apideck, Unified.to, Codat, and Rutter built unified APIs to solve the integration sprawl problem - one API to connect to hundreds of services. Now we’re seeing Unified MCPs emerge.

A Unified MCP works like a unified API but for AI agents. Instead of your AI needing separate MCP connections to Salesforce, HubSpot, and Pipedrive, it connects to one Unified MCP that handles all CRM systems. Same concept, different consumer.

For companies like Apideck that already aggregate APIs, adding an MCP layer is the logical next step. You’ve already solved the hard part - normalizing data across providers. Now you’re just making it AI-accessible. This creates a powerful stack: unified APIs for developers, unified MCPs for AI agents, all backed by the same normalized data layer.

When to Actually Use Each

Use traditional APIs when:

Building mobile or web applications
Creating microservice architectures
Processing payments or high-frequency trades
You need predictable, deterministic behavior
Performance and scaling are critical

Use MCP when:

Building AI assistants or agents
Orchestrating multi-step workflows via natural language
Creating development copilots
Exposing existing APIs to LLM-powered applications
Users express intent conversationally, not programmatically

Use both when: You’re smart. MCP servers typically wrap REST APIs. Your API handles the actual operations; MCP makes them AI-friendly. It’s not either/or - it’s using the right tool for the right job.

The Bottom Line

MCP isn’t replacing APIs any more than Uber replaced cars - it’s just a smarter way to use them for AI applications. APIs remain the backbone of digital infrastructure. MCP adds the intelligence layer that lets AI agents work with those APIs effectively.

For developers, this means your API skills aren’t obsolete - they’re more valuable. You’ll build REST APIs for core services, then potentially add MCP servers to make them AI-accessible. For businesses, it means AI agents can finally integrate with your existing tools without armies of developers writing custom connectors.

Stop overthinking whether MCP will “disrupt” APIs. Start thinking about how to use both strategically. Your existing APIs aren’t going anywhere. But if you want AI to use them intelligently, MCP is how you make that happen.

Next Steps

Keep building robust APIs - they’re still the foundation
Experiment with MCP for AI-facing services
Watch unified MCP providers - they’ll simplify AI integrations like unified APIs simplified SaaS integrations
Focus on the user need, not the technology hype

The future isn’t MCP versus APIs. It’s MCP plus APIs, working together to make AI actually useful instead of just impressive.

Understanding the security landscape of MCP

𝚂𝚊𝚞𝚛𝚊𝚋𝚑 𝚁𝚊𝚒 — Tue, 12 Aug 2025 09:30:00 +0000

The State of MCP Security in 2025: Key Challenges and Emerging Defenses

Model Context Protocol (MCP) is becoming the standard for communication and operation between external applications, LLMs, and AI agents. Think of it like USB-C, a standard and a protocol for communication and power transfer. MCPs are also a standard for communication between large language models (LLMs) and other applications, databases, etc.

It hasn’t been a year (MCP was introduced in November 2024), and the adoption of the protocol has been great so far. We are seeing a wide adoption from giant corporations like Atlassian, AWS, Google, GitHub, Cloudflare, and Supabase. etc., they all have their MCPs available to try and download. And more enterprises are looking forward to being more AI-ready by building MCPs for their LLM stack. As of January 2025, more than 1000 community-made MCPs are available for end-users to try. Model Context Protocol is becoming the standard for enabling data in apps to communicate with LLMs.

While the hype and adoption are going great, we also need to consider the security, vulnerability, and other issues associated with MCPs. While APIs have been around for more than a decade, we’ve developed security patterns, rate-limiting, and other measures. MCPs must undergo cycles of improvement on the security front. The current goal is to discuss security issues in MCPs and raise awareness among readers.

The Core Security Challenge: The "Confused Deputy" Problem

The confused deputy is a classic security flaw that is highly relevant to MCP. An MCP server, acting on behalf of a user, might have more permissions than the user. An attacker could potentially trick the LLM into requesting that the MCP server execute with its elevated privileges, leading to unauthorized actions. For example, an LLM could be manipulated into telling a high-privilege MCP server to delete a file that the user shouldn't have been able to delete. The AI doesn't realize it's being manipulated because the malicious instructions come through normal channels like tool descriptions, user inputs, or data it reads from files.

Prompt Injection Vulnerabilities

This is a major attack vector for any LLM-based application, and MCP creates new opportunities for it. Attackers can embed malicious instructions in documents, emails, or any data that the MCP processes. When the AI reads this content, it interprets the hidden commands as legitimate instructions. Some of the common tricks for prompt injection are:

Hijack the AI's behavior: Make the model ignore previous instructions or perform unintended actions.
Data exfiltration: Trick the AI into revealing sensitive information it has access to through other MCP connections.
Trigger malicious actions: Instruct the AI to use one of its connected tools to send spam, delete data, or purchase items.

Supply Chain Risks and Unverified Third-Party Tools

Since anyone can develop an MCP server, there's a significant risk from unverified or malicious third-party tools. You can discuss the following points:

Malicious MCP Servers: Attackers could create and distribute MCP servers that appear legitimate but are designed to steal data, credentials, or execute malicious code.
Typosquatting: Similar to domain name typosquatting, an attacker could name their malicious MCP server something very similar to a trusted one, hoping users will mistakenly connect to it.
Lack of a Central Vetting Process: Unlike an app store, there isn't a universal, mandatory security review for all MCP servers. This places a heavy burden on users and organizations to vet the tools they use.

Tool Poisoning Attacks

Attackers embed malicious instructions within tool descriptions that are invisible to users but interpreted by AI models. These attacks can manipulate AI behavior to exfiltrate sensitive data, read SSH keys, or execute unauthorized system commands. The scary part is that these instructions can be hidden in any part of the tool definition, not just descriptions.

Credential and Token Exposure

MCP servers need to connect to various external services, and they often do so using API keys, OAuth tokens, and other credentials. This creates a centralized point of failure. If an MCP server is compromised, an attacker could gain access to all the credentials it stores, potentially giving them the "keys to the kingdom" to a user's or a company's various connected services (like email, cloud storage, code repositories, etc.).

Over-Privileged Access and Excessive Permissions

Developers of MCP servers might request broad permissions to make their tools as flexible as possible. This violates the principle of least privilege. An MCP server with read, write, and delete access to a user's entire email account, when it only needs to read subject lines, poses a significant and unnecessary risk.

Lack of Granular Monitoring and Auditing

Since MCP is in the early stage, it does not have robust, built-in mechanisms for detailed logging and auditing of all actions performed through it. This can make it difficult to detect malicious activity, investigate security incidents, and understand what data has been accessed or modified.

What makes this especially dangerous is that MCP servers often store tokens for multiple services all in one place. Suppose an attacker breaks into one MCP server. In that case, they potentially get access to your Gmail, Google Drive, Calendar, and everything else you've connected, creating what security researchers call a "keys to the kingdom" scenario.

What has been done so far?

A new specification was released on June 18, 2025, which introduces numerous features and clarifies that all MCP servers are classified as OAuth 2.0 Resource Servers.

Here are some of the details shared by the team on authorization:

Authorization Flow Architecture

Key Roles:

MCP Server: Acts as an OAuth 2.1 resource server
MCP Client: Acts as an OAuth 2.1 client, making requests on behalf of users
Authorization Server: Issues access tokens (may be hosted with resource server or separately)
Implementation Requirements

Authorization Servers:

MUST implement OAuth 2.1 with security measures for both confidential and public clients
MUST provide OAuth 2.0 Authorization Server Metadata (RFC8414)
SHOULD support Dynamic Client Registration Protocol (RFC7591)

MCP Servers:

MUST implement OAuth 2.0 Protected Resource Metadata (RFC9728)
MUST use WWW-Authenticate header when returning 401 Unauthorized
MUST validate access tokens and ensure they were issued specifically for them
MUST NOT accept or transit tokens issued for other resources

MCP Clients:

MUST use OAuth 2.0 Authorization Server Metadata and Protected Resource Metadata
MUST parse WWW-Authenticate headers and respond to 401 responses
MUST implement PKCE (Proof Key for Code Exchange)
MUST include resource parameter in authorization and token requests (RFC 8707)
MUST NOT send tokens other than those issued by the MCP server's authorization server

Security Requirements

Token Security:

MUST use Authorization: Bearer header for all requests
MUST NOT include tokens in URI query strings
MUST validate token audience binding
MUST implement secure token storage
Authorization servers SHOULD issue short-lived access tokens

Communication Security:

All authorization server endpoints MUST use HTTPS
All redirect URIs MUST be either localhost or use HTTPS

Additional Protections:

MUST implement exact redirect URI validation
SHOULD use and verify state parameters
MUST obtain user consent for each dynamically registered client (for proxy servers)
MUST follow OAuth 2.1 security best practices

Security Best Practices shared by the MCP team at Anthropic

You can read the full specification for the security best practices shared here. It details how to implement the MCPs to avoid falling

Core Security Principles

Token Management:

MCP servers MUST NOT accept tokens that were not explicitly issued for the MCP server (avoid "token passthrough")
Always validate that tokens have the proper audience and were issued specifically for your MCP server

Authorization and Authentication:

MCP servers that implement authorization MUST verify all inbound requests
MCP servers MUST NOT use sessions for authentication
Always obtain proper user consent before accessing third-party services

Session Security

Session ID Generation:

MUST use secure, non-deterministic session IDs
SHOULD use secure random number generators (avoid predictable or sequential identifiers)
Consider rotating or expiring session IDs to reduce risk

Session Binding:

SHOULD bind session IDs to user-specific information
Use key formats like : to prevent impersonation
Combine session data with information unique to the authorized user
Proxy Server Security

Consent Management:

When using static client IDs with third-party services, MUST obtain user consent for each dynamically registered client
Implement proper consent flows to prevent confused deputy attacks

Implementation Guidelines

Security Controls:

Implement proper rate limiting, request validation, and traffic monitoring
Maintain clear audit trails and accountability mechanisms
Validate token claims (roles, privileges, audience) and metadata
Preserve trust boundaries between services

These practices are designed to prevent the three main attack vectors identified: confused deputy problems, token passthrough vulnerabilities, and session hijacking attacks.

Recent Security Issues for MCPs

The community has reported numerous security issues affecting top companies like GitHub and Supabase. These issues highlight that, despite its rapid adoption, the protocol's security is still maturing and requires immediate and careful attention from all developers.

GitHub MCP Exploit: The GitHub MCP exploit was discovered in May, allowing unauthorized access to private repositories and the ability to exfiltrate sensitive information. You can read about it in detail here.
Supabase MCP: The Supabase MCP was found to leak all of your private SQL database. Read the Hackernews discussion and the original article, showcasing the attack.
Asana MCP Workspace Data Leak: Asana’s MCP allowed users to look into other users’ workspaces. The company took two weeks to fix the issue, ensuring it doesn’t happen again. You can read about the fix and the incident here.
SQL Injection & Privilege Escalation: A single SQL injection bug in Anthropic’s SQLite MCP server (forked 5,000+ times) has enabled attackers to inject stored prompts, exfiltrate data, and escalate privileges within production agents. Many downstream agents, due to the use of unpatched code, remain vulnerable, amplifying both supply-chain and agent-wide compromise risks. Read about this here.
Command Injection in mcp-remote Proxy (CVE-2025-6514): JFrog researchers revealed a critical (CVSS 9.6) vulnerability in the popular mcp-remote project, used for integrating LLM hosts like Claude Desktop with remote MCP servers. A malicious MCP server can supply a crafted authorization endpoint to the client, resulting in arbitrary OS command execution on Windows and arbitrary executable run on Linux/macOS. The vulnerability affects mcp-remote versions 0.0.5–0.1.15 and is now fixed in 0.1.16. Users connecting to untrusted or insecure MCP servers are most at risk. Read about this here.

There are many more instances like these, where MCPs can result in new security vulnerabilities.

Conclusion

While the adoption of Model Context Protocol (MCP) is accelerating, it's crucial to address its inherent security risks. Vulnerabilities like prompt injection and token exposure can undermine the protocol's integrity. The new security specifications, based on OAuth 2.0, provide the necessary tools for defense. Ultimately, the long-term success of MCP hinges on developers consistently implementing these security best practices to create a safe and reliable ecosystem.

API Based RAG using Apideck’s Filestorage API, LangChain, Ollama, and Streamlit

𝚂𝚊𝚞𝚛𝚊𝚋𝚑 𝚁𝚊𝚒 — Mon, 11 Aug 2025 10:57:44 +0000

In previous articles, we explored the fundamentals of Retrieval-Augmented Generation (RAG) and demonstrated a practical implementation using FAISS, Hugging Face, and Ollama to chat with local data. In this article, we will take RAG a step further. We'll move beyond static vector databases to show how you can fetch information from diverse sources in real-time. This principle is already in effect in major AI assistants and chatbots. This approach is conceptually similar to how services like ChatGPT or Claude can connect to your Google Drive, OneDrive, or Dropbox, retrieving live data to answer your questions.

For instance, Claude allows users to connect directly to their live data sources, enabling its RAG system to search for real-time information.

Similarly, ChatGPT provides integrations for apps like Google Drive and Microsoft OneDrive, allowing it to retrieve and reason over your personal or work documents.

In the previous article, we demonstrated a complete Retrieval-Augmented Generation (RAG) pipeline. First, we sourced a dataset from Hugging Face and used the all-MiniLM-L6-v2 model to generate vector embeddings for the text. Next, we indexed these embeddings in a FAISS vector store. When a user asks a question, this system retrieves the most relevant information from the index through semantic search, providing the necessary context to generate a precise answer. This architecture is a classic example of a RAG system powered by a vector database.

That "classic" approach, however, is just one of many ways to build a RAG system. While vector search on a static document set is common, the true power of RAG lies in its flexibility and adaptability. The retrieval strategy can be adapted to many different data types and needs:

Vector Search: The method we used previously. Finds data based on conceptual similarity.
Lexical Search: Traditional keyword-based search (e.g., BM25) that excels at matching specific terms.
Hybrid Search: A powerful combination of both vector and lexical search for balanced results.
Structured Retrieval: Querying structured sources like databases (using SQL) or knowledge graphs.
API-based Retrieval: A dynamic approach where the system calls an external tool or API to fetch live information, rather than relying on a pre-built, static index.

In this article, we will focus on the powerful API-based retrieval method. Our goal is to build a system that utilizes the file-storage API to select files directly from Box.com, then feed their content to an LLM to generate summaries in real-time.

File Storage API

The file storage API provides a unified interface for major online storage platforms, including Box, Google Drive, OneDrive, Dropbox, and SharePoint.

Instead of juggling multiple APIs for different storage providers, the file storage API provides a single endpoint for pushing and pulling data across all these systems. Think of it like how Claude and ChatGPT handle app connections; it uses a secure vault for authorization, then provides seamless access to list and download files from your connected storage. Our objective is to: fetch a list of available files, select the relevant ones, and download them for data summarization. Since all Apideck APIs share the same base: https://unify.apideck.com, which then branches into specific unified endpoints like /accounting, /file-storage, and /ats. For our purposes, we'll work with https://unify.apideck.com/file-storage.

To keep things simple, we're focusing exclusively on the Box.com connector and its file operations. All our operations will use the base URL: https://unify.apideck.com/file-storage/, with Apideck handling the underlying complexity.

Here's how Apideck’s file-storage API works

The File Storage API is a unified API gateway that connects to multiple applications providing document storage. Suppose a developer has to create a service that connects to Google Drive, SharePoint, and Box. In that case, they have to build and maintain three separate connectors, each with different data fields and authentication logic. This is a major overhead. Apideck solves this by providing a simple, unified API structure. It handles maintaining the connectors and mapping the different data models, so for the developer, the API endpoint is always the same.

Take this example: the base URL is always https://unify.apideck.com. For the File Storage API, you add the path, like /file-storage/files/{id}. This consistency makes managing the APIs much easier.

All calls, whether to Box, Google Drive, or SharePoint, go through the same Apideck endpoint. Apideck uses a set of simple headers to direct the request to the right place. That’s it. Apideck handles the rest.

Here’s what a real API call to download a file looks like using curl:

curl --request GET \
      --url https://unify.apideck.com/file-storage/files/{file_id}/download \
      --header 'Authorization: Bearer YOUR_API_KEY' \
      --header 'x-apideck-app-id: YOUR_APP_ID' \
      --header 'x-apideck-consumer-id: a_user_id_from_your_app' \
      --header 'x-apideck-service-id: box'

Authorization: Your secret Apideck API key.
x-apideck-app-id: The ID of your application in Apideck.
x-apideck-consumer-id: The ID of the end-user in your system.
x-apideck-service-id: This is where you specify which service to use, like Box, Google Drive, or SharePoint.

Now let’s talk about authentication, how to get access to the box via APIs.

How does our application get permission to access a user's files in the first place?

Handling authentication for services like Box or Google Drive can be complex. Each has its own OAuth 2.0 flow, requiring you to manage redirects, handle callbacks, and securely store sensitive access and refresh tokens. Building this for multiple providers is not just a development challenge; it’s a significant security responsibility.

This is where Apideck Vault comes in. Vault acts as a secure, isolated container that manages the entire authentication process on your behalf. You can direct your users to a pre-built, secure UI called Hosted Vault, where they can safely log in to their Box or Google Drive accounts. Vault handles the entire OAuth handshake and securely encrypts and stores the user's credentials, completely abstracting them away from your application. Your system then only needs to reference the user's consumer_id in your API calls, as shown in the example above. This approach drastically simplifies development and enhances security, as your application never has to handle or store the end-user's sensitive API tokens. You can read about the vault here.

Core Functionality Overview

Our system follows a simple workflow: The app first fetches a list of files present on the active connectors (Box in our case). We fetch and display the files available in the Box connector on our dashboard. The user selects a specific file from a drop-down list in the app. The app then downloads the selected file. Once the file is downloaded, the AI generates a summary of its content, which is delivered to the user.

Technical Requirements

A free Apideck account. Python 3.12+ installed in your system. Basic understanding of how virtual environments, requests, etc. works in Python. Knowledge of LangChain, LLM basics, and how APIs work would help in better understanding the project.

Setting up the Environment

Before we dive into the code, we need to handle our credentials securely. Create a .env file in the root of your project directory. This file will store the API keys that our application needs to connect to Apideck.

    APIDECK_API_KEY="sk_live_..."
    APIDECK_APP_ID="YOUR_APP_ID..."
    APIDECK_CONSUMER_ID="test-consumer"

You can get your API_KEY and APP_ID directly from your Apideck dashboard under the API Keys section. The CONSUMER_ID is a unique identifier for the end-user of your application; for this demo, we can just use a static value like test-consumer.

The Coding Workflow

Our application logic is split into two main utility files: apideck_utils.py for handling the file storage connection, and llm_utils.py for processing the documents with our AI model. The full code can be found in this GitHub repository.

Connecting to Apideck (apideck_utils.py)

The code for this file can be found here.

    import requests
    from apideck_unify import Apideck

    def fetch_file_list(api_key, app_id, consumer_id, service_id="box"):
"""Fetches a list of files from the specified service."""
try:
    with Apideck(
api_key=api_key, app_id=app_id, consumer_id=consumer_id
    ) as apideck:
response = apideck.file_storage.files.list(service_id=service_id)
if response.get_files_response and response.get_files_response.data:
    return response.get_files_response.data
else:
    print("No files found or an issue occurred.")
    return []
except Exception as e:
    print(f"An error occurred while fetching file list: {e}")
    return []

    def download_file(file_id, file_name, api_key, app_id, consumer_id, service_id="box"):
"""Downloads a specific file and saves it locally."""
try:
    download_url = (
f"https://unify.apideck.com/file-storage/files/{file_id}/download"
    )
    headers = {
"Authorization": f"Bearer {api_key}",
"x-apideck-app-id": app_id,
"x-apideck-consumer-id": consumer_id,
"x-apideck-service-id": service_id,
    }

    response = requests.get(download_url, headers=headers, allow_redirects=True)
    response.raise_for_status()
    with open(file_name, "wb") as f:
f.write(response.content)

    print(f"Successfully downloaded '{file_name}'")
    return file_name

except requests.exceptions.RequestException as e:
    print(f"An error occurred during download: {e}")
    return None
except Exception as e:
    print(f"An unexpected error occurred: {e}")
    return None

This file is our bridge to the Apideck File Storage API. It contains two core functions:

fetch_file_list(): This function initializes the Apideck SDK with our credentials and calls the file_storage.files.list() endpoint. It simply asks Apideck to return a list of all files available in the connected Box account and gives us back a clean list of file objects, including their names and unique IDs.
download_file(): Once we have a file's ID, this function takes over. As we discovered during development, the most reliable way to handle downloads is to make a direct HTTP request to the download endpoint. The function constructs the specific URL (https://unify.apideck.com/file-storage/files/{id}/download) and includes the necessary authentication headers (Authorization, x-apideck-app-id, etc.). It then uses the requests library to fetch the file, automatically handling any redirects from Apideck's servers to Box's content servers. The raw file content is then saved locally.

Summarizing with LangChain and Ollama (llm_utils.py)

The code for this file can be found here.

from langchain_community.document_loaders import PyPDFLoader
    from langchain_ollama import ChatOllama
    from langchain.chains.summarize import load_summarize_chain
    from langchain.prompts import PromptTemplate

    def summarize_pdf(pdf_file_path: str, model_name: str = "llama3"):
"""
Extracts text from a PDF and uses a local Ollama model to generate a detailed summary.
"""
try:
    llm = ChatOllama(model=model_name, temperature=0)

    prompt_template = """Write a concise summary of the following text.
    Aim for a summary that is about 4-5 sentences long.
    After the summary, provide 2-3 key takeaways as bullet points.

    Text:
    "{text}"

    CONCISE SUMMARY AND KEY TAKEAWAYS:"""

    PROMPT = PromptTemplate(template=prompt_template, input_variables=["text"])
    loader = PyPDFLoader(pdf_file_path)
    docs = loader.load()
    chain = load_summarize_chain(
        llm, chain_type="map_reduce", map_prompt=PROMPT, combine_prompt=PROMPT
    )
    summary_result = chain.invoke(docs)

    return summary_result["output_text"]

    except FileNotFoundError:
return f"Error: The file was not found at {pdf_file_path}"
    except Exception as e:
return f"An error occurred during summarization: {e}. Please ensure Ollama is running and the PDF file is valid."

This file has one main function, summarize_pdf(), that orchestrates the entire summarization process using LangChain:

Initialize the LLM: First, we connect to our local AI model using langchain_ollama import ChatOllama. We point it to the model we're running locally (gemma3:1b-it-qat).
Define a Prompt: We create a custom PromptTemplate. This is more than just asking for a summary; it's a specific set of instructions for the AI. We ask it to write a summary of a certain length and then provide key takeaways as bullet points, ensuring the output is structured and consistently useful.
Load the Document: Using PyPDFLoader from langchain_community, the function loads the PDF file that we just downloaded and splits its content into processable documents.
Run the Chain: Finally, we use LangChain's powerful load_summarize_chain. We configure it with the map_reduce chain type, which is excellent for documents of any size. It first runs our custom prompt on smaller chunks of the document (the "map" step) and then combines those partial summaries into a final, coherent output (the "reduce" step). The final text is then returned to the main application for display.

The Final Application

To bring this all together, we've built a simple but powerful user interface using Streamlit. This application orchestrates the entire workflow, serving as a practical demonstration of API-based RAG. Providing the user with AI-generated summaries of their files from Box. The complete code for the project can be found on GitHub here.

Here's what the final application looks like in action:

Conclusion & What’s Next?

This article concludes our three-part series on building modern RAG systems. We began by establishing a foundational understanding of RAG with a static vector database using FAISS. In this final piece, we evolved that concept significantly by integrating a live data source through the Apideck File Storage API. By connecting directly to a service like Box, we’ve shown that RAG is not limited to static, pre-indexed documents but can be a dynamic, powerful tool for interacting with real-time information from a vast array of sources.

This project is just the starting point for API-based RAG. The true potential comes into play when an AI Agent can request data from multiple systems simply and easily. The groundwork we've laid with the File Storage API can be directly extended. Imagine building an agent that not only fetches files but also pulls customer data from a CRM or candidate information from an ATS. Since Apideck also provides unified APIs for those systems, you can create sophisticated agents that reason across your entire business toolkit.

DEV Community: Apideck

Your MCP Server Is Eating Your Context Window. There's a Simpler Way

The problem demos never show you

Three approaches to the same problem

MCP with compression tricks

Code execution

CLI as the agent interface

Why CLIs are the pragmatic sweet spot

Progressive disclosure saves tokens

Reliability: local beats remote

Structural safety beats prompt-based safety

Universal compatibility, zero protocol overhead

How we built it

When CLI isn't the answer

What this means for API providers

Further reading

Accounting Integration

What Is an Accounting Integration?

Why Accounting Integrations Matter for Your Product

Two Types of Accounting Integrations

6 Common Use Cases for Accounting Integrations

1. Expense Management → General Ledger Sync

2. Invoicing and Billing → Accounts Receivable

3. Procurement and AP Automation → Purchase Order Matching

4. Revenue Recognition → Compliance with Accounting Standards

5. Embedded Fintech → Real-Time Cash Flow Visibility

6. AI and Machine Learning → Financial Intelligence

How Companies Build Accounting Integrations

Option 1: Build Direct Integrations

Option 2: Use a Unified API

Option 3: Hybrid Approach

How to Prioritize Which Integrations to Build

Integration Prioritization Scorecard

How to use it:

Common Pitfalls: What Goes Wrong with Accounting Integrations

1. Auth Token Expiry and Refresh Failures

2. Schema Drift and API Changes

3. Rate Limit Hell

4. Multi-Entity and Multi-Currency Complications

5. GL Code Mapping Mismatches

6. Partnership Agreement Delays

What to Look for in an Accounting Integration Solution

The Bottom Line

Frequently Asked Questions

Go Deeper: Related Guides

Top Fintech APIs for Startups

The Financial Impact of API Strategy

The Money Movers: Payments and Transfers

Payment Processing

ACH and Bank Transfers

The Data Layers: Banking Connectivity and Identity

Banking Data and Account Connectivity

Identity Verification and KYC

The Back Office: Accounting, ERP, and HRIS

Accounting and ERP Integration

The Unified API Alternative

HRIS and Payroll Integration

Lending and Investment APIs

Lending and Credit

Investment and Trading

Embedded Finance Considerations

When to Use Direct vs. Unified APIs

Recommended Stacks by Product Type

Next Steps

Stripe's llms.txt has an instructions section. That's a bigger deal than it sounds.

What llms.txt actually is

Stripe's implementation is the industry outlier

Who else is worth looking at

Why Stripe specifically makes this move

What this means for your API

The broader pattern

How to Make Your API Agent-Ready: Design Principles for the Agentic Era

Bad OpenAPI descriptions break agent routing

Your errors should tell agents how to fix themselves

llms.txt: tell AI what to read

Get your docs indexed by Context7

Your deprecated APIs are an agent experience problem

MCP: build it when people ask for it

Skills: Teaching Agents to Do Your Job at 100x the Scale

What Are Skills?