Onboarding Agents to an API

An API Evangelist Paper — letting an autonomous caller get in, get a credential, pace itself and pay, and handing off cleanly when only a person can

By Kin Lane, the API Evangelist · Version 1.0 · September 2026
_{Status as of September 2026. Agent identity and payment are moving monthly; this paper is updated on a regular cycle.}

Executive summary

API onboarding is the gap between finding an API and calling it: the account, the form, the key, the consent screen, the pricing page. For fifteen years the industry has worked to shrink that gap, and the tools it built are good ones. Every one of them assumes the same thing about the caller. It assumes a person with a browser.

An agent is not that caller. It can read a contract and make a request. It cannot fill in a sign-up form, click a verification link, copy a key out of a dashboard, or put a card down. When it meets an onboarding flow built for a person, it does not complain. It retries.

This paper is a provider’s guide to onboarding a caller that cannot use a browser. The argument, in one line: every step of onboarding needs a machine-readable answer, and every step an agent cannot take alone needs a clean handoff to the person it is working for.

1. Count your doors. Most APIs have one way in, and it runs through a browser. An agent-ready API has several, and says plainly which ones an agent can walk through without a person.
2. Make the front door answer. The first request any client makes is GET on the base URL. It should return who you are, how big you are, and where everything else is — for free.
3. Make every refusal route forward. A 401 or 402 is the moment of highest intent. It should say what was refused, what it costs, what would unlock it, and who can do the unlocking.
4. Be honest about ceilings. If a self-registered client can never be granted a scope, the challenge must not keep telling it to go and get one.
5. Let the caller pace itself. Rate-limit headers have to describe the limit that is actually enforced, and nothing you cannot measure.
6. Publish the price where the decision is made. On the refusal, in a header a browser can read, from one flag that decides every surface at once.
7. Give the agent somewhere safe to start, and make any freshness promise police itself.
8. Put every door in the contract. An agent finds what the contract lists. A door that only a marketing page describes does not exist for it.

This paper gives you a map of the doors, a practice for each of the eight steps, the anti-patterns worth watching for, and a self-assessment you can run against your own API this afternoon.

Where the examples come from. The patterns here come from API Evangelist research across the APIs.io catalog, and from walking the APIs.io API itself through an agent’s first hour in September

1. Each section names the practice first and shows what it looks like on the wire second.

1. Why onboarding breaks when the caller is an agent

The self-service portal was the great onboarding innovation of the last decade and a half. Sign up with an existing account, get a key on the next screen, try it in a console, read a getting-started guide, pick a plan. The best providers got this down to minutes, and time to first call became the measure everyone competed on.

Look at what each step asks of the caller:

An agent can do almost none of it. That is not a gap in the agent. The flow was designed around the things a person is good at, and every step is a place where the agent stops.

API Evangelist research put numbers on it in 2026 by scripting a credential for each of 36 providers, gateways and identity platforms. The question was whether a stranger, or a stranger’s agent, could arrive with nothing and leave with working credentials without a person clicking through a console. Only one or two could, in full. Twenty-five had a clean management API for everything except the first token, which a person mints once in a console and pastes somewhere. Seven more automated the OAuth handshake but needed the application itself created by hand. Three had no programmatic path at all. The industry standardized the API and the handshake. Nothing describes what it takes to get to the handshake.

There are two tempting responses, and both are wrong.

The first is to remove the person entirely — let an agent mint its own identity, grant itself any scope, and start calling paid endpoints. An identity that costs nothing to create carries no accountability. Abuse the quota, take a fresh identity, repeat. Paid data behind a door anyone can open for free is not behind a door.

The second is to change nothing and let agents fail. This one is quieter and more expensive. An agent that fails does not file a support ticket. It retries, loops, creates orphaned registrations, and gives up. The provider never learns that a qualified caller arrived, named exactly the capability it wanted, and left.

The practice sits between the two. Let an agent do everything that does not need accountability on its own. For everything that does, make the handoff to a person explicit, machine-readable, and cheap.

I will be plain about the tension here, because I have argued both sides of it. For most of the self-service era the advice was to open the door as wide as possible and keep limits loose. AI-era traffic changed that: strict limits for unverified callers, and more trust as a caller proves itself, is the right default now. Those two positions are compatible. Being strict about what an unverified caller can reach is different from being obscure about how it can get in. Strict and clear is the goal. Strict and silent is what produces the loop.

2. Count your doors

Most APIs have one door, and it runs through a browser. An agent-ready API has several, and each one earns something different. Here is a typical set, in the order an unattended agent should try them:

Four things about this table matter more than its rows.

Order it by who can walk through alone. The door an unattended agent can use without anyone’s help belongs at the top, not at the bottom under “advanced”. An agent reading an onboarding page top-down will try the first door it finds.

Price each door in accountability, not money. The keyless door is free because it earns little. The client-credentials door earns an account, so something has to vouch for the caller. The self-registration door earns a listing, so the caller has to present evidence it controls a host — something no spammer gets for free. Each door asks exactly as much as it gives.

Start strict and let trust grow. An unverified caller gets tight limits and read access. A caller that has presented evidence, or that a person has vouched for, gets more. Publish the ladder, so a caller can see what the next rung costs and what it earns.

Say which doors need a person. “Sign in” is the only door on this list that needs a browser. If it is the only door that unlocks paid access, say so on the page, in the contract, and in every refusal. The rest of this paper is largely about that sentence.

A self-registration door deserves special mention because it is the least common and the most useful. The pattern is simple. The agent serves a standard identity document — an A2A agent card at /.well-known/agent-card.json is the one with momentum — and calls a registration endpoint with its URL. The provider fetches it, checks it against the specification’s hard requirements, and queues it. A bare GET on the registration endpoint returns its own contract, so an agent that arrives with no documentation can still proceed. An empty POST returns a validation error that names the missing field and shows an example. No form, no account, and nothing to wait for.

3. Make the front door answer

The first request every client makes is GET on the base URL. Client libraries use it as a smoke test. Agents use it to confirm they are talking to the right service. People type it out of habit.

It should answer, and it should answer for free. The service root is metadata about the API: a name, a version, a few counts, and pointers. It synthesizes nothing and costs almost nothing to serve. Gating it turns the cheapest orientation request into the first refusal a stranger ever sees.

A useful service root carries:

{
  "service": "example.io",
  "version": "v1",
  "counts": { "providers": 27459, "apis": 132853 },
  "openapi":    "https://…/example-v1-openapi.yml",
  "docs":       "https://example.io/developer/",
  "plans":      "https://example.io/developer/plans/",
  "prices":     "https://example.io/api/v1/prices",
  "playground": "https://example.io/api/v1/playground",
  "mcp":        "https://example.io/mcp"
}

Every pointer is absolute, and every pointer should be fetched before it is written down. A contract URL that looks plausible and returns 404 is worse than no pointer, because the client that follows it concludes the contract does not exist.

Make sure the door opens for the client you want. Bot protection at the edge is often switched on to stop scrapers, and it does exactly what it says. The side effect is that “bot” now includes the customer you are courting. API Evangelist research keeps finding the same shape: the same URL, the same second, a 403 challenge page for a default client user-agent and a 200 for a browser one. The agent never files a ticket. It leaves. Test your base URL, your contract URL and your docs with the user-agents your SDKs and the common agent frameworks actually send.

The same rule applies to a refusal’s wording. If your gates build a sentence from a path segment, check what they say for the path with no segments. “The undefined endpoint requires an authenticated caller” is a real response, and an agent that reads it has nothing to act on.

4. Make every refusal route forward

A refusal is the moment of highest intent in the whole relationship. The caller has found you, formed a request, and named the exact capability it wants. What the response says next decides whether that turns into a customer or a retry loop.

4.1 Use the status code to say what kind of problem it is

Two codes, two meanings:

• 401 Unauthorized — no credential was presented. Identify yourself first.
• 402 Payment Required — a valid credential was presented, and it is below the tier this resource needs.

A client that refreshes credentials on 401 and shows a paywall on 402 then behaves correctly. Collapse the two and that client inverts: every upgrade opportunity arrives as a broken token. Your documentation has to state the precondition too. “A gated path returns 402” is true only for a caller that sent a key, and a developer testing without one will conclude the docs are wrong.

Avoid 403 if anything between your origin and the caller rewrites it. Many CDNs replace 403 and 404 with an HTML error page, and a JSON client cannot parse the explanation. Choose codes that survive the trip.

4.2 Check that your challenge header survives the trip

An OAuth-protected resource answers an unauthenticated request with a WWW-Authenticate challenge, and RFC 9728 lets that challenge name the resource metadata so a client can discover the authorization server on its own. This is exactly the discovery an agent needs.

It is also a header that intermediaries like to touch. Some API gateways rename WWW-Authenticate on the way out, and some edge function platforms will not let you rename it back. Test what the caller actually receives, not what your origin emits. If the standard name does not survive, emit the value under a second name as well, and document the name that arrives.

Over MCP, the refusal travels as the text of a tool result inside a JSON-RPC 200. No header travels at all. Whatever the agent needs to know has to be in the body.

4.3 Say who can resolve it

This is the step almost everyone misses. Read a typical refusal as the agent would:

The ratings endpoint requires an authenticated caller. Register at https://example.io/developer/, or start OAuth from the authorization server metadata.

Every instruction is addressed to the caller, and for an unattended agent every one is a dead end. The registration page needs a browser. The OAuth flow yields a client that cannot hold the scope it needs. Nothing is addressed to the person behind the agent, who is the only party who can resolve it. So a competent agent registers a client, gets read-only access, retries, sees the same refusal, and gives up.

Put a structured handoff in every 401 and 402:

"resolution": {
  "self_serve": false,
  "by": "human",
  "action": "You cannot resolve this yourself. Show this URL to the person you are working for.",
  "url": "https://example.io/developer/account/?access=1&from=ratings"
}

self_serve: false is the most valuable field in the response. It is the only thing that tells an agent to stop trying to register itself. The action text is written to be relayed, not acted on — over MCP it is the whole message. And the url carries the refused capability, so the person lands on a page that says “you were turned away from ratings, and here is what it costs” instead of a generic pricing table.

Check the landing page as carefully as the refusal. If the “you were turned away from…” note only renders inside a block that is hidden in some states, the person arrives at a page that does not say why they came.

4.4 Give the person a way to hand over access without a pasted key

Today the usual handoff is that the person copies a key into the agent’s conversation, which is how a long-lived credential ends up in a transcript and a log. The standard answer is the OAuth 2.0 Device Authorization Grant (RFC 8628), built for exactly this: a client that cannot use a browser, with a person nearby.

The agent asks for a device code and shows the person one short URL. The person signs in with the flow you already run. The agent polls the token endpoint and receives a token directly. A real person consented, at their own tier, so the token carries the same accountability as any authorization-code token — and the key never passes through the agent’s context.

A second pattern suits requests that need a person’s approval rather than a person’s sign-in — a scope upgrade, a higher quota, a partner tier. Accept the request, answer 202 Accepted with a status URL, and let the agent poll it while a person decides. The agent gets a real answer and a place to wait, instead of a refusal it will retry.

When you ship the device grant, advertise it in two places: device_authorization_endpoint in your authorization server metadata, and a device_flow field in the resolution object. Until you ship it, advertise it in neither. A field that points at a 404 is exactly the kind of dead end the resolution object exists to remove.

5. Be honest about ceilings

A self-registered client should not be able to grant itself paid access. That policy is right, and it should stay. The problem is what the rest of the system says about it.

If every gated route challenges with scope="pro", and the authorization server silently caps self-registered clients at a read scope, then an agent that follows the challenge exactly will register, request pro, receive read, retry, and see the same challenge naming the same unreachable scope. Nothing in the protocol distinguishes “not requested yet” from “not available to you”. A well-behaved client loops. A poorly behaved one loops faster.

Three practices close the loop:

1. Challenge for a scope that would actually satisfy the route. If you have more than one paid tier, give each tier a scope, grant it only to that tier, and have each route challenge for its own. A route that challenges a Pro subscriber for the Pro scope they already hold, and then refuses them again, is not just unhelpful. It is wrong.
2. Carry the ceiling in the body. RFC 6750 has no way to say “obtainable, but not by you”. The resolution.self_serve: false field from §4.3 says it.
3. Document the loop as intended. Where you describe the challenge, say in one plain sentence that a self-registered client tops out at the read scope and that register-and-retry will see the same challenge again. An implementer who reads that will not write the retry.

When you add a scope, update every place that reads one. An authorization server that grants a new scope, paired with a request authorizer that only recognizes the old one, will quietly treat your highest-tier tokens as free.

6. Let the caller pace itself

An agent on a free tier with a daily quota has one question it asks constantly: how much is left? Without an answer it cannot pace, batch, or degrade gracefully. It runs until it hits a 429, which is the one outcome rate-limit headers exist to prevent.

The IETF RateLimit header fields draft gives you the vocabulary. The discipline is in what you put in it.

Describe the limit that is actually enforced. Anonymous callers are often not on a usage plan at all. They are limited per IP at the edge, over a rolling window. Printing the free plan’s daily quota to a caller the plan never applies to is not incomplete, it is wrong. Give the anonymous response the edge policy, and give keyed responses their plan. Build both headers from the same configuration object that builds the enforcement, so they cannot drift.

Emit only what you can measure. If your gateway or your web application firewall enforces the limit and does not hand you its live counter, do not invent a remaining from a counter of your own. A second copy of the number drifts, and an agent that paces against a wrong number fails worse than one that meets the limit honestly. Say so in your source so the next engineer does not add one.

Emit what is computable. A daily quota that resets at midnight UTC has a reset time you can calculate with no lookup. Send it.

Offer the live number where you can get it. An account endpoint that asks the gateway for today’s usage can return used, remaining and reset for the enforced window — one round trip on an explicit call, rather than a guess on every response. Report it against the window you enforce. A seven-day total cannot answer “how many do I have left today”.

Expose every rate-limit header you send in Access-Control-Expose-Headers. A browser-hosted agent cannot read what you do not expose.

7. Publish the price where the decision is made

Agents are becoming paying callers, through pay-as-you-go plans, prepaid balances, and on-chain payment protocols such as x402. Whatever the mechanism, the pricing discipline is the same.

An OpenAPI describes what a call does. Nothing standard describes what it costs, and an agent choosing between providers cannot choose one whose pricing it cannot parse. The price list is the financial half of the contract, and it deserves the same care as the technical half.

Publish the price list before the till opens. A machine-readable price list — every paid capability, its band, its price per call — can go live before you take a single payment. The numbers are in the open and can be argued with before anyone is charged. Mark its status honestly: preview while you cannot sell, live when you can.

Let one flag decide every surface. The price list, the refusal text, the pricing page and the account page all say whether the pay-as-you-go plan exists. If they read from different places, they will disagree: the pricing page sells a plan, the refusal tells the caller to buy it, and the price list calls it forthcoming. Derive the refusal and the price-list status from the same flag that opens the till. A static page cannot read a flag, so have it say what is true and point at the price list as the authority.

Put the price on the refusal. The 401 and 402 are where the buying decision happens, and for an unsubscribed caller they are the only responses it ever sees. Quote the price of the call that was just refused, in the body and in x-price-usd / x-price-band headers. A cross-origin browser client cannot read the body of a failed fetch, only exposed headers. Never quote a price beside a 404; that invites a caller to pay for something that does not exist.

Test the price map from the contract, not from your code. The tempting test iterates your own list of gated resources and checks each has a price. It can only confirm what someone already listed. The test that finds omissions iterates every non-free operation in your published contract and resolves each to a price. Let it tell a deliberate zero — a correction channel you never charge for — apart from a missing entry.

Publish the mandate a machine can evaluate. If you charge a saved card automatically, serve the terms as a versioned document the client fetches, with the trigger, the amount, the escalation ladder, the caps and the off switch stated plainly. That is a mandate an agent can check and a person can understand.

8. Give the agent somewhere safe to start

An agent learning to call APIs needs a place to practice where nothing is at stake. A curated starter set — keyless, free, read-only, no money movement, no messaging side effects — with a working example request for each entry is one of the most useful things a catalog can publish. Point new callers at it first.

The same thinking applies inside a paid API. A dry-run or rehearsal mode — the call is validated and priced, and nothing happens — lets an agent find out what a request would do before it does it. It is the agent-era sandbox, and it matters most on exactly the endpoints that cost money.

A starter set that makes promises has to keep them.

Every link in it must resolve. A one-character path mistake repeated across every entry sends a newcomer’s first click to a 404.

A freshness promise must police itself. “Every example is re-proved nightly” is a strong claim and a valuable one. It is also easy to break without noticing: the nightly check can run and write its results to one file while the endpoint serves an older build of another. Carry a checked_at field — the newest verification in the served list — and compute a stale flag at read time when it is more than a couple of days old. Then a missed night is reported by the endpoint instead of discovered by a caller.

A two-client check needs two clients that genuinely differ. Some hosts refuse any request without an Accept header. If both of your verification clients happen to send one, the host passes forever while real callers get 400. Make one client send no default headers, and let an entry declare the headers its host requires — then return them in the payload so the caller can send them too.

9. Put every door in the contract

An agent does the correct thing: it fetches the contract and enumerates the paths. Whatever the contract lists, the agent can find. Whatever it does not, does not exist for that agent — no matter how well a marketing page describes it.

Every door belongs in the OpenAPI. The registration endpoint, the registry behind it, the price list, the playground, the account-usage call. If an onboarding page says “there are four ways in” and the API has five, fix the page, and put the fifth at the top.

Describe the onboarding itself in a machine-readable document. The contract says what the API does. An onboarding descriptor says what it takes to get in: which doors exist, what each one requires of a person, the verification gates and how long they take, the credential shapes, the scope model, and the ordered steps. API Evangelist published one — the API Onboarding Descriptor, at /.well-known/api-onboarding — and the most useful field in it is the honest list of what still needs a human. Whatever format you use, write that list down where a machine can read it.

Every route belongs in your agent surface too. If you run an MCP server beside the REST API, give each documented route a tool, or write down why it has none. “No tool” and “no tool yet” look identical from outside, and only one of them is a decision.

Unknown parameters must be reported, per route. A filter parameter that is silently ignored returns the whole collection, shaped exactly like a filtered answer. A caller who typed tag instead of tags gets every record and believes the filter applied. Report ignored parameters in the response metadata, and compute “ignored” against the route’s own vocabulary, not against every parameter the API knows anywhere. A parameter that is valid on one route and meaningless on another is the case a global allowlist cannot see.

Tool descriptions are part of the contract. A shared parameter description that says “use api_tags below” is true on the one tool that has api_tags below it, and false on every other tool that reuses the description. Agents follow that advice literally.

Any count in a next-step hint must be reproducible. “All 3,654 APIs — paginated” is a promise. If the tool and arguments attached to it return 627, the hint is confidently wrong in a way the caller cannot detect. Test it: take the number out of the label, run the tool with its own arguments, and compare totals.

10. Anti-patterns worth watching for

• The browser-only paid door. Every route to paid access runs through a sign-up form, and nothing in the API says so.
• The gated front door. GET on the base URL returns a 401, often with a sentence built from a path segment that is not there.
• The refusal addressed to the wrong party. Every instruction tells the agent to do something only a person can do.
• The unreachable scope. A challenge that names a scope the authorization server will never grant this caller, repeated on every retry.
• The invented counter. A remaining header computed from a local tally the enforcer never sees.
• The wrong policy for the anonymous caller. Plan numbers printed to a caller who is limited somewhere else entirely.
• Three surfaces, two answers. The pricing page sells a plan the price list calls forthcoming.
• The price you learn after the charge. Prices quoted only on the successful response.
• The freshness claim that cannot see itself. “Re-proved nightly” over a payload nobody rebuilt.
• The siloed door. A well-made registration endpoint that no contract, no developer page and no refusal ever mentions.
• The silent parameter. An unrecognized or inapplicable filter that returns everything with 200 OK.
• Bot protection that refuses your own customers. An edge rule that answers 403 to the user-agents your SDKs and agents send.
• The console-minted first token. A complete management API that still needs a person in a dashboard before the first call, with nothing saying so.
• The pasted key. A long-lived credential handed to an agent by copying it into a conversation.

11. Provider self-assessment

Run these against your own API. Each is answerable today.

Doors

• Can an unattended agent get read access without any person’s involvement?
• Is there a door an agent can walk through by presenting evidence rather than a form?
• Does your onboarding page list every door, with the agent-only one first?
• Does it say which doors need a person?
• Is there a machine-readable document that lists what onboarding still requires of a human?
• Have you requested your base URL, contract and docs with the user-agents your SDKs and common agent frameworks send, and confirmed none of them get a bot-challenge page?

Front door and contract

• Does GET on your base URL answer an anonymous caller with 200 and pointers to everything else?
• Is every onboarding route — registration, registry, prices, playground, usage — in your OpenAPI?
• If you run an MCP server, does every documented route have a tool or a written reason for none?
• Does every list route report parameters it ignored, judged against that route’s own vocabulary?

Refusals

• Do you answer 401 with no credential and 402 with an insufficient one, and do your docs say so?
• Have you checked which challenge header actually reaches the caller through your gateway and CDN?
• Does every refusal carry a resolution object with self_serve, a relay-ready action, and a URL that names the refused capability?
• Does the page that URL opens acknowledge why the person arrived, in every state?
• Can a person hand an agent access without pasting a key? (For most teams today the honest answer is no. The device grant is the highest-value gap on this list.)

Scopes

• Does each gated route challenge for a scope that would actually satisfy it?
• Do you document, where the challenge is described, that self-registered clients stop at read?

Pacing

• Do your rate-limit headers describe the limit that is actually enforced for each kind of caller?
• Do you send a reset time, and only the numbers you can measure?
• Can a keyed caller read its usage against the enforced window?
• Are all of these exposed to browser clients?

Price

• Is your price list public and machine-readable, with an honest status?
• Do the price list, the refusal, the pricing page and the account page all read from one flag?
• Is the price of a refused call in the body and in exposed headers?
• Does a test iterate your contract’s paid operations and find any without a price?

Starter set

• Does every link in it resolve?
• Does it report its own staleness?
• Do your two verification clients differ in their default headers?

Most teams will answer “no” to the device-grant and resolution questions. That is the state of the practice in September 2026, not a mark against anyone.

12. Where this is going

The handoff will become a protocol, not a paragraph. Today “ask your human” is prose at best. The device grant already standardizes the credential half of it. The structured resolution object is a local convention that deserves to become a shared one, because every agent framework will need to render the same thing: this needs a person, here is the link, here is why.

Evidence will replace forms. The self-registration pattern — prove you control a host by serving a standard document there — scales in a way sign-up forms never did. Agent cards, signed requests and issuer attestations are all converging on the same idea: an agent’s identity is something it presents, not something it fills in.

Pricing will move onto the wire. Machine payment protocols make it possible for an agent to pay per call without a subscription. That only works if the price is on the refusal, the terms are fetchable, and the caller can check its own spend. The providers who publish all three first will get the agent traffic that is already arriving.

And onboarding will be measured from the agent’s side. Time to first call was the measure of the portal era. The measure of this one is simpler: how many requests does an agent make before it either succeeds or hands off to its person? For most APIs today that number is unbounded, because the loop never ends. Getting it to a small, fixed number is the whole job, and every practice in this paper is a way of shortening it.

None of this needs a standard that does not exist yet. It needs a provider to walk its own API as an agent would — one request at a time, reading every response literally — and fix what it finds.

Appendix A — Standards and specifications referenced

Appendix B — Onboarding surfaces on APIs.io

The APIs.io API was walked through an agent’s first hour while this paper was written. These surfaces are live and can be called directly:

• Agent self-registration — GET /api/v1/agents/register returns its own contract; the human-readable procedure is at apis.io/agents/register, and the registry at apis.io/agents.
• Price list — GET /api/v1/prices, with its status.
• Access terms — GET /api/v1/billing/access/terms, the versioned mandate for automatic top-ups.
• Playground — GET /api/v1/playground, the keyless starter set.
• Authorization server metadata — /.well-known/oauth-authorization-server.
• Protected resource metadata — /.well-known/oauth-protected-resource/api/v1.
• Onboarding descriptor — /.well-known/api-onboarding, including its list of what still runs through a person.
• Onboarding guide — apis.io/developer/onboarding.

About API Evangelist

API Evangelist is the research, analysis, and advisory practice of Kin Lane, studying the business and politics of the API industry since 2010. For sixteen years it has been one of the most cited independent voices in the space, publishing open research at apievangelist.com and maintaining a working catalog of the API landscape at APIs.io — the catalog whose own API is walked through in this paper.

The practice is deliberately independent and vendor-neutral. Kin is a former Presidential Innovation Fellow and has advised platform teams, enterprises, and government agencies on API strategy, governance, and developer experience. The method is consistent: survey what providers actually ship, define it as open, machine-readable artifacts (OpenAPI, APIs.json, and now MCP), and turn that evidence into guidance practitioners can act on. This paper is a direct product of that method.

About API Evangelist White Papers

API Evangelist White Papers are formal, practitioner-focused guides distilled from ongoing research across the API landscape. Each one takes a single, consequential shift in API operations — like onboarding a caller that cannot use a browser — and turns a broad scan of how real providers handle it into an opinionated, reusable playbook, complete with archetypes, anti-patterns, and a self-assessment you can run against your own operations.

They differ from a typical blog post or vendor white paper in three ways:

• Evidence-based. Every recommendation is grounded in what providers actually shipped, cross-referenced to the live catalog at APIs.io.
• Vendor-neutral. No sponsor steers the conclusions; tools and platforms are named on merit.
• Living documents. Each paper carries a version and an “as of” date, and is revised on a regular cycle as the landscape moves — you have access to a maintained reference, not a frozen PDF.

White papers are distributed to a select group of API providers and teams. If you’re reading this, you’re part of that group.

API Evangelist Services

This paper is a map; API Evangelist also does the work alongside you. Engagements draw on the same research practice behind these papers and are organized into three areas of work — discovery, governance, and evangelism. Each area is made up of focused, repeatable engagements you can mix and match to define what your business needs, operate it in consistent ways, and tell the story of the work as it happens. Most start with a single conversation about your priorities.

• Discovery — map the words, interfaces, and standards that define what your operations actually need before anything gets built: Vocabulary (the terms that define what is needed), Interfaces (mapping existing commercial or open-source interfaces and developing new ones — your OpenAPI and now your MCP server), and Standards (the standards required for interoperability).
• Governance — define and iterate upon the Strategies, Experiences, Policies, Rules, Pipelines, Skills, and Reviews that make your operations consistent, compliant, and repeatable — including the refusal, scope, rate-limit and pricing surfaces an agent-facing API depends on.
• Evangelism — craft and publish the Stories, Conversations, Talks, Research, Papers, and Workshops that tell the story of your work at the intersection of people and interfaces — the same practice that produced this paper.

Get in touch

If you’d like to go deeper on anything in this paper — an agent walk-through of your own API, a design for refusals that hand off cleanly, or a broader API governance engagement — API Evangelist welcomes the conversation.

• Email: [email protected]
• Web: apievangelist.com · Services: services.apievangelist.com
• Catalog: APIs.io · MCP directory: mcp.apis.io

— Kin Lane, the API Evangelist

_{© API Evangelist · Kin Lane · This paper is part of a regularly-updated series.
The supporting per-provider profiles and cross-provider comparison live alongside this paper in the API Evangelist research archive.}