Agent-Native APIs Explained: What Makes an API Agent-Ready

Human-first APIs assume a reader. Agents do not read.

Most data APIs were designed around a specific ritual. A developer finds the docs site, signs up through a web console, verifies an email, copies a key from a dashboard, reads the pagination section, installs an SDK, and writes integration code. That code then runs unchanged for years. The expensive step, a human understanding the interface, happens exactly once and gets frozen into software.

Agents invert the ritual. When Claude or another LLM agent calls a data API, the integration happens at inference time, in context, every session. The caller has not read your docs site. It cannot complete a CAPTCHA, click a verification link, or interpret an error message that assumes the reader will search a forum thread. Everything the caller knows about your API has to fit in its context window: tool names, parameter schemas, descriptions, and whatever your last response taught it.

This changes what good API design means. Clean REST semantics still matter, but they are no longer sufficient. The interface has to be discoverable by a machine, priced for unattended usage, and trustworthy enough that the model's output can be checked by the human it reports to. That is the gap the term agent-native API describes, and it is the practical core of the MCP vs REST debate: same data underneath, different assumptions about who is calling.

Four properties, side by side

"Agent-native" compresses into four design decisions, each a small inversion of a default that made sense when the caller was a person:

None of this requires exotic engineering, which is why the distinction is easy to underestimate. But together these decisions determine whether an agent can go from zero to a correct, grounded answer in a single session, or whether it stalls on a signup wall, burns tokens parsing prose documentation, or, worst of all, fabricates the answer it could not fetch.

The next three sections take the most consequential properties in turn: discovery, metering, and provenance.

Self-describing tools: the schema is the documentation

The Model Context Protocol standardizes discovery. An agent connects to an MCP server and requests the tool list; the server answers with names, JSON schemas for parameters, and natural-language descriptions of each tool. No SDK, no docs crawl. The schema is the documentation, and the descriptions are effectively prompts: they are the only copy your API gets to show the model before it decides which tool to call.

Writing for that reader is its own discipline. A tool description must state what the tool returns, what its parameters mean, and when to prefer it over a sibling tool, in language a model parses reliably. Responses need to be compact and structured, because every byte you return is a token the agent pays to read. A human-first API can afford a verbose envelope with redundant metadata and hypermedia links. An agent-native one returns the answer, the units, and the source, then stops.

Arkolith exposes the same SEC filings data two ways: REST endpoints under /api/v1 for code, and an MCP server at /api/mcp for agents, with one key and one credit balance across both. The docs for the tool surface are generated from the same catalog the MCP server serves, so the human-readable documentation cannot drift from what the agent actually sees. If you want to try the agent path first, connecting Claude to market data over MCP takes a few minutes.

Metering that matches how agents spend

Agent traffic does not look like human traffic. A research agent might make forty calls in ninety seconds while reconstructing a fund's quarter-over-quarter changes, then go silent for a week. Seat-based pricing has no meaning for that pattern (how many seats does a cron job occupy?), and monthly tiers force a choice between overpaying for idle months and hitting a ceiling mid-task.

Prepaid metered credits fit the shape better. The caller buys a balance, each tool call debits it, and the price of a call reflects its cost: a single-fund lookup is cheap, a cross-universe aggregate costs more. That weighting doubles as a behavioral signal. Agents respond to cost gradients, and pricing a heavy query honestly nudges the model toward the cheap, precise tool when it suffices.

Prepaid also caps the blast radius of the failure mode every operator fears: the runaway loop. An agent stuck retrying a malformed query at 3 a.m. can exhaust a prepaid balance, but it cannot generate an unbounded invoice. The hard ceiling is a feature for the buyer, not just the seller.

The honest tradeoff is that balances run out, sometimes mid-task. An agent-native API mitigates this by reporting the remaining balance in responses, so the agent can warn its human or degrade gracefully instead of failing blind. That courtesy, telling the caller what its own situation is, is exactly the kind of state human-first APIs leave to a dashboard no agent can see.

Provenance is the anti-hallucination contract

Language models fabricate plausible numbers, and they are most dangerous with financial data, because a hallucinated position or share count looks identical to a real one and is costly to act on. The strongest structural defense is provenance: every datapoint travels with a pointer to its source document, so a claim can be verified rather than trusted.

For SEC filings data, the natural provenance unit is the EDGAR accession number, the unique ID of the filing a datapoint came from. When an agent reports that a fund opened a position, an agent-native API lets it cite the specific 13F filing, which anyone can pull up on EDGAR. Arkolith's Q1 2026 13F dataset covers 1,824 institutional filers reporting 1.87 million long positions worth $53.7 trillion, plus more than 51,000 tracked insider transactions, and every row resolves back to the accession number of the filing it came from.

Provenance also forces honesty about timeliness, which matters as much as accuracy. A 13F is due 45 days after quarter end (the 2026 deadlines are Feb 17, May 15, Aug 14, and Nov 16), and only managers above $100 million in covered US equities must file; the SEC's 13F FAQ covers the mechanics. Insider trades on Form 4 arrive within 2 business days, and a Schedule 13D within 5 business days of crossing its threshold. An agent that knows the filing date of its source can say "as of the March 31 snapshot, filed May 15" instead of implying real-time knowledge. That single habit eliminates a whole class of confident-sounding errors, which is why grounding beats guessing and why knowing what 13F data can and cannot tell you is part of using it well.

What this looks like in practice

The agent-native test is simple: can a fresh agent, holding nothing but a key, reach grounded data in one step? Here is the REST surface; the same operations exist as MCP tools at /api/mcp.

List the covered fund universe:

curl -H "Authorization: Bearer YOUR_KEY" "https://arkolith.com/api/v1/funds"

Resolve a name or ticker to an entity:

curl -H "Authorization: Bearer YOUR_KEY" "https://arkolith.com/api/v1/search?q=NVIDIA"

Pull a fund's holdings by CIK (here, Berkshire Hathaway):

curl -H "Authorization: Bearer YOUR_KEY" "https://arkolith.com/api/v1/funds/1067983/holdings"

Each holdings row carries its reported value, share count, and the accession number of the source filing. The same data backs the human-readable pages, so an agent can hand its human a link, such as Berkshire's fund page, and the human sees exactly what the agent saw. That handoff, where the agent does the work and the human verifies through a link, is the flow agent-native design optimizes for.

To wire this into your own agent, the quickstart covers minting a key and connecting over MCP or REST in a few minutes.

Frequently asked questions about agent-native APIs

What is an agent-native API?

An agent-native API is one designed for an AI agent as the primary caller rather than a human developer. In practice it combines a self-describing tool surface (typically MCP), instant bearer-key auth, prepaid metered credits, and per-datapoint provenance. The goal is for a model to discover, call, and verify the API within a single session, without a human in the loop.

Is an agent-native API just an MCP server?

No. MCP solves discovery and transport, but an MCP server bolted onto a human-first API inherits that API's problems: seat pricing, dashboard-only account state, and unverifiable outputs. Agent-native describes the full stack of design decisions, of which the MCP surface is only the most visible.

Why do agent-native APIs prefer prepaid credits over subscriptions?

Agent workloads are bursty and unattended, so seat counts and monthly tiers map poorly onto them. Prepaid credits meter actual usage, let heavy tools cost more than cheap lookups, and hard-cap the damage from a runaway loop. The balance is also a number the agent itself can check and reason about mid-task.

Can an existing REST API be made agent-native?

Mostly, yes, and many will be. Adding an MCP surface, machine-actionable errors, and per-call metering is straightforward engineering. The hardest retrofit is provenance, because attaching a verifiable source to every datapoint has to be built into the data pipeline itself, not layered onto the API afterward.

This article explains public filings and data concepts. It is not investment advice.