{
    "ok": 1,
    "version": "2.0",
    "base_url": "https://brringit.com",
    "description": "Browse shops, build a cart, and place orders on behalf of a customer across the Brringit marketplace. One tool registry is served over several transports; pick whichever your agent supports.",
    "transports": {
        "mcp": {
            "url": "https://brringit.com/?pp=agent_mcp",
            "protocol": "Model Context Protocol (JSON-RPC 2.0 over HTTP)",
            "note": "Preferred. Discover tools with tools/list, invoke with tools/call. Recommended for Claude and other MCP-capable voice agents."
        },
        "openapi": {
            "url": "https://brringit.com/?pp=agent_openapi",
            "protocol": "OpenAPI 3.1",
            "note": "For platforms that import HTTP tools from a spec (e.g. ChatGPT actions, ElevenLabs). Operations are POST /agent/{tool}."
        },
        "rest": {
            "url": "https://brringit.com/?pp=agent_call&tool={tool_name}",
            "method": "POST",
            "body": "application/json",
            "note": "Generic first-party REST. Same tools, same JSON responses."
        }
    },
    "auth": {
        "model": "Optional consumer identity, to act on behalf of a signed-in customer.",
        "how": "Send the customer auth_token as HTTP header \"Authorization: Bearer <token>\" (MCP) or as an \"auth_token\" field in the request body (REST). When present, saved address and profile fields backfill the order and past orders/addresses become available.",
        "anonymous": "All browsing and ordering tools also work without a token; the agent then supplies the customer object explicitly on place_order/submit_order."
    },
    "response_shape": {
        "success": "{ \"ok\": 1, ...payload }",
        "error": "{ \"ok\": 0, \"error\": \"<code>\", \"message\": \"<human readable>\", ...context }",
        "note": "Error messages are written to be read aloud to the caller. On option errors, an \"available\" list of valid choices is included."
    },
    "recommended_flow": [
        {
            "step": 1,
            "tool": "confirm_address",
            "when": "delivery only",
            "note": "Geocode and read the address back before searching."
        },
        {
            "step": 2,
            "tool": "find_shops",
            "note": "delivery (with address) or takeout. Pick a shop -> use its ssh."
        },
        {
            "step": 3,
            "tool": "get_menu",
            "note": "Always fetch before ordering. Use exact item codes; never guess."
        },
        {
            "step": 4,
            "tool": "add_to_cart",
            "note": "Leave session_id empty first time, reuse the returned one. Include required option groups."
        },
        {
            "step": 5,
            "tool": "get_cart",
            "note": "Read items + total back to the caller to confirm."
        },
        {
            "step": 6,
            "tool": "place_order",
            "note": "Submits the order and returns a hosted payment link (card) or confirms cash on delivery. See payment below."
        },
        {
            "step": 7,
            "tool": "order_status",
            "note": "Poll to confirm payment/fulfilment."
        }
    ],
    "payment": {
        "model": "The agent never handles card details. place_order with payment_method \"card\" returns a checkout_url on the active PSP (Viva Smart Checkout for Greece, which offers IRIS and cards); the customer opens it and pays. payment_method \"cod\" is cash on delivery and returns no link.",
        "confirmation": "Payment is confirmed out of band by the PSP webhook; the order flips to paid. Use order_status to see the paid flag.",
        "note": "payment_status in the place_order response is \"pending\" for card until the webhook confirms."
    },
    "rules": [
        "always_fetch_menu_before_ordering",
        "always_use_exact_item_code_never_guess",
        "always_confirm_cart_and_total_before_place_order",
        "store_and_reuse_session_id_across_cart_calls",
        "read_error_message_to_caller_and_offer_valid_choices"
    ],
    "tools": [
        {
            "name": "confirm_address",
            "summary": "Geocode a spoken address for confirmation",
            "description": "Geocode an address and return the structured result. Call this before find_shops for delivery. Read display_name back to the caller and confirm. If is_precise is false, ask for the street number.",
            "auth": "none",
            "params": [
                {
                    "name": "address",
                    "type": "string",
                    "required": true,
                    "description": "The address as spoken, as complete as possible incl. street number and city."
                }
            ]
        },
        {
            "name": "find_shops",
            "summary": "Find shops that serve an address (delivery) or offer takeout",
            "description": "Search shops that deliver to the address, or all takeout shops. For delivery, pass a confirmed address. Returns a list of shops with their ssh identifiers.",
            "auth": "none",
            "params": [
                {
                    "name": "service_type",
                    "type": "string",
                    "required": true,
                    "description": "delivery or takeout.",
                    "enum": [
                        "delivery",
                        "takeout"
                    ]
                },
                {
                    "name": "address",
                    "type": "string",
                    "required": false,
                    "description": "Delivery address. Required when service_type is delivery."
                }
            ]
        },
        {
            "name": "check_address",
            "summary": "Check whether one specific shop serves an address",
            "description": "Given a shop ssh and an address, check whether that shop delivers there (or confirm takeout).",
            "auth": "none",
            "params": [
                {
                    "name": "ssh",
                    "type": "string",
                    "required": true,
                    "description": "Shop identifier."
                },
                {
                    "name": "service_type",
                    "type": "string",
                    "required": true,
                    "description": "delivery or takeout.",
                    "enum": [
                        "delivery",
                        "takeout"
                    ]
                },
                {
                    "name": "address",
                    "type": "string",
                    "required": false,
                    "description": "Address to check. Required for delivery."
                }
            ]
        },
        {
            "name": "get_menu",
            "summary": "Fetch a shop full menu",
            "description": "Fetch the full menu (categories, items, options) for a shop. Always call before ordering. Use exact item codes; never guess. Watch required option groups.",
            "auth": "none",
            "params": [
                {
                    "name": "ssh",
                    "type": "string",
                    "required": true,
                    "description": "Shop identifier from find_shops."
                },
                {
                    "name": "lang",
                    "type": "string",
                    "required": false,
                    "description": "Menu language, e.g. English or Greek. Default English."
                }
            ]
        },
        {
            "name": "add_to_cart",
            "summary": "Add a menu item (with options) to the cart",
            "description": "Add an item to the cart using the exact item_code from get_menu. Leave session_id empty on the first call and reuse the one returned. Options is an array of {group_id, value_code, quantity}. If a required group is missing you get an option_group_below_min error listing valid choices.",
            "auth": "optional",
            "params": [
                {
                    "name": "ssh",
                    "type": "string",
                    "required": true,
                    "description": "Shop identifier."
                },
                {
                    "name": "item_code",
                    "type": "string",
                    "required": true,
                    "description": "Exact item code from the menu."
                },
                {
                    "name": "session_id",
                    "type": "string",
                    "required": false,
                    "description": "Cart session id. Empty on first call, reuse afterwards."
                },
                {
                    "name": "quantity",
                    "type": "integer",
                    "required": false,
                    "description": "How many. Default 1."
                },
                {
                    "name": "options",
                    "type": "array",
                    "required": false,
                    "description": "Array of {group_id, value_code, quantity}."
                },
                {
                    "name": "line_comment",
                    "type": "string",
                    "required": false,
                    "description": "Special instructions. Optional."
                }
            ]
        },
        {
            "name": "get_cart",
            "summary": "Read the current cart",
            "description": "Return the cart contents and total. Call before submit_order to confirm with the caller.",
            "auth": "none",
            "params": [
                {
                    "name": "ssh",
                    "type": "string",
                    "required": true,
                    "description": "Shop identifier."
                },
                {
                    "name": "session_id",
                    "type": "string",
                    "required": true,
                    "description": "Cart session id."
                }
            ]
        },
        {
            "name": "update_cart_line",
            "summary": "Change quantity/options on a cart line",
            "description": "Update an existing cart line by cart_line_id (from get_cart).",
            "auth": "none",
            "params": [
                {
                    "name": "ssh",
                    "type": "string",
                    "required": true,
                    "description": "Shop identifier."
                },
                {
                    "name": "session_id",
                    "type": "string",
                    "required": true,
                    "description": "Cart session id."
                },
                {
                    "name": "cart_line_id",
                    "type": "integer",
                    "required": true,
                    "description": "cart_line_id from get_cart."
                },
                {
                    "name": "quantity",
                    "type": "integer",
                    "required": false,
                    "description": "New quantity. Default 1."
                },
                {
                    "name": "options",
                    "type": "array",
                    "required": false,
                    "description": "Replacement options array."
                },
                {
                    "name": "line_comment",
                    "type": "string",
                    "required": false,
                    "description": "Replacement comment."
                }
            ]
        },
        {
            "name": "remove_cart_line",
            "summary": "Remove a cart line",
            "description": "Remove a cart line by cart_line_id (from get_cart).",
            "auth": "none",
            "params": [
                {
                    "name": "ssh",
                    "type": "string",
                    "required": true,
                    "description": "Shop identifier."
                },
                {
                    "name": "session_id",
                    "type": "string",
                    "required": true,
                    "description": "Cart session id."
                },
                {
                    "name": "cart_line_id",
                    "type": "integer",
                    "required": true,
                    "description": "cart_line_id from get_cart."
                }
            ]
        },
        {
            "name": "clear_cart",
            "summary": "Empty the cart for a session",
            "description": "Empty the cart for this session across all shops. Use when the caller switches shops or cancels.",
            "auth": "none",
            "params": [
                {
                    "name": "session_id",
                    "type": "string",
                    "required": true,
                    "description": "Cart session id."
                }
            ]
        },
        {
            "name": "submit_order",
            "summary": "Submit the cart as an order",
            "description": "Turn the cart into an order. Provide a customer object {name, phone, address, zip, city} — or, if the caller is signed in (auth_token), missing fields are filled from their profile. Returns order_id and amount. Payment is a separate step.",
            "auth": "optional",
            "params": [
                {
                    "name": "ssh",
                    "type": "string",
                    "required": true,
                    "description": "Shop identifier."
                },
                {
                    "name": "session_id",
                    "type": "string",
                    "required": true,
                    "description": "Cart session id."
                },
                {
                    "name": "customer",
                    "type": "object",
                    "required": false,
                    "description": "Customer details {name, phone, email, address, zip, city}. Optional when signed in."
                }
            ]
        },
        {
            "name": "place_order",
            "summary": "Submit the cart and get a hosted payment link (agent never handles cards)",
            "description": "Submit the cart as an order and, for card payment, return a short-lived hosted checkout URL the customer opens to pay. This is the payment path for agents: card details never pass through the agent or this API. Use payment_method \"cod\" for cash on delivery (no link is returned). Provide a customer object, or rely on auth_token when signed in.",
            "auth": "optional",
            "params": [
                {
                    "name": "ssh",
                    "type": "string",
                    "required": true,
                    "description": "Shop identifier."
                },
                {
                    "name": "session_id",
                    "type": "string",
                    "required": true,
                    "description": "Cart session id."
                },
                {
                    "name": "customer",
                    "type": "object",
                    "required": false,
                    "description": "Customer details {name, phone, email, address, zip, city}. Optional when signed in."
                },
                {
                    "name": "payment_method",
                    "type": "string",
                    "required": false,
                    "description": "card returns a checkout link; cod is cash on delivery. Default card.",
                    "enum": [
                        "card",
                        "cod"
                    ]
                },
                {
                    "name": "success_url",
                    "type": "string",
                    "required": false,
                    "description": "Optional return URL after successful payment."
                },
                {
                    "name": "cancel_url",
                    "type": "string",
                    "required": false,
                    "description": "Optional return URL if payment is cancelled."
                },
                {
                    "name": "send_link_sms",
                    "type": "boolean",
                    "required": false,
                    "description": "Text the checkout link to the order phone by SMS. Defaults on for voice (el) calls."
                }
            ]
        },
        {
            "name": "order_status",
            "summary": "Check the status of an order",
            "description": "Return basic status for an order_id: total, paid flag, submitted/delivered timestamps. If signed in, only the caller own orders are visible.",
            "auth": "optional",
            "params": [
                {
                    "name": "order_id",
                    "type": "integer",
                    "required": true,
                    "description": "Order id from submit_order."
                }
            ]
        },
        {
            "name": "me",
            "summary": "Return the signed-in caller profile",
            "description": "Validate the auth_token and return the consumer profile.",
            "auth": "required",
            "params": []
        },
        {
            "name": "my_addresses",
            "summary": "Saved + order-history addresses for the caller",
            "description": "Return the signed-in caller saved addresses and addresses seen in past orders.",
            "auth": "required",
            "params": []
        },
        {
            "name": "my_orders",
            "summary": "Past orders for the caller",
            "description": "Return the signed-in caller past orders with line items.",
            "auth": "required",
            "params": [
                {
                    "name": "limit",
                    "type": "integer",
                    "required": false,
                    "description": "Max orders (1-100, default 20)."
                },
                {
                    "name": "offset",
                    "type": "integer",
                    "required": false,
                    "description": "Pagination offset."
                }
            ]
        },
        {
            "name": "send_payment_link",
            "summary": "Text the hosted payment link for an order to the caller",
            "description": "Send (or resend) the hosted checkout link for an existing card order by SMS to the phone on that order. Use after place_order on a voice call, or when the caller asks for the link again. Reuses the stored link; never creates a duplicate charge.",
            "auth": "optional",
            "params": [
                {
                    "name": "order_id",
                    "type": "integer",
                    "required": true,
                    "description": "Order id from place_order / submit_order."
                }
            ]
        }
    ]
}