Documentation

Everything you need to set up your business, connect with AI agents, and get the most out of AgentReadi.

Overview

AgentReadi makes your business discoverable and actionable by AI agents. Set up a structured profile, define the actions agents can take, and install a lightweight embed on your website — AI agents can then find, understand, and interact with your business automatically.

I'm a business owner

Learn how to set up your profile, configure actions, and go live.

I'm building an AI agent

Jump to the API reference to search businesses and execute actions.

Getting Started

Go from sign-up to live in minutes with our AI-powered onboarding.

1
Sign up
Create your account with email or Google.
2
AI-powered onboarding
Paste your website URL and our AI will automatically extract your business name, description, category, services, contact info, and more.
3
Review & edit
The AI populates your profile — review the details, tweak anything that needs adjusting, and add any missing information.
4
Choose a plan
Select Starter or Pro based on your needs. You can upgrade or downgrade at any time.
5
Install the embed & go live
Add a single script tag to your website. AI agents can now discover and interact with your business.

What does the AI extract from my website?

Our AI scrapes your website and uses Claude to extract structured data including:

Business name and description
Category and subcategory
Contact info (phone, email)
Physical address and location
Operating hours
Services with pricing
Suggested actions (booking, inquiries, etc.)
Relevant tags

It also reads any structured data (JSON-LD) already on your site for extra accuracy.

Can I skip AI onboarding and set up manually?

Yes. During onboarding you can click "Skip to manual setup" to fill in all fields yourself. The AI setup is purely optional — it just saves time.

Business Profile

Your profile is the structured representation of your business that AI agents read and understand.

Field	Description
Name	Your business name
Short Description	A one-liner summary (shown in search results)
Full Description	Detailed description of your business
Category / Subcategory	Primary category (e.g. restaurant, salon, plumber) and optional subcategory
Tags	Keywords that help agents find you (e.g. vegan, pet-friendly, 24hr)
Contact	Phone number, email address, website URL
Location	Street address, city, state/province, postal code, country, and GPS coordinates
Operating Hours	Open/close times for each day of the week
Logo	A URL to your business logo (shown in agent results)
Agent Instructions	Free-text instructions that AI agents will follow when interacting with your business

What are Agent Instructions?

Agent Instructions are free-text directives that AI agents read before interacting with your business. Use them to set rules, preferences, or context that agents should know about. Examples:

"Always confirm dietary restrictions before booking a table."
"We do not accept bookings for parties larger than 12."
"Recommend our house blend when asked about coffee."
"Emergency plumbing is available 24/7, standard bookings are business hours only."

How does location-based search work?

If you provide GPS coordinates (latitude/longitude), AI agents can search for businesses near a specific location. The search supports a configurable radius (1–100 km, defaults to 25 km). Your street address is shown to agents for display purposes.

Services

Services represent the things your business offers — products, appointments, consultations, treatments, and more.

Each service has a name, description, optional category, optional duration (in minutes), and flexible pricing. You can create as many services as your plan allows.

Pricing Type	Fields Used	Example Display
Fixed	Price amount	£50.00
Range	Price min & max	£30 – £60
From	Price amount	From £25.00
Free	—	Free
Custom	Price description (text)	Contact for pricing

How do AI agents see my services?

When an agent queries your services via the API, they receive structured data like this:

Response — GET /api/v1/businesses/{slug}/services

[
  {
    "id": "svc-123",
    "name": "Deep Tissue Massage",
    "description": "60-minute therapeutic massage",
    "category": "massage",
    "pricing": {
      "type": "fixed",
      "amount": 85,
      "currency": "GBP",
      "displayText": "£85.00"
    },
    "durationMinutes": 60
  }
]

Actions

Actions are executable operations that AI agents can trigger on behalf of customers — like booking an appointment, sending an inquiry, or requesting a quote.

Action Types

Type	Use Case
Inquire	General inquiries and questions
Book	Appointment and reservation booking
Get Quote	Price quote requests
Purchase	Direct purchases and orders
Custom	Any other action type

Delivery Methods

When an AI agent executes an action, AgentReadi delivers it to you using the method you configure:

Method	How It Works	Plan
Email	Sends a formatted email to your chosen address	Starter+
Form Submit	Stores the submission in your dashboard for review	Starter+
Webhook	POSTs a signed payload to your URL	Pro
External URL	Returns a URL for the agent to redirect the user to	Starter+

Actions can define an input schema (JSON Schema) that specifies what data the AI agent must provide when executing the action. For example, a booking action might require name, email, date, and party size.

How does email delivery work?

When an agent executes an email action, AgentReadi sends a formatted email to the address you configured. The subject line can include template variables like {{name}} that are filled in from the submitted data. The email body lists all submitted fields as key-value pairs.

How does webhook signing work?

Webhook payloads are signed with HMAC-SHA256 using your business's embed token as the secret. The signature is sent in the X-AgentReadi-Signature header. The payload structure:

Webhook payload

{
  "referenceId": "550e8400-e29b-41d4-a716-446655440000",
  "actionId": "act-123",
  "actionType": "book",
  "businessSlug": "the-coffee-house",
  "data": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "date": "2025-03-15"
  },
  "submittedAt": "2025-02-22T10:30:00.000Z"
}

Verify the signature on your server by computing HMAC-SHA256 of the raw request body using your embed token and comparing it to the header value.

What is an input schema?

An input schema is a JSON Schema object that defines what data an AI agent must provide when executing the action. For example:

Example input schema for a booking action

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "email": { "type": "string", "format": "email" },
    "date": { "type": "string", "format": "date" },
    "partySize": { "type": "integer", "minimum": 1 }
  },
  "required": ["name", "email", "date"]
}

AgentReadi validates the agent's submission against this schema before executing the action. If validation fails, the agent receives a clear error message.

Embed Script

A single line of code that makes your website discoverable by AI agents.

The embed script injects invisible metadata into your website's HTML that AI agents use to discover your business. It adds:

A link tag pointing to your agent manifest
A meta tag with your manifest URL
JSON-LD structured data (Schema.org) for search engines and agents

Installation

<script
  src="https://agentreadi.com/embed/v1.js"
  data-token="YOUR_EMBED_TOKEN"
  defer
></script>

You'll find your embed token and ready-to-copy code in the Embed & Integration section of your dashboard.

Platform installation guides

WordPress

Go to Appearance → Theme File Editor and add the script tag before the closing </body> tag in your theme's footer. Alternatively, use the "Insert Headers and Footers" plugin.

Shopify

Go to Online Store → Themes → Edit Code. Open theme.liquid and paste the script before the closing </body> tag.

Squarespace

Go to Settings → Advanced → Code Injection and paste the script into the Footer field.

Custom HTML

Paste the script tag anywhere in your HTML, ideally before the closing </body> tag. The defer attribute ensures it loads without blocking your page.

Is the embed visible to website visitors?

No. The embed script is completely invisible. It only adds metadata to your page's HTML <head> — no visual elements are rendered. Your visitors won't see or notice anything different.

Does it affect page performance?

Minimal impact. The script is deferred (non-blocking), under 1 KB in size, and only injects a few HTML tags. It does not load any external stylesheets, fonts, or additional scripts.

API Keys

Manage authentication keys for programmatic access.

AgentReadi uses two types of API keys:

Key Type	Prefix	Purpose
Agent API Key	`ar_live_` / `ar_test_`	For AI agent developers to authenticate API requests
SME API Key	`ar_sme_`	For business owners to programmatically manage their data (Pro plan only)

Security

API keys are hashed with SHA-256 before storage. The raw key is shown exactly once when created — copy it immediately and store it securely. Lost keys cannot be recovered; you'll need to revoke and create a new one.

How do I create an API key?

Navigate to API Keys in your dashboard (Pro plan required). Click "Create API Key", give it a name, and copy the raw key from the confirmation dialog. Store it in a secure location — it won't be shown again.

What if I lose my API key?

Lost keys cannot be recovered because we only store a one-way hash. Go to your dashboard, revoke the lost key, and create a new one. Update your integrations with the new key.

Analytics

Track how AI agents discover and interact with your business.

AgentReadi automatically tracks the following events:

Event	What It Means
Profile View	An AI agent viewed or searched for your business profile
Service Query	An agent queried your list of services
Action Execution	An agent executed one of your actions (booking, inquiry, etc.)
Manifest Fetch	Your agent manifest was fetched (from the embed or directly)
Embed Load	The embed script loaded on your website

View analytics by time period (7 days, 30 days, or 90 days) in your dashboard. Pro plan users get advanced insights including per-action breakdowns and conversion rates.

Analytics are tracked automatically once the embed script is installed. No additional setup required.

Plans & Limits

Choose the plan that fits your business.

Feature	Starter (£29/mo)	Pro (£79/mo)
Business profiles	1	Unlimited
Actions	Up to 5	Unlimited
Agent requests	1,000/mo	50,000/mo
Action methods	Email, Form	All methods
Webhook integrations	—	Included
API key management	—	Included
Analytics	Basic	Advanced insights
Custom branding	—	Included
Support	Email	Priority + onboarding call

See the full comparison on the pricing page. You can upgrade or downgrade at any time from your dashboard.

What counts as an agent request?

Any API call to the /api/v1/* endpoints counts as one request against your monthly quota. This includes searches, profile views, service queries, and action executions. Manifest fetches from the embed script also count.

API Reference

The AgentReadi API lets AI agents discover businesses, query services, and execute actions. All endpoints are under /api/v1/.

Authentication

Pass your API key in the Authorization header:

Authorization: Bearer ar_live_xxxxxxxxxxxxx

Most read endpoints work without authentication (anonymous), but with lower rate limits. Action execution (POST .../execute) requires a valid API key.

Rate Limits

Tier	Requests/min	Access
Anonymous	10	No API key
Free	60	Free-tier API key
Pro	300	Pro-tier API key
Enterprise	1,000	Contact sales

Rate limit info is included in every response via headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

GET/api/v1/businessesAuth optional

Search for businesses by name, category, location, tags, or action type.

Query Parameters

Param	Type	Description
`q`	string	Search by name or description
`category`	string	Filter by category
`subcategory`	string	Filter by subcategory
`tags`	string	Comma-separated tags to match
`has_action`	string	Filter by action type (book, inquire, etc.)
`lat`	number	Latitude for location search (–90 to 90)
`lng`	number	Longitude for location search (–180 to 180)
`radius_km`	number	Search radius in km (1–100, default 25)
`page`	number	Page number (default 1)
`per_page`	number	Results per page (1–100, default 20)

Example request

curl "https://agentreadi.com/api/v1/businesses?category=restaurant&lat=45.5&lng=-122.6&radius_km=10" \
  -H "Authorization: Bearer ar_live_xxxxxxxxxxxxx"

Example response

{
  "data": [
    {
      "slug": "the-coffee-house",
      "name": "The Coffee House",
      "shortDescription": "Premium espresso bar and bakery",
      "category": "restaurant",
      "subcategory": "cafe",
      "tags": ["vegan", "pet-friendly"],
      "location": {
        "city": "Portland",
        "stateProvince": "OR",
        "country": "US"
      },
      "actionTypes": ["book", "inquire"],
      "serviceCount": 5,
      "profileUrl": "https://agentreadi.com/api/v1/businesses/the-coffee-house"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 3,
    "totalPages": 1
  }
}

GET/api/v1/businesses/{slug}Auth optional

Get the full profile for a specific business, including services, actions, operating hours, and agent instructions.

Example response

{
  "slug": "the-coffee-house",
  "name": "The Coffee House",
  "description": "Premium espresso bar and bakery in downtown Portland.",
  "shortDescription": "Best espresso in town",
  "category": "restaurant",
  "subcategory": "cafe",
  "tags": ["vegan", "pet-friendly"],
  "location": {
    "address": "123 Main St",
    "city": "Portland",
    "stateProvince": "OR",
    "postalCode": "97214",
    "country": "US",
    "coordinates": { "lat": 45.5, "lng": -122.6 }
  },
  "contact": {
    "phone": "(503) 555-0123",
    "email": "hello@coffeehouse.com",
    "website": "https://coffeehouse.com"
  },
  "operatingHours": {
    "monday": { "open": "07:00", "close": "19:00" },
    "tuesday": { "open": "07:00", "close": "19:00" },
    "wednesday": "closed"
  },
  "agentInstructions": "Recommend our house blend. No parties over 12.",
  "services": [ ... ],
  "actions": [ ... ],
  "_meta": {
    "agentReadiVersion": "1.0",
    "lastUpdated": "2025-02-22T10:30:00Z",
    "profileUrl": "https://agentreadi.com/api/v1/businesses/the-coffee-house",
    "manifestUrl": "https://agentreadi.com/api/v1/manifest/abc123"
  }
}

GET/api/v1/businesses/{slug}/servicesAuth optional

List all active services for a business with pricing details.

Example response

[
  {
    "id": "svc-123",
    "name": "Espresso",
    "description": "Single or double shot",
    "category": "beverages",
    "pricing": {
      "type": "fixed",
      "amount": 3.50,
      "min": null,
      "max": null,
      "currency": "GBP",
      "displayText": "£3.50"
    },
    "durationMinutes": null
  }
]

GET/api/v1/businesses/{slug}/actionsAuth optional

List all active actions for a business, including input schemas and execute URLs.

Example response

[
  {
    "id": "act-456",
    "type": "book",
    "name": "Book a Table",
    "description": "Reserve a table at the restaurant",
    "serviceId": null,
    "inputSchema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string", "format": "email" },
        "date": { "type": "string", "format": "date" },
        "partySize": { "type": "integer", "minimum": 1 }
      },
      "required": ["name", "email", "date"]
    },
    "executeUrl": "https://agentreadi.com/api/v1/businesses/the-coffee-house/actions/act-456/execute"
  }
]

POST/api/v1/businesses/{slug}/actions/{actionId}/executeAuth required

Execute an action on behalf of a user. The request body must match the action's input schema.

This is the only endpoint that requires authentication. Anonymous requests receive a 401 error.

Example request

curl -X POST "https://agentreadi.com/api/v1/businesses/the-coffee-house/actions/act-456/execute" \
  -H "Authorization: Bearer ar_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "jane@example.com",
    "date": "2025-03-15",
    "partySize": 4
  }'

Example response

{
  "status": "accepted",
  "message": "Action executed successfully",
  "referenceId": "550e8400-e29b-41d4-a716-446655440000",
  "action": {
    "type": "book",
    "name": "Book a Table"
  }
}

GET/api/v1/manifest/{token}Public

Fetch the machine-readable agent manifest for a business. This is the endpoint the embed script points AI agents to. Cached for 5 minutes.

Example response (abbreviated)

{
  "schema_version": "1.0",
  "generated_at": "2025-02-22T10:30:00Z",
  "business": {
    "name": "The Coffee House",
    "slug": "the-coffee-house",
    "description": "Premium espresso bar and bakery",
    "category": "restaurant"
  },
  "contact": {
    "email": "hello@coffeehouse.com",
    "phone": "(503) 555-0123"
  },
  "services": [ ... ],
  "actions": [ ... ],
  "agent_instructions": "Recommend our house blend.",
  "_links": {
    "self": "https://agentreadi.com/api/v1/manifest/abc123",
    "api_profile": "https://agentreadi.com/api/v1/businesses/the-coffee-house"
  },
  "_provider": {
    "name": "AgentReadi",
    "url": "https://agentreadi.com",
    "api_version": "v1"
  }
}

Error Responses

All errors return a consistent JSON format:

Error format

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Business not found"
  }
}

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing or invalid API key
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource does not exist
`VALIDATION_ERROR`	400	Invalid request parameters
`RATE_LIMITED`	429	Rate limit exceeded — wait and retry
`INTERNAL_ERROR`	500	Server error

Key Concepts

Understand the ideas behind AgentReadi.

What are AI agents?

AI agents are software programs that act on behalf of users — browsing the web, searching for information, and taking actions. Unlike traditional search engines that show links, agents can directly interact with businesses: booking appointments, sending inquiries, and completing purchases. They're the next generation of "customers" for your business.

How does discovery work?

Here's the flow from installation to interaction:

You install the embed script on your website
The script injects a manifest link into your page's HTML
An AI agent visits your website and finds the manifest link
The agent fetches your manifest — a structured JSON file with your business data
The agent now knows your services, actions, hours, location, and instructions
The agent can search, query, and execute actions via the AgentReadi API

How does action execution work?

An AI agent calls POST .../execute with data matching your action's input schema
AgentReadi validates the input
The action is dispatched via your configured method (email, webhook, form submission, or external URL)
A reference ID is returned so both you and the agent can track the interaction

Why structured data matters

Traditional websites are designed for humans — unstructured text, images, and navigation that AI agents struggle to parse reliably. AgentReadi provides a structured, machine-readable manifest that agents can understand instantly: your services with exact pricing, available actions with input requirements, operating hours, and explicit instructions. This means agents interact with your business accurately instead of guessing from web page content.

Ready to be discovered by AI agents?

Join hundreds of businesses already using AgentReadi to connect with the next generation of customers.

Get Started