AI Agent-Friendly APIs Explained: Why Websites May Need Actions, Not Just Pages

Why Would a Website Need Actions, Not Just Pages?

Because agents that operate pages have to guess where the controls are and what will happen when they click, while an API states exactly what actions exist, what inputs they need and what comes back. For repeated or high-value tasks, actions are faster, cheaper and far more reliable.

Pages will not go away. People read them and agents will keep browsing them, and everything in our guides on accessibility and forms still applies. But for tasks such as checking stock, booking a slot, tracking an order or submitting a request, a defined action beats a scripted click-through. It is the same reason apps talk to servers through APIs instead of pretending to be a browser.

Four Ways to Offer Actions

If you have nothing today, the practical order is: make a clear API, describe it in OpenAPI, then consider an MCP wrapper. Our explainers on MCP and MCP apps describe the protocol and how assistants use it.

What Makes an API Easy for an Agent to Use

A language model reads your API description and decides what to call. Everything a human developer would infer from experience has to be stated.

Design around tasks, not tables. A generic "update record" endpoint is hard to use safely. Task-shaped actions such as create_booking, cancel_booking and check_availability say what they do and are easier to guard.

Name and describe clearly. Use plain names and one-sentence descriptions that say when to use the action, not only what it does. "Use this to check whether a table is free before booking" is more useful than "Availability endpoint."

Use strict schemas. Typed fields, enumerations for fixed choices, required markers and examples reduce guessing. Say what units and formats you expect.

Return useful, compact results. Include what the agent needs and little else, and use stable identifiers. Oversized responses waste an agent's limited context.

Make retries safe. Accept an idempotency key for any action that creates or charges, so a repeated request does not duplicate an order.

Offer a preview. A "dry run" or "quote" action lets an agent show a person what will happen before the final call.

Return actionable errors. Give a stable code, a plain explanation and a hint. For example:

{
  "error": "date_in_past",
  "message": "The requested booking date is before today.",
  "hint": "Choose a date on or after 2026-09-20."
}

Describing an Action in OpenAPI

An OpenAPI file is a structured description of your API that agents and tools can read. A trimmed example for a booking action:

paths:
  /bookings:
    post:
      operationId: create_booking
      summary: Create a table booking after availability has been checked.
      description: Use only after check_availability confirms the slot is free.
      parameters:
        - in: header
          name: Idempotency-Key
          required: true
          schema: {type: string}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [date, time, party_size, contact_email]
              properties:
                date: {type: string, format: date}
                time: {type: string, example: "19:30"}
                party_size: {type: integer, minimum: 1, maximum: 12}
                contact_email: {type: string, format: email}
      responses:
        "201": {description: Booking created}
        "409": {description: Slot no longer available}

Notice what the description does for an agent: it says when to call the action, which inputs are required, what limits apply and which responses to expect. That is far more than a page with a form can convey.

Control What an Action Can Do

Actions raise the stakes, because an agent can change data quickly. Apply the permission model from AI agent permissions for websites.

1. Authenticate every write. Use tokens tied to a person or account, with narrow scopes.
2. Separate read and write scopes. An agent that only needs order status should not be able to cancel orders.
3. Confirm risky actions. Return a "requires confirmation" state for payments, deletions and account changes, and let a person approve.
4. Rate limit per client and per action. Return 429 with a Retry-After header.
5. Log everything. Record client, action, inputs and result for audit and dispute handling.
6. Validate on the server. Never rely on the agent to enforce your rules.
7. Treat tool descriptions as sensitive. Attackers can try to manipulate tools or their descriptions. Our explainer on tool injection in AI agents covers the risk.

Wrapping Your API as an MCP Server

The Model Context Protocol gives assistants a common way to connect to tools. An MCP server lists tools, each with a name, description and input schema, and executes calls. If your API is already clean, the wrapper can be thin.

Some practical guidelines help.

• Keep the toolset small and meaningful. Ten well-described tools beat a hundred low-level ones, because a model chooses better among fewer options.
• Reuse your API descriptions. Generate tool definitions from your OpenAPI file where possible so they stay in sync.
• Return concise, structured results. Long dumps of data eat context and confuse models.
• Require authorization. Use the protocol's authorization support or your existing OAuth setup, and never expose privileged tools without it.
• Test with more than one assistant. Behavior differs, and each may interpret descriptions a little differently.

Handling Slow and Multi-Step Actions

Not every action finishes instantly. A refund may take minutes, a report may take longer, and a booking may need approval from a person. Agents handle these badly when the API simply hangs or returns a bare "ok."

Return a clear status immediately, such as pending, with an identifier the agent can use to check progress. Provide a status endpoint that reports pending, succeeded or failed with a reason, and tell the agent how often it is reasonable to check. Where a person must approve something, say so in the response and describe what will happen next, so the agent can pass that on accurately. Webhooks can notify a partner system when work completes, but many assistants cannot receive them, so polling remains the practical default.

Write Docs an Agent Can Actually Use

Agents read documentation as text, so the docs are part of the interface. Keep a single, current reference at a stable URL, publish the OpenAPI file next to it and include a short "getting started" example for each common task. Describe limits plainly: rate limits, maximum sizes, supported regions and what requires confirmation. Include realistic examples of both successful responses and errors, because models learn how to react from the examples you show.

Avoid documentation that lives only in screenshots, PDFs behind logins or interactive widgets. If a person cannot copy the text, a parser cannot either. And keep the docs honest: an action that the docs describe but the server no longer supports is worse than no documentation, since an agent will try it, fail and may loop.

A Safe Order of Operations

1. List the top five tasks customers or partners want to do that pages make awkward.
2. Start read-only. Expose lookups such as order status, stock, prices and opening hours. Risks are low and value is immediate.
3. Add low-risk writes. Actions such as saving a wishlist or joining a waitlist, with idempotency and clear responses.
4. Guard high-risk actions. Payments, cancellations and account changes require confirmation and step-up verification.
5. Publish documentation for people and machines: an OpenAPI file, a short guide and a contact address.
6. Test with real agents. Give an assistant a task and watch where it hesitates or errs.
7. Monitor. Track call volume, error rates and unusual patterns, and adjust limits.

What You Take On

Offering actions means maintaining them. You will need to version the API, keep documentation accurate, handle abuse and support integrators. Some businesses will decide that browsing is enough for now, and that is a reasonable choice if agent traffic is small. Others, such as booking, logistics and commerce sites, may find that a clear action interface cuts errors and support tickets quickly.

Also remember that not all agents will use your API. Many will keep browsing pages, so the API complements good page design instead of replacing it. Our guide on designing a website for humans and autonomous browsers covers keeping both paths healthy. And to publish your rules in a form software can read, see machine-readable policies for AI agents.

Frequently Asked Questions