# AgentReady public API

> AgentReady makes Irish service businesses bookable by AI shopping agents. Any AI assistant or
> developer can read a business, check live availability and create a confirmed booking through a
> public JSON API with no authentication. Every agent interaction is logged with an EU AI Act
> Article 50 disclosure record.

base_url: https://agentready.ie
docs: https://agentready.ie/developers
auth: none
content_type: application/json
method: POST (all endpoints)
timezone: Europe/Dublin (slots also carry UTC instants)

## Endpoints

### getServices
url: https://agentready.ie/functions/getServices
request: {"slug":"<business-slug>","agent_name":"<string>","agent_version":"<string>"}
returns: business{name,slug,category,description,address,city,county,phone,email},
         services[]{id,name,description,duration_minutes,price,category},
         disclosure{required:true,ai_act_article:50,text},
         endpoints{services,availability,createBooking,discovery}, storefront_url
errors: 400 slug is required; 404 business not found; 404 business is not published

### getAvailability
url: https://agentready.ie/functions/getAvailability
request: {"slug":"<business-slug>","service_id":"<service-id from getServices>","date":"YYYY-MM-DD"}
request_alt: {"slug":"<slug>","service_id":"<id>","from":"YYYY-MM-DD","to":"YYYY-MM-DD"} (max 60 days)
returns: business{name,slug,category}, service{id,name,duration_minutes,price}, timezone:"Europe/Dublin",
         days[]{date, slots[]{start,end,local_start,local_end}}
notes: slots are real bookable times only; availability rules, existing bookings and the business's
       minimum notice window are already applied. start/end are UTC ISO-8601 instants.
errors: 400 slug is required; 400 date, or from and to, is required; 404 business not found; 404 service not found

### createBooking
url: https://agentready.ie/functions/createBooking
request: {"slug":"<business-slug>","service_id":"<service-id>","start_time":"<start from getAvailability>",
          "customer_name":"<string>","customer_email":"<email>","customer_phone":"<string, optional>",
          "agent_name":"<string>","agent_version":"<string, optional>","disclosure_acknowledged":true}
returns_201: {booking_id, status:"confirmed", hold_expires_at:null, business, service,
              start, end, local_start, local_end, timezone}
errors:
  400 {"error":"disclosure_acknowledged must be true: the agent must acknowledge the Article 50 AI Act disclosure before creating a booking"}
  400 {"error":"customer_name is required"}
  400 {"error":"customer_email is required and must be a valid email address"}
  400 {"error":"service_id and start_time are required"} | {"error":"invalid start_time"}
  409 {"error":"requested slot is not available"}
notes: send only a start_time value returned by getAvailability; never construct slots.
       status 202 with status:"pending" is returned only when "hold":true is requested.

### getDiscovery
url: https://agentready.ie/functions/getDiscovery
request: {"slug":"<business-slug>"}
returns: schema_version, type:"agentready.service-business", business, api{...},
         capabilities[list_services,check_availability,create_booking],
         booking_rules{min_notice_hours,max_advance_days,cancellation_policy},
         disclosure{required:true,ai_act_article:50,text}, storefront_url, updated_at
errors: 400 slug is required; 404 business not found; 404 business is not published

## Booking flow

1. getServices with a business slug.
2. getAvailability with the service id and a date.
3. createBooking with a returned slot start_time and the customer details.
4. A 201 response confirms the booking; a 409 means the slot was taken in the meantime.

## Article 50 requirement

Every createBooking call MUST pass disclosure_acknowledged: true, and only after the business's
disclosure text from getServices (disclosure.text) has been presented to the user.
Attempts without it are rejected with 400 and are still logged with the disclosed value, so the
business sees them in the audit trail of its dashboard.

## Agent etiquette

Send agent_name and agent_version with every call, so the business can see which agent is booking.

## Storefronts

https://agentready.ie/s/<business-slug> — the human page for the same business and the same slug.

## Optional: MCP

url: https://agentready.ie/functions/mcpServer
MCP clients can use the tools search_business, get_business_info, get_availability and create_booking
instead of the REST endpoints.

## Links

GitHub: https://github.com/pronet630/agentready (OpenAPI spec, reference agent, MCP server)

## Operator

ProNetworks Ltd — https://agentready.ie