aiendpoint.dev
Spec v1.0 · Apache 2.0

The /ai Spec

A standard endpoint every web service can implement so AI agents can discover and use it — without scraping, guessing, or reading documentation.

Overview

Any service exposes GET /ai returning a structured JSON object. AI agents query this to understand what the service does and how to call it.

robots.txt

Tells crawlers what NOT to do

sitemap.xml

Tells crawlers where pages are

/ai

Tells AI agents what you can DO

Full example

GET /ai → 200 OK · Content-Type: application/json
{
  "aiendpoint": "1.0",
  "service": {
    "name": "Acme Store",
    "description": "E-commerce API for products, cart, and orders",
    "language": ["en"],
    "category": ["ecommerce"]
  },
  "capabilities": [
    {
      "id": "search_products",
      "description": "Search for products by keyword or category",
      "endpoint": "/api/products/search",
      "method": "GET",
      "params": {
        "q":        "search keyword (string, required)",
        "category": "filter by category (string, optional)",
        "limit":    "max results (integer, optional, default: 20, max: 100)"
      },
      "returns": "products[] with id, name, price, stock, image_url"
    },
    {
      "id": "get_product",
      "description": "Get full details for a product",
      "endpoint": "/api/products/:id",
      "method": "GET",
      "params": {
        "id": "product ID (string, required, path param)"
      },
      "returns": "product with full spec, variants, reviews"
    }
  ],
  "auth": {
    "type": "apikey",
    "docs": "https://acme.com/docs/auth"
  },
  "token_hints": {
    "compact_mode": true,
    "field_filtering": true,
    "delta_support": false
  },
  "rate_limits": {
    "requests_per_minute": 60,
    "agent_tier_available": true
  },
  "meta": {
    "last_updated": "2026-03-12",
    "spec_url": "https://acme.com/ai"
  }
}

Required fields

aiendpointstringrequired

Version string. Must be "1.0".

"aiendpoint": "1.0"
service.namestringrequired

Human-readable service name.

"name": "Acme Store"
service.descriptionstringrequired

Concise description for AI agents. Keep it under 200 chars. No marketing fluff.

"description": "E-commerce API for products, cart, and orders"
capabilitiesarrayrequired

One or more capability objects describing what the service can do.

Capability object

Each item in the capabilities array describes one action an AI agent can take.

idstringrequired

Snake_case identifier. Must match ^[a-z][a-z0-9_]*$

"id": "search_products"
descriptionstringrequired

What this capability does. One sentence.

"description": "Search for products by keyword"
endpointstringrequired

Relative URL path. Use :id notation for path params.

"endpoint": "/api/products/search"
methodstringrequired

HTTP method: GET, POST, PUT, DELETE, PATCH

"method": "GET"
paramsobject

Map of param names to descriptions. Include type, required/optional, default.

"params": {
  "q": "keyword (string, required)",
  "limit": "max results (integer, optional, default: 20)"
}
returnsstring

Describe the response shape. Helps AI know what data to expect.

"returns": "products[] with id, name, price, stock"

Optional fields

service.languagestring[]

BCP-47 language codes. Defaults to ["en"].

"language": ["en", "ko", "ja"]
service.categorystring[]

Service categories. See list below.

"category": ["ecommerce", "productivity"]
authobject

Auth info. type: none | apikey | oauth2 | bearer. docs: URL to auth docs.

"auth": {
  "type": "apikey",
  "docs": "https://example.com/auth"
}
token_hintsobject

Tell agents how to reduce token usage. compact_mode, field_filtering, delta_support.

"token_hints": {
  "compact_mode": true,
  "field_filtering": true
}
rate_limitsobject

Rate limit info for agents to plan requests.

"rate_limits": {
  "requests_per_minute": 60,
  "agent_tier_available": true
}
metaobject

Metadata: last_updated (YYYY-MM-DD), spec_url.

"meta": {
  "last_updated": "2026-03-12",
  "spec_url": "https://example.com/ai"
}

Category values

productivityecommercefinancenewsweathermapssearchdatacommunicationcalendarstoragemediahealtheducationtravelfoodgovernmentdeveloper

Quick implementation

Express (Node.js)

app.get('/ai', (req, res) => {
  res.json({
    aiendpoint: '1.0',
    service: { name: 'My Service', description: '...' },
    capabilities: [{ id: 'do_thing', description: '...', endpoint: '/api/thing', method: 'GET' }]
  })
})

FastAPI (Python)

@app.get("/ai")
def ai_spec():
    return {
        "aiendpoint": "1.0",
        "service": {"name": "My Service", "description": "..."},
        "capabilities": [{"id": "do_thing", "description": "...", "endpoint": "/api/thing", "method": "GET"}]
    }

Rules

  • ✓GET /ai must return HTTP 200
  • ✓Content-Type must be application/json (or JSON body)
  • ✓Response must be valid JSON (no trailing commas, no comments)
  • ✓aiendpoint field must equal "1.0"
  • ✓capabilities must have at least one item
  • ✓capability id must be snake_case
  • ✓No authentication required to access /ai itself
  • ✓Keep response under 10KB for token efficiency
Validate your /aiRegister your serviceGitHub ↗