Sign in Sign up

Public API for AI assistants

Updated on Wednesday 04 November 2026

How an AI assistant or your own software looks up Citauno businesses, services, prices and free times, and builds the booking link.

Citauno has a read-only public API: an AI assistant (ChatGPT, Claude, Gemini, Perplexity) or any program can search businesses, read their services with price and duration, their locations and hours, and see the real free times for a service. To book, the API returns the link to the booking form with everything already chosen: the person opens it, reviews it, enters their details and confirms.

There is nothing to sign up for and no key to ask for. Assistants that take MCP servers connect directly at https://citauno.com/mcp (see Connect an assistant (MCP)).

Which businesses are listed

The same ones listed in Explore (/explorar): published, with “Show in marketplace home and search” ticked, taking online bookings and ready to be booked (at least one active service, a location with an open day and a professional who takes bookings). A business that is paused, deleted, hidden from the marketplace or has online bookings off is not listed, and its API address answers 404.

If you own a business and don’t want to be listed, untick “Show in marketplace home and search” in Settings. Your profile and booking link keep working for anyone who already has them.

What it returns and what it doesn’t

It returns only what anyone sees on your profile and your booking page:

  • name, category, description, cover and logo, rating (only when the profile shows it);
  • locations with address, city, coordinates and opening hours;
  • services bookable online, with duration and price in the business’s currency (“from” when the price depends on the professional);
  • free days and times, worked out as the booking page does, with no professional chosen.

It does not return phone numbers, emails, professionals’ names, clients, bookings or anything only the owner sees. It does not create bookings: it only builds the link for the person to confirm.

The addresses

All of them answer JSON at https://citauno.com/api/v1. The language of names and messages is chosen with ?locale=es, pt or en (Spanish when none is given).

Address What it returns Parameters
GET /api/v1/businesses Businesses that match the search, 20 at a time q (text), city, country (code, e.g. PY), category[] (an Explore category, e.g. barberia), service (a service name), page, per_page (up to 50)
GET /api/v1/businesses/{slug} One business with its locations, hours and services
GET /api/v1/businesses/{slug}/availability The days with at least one free time service_ids[] (required, up to 5), location_id, from and to (YYYY-MM-DD; up to 62 days)
GET /api/v1/businesses/{slug}/slots One day’s free times, each with its booking link service_ids[], date (required), location_id
GET /api/v1/businesses/{slug}/booking_link The link to the booking form with everything chosen service_ids[], location_id, date, starts_at (ISO 8601)

The slug is the end of the profile link: for citauno.com/downtown-barbers it is downtown-barbers. Service and location ids come from the business’s address. Without location_id the first location is used, as on the booking page.

An example

  1. Search for barbers in Asunción:

    GET https://citauno.com/api/v1/businesses?q=barber&city=Asuncion&locale=en

  2. Read a business and its services:

    GET https://citauno.com/api/v1/businesses/downtown-barbers?locale=en

  3. See which days have room for service 12:

    GET https://citauno.com/api/v1/businesses/downtown-barbers/availability?service_ids[]=12

  4. See one day’s times. Each time carries its booking_url:

    GET https://citauno.com/api/v1/businesses/downtown-barbers/slots?service_ids[]=12&date=2026-11-10&locale=en

    {
  "business": "downtown-barbers",
  "timezone": "America/Asuncion",
  "location_id": 3,
  "service_ids": [12],
  "date": "2026-11-10",
  "slots": [
    {
      "starts_at": "2026-11-10T09:00:00-03:00",
      "ends_at": "2026-11-10T09:30:00-03:00",
      "booking_url": "https://citauno.com/en/businesses/downtown-barbers/book?..."
    }
  ]
}

  5. Give the person the booking_url. It opens the form with the service, location, day and time already chosen; they enter their name and WhatsApp and confirm. The booking is marked as coming from an AI assistant.

Times are in the business’s time zone, with their offset (-03:00), and timezone is that zone’s IANA name (America/Asuncion, America/Sao_Paulo), which any programming language understands.

When a day has no times, slots is empty and reason says why: closed_day (the location is closed that day), fully_booked (everything is taken), all_past (they have passed), outside_window (before today or beyond the days the business takes bookings for), among others.

Connect an assistant (MCP)

Assistants that take remote MCP servers (Claude, ChatGPT, Cursor and others) connect with no programming. The server’s address is:

https://citauno.com/mcp

Add it as a custom connector or MCP server in your assistant. It asks for no sign-in and no key. The assistant sees four tools, all read-only:

Tool What it does
search_businesses Searches businesses by text, city, country, category or service
get_business One business with its locations, hours and services with prices
get_availability The days with a free time or, with date, that day’s times
booking_link The link to the booking form with everything chosen

They answer what the addresses above answer, for the same businesses. The language is chosen with locale (es, pt or en) on each tool, or for all of them in the address: with https://citauno.com/mcp?locale=en the assistant reads the tools and the answers in English. They don’t book either: the assistant gives the person the link and they confirm. An error comes back as the tool’s result with isError and the same message the API gives.

For developers: it is an MCP server over Streamable HTTP, stateless (there is no Mcp-Session-Id), that answers each POST with JSON. A test from the terminal:

curl -X POST https://citauno.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_businesses","arguments":{"city":"Asunción"}}}'

Limits and errors

  • Limit per connection: 300 requests every 5 minutes, the API and the MCP server together. Past it, the answer is 429 with Retry-After.

  • No cookies or session. It can be called from the browser on any site (CORS open for GET on the API and for POST on /mcp).

  • Answers may be kept for a minute (30 seconds for times).

  • An error carries a fixed code and a message in the language asked for:

    { "error": { "code": "service_not_found", "message": "One of the services does not exist at this business or cannot be booked online." } }
    code Status When
    business_not_found 404 The business does not exist or is not listed in Explore
    services_required 400 The service_ids[] are missing
    too_many_services 400 More than 5 services
    service_not_found 400 A service is not this business’s or cannot be booked online
    location_not_found 400 The location_id is not this business’s
    date_required, invalid_date 400 date is missing or not YYYY-MM-DD
    invalid_starts_at 400 starts_at is not a valid date and time
    rate_limited 429 The limit was passed
    route_not_found 404 The address does not exist

The API is version 1 (/api/v1). A change that breaks what already works will go in a new version.