Agoria

Find businesses on Agoria by free-text query, category, and/or city. Returns each business's slug plus the actions its agent can take, so you can act on it directly from this same connection.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "e.g. 'emergency plumber', 'gluten free pizza'"
    },
    "category": {
      "type": "string"
    },
    "city": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Search individual items across every business on the network — property listings, vehicles, courses, products, services, events, plans — with typed filters, a price range and a radius around a place. Prefer this over search_businesses whenever the user is looking for a THING rather than a company. Returns items with prices, locations, photo counts and the seller's verification status.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Free text, e.g. 'renovated terrace', 'diesel ute'"
    },
    "kind": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Item kinds to include, e.g. ['listing'], ['vehicle'], ['course']. Call list_market_filters to see what exists."
    },
    "where": {
      "type": "string",
      "description": "A suburb, postcode, city or 'lat,lng'"
    },
    "radiusKm": {
      "type": "number",
      "description": "Radius around `where`. Defaults to the size of the place named."
    },
    "minPrice": {
      "type": "number"
    },
    "maxPrice": {
      "type": "number"
    },
    "filters": {
      "type": "object",
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          {
            "type": "object",
            "properties": {
              "min": {
                "type": "number"
              },
              "max": {
                "type": "number"
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "description": "Typed facet filters keyed by field id, e.g. {\"beds\":{\"min\":3},\"make\":\"toyota\"}"
    },
    "verifiedOnly": {
      "type": "boolean",
      "description": "Only items from businesses whose details have been checked against an outside register"
    },
    "sort": {
      "type": "string",
      "enum": [
        "relevance",
        "price_asc",
        "price_desc",
        "newest",
        "nearest",
        "proven"
      ]
    },
    "limit": {
      "type": "number"
    },
    "page": {
      "type": "number"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Same index as search_market, but takes a plain sentence — 'three bedroom house under 800k in Geelong', 'automatic ute under 80,000km' — and works out the filters itself. Use it when you have the user's own words; use search_market when you already know the exact filters.

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The user's request, in their words"
    }
  },
  "required": [
    "question"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Everything about a single item: full facets, photos, where it is, who is selling it and how well-proven they are, a price guide computed from comparable items on the network, and the adjacent services a buyer usually needs next (finance, inspection, conveyancing, transport).

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "description": "Item ref from search_market, e.g. 'acme-motors/offering:stk991'"
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

What can be searched and filtered on. Call this when you are unsure which `kind` or which `filters` keys search_market will accept.

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Narrow to specific kinds"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

A price distribution for comparable items on the network — asking prices, and where the network settled the sale, what buyers actually paid. Widens the comparison and says so when the exact match is too thin to be meaningful.

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "Item kind, e.g. 'vehicle' or 'listing'"
    },
    "attributes": {
      "type": "object",
      "additionalProperties": {
        "type": [
          "string",
          "number"
        ]
      },
      "description": "What is being priced, e.g. {\"make\":\"Toyota\",\"model\":\"HiLux\",\"year\":2021}"
    },
    "where": {
      "type": "string",
      "description": "Restrict to a locality first; dropped automatically if too thin"
    }
  },
  "required": [
    "kind",
    "attributes"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Save a standing search on the customer's behalf. They get told when matching supply appears, AND — anonymously, without their contact details — sellers who could satisfy it can see it and offer. Use this when search_market found nothing good: it converts a dead end into a request the market can answer.

{
  "type": "object",
  "properties": {
    "contact": {
      "type": "string",
      "description": "The customer's email — never shown to sellers"
    },
    "request": {
      "type": "string",
      "description": "What they want, in their words"
    },
    "name": {
      "type": "string"
    },
    "cadence": {
      "type": "string",
      "enum": [
        "instant",
        "daily",
        "weekly"
      ],
      "description": "How often to tell them about new matches"
    }
  },
  "required": [
    "contact",
    "request"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Open standing requests from real buyers, anonymised. Useful for a business deciding what to stock or list, and for understanding where the network has no supply at all.

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "where": {
      "type": "string"
    },
    "unmetOnly": {
      "type": "boolean",
      "description": "Only requests nothing currently matches"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Resolve a suburb, postcode or city to coordinates and the radius that name implies. Use it to check a place exists before passing it to search_market.

{
  "type": "object",
  "properties": {
    "where": {
      "type": "string",
      "description": "e.g. 'Fitzroy', '3065', 'Geelong VIC'"
    }
  },
  "required": [
    "where"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get full details for a business by slug: description, contact, hours, services, FAQs, and the actions its agent supports.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Business slug from search_businesses"
    }
  },
  "required": [
    "slug"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List the products a business sells by slug — price/sale, availability/stock, brand, SKU/GTIN, variants, specs, dimensions.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Business slug"
    },
    "query": {
      "type": "string",
      "description": "Optional keyword filter"
    }
  },
  "required": [
    "slug"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get a business's aggregate rating and reviews by slug. Optionally filter to a product/service id.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Business slug"
    },
    "targetId": {
      "type": "string",
      "description": "Product/service id; omit for whole business"
    }
  },
  "required": [
    "slug"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Check open appointment slots for a service at a business on a date (YYYY-MM-DD).

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Business slug"
    },
    "serviceId": {
      "type": "string",
      "description": "Service id from get_business"
    },
    "date": {
      "type": "string",
      "description": "YYYY-MM-DD"
    }
  },
  "required": [
    "slug",
    "serviceId",
    "date"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Book an appointment at any business by slug. Confirm the slot with check_availability first.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Business slug"
    },
    "serviceId": {
      "type": "string"
    },
    "startsAt": {
      "type": "string",
      "description": "ISO datetime from check_availability"
    },
    "customerName": {
      "type": "string"
    },
    "customerContact": {
      "type": "string",
      "description": "Phone or email"
    },
    "note": {
      "type": "string"
    }
  },
  "required": [
    "slug",
    "serviceId",
    "startsAt",
    "customerName",
    "customerContact"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Perform any non-booking action a business supports (request_quote, place_order, send_message, pay_invoice, sign_document, subscribe, register…). Get valid action ids and their fields from get_business. Pass the action's fields as a JSON object. If the result is 'action_required', hand the user the next.url (payment/signing link) or re-call with fields.confirmToken to confirm.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Business slug"
    },
    "action": {
      "type": "string",
      "description": "Action id, e.g. 'request_quote'"
    },
    "fields": {
      "type": "object",
      "additionalProperties": {},
      "description": "The action's input fields as a JSON object (include confirmToken to complete a gated action)"
    }
  },
  "required": [
    "slug",
    "action",
    "fields"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Describe a job once and send it to the businesses that can price it. Each one answers with a real number, what it covers, and how long the price stands. Returns a briefToken — poll compare_quotes with it to see the prices as they land, then accept_quote to choose one. Use this instead of calling request_quote at each business separately.

{
  "type": "object",
  "properties": {
    "details": {
      "type": "string",
      "description": "What the customer needs, in plain language. The more specific, the better the quotes."
    },
    "title": {
      "type": "string",
      "description": "Short label for the job"
    },
    "category": {
      "type": "string",
      "description": "Business category to target, e.g. 'Plumber'"
    },
    "location": {
      "type": "string",
      "description": "City or suburb"
    },
    "budget": {
      "type": "number"
    },
    "neededBy": {
      "type": "string",
      "description": "When it's needed"
    },
    "customerName": {
      "type": "string"
    },
    "customerContact": {
      "type": "string",
      "description": "Email or phone — businesses quote back to this"
    },
    "slugs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Specific businesses to ask. Omit to have Agoria match them."
    }
  },
  "required": [
    "details",
    "customerContact"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

See every business's answer to a brief side by side: price, what it covers, lead time, rating, whether the payment would be protected, and which is cheapest or soonest.

{
  "type": "object",
  "properties": {
    "briefToken": {
      "type": "string",
      "description": "From request_quotes"
    }
  },
  "required": [
    "briefToken"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Choose a business's quote. This creates a real order at that business and declines the others. If that business protects payments, the reply carries a payment link where the money is held by Agoria until the customer confirms they got the work — hand that link to the customer.

{
  "type": "object",
  "properties": {
    "briefToken": {
      "type": "string",
      "description": "From request_quotes"
    },
    "slug": {
      "type": "string",
      "description": "The business whose quote to accept"
    }
  },
  "required": [
    "briefToken",
    "slug"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}