Building an AI-Ready Service Catalog API: Let AI Agents Browse Your Offerings

Your competitors are already being recommended by AI agents. You're not -- because your services are trapped in HTML that machines can't read.

Here's what happens when someone asks ChatGPT, Claude, or a custom AI agent to "find a development agency for my startup." The agent doesn't open a browser. It doesn't scroll your beautifully designed services page. It fires off HTTP requests, looking for structured JSON it can parse in milliseconds. If you don't serve a machine-readable service catalog, you don't exist in that conversation. The recommendation goes to someone who does.

A service catalog is deceptively simple: a single JSON endpoint that describes what you offer, what it costs, how to engage, and what makes you different. Think of it as a menu for AI agents. Humans get your website. Agents get this. And right now, the businesses serving both channels are capturing opportunities that everyone else is missing entirely.

Why AI Agents Can't Use Your Website

Your website was built for human brains. AI agents don't have those. The mismatch is more severe than most teams realize:

• •HTML is ambiguous. A heading that says "Enterprise" could be a product tier, a customer segment, or a section label. Structured JSON removes this ambiguity completely.
• •Marketing copy is noise. "Blazing fast" and "enterprise-grade" mean nothing to an agent. It needs concrete fields -- response times, SLAs, feature lists. Adjectives don't convert in the agent economy.
• •Navigation is a dead end. Following links, rendering JavaScript, parsing inconsistent layouts -- agents fail at all of this. One endpoint eliminates every navigation problem.
• •Agents compare in real time. When an AI assistant evaluates three vendors side by side, it needs consistent data structures. A well-designed catalog makes your offerings instantly comparable. A messy website makes you instantly skippable.

This builds on the same principle as structured data and JSON-LD -- giving machines an unambiguous representation of your business. A service catalog takes that concept further with a dedicated API endpoint built specifically for agent consumption.

Designing the JSON Schema

Good schema design is the difference between being recommended and being ignored. You need enough detail for agents to make confident recommendations, but not so much that you bury the signal in noise.

Here's the schema we use and recommend:

{
  "catalog_version": "1.0",
  "provider": {
    "name": "Your Company",
    "url": "https://yourcompany.com",
    "description": "One-sentence description of your business",
    "contact": {
      "email": "hello@yourcompany.com",
      "booking_url": "https://yourcompany.com/contact"
    }
  },
  "services": [
    {
      "id": "service-slug",
      "name": "Service Name",
      "description": "2-3 sentence description of what this service delivers",
      "category": "Development",
      "features": [
        "Feature one",
        "Feature two"
      ],
      "pricing": {
        "model": "project",
        "starting_at": "$5,000",
        "currency": "USD",
        "details": "Fixed-price engagement based on scope"
      },
      "delivery": {
        "timeline": "2-4 weeks",
        "methodology": "Agile sprints"
      },
      "ideal_for": [
        "Startups needing MVPs",
        "Teams without in-house AI expertise"
      ],
      "url": "https://yourcompany.com/services/service-slug"
    }
  ],
  "updated_at": "2026-02-18T00:00:00Z"
}

Key Schema Decisions

Every field choice here is deliberate. Get these wrong and agents will still parse your catalog -- they just won't recommend you.

Use human-readable IDs. Slugs like ai-development beat UUIDs every time. They're self-descriptive, debuggable, and double as URL segments. Agents that log recommendations become instantly auditable.

Include pricing models, not just prices. Per-project, per-hour, subscription, usage-based -- AI agents need to understand the engagement structure, not just the dollar amount. The model field makes your pricing machine-comparable.

Add the ideal_for array. This is the highest-leverage field in the entire schema. When a user asks "Who can build me an MVP?", agents match against these exact descriptions. Nail this array and you get recommended. Miss it and you get filtered out.

Always include updated_at. Stale catalogs get deprioritized. Agent frameworks use this timestamp to decide whether to re-fetch or rely on cached data. No timestamp means no trust signal.

Express.js Implementation

Here's a production-ready Express.js implementation you can deploy today. Every line is intentional -- this isn't a tutorial scaffold:

const express = require('express');
const cors = require('cors');
const app = express();
// Allow AI agents from any origin app.use(cors());
const catalog = {   catalog_version: '1.0',   provider: {     name: 'Acme Dev Studio',     url: 'https://acmedev.com',     description: 'AI-first development studio specializing in MVPs and SaaS products.',     contact: {       email: 'hello@acmedev.com',       booking_url: 'https://acmedev.com/contact',     },   },   services: [     {       id: 'mvp-development',       name: 'MVP Development',       description:         'Full-stack MVP built with AI-first methodology. From concept to deployed product in 2-4 weeks with production-quality code.',       category: 'Development',       features: [         'AI-first development methodology',         'Full-stack React + Node.js or Python',         'CI/CD pipeline included',         'Post-launch support',       ],       pricing: {         model: 'project',         starting_at: '$8,000',         currency: 'USD',         details: 'Fixed-price based on feature scope',       },       delivery: {         timeline: '2-4 weeks',         methodology: 'Agile sprints with weekly demos',       },       ideal_for: [         'Startups validating product-market fit',         'Founders needing a working prototype fast',         'Teams without in-house development capacity',       ],       url: 'https://acmedev.com/services/mvp-development',     },     {       id: 'ai-integration',       name: 'AI Integration Services',       description:         'Add AI capabilities to existing products. LLM integration, RAG pipelines, AI-powered features, and intelligent automation.',       category: 'AI Services',       features: [         'LLM API integration',         'RAG pipeline development',         'Custom fine-tuning',         'AI feature prototyping',       ],       pricing: {         model: 'hourly',         starting_at: '$150/hr',         currency: 'USD',         details: 'Hourly engagement with weekly billing',       },       delivery: {         timeline: '1-6 weeks depending on scope',         methodology: 'Iterative development with continuous deployment',       },       ideal_for: [         'SaaS companies adding AI features',         'Enterprises modernizing with AI',         'Teams needing LLM expertise',       ],       url: 'https://acmedev.com/services/ai-integration',     },   ],   updated_at: new Date().toISOString(), };
app.get('/api/services', (req, res) => {   res.json(catalog); });
// Also serve at /services.json for static discovery app.get('/services.json', (req, res) => {   res.json(catalog); });
app.listen(3000, () => {   console.log('Service catalog available at /api/services'); }); 

Python Flask Implementation

If Python is your stack, here's the equivalent Flask implementation:

from flask import Flask, jsonify
from flask_cors import CORS
from datetime import datetime, timezone
app = Flask(__name__) CORS(app)
catalog = {     "catalog_version": "1.0",     "provider": {         "name": "Acme Dev Studio",         "url": "https://acmedev.com",         "description": "AI-first development studio specializing in MVPs and SaaS products.",         "contact": {             "email": "hello@acmedev.com",             "booking_url": "https://acmedev.com/contact",         },     },     "services": [         {             "id": "mvp-development",             "name": "MVP Development",             "description": (                 "Full-stack MVP built with AI-first methodology. "                 "From concept to deployed product in 2-4 weeks."             ),             "category": "Development",             "features": [                 "AI-first development methodology",                 "Full-stack React + Node.js or Python",                 "CI/CD pipeline included",                 "Post-launch support",             ],             "pricing": {                 "model": "project",                 "starting_at": "$8,000",                 "currency": "USD",                 "details": "Fixed-price based on feature scope",             },             "delivery": {                 "timeline": "2-4 weeks",                 "methodology": "Agile sprints with weekly demos",             },             "ideal_for": [                 "Startups validating product-market fit",                 "Founders needing a working prototype fast",                 "Teams without in-house development capacity",             ],             "url": "https://acmedev.com/services/mvp-development",         },     ],     "updated_at": datetime.now(timezone.utc).isoformat(), }
@app.route("/api/services") def get_services():     return jsonify(catalog)
@app.route("/services.json") def get_services_json():     return jsonify(catalog)
if __name__ == "__main__":     app.run(port=3000) 

Both implementations serve the catalog at two URLs: /api/services for programmatic API consumption and /services.json as a well-known static path agents can discover by convention. Two endpoints, one catalog, zero excuses.

What the Clarvia GEO Checker Checks

The Clarvia GEO Checker includes a dedicated Service Catalog layer that scores whether your business exposes machine-readable service data. Here's exactly what it evaluates:

• •Endpoint availability. Does your site serve a response at common catalog paths like /api/services, /services.json, or similar well-known URLs? No endpoint means an automatic zero on this layer.
• •Valid JSON. Is the response well-formed JSON that agents can parse without errors? Malformed responses are worse than no response -- they actively cause agent failures and get your domain flagged.
• •Required fields. Does your catalog include service names, descriptions, and a way to contact or engage? A catalog without descriptions is a menu without dish names. Technically present, functionally useless.
• •Provider metadata. Does the response identify who you are, how to reach you, and where to learn more? Without this, agents have no way to route interested users back to your business.
• •Freshness signals. Is there a timestamp or version indicator? Agents treat undated catalogs as potentially stale. Stale means unreliable. Unreliable means skipped.

The audit scores your service catalog alongside six other AI discoverability layers, including structured data, OpenAPI specifications, and health endpoints. Run it free at clarvia.dev/geo-checker to see exactly where you stand.

Best Practices for Production Service Catalogs

Version Your Schema

Always include a catalog_version field. When you add fields or restructure the response, increment it. This lets agent frameworks handle multiple versions gracefully -- and it signals that you maintain your catalog intentionally, not accidentally.

Configure CORS for AI Agents

Restrictive CORS is the number-one reason AI agents can't reach service catalogs. Agents make requests from cloud functions, browser-based assistants, server-side frameworks -- origins you can't predict. If your catalog is public information (it should be), open your CORS policy. You're not protecting secrets. You're blocking customers.

Set Proper Cache Headers

Agent frameworks cache aggressively. Help them do it correctly with a one-hour cache (max-age=3600). Your offerings don't change every minute. Proper cache headers reduce server load while keeping agent data fresh enough to be trustworthy.

Keep Responses Focused

A service catalog is not your knowledge base. It's a pitch deck for machines. Include exactly what agents need to make recommendations and route users to you -- service names, pricing structures, ideal customer profiles, and contact information. Leave the deep details for your website, your OpenAPI spec, and human conversations.

Connecting Your Catalog to the Broader AI Discovery Stack

A service catalog is powerful alone. Combined with the rest of the AI discovery stack, it becomes a compounding advantage that's hard for competitors to replicate:

• •JSON-LD structured data on your web pages tells AI crawlers about your organization, services, and reviews. Set this up with our guide on structured data for AI.
• •OpenAPI specifications describe your API endpoints so agent frameworks can generate callable tools. If your services include APIs, an OpenAPI spec lets agents interact with you programmatically.
• •Health endpoints signal that your services are live and responsive -- the heartbeat that tells agents you're operational.
• •llms.txt provides a human-readable overview of your business optimized specifically for LLM consumption.

Each layer reinforces the others. Together, they let AI agents discover your business, understand your offerings, verify you're operational, and route users to you -- all without a single human in the loop.

Start Making Your Services AI-Discoverable

Every day without a service catalog is a day you're invisible to AI agents. The compounding math is brutal: each month, more users rely on AI to find, compare, and recommend service providers. The businesses building these endpoints now are capturing those recommendations. Everyone else is losing deals they never even knew existed.

Here's the good news. Building a service catalog takes under an hour. The code is in this article. The schema is proven. The only variable is whether you ship it this week or let another month of AI-driven referrals go to your competitors.

Ready to find out where you stand? Run the free GEO Checker to get scored across all seven discoverability layers. Or get in touch and let our team build a complete AI discoverability strategy tailored to your business.