Specification · v0.1

botaccess.json

The tiny, declarative file your business publishes at /.well-known/botaccess.json to tell AI agents not just what they may read, but what they may do for a customer — request a quote, check availability, book an appointment.

Why another file?

robots.txt

Crawling

Tells crawlers which URLs they may fetch. Says nothing about what an agent can do for a customer.

llms.txt

Content

Points agents at the pages worth reading — your services, your hours. Still only about reading.

botaccess.json

Actions

Declares the actions an agent may take on your behalf — quote, availability, book — and exactly how.

Example 1 · Plumber

“Quote me, check availability, book me — but don’t take payment”

A local plumber wants agents to read everything, request a quote, check the next slot, send the customer to the booking page, and flag emergencies — while payment stays human. That whole policy is a handful of actions:

request_quote — allowed via a form POST, with a payload schema.
check_availability — allowed via an api GET.
book_appointment — allowed; agent sends the customer to a booking URL.
emergency_callout — allowed; flags the request urgent.
make_payment — forbidden.

/.well-known/botaccess.json

{
  "botaccess": "0.1",
  "site": "https://citywide-plumbing.com",
  "updated": "2026-10-22",
  "contact": "mailto:bookings@citywide-plumbing.com",
  "policy": "Agents may read everything, request a quote, check availability and book. Payment stays human.",
  "actions": [
    {
      "id": "read_content",
      "title": "Read public pages",
      "allowed": true,
      "how": "page",
      "auth": "none",
      "note": "All service + pricing pages are open. See /llms.txt for the index."
    },
    {
      "id": "request_quote",
      "title": "Request a quote",
      "allowed": true,
      "how": "form",
      "endpoint": "https://citywide-plumbing.com/api/quote",
      "method": "POST",
      "auth": "none",
      "schema": "https://citywide-plumbing.com/schemas/quote.json",
      "note": "Submit name, postcode, service type and a short description. A human replies within 1h."
    },
    {
      "id": "check_availability",
      "title": "Check next available slot",
      "allowed": true,
      "how": "api",
      "endpoint": "https://citywide-plumbing.com/api/availability",
      "method": "GET",
      "auth": "none",
      "note": "Returns the next bookable windows by service type and postcode."
    },
    {
      "id": "book_appointment",
      "title": "Book an appointment",
      "allowed": true,
      "how": "page",
      "endpoint": "https://citywide-plumbing.com/book",
      "auth": "none",
      "note": "Send the customer to this booking URL with the chosen slot prefilled."
    },
    {
      "id": "emergency_callout",
      "title": "Request an emergency call-out",
      "allowed": true,
      "how": "form",
      "endpoint": "https://citywide-plumbing.com/api/emergency",
      "method": "POST",
      "auth": "none",
      "note": "For burst pipes / no water. Flags the request as urgent; a human calls back within minutes."
    },
    {
      "id": "make_payment",
      "title": "Take payment",
      "allowed": false,
      "how": "none",
      "auth": "none",
      "note": "No agent-initiated payments. The invoice is sent by a human after the job."
    }
  ]
}

Example 2 · Shop

“Tell them my hours, check stock, reserve for pickup — no online sales”

A neighbourhood hardware store doesn’t sell online, but it wants agents to answer “are they open?”, “do they have it?”, and hold an item at the counter for a customer:

opening_hours — allowed via an api GET.
check_stock — allowed; query by SKU or name.
reserve_item — allowed; holds it 24h, no payment.
purchase — forbidden; pay in person.

These examples are illustrative — they show what a declaration looks like, not real directory data.

/.well-known/botaccess.json

{
  "botaccess": "0.1",
  "site": "https://corner-hardware.com",
  "updated": "2026-10-22",
  "contact": "mailto:shop@corner-hardware.com",
  "policy": "Agents may read, check opening hours, check stock and reserve an item for pickup. No online purchase.",
  "actions": [
    {
      "id": "read_content",
      "title": "Read public pages",
      "allowed": true,
      "how": "page",
      "auth": "none",
      "note": "Catalog and store pages are open."
    },
    {
      "id": "opening_hours",
      "title": "Read opening hours",
      "allowed": true,
      "how": "api",
      "endpoint": "https://corner-hardware.com/api/hours",
      "method": "GET",
      "auth": "none",
      "note": "Returns today’s hours plus any holiday overrides."
    },
    {
      "id": "check_stock",
      "title": "Check if an item is in stock",
      "allowed": true,
      "how": "api",
      "endpoint": "https://corner-hardware.com/api/stock",
      "method": "GET",
      "auth": "none",
      "schema": "https://corner-hardware.com/schemas/stock-query.json",
      "note": "Query by SKU or product name; returns quantity on hand at this store."
    },
    {
      "id": "reserve_item",
      "title": "Reserve an item for pickup",
      "allowed": true,
      "how": "form",
      "endpoint": "https://corner-hardware.com/api/reserve",
      "method": "POST",
      "auth": "none",
      "note": "Holds the item at the counter for 24h under the customer’s name. No payment taken."
    },
    {
      "id": "purchase",
      "title": "Buy online",
      "allowed": false,
      "how": "none",
      "auth": "none",
      "note": "This store does not sell online. Reserve for pickup and pay in person."
    }
  ]
}

Schema

Document

Field	Type	Req
botaccess Spec version, e.g. "0.1".	string	yes
site Canonical origin the declaration covers.	string (URL)	yes
updated ISO date the declaration was last changed.	string (date)	yes
contact A mailto: or https: where a human can be reached.	string (URI)	yes
policy One line summarising the intent, for quick reading.	string	yes
actions The list of declared actions (below).	Action[]	yes

Action

Field	Type	Req
id Stable machine id, e.g. "request_quote".	string	yes
title Human-readable label.	string	yes
allowed Whether agents may perform this action.	boolean	yes
how The mechanism an agent should use.	"api" \| "form" \| "page" \| "none"	yes
endpoint Absolute URL for api/form/booking actions.	string (URL)	no
method HTTP method where relevant.	"GET" \| "POST"	no
auth What it takes to call it.	"none" \| "api-key" \| "oauth" \| "session"	yes
schema Optional JSON Schema for the payload.	string (URL)	no
note Free-text clarification for the agent.	string	no

Get agent-ready in three steps

1
List your actions
Decide what an agent may do for a customer — quote, availability, book — and what stays human. Start restrictive; allow only what you’re comfortable automating.
2
Publish the file
Serve it at /.well-known/botaccess.json with content-type application/json and an open CORS header so any agent can fetch it.
3
Show the badge
Add the widget to your site. SIbotaccess picks up your declaration, your badge flips to “Agent-ready”, and agents know they can quote and book you.

Add the badge See ours

botaccess.json

Why another file?

“Quote me, check availability, book me — but don’t take payment”

“Tell them my hours, check stock, reserve for pickup — no online sales”

Schema

Document

Action

Get agent-ready in three steps

List your actions

Publish the file

Show the badge