fi.

Headless APIs In An AI Age

API

Every product eventually has more than one interface. There is the app people click through. There are admin tools, support workflows, integrations, imports, exports, internal scripts, and now AI agents that need to inspect or act on behalf of a user.

That is why a headless API is not just an integration feature. It is product infrastructure.

Survey Loop is a useful example because the app is not built as one monolithic screen-driven system. The frontend, backend, public survey experience, API documentation, and MCP server all meet around the same backend contracts. The UI is important, but it is not the only way to operate the product.

The API Is The Product Surface

The backend uses Express, but the interesting part is the route shape. Routers define path maps, and createRouter turns those maps into Express routes. Path params, query values, request body fields, auth context, current user, headers, and raw upload bodies are normalized into a single handler payload.

That means feature code can focus on product behavior instead of Express ceremony. It also means the same core surface can serve different clients:

  • The Next.js app calls backend routes through the /api/... proxy.
  • Public respondent flows use unauthenticated survey endpoints with public roles.
  • Admin and platform routes use stricter permissions.
  • API docs and Bruno collections expose the contract to humans.
  • The MCP server forwards tool calls to the same backend API.

This matters because "headless" is not just "we have endpoints." It is "our product behavior is addressable without a browser."

OpenAPI Makes The Contract Legible

Survey Loop keeps OpenAPI specs in backend/SurveyLoopApiDocs/SurveyLoopOpenApi.yaml and mirrors static API docs under api-docs. That gives humans a readable map of the system: users, organizations, surveys, public survey responses, analytics, files, and more.

The practical win is discoverability. A new engineer, customer integration, or AI tool does not need to reverse-engineer frontend components to understand what the product can do. The API has its own vocabulary.

That is especially valuable in an AI age. Agents are good at moving through structured contracts. They can read an OpenAPI surface, understand available operations, and compose actions. They are much worse when the only contract is a pile of click handlers inside a UI.

MCP Turns The API Into Tools

Survey Loop goes a step further with a standalone MCP server in mcp-server. It exposes a remote MCP endpoint, handles OAuth-style authorization, and forwards authenticated tool calls to the backend.

The important design choice is that MCP does not invent a second product model. It reuses Survey Loop's real user identity, backend bearer tokens, feature-flag checks, and OpenAPI-derived artifacts. The MCP server is a tool-facing facade over the product API, not a parallel shadow product.

That keeps the system easier to reason about:

  • Permissions stay attached to the backend.
  • Feature flags still decide who can use the surface.
  • Usage can be logged as MCP-originated traffic.
  • Tool coverage can be generated and verified against OpenAPI.

For AI clients, this is the difference between a fragile browser automation and a governed product interface.

Public And Authenticated Surfaces Can Coexist

Survey Loop also shows why headless APIs should not mean one giant authenticated API. Respondents filling out a public survey are not the same kind of actor as an organization admin managing surveys.

The repo treats those as different surfaces. Public survey routes can find and submit survey responses without carrying app credentials. Authenticated dashboard routes use bearer tokens and the frontend API helpers. Admin and platform routes sit behind higher permission checks.

That split is healthy. It keeps public experiences lightweight, makes permission boundaries explicit, and avoids leaking admin assumptions into respondent flows.

Why This Matters For AI

AI will create more product clients, not fewer. Some will be visible chat experiences. Some will be background workers, support copilots, reporting agents, customer-owned frontends, or internal ops tools.

If a product only works through the UI, every AI integration becomes screen scraping or browser driving. If the product has a stable headless API, AI can become another client.

The strategic advantage is not that agents can click buttons faster. It is that they can use the same durable business surface as the app:

  • Read survey data.
  • Summarize activity.
  • Inspect organization health.
  • Generate reports.
  • Create or update resources when permissions allow.

The UI remains the best interface for many humans. The API becomes the shared substrate for everything else.

The Learning

Build the app, but do not trap the product inside the app.

Survey Loop's API, OpenAPI docs, public endpoints, authenticated helpers, and MCP facade make the product easier to extend because they all point back to the same backend model. That is the real promise of a headless architecture in an AI age: not replacing the UI, but making the product available to every interface that comes next.