DEV Community: Kin Lane

API Evangelist Daily — Monday, November 2, 2026

Kin Lane — Tue, 03 Nov 2026 16:52:43 +0000

This is the API Evangelist Daily for Monday, November 2, 2026 — what is new across APIs.io, API Evangelist and API Commons, plus a few things from the shelf.

New on API Evangelist

Add Webhooks To Your Product And Recover Failed Deliveries With Svix — A big customer asks whether your product can notify their system the moment an order ships. Your engineers say yes, then quote you weeks of work, because sending the message turns out to be the easy part.
Check Two OpenAPI Versions For Breaking Changes, And Know What It Cannot See — This is the third story in my series on what each API Evangelist operation can do. Friday I searched sixteen years of research.
Control Who Sees Your Data, Manage Warehouses And Run AI Models With Snowflake — A new analyst starts on Monday and can't see the sales tables until someone files a request. A departing contractor still has access nobody remembered to remove.
Plus 6 more today: Find The Root Cause Of Outages, Search Logs And Forecast Monitoring Costs With Dynatrace; Manage Marketing Emails, Campaign Budgets And Customer Conversations With HubSpot; Run Website Reports, Send Server Events And Handle Privacy Deletion Requests With Google Analytics; The Decoder Only Pours Part Of The Bedrock; The Same Fifty Providers Sit Under Every Kind Of Application; Use A Score To Build Your API Roadmap And Not To Chase A Number

New on APIs.io

AI Agents has 1,016 providers and 41.0% of them are still human-only — The AI Agents tag on apis.io holds 1,016 providers and 323 APIs, and one number frames it: 417 of those providers, 41.0%, sit in the human-only band of our agent readiness measure. These are companies carrying the word agent on their own listing.
Four of the top 20 in our investing industry manage infrastructure, not money — Four of the 20 highest scorers in our Investing & Venture Capital industry have nothing to do with investing. Bentley Systems is fifth at 71.2, Limble CMMS seventh at 70.8, MaintainX twelfth at 66.7 and SewerAI tied for eighteenth at 63.9.
Infobip's Connectivity API offers SIM swap checks twice, and its async lookup has no webhook contract — The Infobip Connectivity API is the telecom identity layer of Infobip: number lookups, silent mobile verification, SIM swap checks, national ID checks, biometric sessions, and CAMARA endpoints. Its contract has 36 operations and 7 webhooks.
Plus 8 more today: Just over half of our pricing records cite evidence, and 32% of them were generated; Palo Alto Networks Moves Agent Identity Into Silicon. Its Record Has Not Followed.; Photoroom Says Fix the Catalog Before the Protocol, and Its Own Record Shows the Same Gap; The serverless page shows 30 of 141 providers, and the sample flatters the market by 23 points; SimScale Polled Engineers on AI, and One in Twenty Are Scaling It; Sobot Defines the Customer Service Agent Skill. Its API Pages Do Not Show One Yet.; Three times as many provider sites serve llms.txt as security.txt; A Workato Customer Says Nobody Has Figured Out Agent Pricing, So Build the Meter First

Kin Score mover

Sully AI rose 24.4 points, from 21.0 to 45.4 (developing), between the 2026-10-30 and 2026-10-31 scoring runs.

Provider spotlight

Mastercard — Mastercard is a global technology company in the payments industry, providing APIs for payment processing, fraud detection, data analytics, and financial services. Kin Score 57.3 (strong), agent readiness 42.8 (agent-native).

From the conversations

API Evangelist Conversation with Reza Shafii, Product Executive At Kong — My friend Emanual had tagged me in one of Reza's posts on LinkedIn about API integrations being dead, so I invitied Reza to come over and explain more about what he meant. I knew the title was bait, but I was interested in hearing Reza's argument and after the conversation it is clear that he's done a lot of thinking at this intersection and wasn't just adding to the AI hype.

FAQ

How do I name things in my API? Use the language the business uses, plural nouns for collections, consistent casing everywhere, and no abbreviations that require a decoder ring. Then write the convention down and lint it.

Guidance

Quality — The measurable correctness consistency and completeness of API definitions

Standard

EPCIS — EPCIS (Electronic Product Code Information Services) is the GS1 standard for capturing and sharing supply chain event data — what happened to an object, where, when, and why.

Investor

Foundry Group — Foundry Group is a Boulder, Colorado venture capital firm founded in 2007 by Brad Feld, Seth Levine, Ryan McIntyre, and Jason Mendelson. The firm invests in early-stage technology startups across the United States, organizing its work around long-lived, horizontal investment themes (such as "glue", "protocol", "distribution", and "human computer interaction") rather than narrow verticals, with a particular affinity…

Country

🇵🇹 Portugal — 10 API providers on APIs.io; the most in Artificial Intelligence (3), Customer Support & Service (2), Government & Public Sector (2).

Regulation

ESIGN Act and UETA — ESIGN is the US federal statute giving electronic signatures and records the same legal effect as their paper equivalents, and UETA is the uniform state law adopted in almost every state that does the same at state level.

Tool

Apache CouchDB — NoSQL document database using JSON for documents, HTTP for API, and JavaScript for MapReduce queries.

Everything mentioned is linked in the show notes. Find any API at apis.io, and see what we are working on at apievangelist.com.

Originally published at https://newsletters.apievangelist.com/daily/2026/11/02/.

API Evangelist Daily — Thursday, October 29, 2026

Kin Lane — Fri, 30 Oct 2026 17:57:41 +0000

This is the API Evangelist Daily for Thursday, October 29, 2026 — what is new across APIs.io, API Evangelist and API Commons, plus a few things from the shelf.

New on API Evangelist

API Evangelist Is Now A Financial Contributor To OpenLint — API Evangelist just became a financial contributor to OpenLint on Open Collective, with a €1,000 contribution. I want to explain why, and ask you to do the same if your work depends on API linting.
Automate Branch Cleanup And Push Notifications With GitLab — If you manage a software team, you have seen the repository that nobody tidies: hundreds of old branches, release branches someone forgot to protect, and a chat channel that never hears about a push until somebody complains. Those are housekeeping jobs, and housekeeping is exactly what software is good at.
Automate Ecommerce Email Campaigns And Segment Shoppers With Omnisend — If you run an online store, you already know the email that earns money: the welcome note to a new subscriber, the campaign to people who bought last spring, the reminder to someone who left a cart. The hard part is keeping your subscriber list, your product catalog and your campaigns in step with what is actually happening in the store.
Plus 7 more today: E-Invoicing: The Shape Of The Answer; Google Ships Agent Skills Like Products, And That's The Lifecycle They Need; Lint An OpenAPI And Find Out Which Rules Decide If It Passes; Manage Event Contacts, Discount Codes And Campaign Email With Cvent Event Cloud; Run Code Without Managing Servers And Release It Safely With AWS Lambda; Run Traffic Reports And Build Audience Segments With Adobe Analytics; Skills Over MCP Is Now Officially Beta

New on APIs.io

Barndoor Sorts Okta's MCP Tools Into Allow, Hold and Deny — Barndoor has written a gating plan for Okta's open-source MCP server, which lets agents run Okta management operations through Okta's Admin Management APIs. The post walks the real server.
Traefik Puts Runtime Governance in Front of OCI Agents — Traefik Labs built a full agent stack in an Oracle Cloud tenancy and wrote up what it took to let those agents act: OCI Enterprise AI Sandbox, Identity Domains, Guardrails, Generative AI and Kubernetes Engine, with Traefik Hub as the one path out of the sandbox. Then they poisoned a runbook.
Vercel: The MCP Server Now Takes Feedback From the Agent — Vercel's changelog entry of October 23 adds a submitfeedback tool to the Vercel MCP server: a way to send bug reports, friction reports and feature requests to the Vercel team directly from an agent or harness. You ask in plain language, and the assistant attaches structured context describing the task, the expected behavior and what went wrong.
Plus 2 more today: WorkOS: Zero Trust Means Checking Every MCP Tool Call; Zapier MCP and the Recruiters Who Turned the Knob

Kin Score mover

Spendesk rose 29.1 points, from 30.5 to 59.6 (strong), between the 2026-10-11 and 2026-10-17 scoring runs.

Provider spotlight

Rollee — Rollee is an Open Finance / employment-data platform that lets fintechs, lenders, and HR platforms verify the income, employment, and work history of both salaried and self-employed workers in real time. Kin Score 55.6 (strong), agent readiness 36.9 (agent-ready).

From the conversations

API Evangelist Conversation with Lorna Mitchell, OpenAPI Specification Maintainer with the OpenAPI Initiative — Lorna Mitchell, OpenAPI Specification Maintainer with the OpenAPI Initiative, and overall API experience expert came by to educate me (us) on OpenAPI Overlays, helping contrast with the core OpenAPI spec, as well as with Arazzo Workflows, sharing how it will help bring more stakeholders into the API lifecycle and contribute to better API experiences. Lorna is a well spring of knowledge when it comes to OpenAPI, but…

FAQ

How do I manage policies consistently across multiple API gateways? Define the policy once in a vendor-neutral form, generate or verify each gateway's configuration from it, and report coverage across all of them. Hand-maintaining parallel policy sets never stays in sync.

Guidance

Production — Governing APIs that are live and serving real traffic

Standard

Privacy By Design — A framework and approach that embeds privacy protections into the design and operation of IT systems, networked infrastructure, and business practices from the ground up, rather than as an afterthought.

Investor

Fifth Wall — Fifth Wall is a venture capital firm founded in 2016 by Brendan F. Wallace and Brad Greiwe and headquartered in Los Angeles, California, with additional offices in New York, San Francisco, and London.

Country

🇳🇴 Norway — 34 API providers on APIs.io; the most in IoT & Connected Devices (6), Artificial Intelligence (6), Energy (4).

Regulation

eIDAS Regulation (Electronic Identification and Trust Services) — eIDAS is the EU regulation governing electronic identification and trust services — including the qualified website (QWAC) and seal (QSEAL) certificates that identify regulated third parties in open banking.

Tool

Apache Cocoon — Web application framework built around the areas of pipeline processing and separation of concerns using XML.

Everything mentioned is linked in the show notes. Find any API at apis.io, and see what we are working on at apievangelist.com.

Originally published at https://newsletters.apievangelist.com/daily/2026/10/29/.

API Evangelist Daily — Wednesday, October 28, 2026

Kin Lane — Fri, 30 Oct 2026 17:56:31 +0000

This is the API Evangelist Daily for Wednesday, October 28, 2026 — what is new across APIs.io, API Evangelist and API Commons, plus a few things from the shelf.

New on API Evangelist

Advertising: The Shape Of The Answer — Last week I wrote about DeepInfer and the shape of the answer, and how batch-invariant inference, deterministic sampling and schema-constrained output make valid JSON table stakes and push the real work onto agreeing on the shape. Advertising is the industry I wanted to look at next, because it agreed on its shape more than fifteen years ago and then runs that shape at a volume nobody else does.
Australian Government Is Open But Not Yet Discoverable By Agents — Australian government publishes more than almost anyone, and an agent still cannot find most of it on its own.
Can Your MCP Server Finish The Job? — When I wrote that MCP is last-mile plumbing, the best response I got wasn't a comment. It was a repost, with one example that turned my analogy into a test.
Plus 8 more today: Connect To Your Customers Accounting, HR And CRM Systems With Merge; Run A Managed Graph Database And Predict Connections With Amazon Neptune; Send Contracts For Electronic Signature And Track Them With Docusign; Send Marketing Email And Manage Contact Lists With SendGrid; The MCP Maintenance Bill Depends On How You Built It; Trigger Builds And Retry Failed Jobs Automatically With Buildkite; Two Hundred Nine API Companies And Seven Hundred Seventy-Five Enterprises Hire In Different Worlds; Who Actually Gets To Define API Standards

New on APIs.io

Brale rewrote its docs around a supported path, and deprecated a page its catalog record still shows — Brale has relaunched its developer documentation, and the argument behind it is one most payment APIs never admit out loud. In Introducing the New Brale API Docs, the regulated stablecoin issuer writes that "Stablecoin integrations don't stall at minting.

Kin Score mover

DoorLoop rose 29.7 points, from 21.9 to 51.6 (developing), between the 2026-10-11 and 2026-10-17 scoring runs.

Provider spotlight

Rokt — Rokt is an eCommerce technology platform that uses AI and machine learning to serve personalized non-endemic offers and ads during transaction moments. Kin Score 63.5 (strong), agent readiness 53.8 (agent-native).

From the conversations

API Evangelist Conversation with Henry Calvert, Global Head of Future Networks @ GSMA — Henry Calvert, Global Head of Future Networks at GSMA came by to talk about the GSMA Open Gateway, a suite of APIs the GSMA Open Gateway global initiative aims to drive the exposure and monetization of telecommunication networks through APIs and federation. The GSMA launched the Open Gateway APIs under the Linux Foundation in a project called CAMARA, and you can find all the OpenAPI specifications for the APIs on…

FAQ

How do I make my API discoverable? Publish machine-readable pointers on your own domain — an OpenAPI at a stable URL, an APIs.json index, an llms.txt — get listed where people already look, and make sure a search engine can read your docs.

Guidance

Privacy — The political struggle over personal data and who controls it through APIs

Standard

Postman Environments — Postman environments are collections of variables that let you easily switch between different configurations (like development, staging, and production server URLs) without manually changing values throughout your API requests.

Investor

Felicis Ventures — Felicis Ventures is an early-stage venture capital firm founded in 2006 by Aydin Senkut and headquartered in Menlo Park, California. The firm backs founders "who rewrite the rules," concentrating the majority of its capital at Seed and Series A while also participating in Series B and select growth rounds, with reported assets under management of roughly $2.4B and a tenth flagship fund (FV X) of $900M closed in June…

Country

🇳🇬 Nigeria — 35 API providers on APIs.io; the most in Financial Technology (24), Payments & Money Movement (19), Banking & Open Banking (10).

Regulation

EASA U-space Regulatory Framework — U-space is the European framework for managing large numbers of drones in shared airspace.

Tool

Apache CloudStack — Open-source cloud computing platform for deploying and managing IaaS cloud infrastructure.

Everything mentioned is linked in the show notes. Find any API at apis.io, and see what we are working on at apievangelist.com.

Originally published at https://newsletters.apievangelist.com/daily/2026/10/28/.

API Evangelist Daily — Tuesday, October 27, 2026

Kin Lane — Wed, 28 Oct 2026 15:50:15 +0000

This is the API Evangelist Daily for Tuesday, October 27, 2026 — what is new across APIs.io, API Evangelist and API Commons, plus a few things from the shelf.

New on API Evangelist

Automate Clusters, User Access, And Patching With Red Hat — If you are responsible for the servers and cloud systems your business runs on, the work never really stops: spin up an environment for a new project, give a new hire access, run the same maintenance job across a fleet of machines, and find out which systems still need a security patch. Red Hat lets you do much of that through APIs, which are a way for other software, or an AI assistant, to carry out those tasks for…
Compare USPS, UPS, FedEx, And DHL Shipping Rates With SMKlog — If you ship parcels from the US, you have probably done this: open four carrier websites, type the same box dimensions into each, and compare prices by hand before buying a label. SMKlog does that comparison for you, and it also offers it as an API, a way for your own software, or an AI assistant, to ask for the prices directly.
Manage Products, Orders, And Coupons For Your Online Store With WooCommerce — If you run an online store on WordPress, a lot of your week probably goes to the same chores: adding products, fixing a price on a variation, creating a coupon for a promotion, looking up a customer, and chasing down an order that needs a refund. Doing that by hand in an admin screen works until the store grows.
Plus 6 more today: Regulation Writes The API; Run Your Catalog, Pricing, And Customers In Software With BigCommerce; Share Files And Add Maps, Places, And Routes To Your Business With Google; Telecom Network APIs: The Shape Of The Answer; Why I Forked Spectral, And Why It Became OpenLint; Writing the MCP Style Guide for the Tools an Agent Reads First

New on APIs.io

Amazon MWAA ships four agent skills for Airflow — AWS has given Airflow users a packaged way to hand pipeline work to a coding assistant. In Amazon Managed Workflows for Apache Airflow now offers AI agent skills, AWS announces that MWAA now integrates with the Agent Toolkit for AWS to provide four built-in skills, authoring-mwaa-workflow, debugging-mwaa-workflow, testing-mwaa-workflow and upgrading-mwaa-environments, usable from "any AI coding assistant that…
Canonical scores 74.8, exemplar, on 117 contracts and only twelve percent of them are callable — Canonical scores 74.8 on the Kin Score, exemplar band, and it is falling: down 7.0 from 81.8 at the previous run. Its Agent Readiness is 43.3, agent-ready, and the rubric records that a gate held it back from agent-native.
Greylock's portfolio splits in two at the published contract: 47.3 against 24.4 — Greylock Partners has 157 portfolio companies on the apis.io network, and 91 of them (58%) publish APIs we index. Those 91 average 37.8 on the Kin Score and 24.2 on Agent Readiness, which puts the portfolio in the thin band.
Plus 7 more today: mabl says the author cannot be the only verifier; Sage puts an agent on Making Tax Digital, and the API record stops short; Snowflake's oncology agents stand on one of the catalog's strongest records; The Stannp Letters API has a free test mode the rubric cannot see; Starburst describes an MCP endpoint its public record does not show; The apis.io markets section cannot read integrations for 35 percent of its cohort; Video streaming on apis.io is led by the pipes, not the streamers

Kin Score mover

SMKlog rose 31.9 points, from 54.2 to 86.1 (exemplar), between the 2026-10-11 and 2026-10-17 scoring runs.

Provider spotlight

Google Ads — The Google Ads API is the modern programmatic interface to Google Ads and the next generation of the AdWords API. Kin Score 71.9 (exemplar), agent readiness 41.8 (agent-ready).

From the conversations

API Evangelist Conversation with Asanka Abeysinghe, CTO at WSO2 — Asanka Abeysinghe, CTO at WSO2 came by for a conversation about the realities on the ground within enterprises when it comes to the platformication of all things, from Internet Developer Portals (IDP) to API platforms. Asanka has been at this a while, and he and I have been discussing the realities of API management for years, and we share a lot of the same views when it comes to the expansion and evolution of our…

FAQ

How do I keep my documentation from going stale? Generate everything you can from the contract, keep the prose in version control next to the code, and test the examples in CI. Documentation maintained separately from the API will always drift.

Guidance

Pricing — The structure for monetizing API consumption by volume tier or feature

Standard

ERC-20 — ERC-20 is the Ethereum token standard: a small interface of six functions and two events that any fungible token contract implements.

Investor

EQT Ventures — EQT Ventures is the early-stage venture capital business within EQT Group, launched in 2016 and operating out of Stockholm with investment-advisory offices in London, Berlin, Paris, Amsterdam, and the United States (San Francisco / New York); the funds themselves are domiciled in Luxembourg. The firm is a sector-agnostic, conviction-led lead investor that backs what it calls "Generation-Defining Companies" from…

Country

🇳🇿 New Zealand — 33 API providers on APIs.io; the most in Education & EdTech (8), Real Estate (5), Payments & Money Movement (5).

Regulation

Digital Technology Assessment Criteria (DTAC) — The Digital Technology Assessment Criteria (DTAC) is the NHS's national baseline that digital health technologies are assessed against before being adopted across the health and care system.

Tool

Apache Celix — Implementation of the OSGi specification in C and C++ for building modular, dynamic applications.

Everything mentioned is linked in the show notes. Find any API at apis.io, and see what we are working on at apievangelist.com.

Originally published at https://newsletters.apievangelist.com/daily/2026/10/27/.

API Evangelist Daily — Monday, October 26, 2026

Kin Lane — Tue, 27 Oct 2026 13:49:57 +0000

This is the API Evangelist Daily for Monday, October 26, 2026 — what is new across APIs.io, API Evangelist and API Commons, plus a few things from the shelf.

New on API Evangelist

A Meter With No Rate On It — Salesforce is going to charge Flex Credits when AI agents call into a production org. Every successful call a registered agent makes, over MCP or straight through the API, gets counted as a "Headless Platform Interaction" and draws down credits.
Automate Projects, Tasks And Team Goals With Asana — Every growing team hits the same wall. Work arrives from email, forms, support tickets and chat, and someone has to copy it into the project tool by hand, assign it, and remind people about it.
Calculate Sales Tax And File Returns Automatically With Avalara — If you sell into more than one state, or more than one country, you have probably found yourself searching for how to charge the right sales tax on every order, how to know where you even owe it, and how to get the returns filed without a spreadsheet marathon at the end of every period. Most people asking those questions are not looking for an API.
Plus 9 more today: Create, Track And Report On Issues Automatically With Jira; Shipping: The Shape Of The Answer; Start With The Flow, Not The Agent; Take Payments, Run Subscriptions And Send Invoices With Stripe; The Most Programmable Sectors In Australia; The Specification Layer Now Has a Home; Track Errors, Releases And Cron Jobs In Your Software With Sentry; What 467 Conformant A2A Agent Cards Are Actually Offering; What Sets Australia Apart In Banking And Telco

New on APIs.io

Apigee runs MCP inside your own cluster, and its record has no MCP server — Google has taken Apigee's MCP support to the customers whose runtimes cannot move. In Announcing MCP support in Apigee hybrid, the post explains that last December's preview turned existing APIs "secured, governed and cataloged" into tools agents can call "without writing code or standing up MCP servers of your own," and that the first question back was "can I have this where my runtime actually lives?" With Apigee…
Climate & Sustainability has 1,276 providers, and Postman ranks first because of one tag — The Climate & Sustainability industry page now lists 1,276 providers in its member rows. In June we wrote about the same vertical at 72 providers.
Cloudflare wakes an agent with its first MCP event — Cloudflare has shipped the first production use this series has seen of a feature that is not yet a specification. In Cloudflare API MCP server sends Workers Issues as MCP Events, the changelog explains that Workers Issues, Cloudflare's built-in error monitoring that groups related production failures "without an SDK or application wrapper," now reaches agents as MCP Events.
Plus 7 more today: Diffbot's DQL Search API is its best contract, and we point it at the wrong host; Ghost scores 77.1, exemplar, on fifty-six operations the catalog lists twice; Kong runs its review agents in CI, behind its own AI gateway; MolTrust says a limit in a system prompt is only a request; The RAG use case lists five topic pages scoring 9.6 and leaves out Pinecone; SIM and eSIM lifecycle has thirteen providers, and the IoT specialists trail the CPaaS platforms; Token Security says Anthropic's Compliance API closes the endpoint blind spot

Kin Score mover

Deputy rose 33.0 points, from 23.7 to 56.7 (strong), between the 2026-10-11 and 2026-10-17 scoring runs.

Provider spotlight

Fireflies.ai — Fireflies.ai is an AI meeting assistant that automatically joins video calls, records, transcribes, and summarizes meetings across platforms such as Zoom, Google Meet, and Microsoft Teams. Kin Score 71.1 (exemplar), agent readiness 60.4 (agent-ready).

From the conversations

API Evangelist Conversation with Greg Dennis, Senior Software Engineer at Zeil — Greg Dennis who was on my team at Postman, and part of my master plan to spend as much VC money as I could on open source API technology, came by to share his expert view on the diff between HTTP APIs and programming language library APIs. Greg is one of the caring souls who are tending to the JSON Schema specification, and has extensive experience developing and maintaining his .NET JSON Schema…

FAQ

How do I govern REST, event-driven, GraphQL and gRPC together? Hold every protocol to the same set of obligations — machine-readable contract, named owner, security model, versioning policy, catalog entry — while using each one's native contract format to enforce them.

Guidance

Power — The asymmetric relationships between platforms developers and end users mediated by APIs

Standard

Equator Principles — A risk management framework adopted by financial institutions for determining, assessing and managing environmental and social risk in projects, primarily for project finance and related lending activities.

Investor

Emergence Capital — Emergence Capital is an early-stage venture capital firm founded in 2003 and headquartered in San Francisco, California, focused exclusively on early-stage B2B / enterprise software. Its founding thesis — that business software would move to the cloud — produced some of the defining SaaS bets of the era, including a contrarian 2003 investment in Salesforce and being the sole venture backer of Veeva's 2008 Series A.

Country

🇳🇱 Netherlands — 78 API providers on APIs.io; the most in Education & EdTech (15), Digital Health & Telehealth (9), Healthcare (8).

Regulation

Drug Supply Chain Security Act (DSCSA) — Title II of the US Drug Quality and Security Act, requiring an interoperable, electronic, package-level traceability system for prescription drugs across manufacturers, repackagers, wholesale distributors and dispensers, including serialization, verification and the electronic exchange of transaction information.

Tool

Apache Cayenne — Open-source Java ORM framework providing object-relational mapping, remoting, and web services support.

Everything mentioned is linked in the show notes. Find any API at apis.io, and see what we are working on at apievangelist.com.

Originally published at https://newsletters.apievangelist.com/daily/2026/10/26/.

Deploy a Real MCP Server in Two Minutes — Naftiko Shipyard on Cloudflare Containers

Kin Lane — Fri, 08 May 2026 19:30:56 +0000

The Naftiko Framework's Shipyard tutorial walks through eleven capability YAMLs — mock MCP at one end, a fully wired domain-driven aggregate at the other. Step 1 is what you run to prove the engine reads YAML. Step 11 is what you run to feel what the framework actually produces.

This post is about deploying step 11 with a single click.

What gets deployed

Three protocol adapters from one capability YAML:

Adapter	Path	Tools / resources
MCP	`POST /mcp`	`list-ships`, `get-ship`, `list-legacy-vessels`, `create-voyage`, `get-ship-with-crew`, `get-voyage-manifest`
REST	`/api/...`	Same domain as REST resources
SKILL	`/skill`	Skill groups for structured agent discovery

Backed by two consumed APIs:

Maritime Registry at mocks.naftiko.net/rest/naftiko-shipyard-maritime-registry-api/1.0.0-alpha2 — bearer auth
Legacy Dockyard at mocks.naftiko.net/rest/naftiko-shipyard-legacy-dockyard-api/1.0.0-alpha2 — API key auth

Both are public Naftiko mocks. The deploy ships dummy tokens that work against them — no upstream credentials needed.

The MCP server itself requires a bearer token (dummy sk-mcp-YYYYYYYYYYYY ships in the deploy).

The Cloudflare shape

The Naftiko Framework engine ships as ghcr.io/naftiko/framework:latest. Cloudflare Containers runs Docker images behind a Worker, brokered by a Durable Object. Five files in the deploy repo do the work — the capability YAML, three shared imports, a Dockerfile, a wrangler config, and a small Worker that proxies traffic to the right port (/mcp → 3001, /skill → 3003, everything else → REST 3002).

The same shape powers manage-companies in production today. The Shipyard end-to-end deploy is the production pattern, sized to the canonical tutorial example.

Click → live URL

Click the button. Cloudflare authenticates you, forks the repo, provisions a Worker plus a Container, builds the Dockerfile, and assigns you a *.workers.dev hostname. Two to three minutes from click to running.

When it finishes you have:

https://<your-worker>.workers.dev/ — landing page
https://<your-worker>.workers.dev/mcp — MCP server
https://<your-worker>.workers.dev/api/... — REST adapter
https://<your-worker>.workers.dev/skill — Skill server

That MCP URL is what you give to your AI tools.

Wiring the MCP endpoint into your AI tools

Substitute your worker URL where you see <your-worker> below. Bearer token defaults to sk-mcp-YYYYYYYYYYYY unless you've changed it.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "naftiko-shipyard": {
      "type": "streamable-http",
      "url": "https://<your-worker>.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk-mcp-YYYYYYYYYYYY"
      }
    }
  }
}

Restart Claude Desktop. Tools appear in the picker.

Claude Code

claude mcp add --transport http naftiko-shipyard https://<your-worker>.workers.dev/mcp \
  --header "Authorization: Bearer sk-mcp-YYYYYYYYYYYY"

Confirm with claude mcp list.

ChatGPT

ChatGPT supports remote MCP servers through Custom Connectors (Pro and Enterprise plans). Settings → Connectors → Custom → Add custom connector. Server URL: https://<your-worker>.workers.dev/mcp. Authentication: Custom header — name Authorization, value Bearer sk-mcp-YYYYYYYYYYYY.

Gemini CLI

Edit ~/.gemini/settings.json:

{
  "mcpServers": {
    "naftiko-shipyard": {
      "httpUrl": "https://<your-worker>.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk-mcp-YYYYYYYYYYYY"
      }
    }
  }
}

Restart gemini. Confirm with /mcp list.

Why this matters past the demo

The Shipyard end-to-end is a sample. The interesting thing is that it isn't shaped any differently from a real Naftiko capability. Same one-click pattern — capability YAML in a folder, Dockerfile pulling the framework image, Worker proxying ports, Durable Object brokering a container — runs manage-companies in production. Replace the YAML in your fork, redeploy, and you have a different MCP server at the same URL.

That is the actual unlock. A public MCP endpoint that you control, callable from Claude, Claude Code, ChatGPT, and Gemini.

Source: https://github.com/naftiko/shipyard-cloudflare
Tutorial: https://github.com/naftiko/framework/wiki/Tutorial-%E2%80%90-Part-1
Naftiko Framework: https://github.com/naftiko/framework

JSON Structure: The Schema Language That Actually Works for Developer

Kin Lane — Tue, 05 May 2026 23:09:19 +0000

If you've ever tried to do serious code generation from JSON Schema — or used OpenAPI tooling on a complex schema and watched it give up mid-object — you've felt the same frustration that drove Clemens Vasters to build something new.

Clemens is a principal architect at Microsoft working on Fabric, the messaging and real-time intelligence platform. He needs schemas that work as data definition languages: things you can generate code from, land in database columns, feed to LLMs with enough fidelity that the LLM can reason about the data correctly. JSON Schema is designed to validate documents. Those are not the same job.

I talked with him twice — in February and again this week — and came away with a clear picture of what JSON Structure is and why it matters. Here's the short version.

What's wrong with JSON Schema

JSON Schema's compositional constructs (anyOf, allOf, oneOf) are expressive but carry no semantic guarantees. The convention that you represent inheritance as an allOf with a base type is just a convention — no rule, no standard, no requirement that code generators interpret it consistently. Every tool hits a different wall at a different time.

The type system is anchored to JSON's native types: strings, numbers, booleans, arrays, objects. That's not enough for real data modeling. Datetimes, decimals, durations — you're working around the type system, not with it.

Dollar-ref can appear anywhere in a document and point to arbitrary external locations. Authentication, caching, relative vs. absolute paths — all of that is undefined. The spec hands you the construct and leaves every operational detail to you.

What JSON Structure fixes

Type system: A richer set of types that maps clearly to database columns and programming language primitives. Not "string with format." Actual types.

References: Dollar-ref is only legal in a defined reusable-types section. External references use an $import mechanism — import the whole document, optionally namespace it, then reference from the import. Two steps, no ambiguity.

Extensibility: The $uses clause declares exactly which extension specs a document depends on, expressed in the same language as everything else. Not a foreign vocabulary mechanism bolted on from outside.

Readability: The shape is familiar if you know JSON Schema. The spec is written so a normal developer can read it and understand it, not just metadata specialists.

The tooling

SDK in 8 languages (C#, C++, Rust, Python, Perl, TypeScript, JavaScript) — validates schemas and validates documents against schemas — on all the standard package managers
Avrotize code generator produces organized, compile-ready projects in C#, Java, Rust, Go, C++, TypeScript, JavaScript from a JSON Structure schema. Generated classes are self-serializing and understand conformant JSON. The C# implementation also handles CBOR, MessagePack, and XML.
Spec is in the IETF as a draft — neutral, stable, no lock-in

Why it matters for AI

Clemens made the point directly: most Kafka/messaging systems work today because the publisher and consumer teams are in the same room. They operate on convention and out-of-band communication. An AI agent consuming a data stream doesn't have that room. It gets the schema and nothing else. Schema quality directly determines what the agent can do correctly.

Richer, more precise schemas are not a nice-to-have in the AI era. They're the difference between an agent that reasons correctly about your data and one that hallucinates field meanings.

The relationship to OpenAPI and AsyncAPI

The baseline use case looks exactly the same as JSON Schema — define request/response objects in an HTTP API. Clemens intentionally kept the surface familiar. If OpenAPI adopted JSON Structure, it would get a better type system and better-defined compositional semantics. That's an invitation, not a demand.

Start at jsonstructure.org. The spec, SDKs, and examples are all there. Community is still small enough to get direct answers from the author.

At Naftiko we're actively working through where JSON Structure sits alongside JSON Schema in our capabilities framework. More on that soon.

Wrap the GitHub MCP Registry as a Naftiko Capability — REST, MCP, and Agent Skills From One Spec

Kin Lane — Thu, 30 Apr 2026 23:33:26 +0000

The GitHub MCP Registry exists. It is a real piece of infrastructure now — vendors publish into it, enterprises mirror it, IDEs are starting to point at it for discovery.

The problem with the registry today, as a developer, is that it is a webpage you scroll. Your agent reads it badly. Your security team queries it manually. Your platform automation cannot really call it as a tool because it does not look like one — it looks like a JSON catalog of metadata, with search-as-keyword.

This post is the engineering version of the argument: wrap the registry as a Naftiko capability, expose three surfaces from one spec, and turn it into something every consumer (humans, agents, pipelines) can call the same way.

The shape of a Naftiko capability

A Naftiko capability YAML is a single artifact that declares two things:

consumes — what upstream APIs the capability calls
exposes — what surfaces the capability serves outward (REST, MCP, Agent Skills)

The Naftiko Engine runs the spec. The same artifact is the deployable unit, the documentation, and the governance contract. Specs do not drift from runtime, because the spec is the runtime artifact. The framework wiki has the long-form argument under Spec-Driven Integration.

For the GitHub MCP Registry, the capability shape is roughly:

naftiko: "1.0.0-alpha2"

info:
  name: github-mcp-registry-discovery
  description: Conversational discovery surface over the GitHub MCP Registry
  version: "1.0.0"

consumes:
  github-registry:
    type: http
    baseUrl: https://api.github.com
    auth: github_app_installation
    operations:
      list-registry-entries:
        method: GET
        path: /repos/{{ .registry_owner }}/{{ .registry_repo }}/contents/servers
      get-registry-entry:
        method: GET
        path: /repos/{{ .registry_owner }}/{{ .registry_repo }}/contents/servers/{{ .entry_path }}

That is the consume side. The capability now knows how to read the registry through GitHub's Contents API. The next block is where the conversational discovery comes in — the exposes side.

Three exposures, one spec

exposes:
  rest:
    operations:
      find-mcp-servers:
        method: GET
        path: /v1/mcp-servers
        parameters:
          - name: purpose
            in: query
            schema: { type: string }
          - name: vendor
            in: query
            schema: { type: string }
          - name: review_status
            in: query
            schema: { type: string, enum: [approved, pending, revoked] }
        outputParameters:
          - name: servers
            type: array
            jsonpath: $.results[*]
            items:
              - { name: urn,            jsonpath: $.urn }
              - { name: install_url,    jsonpath: $.install.url }
              - { name: scopes,         jsonpath: $.install.scopes[*] }
              - { name: review_status,  jsonpath: $.governance.review.status }
              - { name: review_date,    jsonpath: $.governance.review.date }

  mcp:
    transport: streamable-http
    tools:
      find-mcp-servers:
        description: Find MCP servers in the registry filtered by purpose, vendor, or review status
        inputSchema:
          type: object
          properties:
            purpose:        { type: string, description: "What task the agent needs the server for" }
            vendor:         { type: string, description: "Vendor name filter (optional)" }
            review_status:  { type: string, enum: [approved, pending, revoked] }
        outputSchema:
          # shaped output, same projection as REST

  skills:
    package: github-mcp-registry-discovery
    skills:
      - find-mcp-servers
      - get-mcp-server-details

That single block emits three runtime surfaces:

A REST endpoint your platform team's existing portal can render
An MCP server your agent can call directly from the IDE
A skill folder you can install into any agent that supports Agent Skills

Same source of truth. The Naftiko Framework Wiki documents the underlying Compose AI Context and Rightsize AI Context use cases that explain why the typed outputParameters matter — you are not handing a verbose registry envelope to the model, you are handing it task-ready fields.

Why this matters for agents

The agent change is the one developers feel first.

Today, an agent that needs an MCP server fetches the registry page and parses it. The model burns tokens reading entries it will not use. The accuracy of selection depends on whether the model parsed the JSON correctly under context-window pressure.

After wrapping the registry, the agent calls a typed tool. find-mcp-servers accepts structured inputs (purpose, vendor, review_status) and returns a structured output. The model is no longer reading a webpage. It is making a tool call.

That is what right-sized AI context looks like in production. Not better prompts. Better tools that return better-shaped data, so the model has less to do.

Why this matters for vendor-neutrality

Two extensions hit the developer-portal market this year — Zuplo x-mcp and Redocly x-mcp. Both let you describe MCP server tools as OpenAPI extensions. Both are useful. Both lock you to whichever portal vendor ships them.

A Naftiko capability YAML is open. It emits valid OpenAPI for any portal that already speaks OpenAPI. The MCP catalog ships as a sibling artifact. Your custom Swagger UI client (or whatever you have) renders the REST half today, and the MCP half feeds whatever MCP-aware tooling you wire up — without picking either Zuplo or Redocly's Redoc fork.

The contract is portable. The vendor extension is not.

Three places this shows up at runtime

Once the capability is shipped, three different consumers call it three different ways:

A developer in VS Code asks Copilot "what MCP servers are approved for Jira?" — Copilot calls the MCP tool, returns a typed list, the developer installs the right server in two clicks
An automation pipeline queries the REST endpoint to check whether a server is allow-listed before installing it in a sandbox — programmatic discovery, no HTML scraping
A security reviewer uses the same MCP tool but filters by review_status: pending and review_date < last 30 days — the same surface, a different question, returns the audit slice

The capability is not a single tool. It is a single contract that all three workflows query.

How to actually ship it

Steps:

Write the capability YAML — declare the GitHub Contents API as consumes, declare the three exposes surfaces
Add governance metadata — tags on consumes for vendor risk, tags on exposes for agent safety + scope
Run it under the Naftiko Engine (docker run naftiko/framework:latest)
Point your IDE at the MCP endpoint, point your portal at the REST endpoint, install the skill package into agents

The Naftiko Framework runs the spec. The framework wiki Tutorial Part 1 walks through the basic engine setup if you have not used Naftiko before.

The closer

A registry is a list. A capability is a tool. The first thing every enterprise running MCP at any meaningful scale is going to need is a way to query its registry without scrolling — for humans, for agents, and for the automation in between.

Naftiko ships that contract today. One YAML, three surfaces, vendor-neutral.

Stop scrolling. Start calling.

Naftiko is the API integration framework for the AI era. Wrap your APIs as capabilities. Expose REST + MCP + Agent Skills from one spec. Ship governance, observability, and identity as defaults. → naftiko.io

What 253 Enterprises Are Actually Investing In (Hint: It's Not Just AI)

Kin Lane — Fri, 24 Apr 2026 13:19:20 +0000

If you read the trade press, every enterprise on earth is doing exactly one thing right now: AI. Every keynote, every analyst note, every LinkedIn post says the same thing. AI-first. Agent-native. Foundation-model-powered.

So we went and looked at what enterprises are actually spending money on. Not what their CMOs are saying. What their engineering orgs are hiring for, contributing to, and buying. And the answer is more interesting than the hype cycle gives it credit for.

How we measured

Naftiko Signals profiles 253 enterprise companies by reading the engineering signals that cost real money: job postings, open source contributions, SaaS portfolios, standards participation, and tooling choices. Marketing is cheap. Headcount is not. A company that has been hiring for a capability for eighteen months is telling you something a press release cannot.

We bucket those signals into 44 areas of technology spanning the full stack — AI, cloud, data, APIs, integrations, security, governance, observability, platform engineering, and the rest. Then we count: out of 253 enterprises, how many show meaningful investment in each area?

Here is what came back.

The top of the list

Rank	Area	Companies	%
1	Artificial Intelligence	253	86%
2	Active Directory	253	86%
3	Electronic Data Interchange	252	86%
4	Deep Learning	252	86%
5	Data	252	86%
6	Machine Learning	251	85%
7	Operations	249	85%

Read that list again. AI is tied for first — with Active Directory. And one rank below both of them, holding 86% of the enterprise market, is EDI. The protocol your grandfather used to send purchase orders.

This is the story the hype cycle refuses to tell.

What it actually means

Three things jump out of this data, and none of them are the thing the analysts are selling.

AI is real, but it is not alone at the top. Yes, 86% of enterprises are investing in AI, ML, and Deep Learning. That part of the narrative is true. What is missing from the narrative is that the same enterprises are investing — at the exact same intensity — in identity infrastructure, B2B document exchange, and operational tooling. The boring stuff did not go away. It got more important, because every AI initiative eventually has to authenticate against Active Directory and exchange data with a partner over EDI.
The unglamorous layers are load-bearing. Active Directory at #2 and EDI at #3 are not legacy footnotes. They are the substrate every shiny initiative runs on top of. When 86% of large enterprises are still actively investing in EDI in 2026, that is not technical debt — it is the operating reality of how business actually moves between organizations. Anyone selling an "agent-to-agent commerce" vision that does not have an EDI story is selling a slide deck.
"Data" is the silent winner. "Data" as a category sits at 86%, alongside Deep Learning and Machine Learning. Enterprises figured out a long time ago that AI without data infrastructure is a demo, not a system. The investment in pipelines, governance, and storage matches the investment in models — because it has to.

What the hype cycle gets wrong

The dominant story of 2026 is that AI is reshaping everything and the rest of the stack is along for the ride. The signals say something more honest: AI is being layered on top of a stack that enterprises are still actively maintaining and growing. The directory service is not going away. The EDI gateway is not going away. The operational tooling is not going away. They are getting more investment, not less, because the AI layer increases the demands on all of them.

If you are building for enterprises, this matters. A product that assumes the legacy substrate is dissolving will lose to a product that assumes it is thickening. Because the data says it is thickening.

Why this is visible at all

The reason any of this is visible is that we stopped relying on what enterprises say and started reading what they do. Job postings are a leading indicator of investment. OSS contributions are a leading indicator of internal capability. SaaS portfolios are a leading indicator of architectural strategy. Standards participation is a leading indicator of interoperability commitment. None of these are secret. They are just unaggregated.

Signals aggregates them. Every company we profile is an open YAML file in a Git repository. Every signal definition is open. Every ranking is reproducible. If you disagree with how we classified a company, you can submit a PR.

What to do with this

If you are an operator inside an enterprise: use this list as a reality check on your own roadmap. If your AI strategy assumes EDI and AD are someone else's problem, the other 86% of enterprises disagree with you.

If you are building software for enterprises: the boring categories at the top of this list are where the buyers are. The fastest path to relevance is connecting the new layer (AI, agents, MCP) to the substrate (identity, EDI, data, ops) — not pretending the substrate is gone.

If you are trying to make sense of the market: stop reading press releases. Read the signals. They are open.

Try it

Platform: signals.naftiko.io
Browse the areas of technology view to see the full ranking across all 44 signal groups
Browse the radar to see how each area sits across Adopting, Optimizing, Evaluating, and Watching

The hype cycle tells you what enterprises want you to think they are doing. The signals tell you what they are actually paying people to build. Those are not the same list — and the gap between them is where the real opportunities live.

Stop Writing Integration Code. Write a Spec Instead.

Kin Lane — Tue, 21 Apr 2026 19:03:35 +0000

Most enterprise integration work follows a familiar pattern. A team needs to connect system A to system B. A developer writes a client, adds authentication, shapes the response, exposes it somewhere. It works. It ships. Within a sprint it starts drifting from whatever documentation existed. Within a quarter, three other teams have written their own version of the same integration with different assumptions.

This is not a tooling failure. It is a methodology failure. The integration intent — what to consume, how to shape it, what to expose — was never captured in a durable, inspectable artifact. It went straight into code and started drifting immediately.

Spec-Driven Integration

Let me talk for a little bit about Spec-Driven Integration (SDI), and why it provides a new way to look at how we integrate.

Spec-Driven Integration (SDI) is a methodology that treats the specification as the primary integration artifact. Not documentation. Not generated code. The executable definition itself.

A capability specification declares:

What upstream APIs are consumed (base URIs, authentication, resources, operations)
How data is shaped (input parameters, output extraction via JSONPath)
What is exposed downstream (REST endpoints, MCP tools, Agent Skills)

The specification is complete enough to execute directly. An engine reads it at runtime, handles HTTP consumption, data transformation, format conversion, and protocol exposure. No code generation. No compilation.

naftiko: "1.0.0-alpha1"

capability:
  consumes:
    - type: http
      namespace: payments
      baseUri: https://api.internal.company/v2
      authentication:
        type: bearer
        token: "{{PAYMENTS_TOKEN}}"
      resources:
        - name: transactions
          path: /transactions
          operations:
            - name: list-transactions
              method: GET
              outputParameters:
                - name: transactions
                  type: array
                  value: $.data

  exposes:
    - type: mcp
      port: 3001
      namespace: payments-tools
      tools:
        - name: list-recent-transactions
          description: "List recent payment transactions"
          call: payments.list-transactions
          outputParameters:
            - type: array
              mapping: "$.data"

That YAML is the integration. Run it in a container. The MCP tool is live on port 3001.

Why Code Generation Creates Drift

The common objection is: "We already generate code from our OpenAPI specs." Code generation moves the specification one step away from execution. The generated code becomes the artifact that runs, not the spec. The moment someone modifies the generated code — to add a retry, to shape a response, to handle an edge case — the spec and the implementation diverge. Drift is reintroduced.

I am looking for SDI to avoid this entirely. The spec IS what executes. There is no intermediate code artifact that can diverge.

The SDI Workflow

Specify — Write a YAML capability spec capturing the integration intent
Validate — Lint and analyze for completeness before execution
Execute — Run the engine. No build step. No code generation.
Refine — Evolve the spec based on production feedback

This cycle keeps the spec primary. What is deployed always matches documented intent because they are the same artifact.

Why This Matters for AI

AI agents need structured contracts to reason about. An agent can parse a capability spec, understand what tools are available, what inputs they require, and what outputs they produce. It cannot do the same with custom integration code spread across multiple repos.

When the spec is the integration, AI agents can:

Discover available capabilities by reading specs
Call tools reliably because the contract is deterministic
Propose spec refinements based on usage patterns
Validate consistency without reverse-engineering code

SDI is not just a cleaner way to build integrations. It is the prerequisite for AI agents to use your integrations reliably. What I like about SDI, is it takes what we have been investing in for the last decade and helps me integrate AI into existing operational workflows I've worked hard on for years.

Read the full methodology | Explore the Naftiko Fleet

A Big Four Firm Just Ranked #1 in API Investment. Ahead of Every Tech Company.

Kin Lane — Thu, 16 Apr 2026 14:32:01 +0000

At Naftiko, We track technology investment signals across 292 companies at Naftiko — APIs, AI, cloud, data, security, governance, automation, integrations. Scored and ranked.

EY ranks number one. Not among professional services firms. Across all 292 companies. Ahead of Citi, UnitedHealth, Morgan Stanley, Cisco, Visa, Nvidia, and Alphabet.

An accounting firm. Number one.

The numbers

EY scores 2,603 points. The professional services sector overall:

EY: 2,603 (22.8% of sector)
Accenture: 2,022
Booz Allen: 1,447
McKinsey: 1,435
KPMG: 1,200
PwC: 1,155
Bain: 991
Deloitte: 572

EY leads every category. APIs, AI, cloud, data, security, governance, services, integrations, containers, observability. Broad, deep, consistent.

Why professional services is ahead

Technology as a sector scores 44,840 points — but across 49 companies (avg 915 each). Professional services scores 11,425 across 8 companies (avg 1,428 each). Per-company investment density is 56% higher than technology.

The reason is structural. Professional services firms don't build one product. They build integration and transformation capabilities for every client, across every industry. A single firm like EY needs competency in financial services data platforms, healthcare interoperability, manufacturing automation, retail personalization, and energy management — simultaneously.

They also sit at the intersection of business strategy and technical implementation. They wire SAP to Salesforce, connect Workday to Azure AD, build data pipelines from Oracle to Snowflake. Their API and integration investment is not aspirational. It is operational.

What EY is doing differently

Cloud and data are the foundation. Cloud (219) and data (222) are where enterprises build the platforms AI agents will consume. EY is investing in the substrate.

Governance is a differentiator. 92 points — significantly ahead of the field. For an audit and compliance firm, this makes strategic sense. But it also positions them for AI agent governance.

Security is the highest in the sector. 139 points. In a world where AI agents are about to get API access to enterprise systems, security investment is the prerequisite for adoption.

Why this matters for developers

The professional services investment pattern maps directly to what AI agent infrastructure needs:

Discover and inventory APIs across environments with hundreds of services
Govern API access with identity propagation, policy enforcement, and audit trails
Compose capabilities from existing APIs into reusable units of work
Observe what agents are doing and whether integrations work

Professional services firms are the most integration-intensive organizations on the planet. They are investing accordingly. The question is whether the rest of the enterprise world catches up before the agents arrive, or after. For me, this is counter to what I read about professional services companies in mainstream team press, that they are irrelevant and going away.

You can explore the full signals data and run governed AI capabilities yourself using the open-source Naftiko Fleet. Feel free to email me personally at kinlane@naftiko.io if you have any questions.

Making Your APIs Visible Using Capabilities for GitHub 7 GitBook Discovery and Documentation

Kin Lane — Wed, 15 Apr 2026 21:26:40 +0000

Your organization has more APIs than anyone thinks. Specs are scattered across GitHub repos. Docs exist in GitBook spaces that were created for a launch and never updated. Some APIs have specs but no docs. Others have docs but no specs. A handful have neither.

This is the API visibility problem, and it's universal. GitHub and GitBook are both excellent platforms. The gap is the workflow between them.

Capabilities

Naftiko capabilities — each a portable YAML file that consumes the GitHub and/or GitBook APIs and exposes MCP tools for the workflows that documentation writers and governance teams need. No code generation, no SDK, no platform subscription.

Discovery

Helping you with your API discovery.

GitHub OpenAPI Scanner — scans every repo in a GitHub org for OpenAPI/AsyncAPI specs
GitBook Space Auditor — checks spaces for completeness, staleness, missing descriptions
API Documentation Gap Analyzer — compares GitHub specs vs GitBook docs, finds gaps in both directions
Documentation Coverage Scorer — measures what percentage of API operations are documented

Here's the scanner:

naftiko: "0.5"
info:
  label: "GitHub OpenAPI Scanner"
  description: "Scans GitHub organization repositories for OpenAPI and AsyncAPI specification files, building an inventory of every API definition across the org."
capability:
  exposes:
    - type: "mcp"
      namespace: "spec-scanner"
      tools:
        - name: "scan-org-for-specs"
          description: "Scans all repositories in a GitHub organization for OpenAPI and AsyncAPI specification files."
          inputParameters:
            - name: org
              in: query
              type: string
          steps:
            - name: search-openapi
              type: call
              call: "github.search-code"
              with:
                q: "org:{{org}} filename:openapi"
                per_page: 100
            - name: search-asyncapi
              type: call
              call: "github.search-code"
              with:
                q: "org:{{org}} filename:asyncapi"
                per_page: 100
  consumes:
    - namespace: "github"
      type: "http"
      baseUri: "https://api.github.com"
      authentication:
        type: "bearer"
        token: "{{github_token}}"
      inputParameters:
        - name: "github_token"
          in: "environment"
        - name: "Accept"
          in: "header"
          value: "application/vnd.github+json"
        - name: "X-GitHub-Api-Version"
          in: "header"
          value: "2022-11-28"
      resources:
        - name: "code-search"
          label: "Code Search"
          description: "Search for code across repositories"
          path: "/search/code"
          operations:
            - name: "search-code"
              method: "GET"
              label: "Search Code"

And here's the gap analyzer that compares both platforms:

naftiko: "0.5"
info:
  label: "API Documentation Gap Analyzer"
  description: "Compares API specifications discovered on GitHub against documentation published in GitBook to identify undocumented APIs and orphaned docs."
capability:
  exposes:
    - type: "mcp"
      namespace: "gap-analyzer"
      tools:
        - name: "compare-specs-to-docs"
          description: "Searches GitHub for API specs and GitBook for documentation spaces, then compares the two to identify gaps."
          inputParameters:
            - name: org
              in: query
              type: string
            - name: gitbook_orgId
              in: query
              type: string
          steps:
            - name: find-github-specs
              type: call
              call: "github.search-code"
              with:
                q: "org:{{org}} filename:openapi"
                per_page: 100
            - name: find-gitbook-spaces
              type: call
              call: "gitbook.list-spaces"
              with:
                orgId: "{{gitbook_orgId}}"
  consumes:
    - namespace: "github"
      type: "http"
      baseUri: "https://api.github.com"
      authentication:
        type: "bearer"
        token: "{{github_token}}"
      inputParameters:
        - name: "github_token"
          in: "environment"
        - name: "Accept"
          in: "header"
          value: "application/vnd.github+json"
      resources:
        - name: "code-search"
          label: "Code Search"
          path: "/search/code"
          operations:
            - name: "search-code"
              method: "GET"
              label: "Search Code"
    - namespace: "gitbook"
      type: "http"
      baseUri: "https://api.gitbook.com/v1"
      authentication:
        type: "bearer"
        token: "{{gitbook_token}}"
      inputParameters:
        - name: "gitbook_token"
          in: "environment"
      resources:
        - name: "org-spaces"
          label: "Organization Spaces"
          path: "/orgs/{{orgId}}/spaces"
          inputParameters:
            - name: "orgId"
              in: "path"
          operations:
            - name: "list-spaces"
              method: "GET"
              label: "List Spaces"

GitHub → GitBook

Keeping your repos in alignment with what teams do in Gitbook.

GitHub-to-GitBook Spec Publisher — fetches specs from GitHub, creates GitBook spaces
API Catalog Publisher — aggregates multi-repo specs into a browsable GitBook collection
OpenAPI GitBook Uploader — uploads specs to GitBook's native interactive API viewer
API Changelog Publisher — generates changelogs from spec diffs, publishes to GitBook

Here's the publisher capabilty:

naftiko: "0.5"
info:
  label: "GitHub-to-GitBook Spec Publisher"
  description: "Discovers OpenAPI specifications in GitHub repositories and publishes them as structured documentation in GitBook spaces."
capability:
  exposes:
    - type: "mcp"
      namespace: "spec-publisher"
      tools:
        - name: "publish-spec-to-gitbook"
          description: "Fetches an OpenAPI spec from a GitHub repo and creates or updates a GitBook space with the spec content."
          inputParameters:
            - name: owner
              in: query
              type: string
            - name: repo
              in: query
              type: string
            - name: spec_path
              in: query
              type: string
            - name: gitbook_orgId
              in: query
              type: string
            - name: space_title
              in: query
              type: string
          steps:
            - name: fetch-spec
              type: call
              call: "github.get-file-contents"
              with:
                owner: "{{owner}}"
                repo: "{{repo}}"
                file_path: "{{spec_path}}"
            - name: create-space
              type: call
              call: "gitbook.create-space"
              with:
                orgId: "{{gitbook_orgId}}"
                title: "{{space_title}}"
                visibility: "public"
        - name: "batch-publish-org-specs"
          description: "Scans a GitHub org for all OpenAPI specs and publishes each to a GitBook space."
          inputParameters:
            - name: org
              in: query
              type: string
            - name: gitbook_orgId
              in: query
              type: string
          steps:
            - name: find-specs
              type: call
              call: "github.search-code"
              with:
                q: "org:{{org}} filename:openapi"
                per_page: 100
            - name: list-existing
              type: call
              call: "gitbook.list-spaces"
              with:
                orgId: "{{gitbook_orgId}}"
  consumes:
    - namespace: "github"
      type: "http"
      baseUri: "https://api.github.com"
      authentication:
        type: "bearer"
        token: "{{github_token}}"
      inputParameters:
        - name: "github_token"
          in: "environment"
        - name: "Accept"
          in: "header"
          value: "application/vnd.github+json"
      resources:
        - name: "repo-contents"
          label: "Repository File Contents"
          path: "/repos/{{owner}}/{{repo}}/contents/{{file_path}}"
          inputParameters:
            - name: "owner"
              in: "path"
            - name: "repo"
              in: "path"
            - name: "file_path"
              in: "path"
          operations:
            - name: "get-file-contents"
              method: "GET"
              label: "Get File Contents"
        - name: "code-search"
          label: "Code Search"
          path: "/search/code"
          operations:
            - name: "search-code"
              method: "GET"
              label: "Search Code"
    - namespace: "gitbook"
      type: "http"
      baseUri: "https://api.gitbook.com/v1"
      authentication:
        type: "bearer"
        token: "{{gitbook_token}}"
      inputParameters:
        - name: "gitbook_token"
          in: "environment"
      resources:
        - name: "org-spaces"
          label: "Organization Spaces"
          path: "/orgs/{{orgId}}/spaces"
          inputParameters:
            - name: "orgId"
              in: "path"
          operations:
            - name: "list-spaces"
              method: "GET"
              label: "List Spaces"
            - name: "create-space"
              method: "POST"
              label: "Create Space"
        - name: "openapi-specs"
          label: "OpenAPI Specs"
          path: "/spaces/{{spaceId}}/openapi"
          inputParameters:
            - name: "spaceId"
              in: "path"
          operations:
            - name: "upload-openapi"
              method: "POST"
              label: "Upload OpenAPI Spec"

GitBook → GitHub

Now let's go back the other way from GitHub to Gitbook.

GitBook-to-GitHub Spec Centralizer — extracts docs from GitBook, commits to a central GitHub repo
Multi-Repo Spec Consolidator — consolidates scattered specs into one canonical repo

Governance

Now you can govern things because you know where the APIs are.

GitBook-GitHub Doc Sync — bi-directional sync, detects drift
API Doc Freshness Monitor — flags stale documentation before consumers notice
GitBook Change Request Reviewer — PR-style review for documentation updates
GitBook Collection Organizer — organizes spaces into domain-based collections
API Style Guide Enforcer — validates docs against style guidelines, creates fix requests
GitBook Search Indexer — cross-space search, duplicate detection

Here's the style guide enforcer — it searches for banned terms and creates change requests for fixes:

naftiko: "0.5"
info:
  label: "API Style Guide Enforcer"
  description: "Validates API documentation in GitBook against organizational style guidelines."
capability:
  exposes:
    - type: "mcp"
      namespace: "style-enforcer"
      tools:
        - name: "search-for-banned-terms"
          description: "Searches for terminology that violates the style guide."
          inputParameters:
            - name: gitbook_orgId
              in: query
              type: string
            - name: banned_term
              in: query
              type: string
          steps:
            - name: search-content
              type: call
              call: "gitbook.search-content"
              with:
                orgId: "{{gitbook_orgId}}"
                query: "{{banned_term}}"
        - name: "create-style-fix-request"
          description: "Creates a change request to track a style violation fix."
          inputParameters:
            - name: spaceId
              in: query
              type: string
            - name: violation_summary
              in: query
              type: string
            - name: fix_description
              in: query
              type: string
          steps:
            - name: create-cr
              type: call
              call: "gitbook.create-change-request"
              with:
                spaceId: "{{spaceId}}"
                subject: "{{violation_summary}}"
                description: "{{fix_description}}"
  consumes:
    - namespace: "gitbook"
      type: "http"
      baseUri: "https://api.gitbook.com/v1"
      authentication:
        type: "bearer"
        token: "{{gitbook_token}}"
      inputParameters:
        - name: "gitbook_token"
          in: "environment"
      resources:
        - name: "search"
          label: "Search"
          path: "/orgs/{{orgId}}/search"
          inputParameters:
            - name: "orgId"
              in: "path"
          operations:
            - name: "search-content"
              method: "GET"
              label: "Search Content"
        - name: "change-requests"
          label: "Change Requests"
          path: "/spaces/{{spaceId}}/change-requests"
          inputParameters:
            - name: "spaceId"
              in: "path"
          operations:
            - name: "create-change-request"
              method: "POST"
              label: "Create Change Request"

How it works

I am not sure how you organization operates, and I tried to cover the bases.

Each capability is a Naftiko 0.5 YAML file that declares:

What APIs it consumes (GitHub, GitBook, or both)
What MCP tools it exposes*

All you do is point the Naftiko Framework at the YAML, and it serves live MCP tools, agent skills, and REST endpoints. The YAML is the runtime — no code generation required.

Why capabilities for this

The individual API calls are simple. The hard part is doing them consistently, across every repo and every space, over time. Manual processes don't scale. One-time audits go stale. Documentation sprints easily get deprioritized.

Capabilities make the workflow repeatable. Run them on a schedule, wire them into your CI, or invoke the MCP tools from an agent. The more alignment you can bring, the more likely you'll be governing the right things. You can't govern what you don't see.