API-first design: giving agents a better interface than your website

When an AI agent interacts with your website, it is doing something awkward. It is a machine using an interface designed for humans. It clicks buttons, reads text, fills in forms. All of this works, but it is slow, fragile, and error-prone. An API gives agents what they actually want: structured data and clear action endpoints.

The case for API-first

Consider what happens when an agent checks product availability on a typical e-commerce site. It loads the homepage, finds the search box, types a query, waits for results, clicks a product, reads the page, and extracts the stock status from somewhere in the HTML.

With an API, the same task is one request:

GET /api/v1/products/search?q=wireless+keyboard&fields=name,price,stock_status

{
  "results": [
    {
      "id": "prod_123",
      "name": "Wireless Keyboard - UK Layout",
      "price": {"amount": 49.99, "currency": "GBP"},
      "stock_status": "in_stock"
    }
  ]
}

One request. Structured response. No HTML parsing, no waiting for JavaScript to render, no ambiguity.

Designing agent-friendly APIs

Not all APIs are equally useful for agents. These principles make the difference:

Predictable URL patterns. Agents can infer endpoints from conventions:

GET    /api/v1/products          # list products
GET    /api/v1/products/:id      # get one product
POST   /api/v1/orders            # create an order
GET    /api/v1/orders/:id        # check order status

RESTful conventions mean an agent that knows one endpoint can guess the others.

Consistent response shapes. Every endpoint should return data in a predictable format:

{
  "data": { ... },
  "meta": {
    "total": 142,
    "page": 1,
    "per_page": 20
  },
  "links": {
    "next": "/api/v1/products?page=2",
    "self": "/api/v1/products?page=1"
  }
}

Agents can learn this shape once and apply it across all endpoints.

Descriptive error responses. When something goes wrong, tell the agent exactly what happened:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "field": "customer.email",
    "expected": "Valid email address",
    "received": "not-an-email"
  }
}

This gives the agent enough information to fix the problem and retry. A generic "400 Bad Request" does not.

OpenAPI specifications are the documentation agents read

Agents can consume OpenAPI (Swagger) specifications to understand your entire API without trial and error. An OpenAPI spec describes every endpoint, parameter, request body, and response format.

openapi: 3.0.3
info:
  title: Example Store API
  version: 1.0.0
paths:
  /api/v1/products/{id}:
    get:
      summary: Get product by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Product details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'

Publish your OpenAPI spec at a well-known URL like /api/openapi.json. Some agents will check for this automatically. You can also reference it in your HTML:

<link rel="api-description" href="/api/openapi.json" type="application/openapi+json" />

Authentication for agent access

Agents need to authenticate, and the method matters. OAuth 2.0 with scoped tokens is the most agent-friendly approach:

POST /api/v1/auth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "agent_abc123",
  "client_secret": "secret_xyz789",
  "scope": "products:read orders:write"
}

Scoped tokens let users grant their agent specific permissions. An agent that can read products but not delete them is much safer than one with full access.

API keys are simpler but less flexible. If you go this route, at minimum support read-only and read-write key types.

Do not abandon your website

API-first does not mean API-only. Your website still needs to work well for agents that browse it directly. Many user-directed agents will land on your website through a link, not through your API, and even SaaS pricing pages can confuse agents without clear structure. The two approaches are complementary.

Think of it this way: your website is for agents that arrive without prior knowledge of your site. Your API is for agents that know what they want and have been given credentials to get it.

Practical starting points

If building a full API feels like a big project, start small:

1. Product or service data endpoint. A single /api/products endpoint that returns structured JSON covers the most common agent use case.
2. Search endpoint. Let agents search your content without using your website's search form.
3. Status and availability endpoints. Stock levels, opening hours, service status. These are high-value, low-effort additions.
4. OpenAPI spec for what exists. Even documenting three endpoints in OpenAPI format gives agents a machine-readable starting point.

The web is shifting. Agents are becoming a significant source of traffic and transactions, especially tool-calling agents that treat websites as tools. Giving them a proper interface is not just a nice-to-have; it is how you make your services available to the next generation of users.