{
    "openapi": "3.1.0",
    "info": {
        "title": "Maid in Allen TX Public Agent API",
        "version": "1.0.0",
        "description": "Read-only public business and service information for Maid in Allen TX, a residential cleaning service in Allen, Texas. This API does not create quotes, bookings, appointments, payments or customer records. Responses carry IETF RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy headers; exceeding the quota returns 429 with Retry-After."
    },
    "servers": [
        {
            "url": "https://maidinallentx.com/api/v1"
        }
    ],
    "paths": {
        "/": {
            "get": {
                "summary": "API discovery index",
                "description": "Returns the absolute URLs of every other resource this API offers, so a client can start from one URL and find the rest without hard-coding paths.",
                "operationId": "getApiIndex",
                "responses": {
                    "200": {
                        "description": "API discovery links",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ApiIndex"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limited. See the RateLimit-* headers and Retry-After.",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Problem"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Problem details",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Problem"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/site": {
            "get": {
                "summary": "Get public business information",
                "description": "Name, address, phone, service areas, vehicle-free service types, differentiators, published price ranges and quote policy. Everything a client needs to answer \"what is this business and how do I reach it\".",
                "operationId": "getSiteInfo",
                "responses": {
                    "200": {
                        "description": "Public business information",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SiteInfo"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limited. See the RateLimit-* headers and Retry-After.",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Problem"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Problem details",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Problem"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/services": {
            "get": {
                "summary": "List public cleaning services",
                "description": "Every cleaning service offered, each with a stable slug, a display name, the canonical page URL and a description of what the service covers.",
                "operationId": "listServices",
                "responses": {
                    "200": {
                        "description": "Service list",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ServiceList"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limited. See the RateLimit-* headers and Retry-After.",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Problem"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Problem details",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Problem"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/services/{slug}": {
            "get": {
                "summary": "Get one public service by slug",
                "description": "Returns a single service. Call listServices first to obtain valid slugs; they are stable and safe to cache.",
                "operationId": "getService",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "description": "Stable service identifier, as returned by listServices. Lowercase letters, digits and hyphens only.",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z0-9-]+$",
                            "examples": [
                                "bi-weekly-cleaning"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Service details",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Service"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown service",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Problem"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limited. See the RateLimit-* headers and Retry-After.",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Problem"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Problem details",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Problem"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/areas": {
            "get": {
                "summary": "List the city hubs served",
                "description": "The cities this business serves, each with the canonical hub page for that city. Use it to decide whether a given address is in the service area.",
                "operationId": "listAreas",
                "responses": {
                    "200": {
                        "description": "City hubs",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AreaList"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limited. See the RateLimit-* headers and Retry-After.",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Problem"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Problem details",
                        "content": {
                            "application/problem+json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Problem"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "PostalAddress": {
                "type": "object",
                "title": "PostalAddress",
                "description": "Street address of the business.",
                "required": [
                    "street",
                    "city",
                    "region",
                    "postal_code",
                    "country"
                ],
                "additionalProperties": false,
                "properties": {
                    "street": {
                        "type": "string",
                        "description": "Street line."
                    },
                    "city": {
                        "type": "string",
                        "description": "City."
                    },
                    "region": {
                        "type": "string",
                        "description": "Two-letter US state code."
                    },
                    "postal_code": {
                        "type": "string",
                        "description": "ZIP code."
                    },
                    "country": {
                        "type": "string",
                        "description": "ISO 3166-1 alpha-2 country code."
                    }
                }
            },
            "SiteInfo": {
                "type": "object",
                "title": "SiteInfo",
                "description": "Public information about the business.",
                "required": [
                    "name",
                    "url",
                    "phone",
                    "service_type",
                    "service_areas"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Business name."
                    },
                    "url": {
                        "type": "string",
                        "format": "uri",
                        "description": "Website home page."
                    },
                    "phone": {
                        "type": "string",
                        "description": "Phone number as published, for display."
                    },
                    "phone_e164": {
                        "type": "string",
                        "description": "Same number in E.164 form, for dialing."
                    },
                    "address": {
                        "$ref": "#/components/schemas/PostalAddress"
                    },
                    "service_type": {
                        "type": "string",
                        "description": "What kind of cleaning work the business does."
                    },
                    "service_areas": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Cities and areas served."
                    },
                    "flagship_service": {
                        "type": "string",
                        "format": "uri",
                        "description": "Page for the primary service, the one most customers buy."
                    },
                    "differentiators": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "What distinguishes this business from a generic cleaner."
                    },
                    "pricing_note": {
                        "type": "string",
                        "description": "How to read the price ranges below."
                    },
                    "estimated_ranges": {
                        "type": "object",
                        "description": "Published price ranges by service. Estimates only, never a quote.",
                        "additionalProperties": {
                            "type": "string"
                        }
                    },
                    "quote_policy": {
                        "type": "string",
                        "description": "What determines a real price and what a request does and does not commit to."
                    },
                    "contact": {
                        "type": "string",
                        "format": "uri",
                        "description": "Quote request form."
                    },
                    "llms_txt": {
                        "type": "string",
                        "format": "uri",
                        "description": "Extended context file for language models."
                    },
                    "agent_instructions": {
                        "type": "string",
                        "format": "uri",
                        "description": "When to use this business, and what not to claim on its behalf."
                    }
                }
            },
            "Service": {
                "type": "object",
                "title": "Service",
                "description": "One cleaning service offered by the business.",
                "required": [
                    "slug",
                    "name",
                    "url",
                    "description"
                ],
                "additionalProperties": false,
                "properties": {
                    "slug": {
                        "type": "string",
                        "pattern": "^[a-z0-9-]+$",
                        "description": "Stable identifier, usable as the {slug} path parameter."
                    },
                    "name": {
                        "type": "string",
                        "description": "Display name of the service."
                    },
                    "url": {
                        "type": "string",
                        "format": "uri",
                        "description": "Canonical page describing this service."
                    },
                    "description": {
                        "type": "string",
                        "description": "What the service covers, in one or two sentences."
                    }
                }
            },
            "ServiceList": {
                "type": "array",
                "title": "ServiceList",
                "description": "All cleaning services offered, in no particular order.",
                "items": {
                    "$ref": "#/components/schemas/Service"
                }
            },
            "Area": {
                "type": "object",
                "title": "Area",
                "description": "A city this business serves, with its hub page.",
                "required": [
                    "name",
                    "url"
                ],
                "additionalProperties": false,
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "City and state, for example \"Allen, TX\"."
                    },
                    "url": {
                        "type": "string",
                        "format": "uri",
                        "description": "Canonical hub page for that city."
                    }
                }
            },
            "AreaList": {
                "type": "array",
                "title": "AreaList",
                "description": "Every city hub served.",
                "items": {
                    "$ref": "#/components/schemas/Area"
                }
            },
            "ApiIndex": {
                "type": "object",
                "title": "ApiIndex",
                "description": "Discovery document: absolute URLs for every other resource.",
                "required": [
                    "name",
                    "version",
                    "openapi",
                    "site",
                    "services"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Human-readable API name."
                    },
                    "version": {
                        "type": "string",
                        "description": "API version, matching info.version in this document."
                    },
                    "openapi": {
                        "type": "string",
                        "format": "uri",
                        "description": "URL of this OpenAPI document."
                    },
                    "site": {
                        "type": "string",
                        "format": "uri",
                        "description": "URL of the business information resource."
                    },
                    "services": {
                        "type": "string",
                        "format": "uri",
                        "description": "URL of the service catalog."
                    },
                    "areas": {
                        "type": "string",
                        "format": "uri",
                        "description": "URL of the city hub list."
                    },
                    "llms_txt": {
                        "type": "string",
                        "format": "uri",
                        "description": "URL of the llms.txt context file."
                    },
                    "agent_instructions": {
                        "type": "string",
                        "format": "uri",
                        "description": "URL of the agent instructions document."
                    }
                }
            },
            "Problem": {
                "type": "object",
                "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "code",
                    "resolution"
                ],
                "properties": {
                    "type": {
                        "type": "string"
                    },
                    "title": {
                        "type": "string"
                    },
                    "status": {
                        "type": "integer"
                    },
                    "detail": {
                        "type": "string"
                    },
                    "instance": {
                        "type": "string"
                    },
                    "code": {
                        "type": "string"
                    },
                    "resolution": {
                        "type": "string"
                    },
                    "message": {
                        "type": "string"
                    },
                    "hint": {
                        "type": "string"
                    }
                }
            }
        }
    }
}