Quick Start

Fastest path

If your service has an OpenAPI/Swagger spec, you can generate /ai in one command:

npx @aiendpoint/cli init --openapi https://your-api.com/openapi.json

This creates ai.json and a route handler for your framework. Done in under a minute.

No OpenAPI? Use the interactive wizard:

npx @aiendpoint/cli init

See the full CLI docs for all options.

Minimal shape

If you prefer to write it by hand, every implementation starts with the same minimum contract.

{
  "aiendpoint": "1.0",
  "service": {
    "name": "Acme Store",
    "description": "E-commerce API for products and orders",
    "category": ["ecommerce"]
  },
  "capabilities": [
    {
      "id": "search_products",
      "description": "Search for products by keyword",
      "endpoint": "/api/products/search",
      "method": "GET"
    }
  ]
}

Express example

app.get("/ai", (_req, res) => {
  res.json({
    aiendpoint: "1.0",
    service: {
      name: "Acme Store",
      description: "E-commerce API for products and orders",
      category: ["ecommerce"],
    },
    capabilities: [
      {
        id: "search_products",
        description: "Search for products by keyword",
        endpoint: "/api/products/search",
        method: "GET",
        params: {
          q: "search keyword (string, required)",
          limit: "maximum results (integer, optional, default: 20)",
        },
        returns: "products[] with id, name, price, stock",
      },
    ],
  });
});

Serve it with @aiendpoint/serve

Instead of writing the route handler yourself, use the @aiendpoint/serve package:

npm install @aiendpoint/serve

// Express
import { aiendpoint } from '@aiendpoint/serve/express'
app.use(aiendpoint({ spec: './ai.json' }))

// Fastify
import { aiendpoint } from '@aiendpoint/serve/fastify'
app.register(aiendpoint, { spec: './ai.json' })

// Next.js (app/ai/route.ts)
import { aiendpoint } from '@aiendpoint/serve/next'
export const GET = aiendpoint({ spec: './ai.json' })

// Hono
import { aiendpoint } from '@aiendpoint/serve/hono'
app.use(aiendpoint({ spec: './ai.json' }))

Next steps

After the endpoint responds:

1. Validate it: npx @aiendpoint/cli validate https://yoursite.com
2. Add auth, token_hints, and meta.last_updated for a higher score
3. Check the Spec Reference for all available fields
4. Register the service in the AIEndpoint directory