Kirah Local Services

{
  "type": "object",
  "required": [
    "tenant",
    "service_id",
    "start_iso",
    "client"
  ],
  "properties": {
    "client": {
      "type": "object",
      "required": [
        "name",
        "email"
      ],
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 200
        },
        "email": {
          "type": "string",
          "format": "email",
          "maxLength": 200
        },
        "phone": {
          "type": "string",
          "maxLength": 60
        }
      },
      "additionalProperties": false
    },
    "tenant": {
      "type": "string",
      "maxLength": 253,
      "description": "The tenant to operate on: the provider.tenant_slug value from the tenant's /.well-known/kirah.json manifest (the tenant's full domain, e.g. <slug>.kirah.ai)."
    },
    "start_iso": {
      "type": "string",
      "format": "date-time"
    },
    "service_id": {
      "type": "string",
      "maxLength": 200
    },
    "provider_id": {
      "type": "string",
      "maxLength": 200
    },
    "agent_metadata": {
      "type": "object",
      "properties": {
        "source": {
          "type": "string",
          "maxLength": 120
        },
        "request_id": {
          "type": "string",
          "maxLength": 120
        }
      },
      "additionalProperties": false
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "minLength": 16
    },
    "intake_responses": {
      "type": "object",
      "description": "Answers to the service's intake form (2.8), keyed by intake field id as advertised in list_services' service.intake_form.fields[].id. FLAT only: values must be a string, a boolean, or a finite number — arrays, nested objects and nulls are rejected. Unknown keys are ignored by the booking engine. Answers are validated against the LIVE form; a required plain boolean accepts an explicit true OR false, a consent boolean accepts only true, and a select must exactly match one advertised option. Omit this field entirely when the service has no intake form.",
      "maxProperties": 40,
      "propertyNames": {
        "type": "string",
        "maxLength": 80,
        "minLength": 1
      },
      "additionalProperties": {
        "type": [
          "string",
          "boolean",
          "number"
        ],
        "maxLength": 4000
      }
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The consumer's service need in plain words — identical semantics to search_businesses.query."
    },
    "location": {
      "type": "string",
      "maxLength": 120,
      "description": "Optional place text ('City, ST', ZIP, bare city/state) OR explicit coordinates 'lat,lng' — identical semantics to search_businesses.location."
    },
    "tenant_mode": {
      "enum": [
        "real_only",
        "include_demos",
        "demos_only"
      ],
      "type": "string",
      "default": "include_demos",
      "description": "The authoritative demo eligibility filter, with the same semantics as search_businesses. include_demos is the default and returns real and demo candidates; real_only excludes demos; demos_only returns only clearly labeled demonstration candidates."
    },
    "include_demo": {
      "type": "boolean",
      "description": "Back-compat alias: true is equivalent to tenant_mode 'include_demos' and false to 'real_only'. When omitted, tenant_mode defaults to include_demos. Every demo candidate carries demo:true and a demo_notice. Supplying both include_demo and tenant_mode with disagreeing demo-inclusion is invalid_tenant_mode."
    },
    "radius_miles": {
      "type": "integer",
      "maximum": 500,
      "minimum": 1,
      "description": "Radius in miles (default 25) — operative when the location resolves to coordinates (2.6 semantics)."
    },
    "earliest_after": {
      "type": "string",
      "format": "date-time",
      "description": "Exact ISO 8601 instant the window opens (default: now). Natural-language times are rejected (invalid_earliest_after)."
    },
    "candidate_limit": {
      "type": "integer",
      "default": 3,
      "maximum": 5,
      "minimum": 1,
      "description": "How many top-matching businesses get LIVE availability checks (invalid_candidate_limit outside 1-5). This bounds the whole fan-out: businesses beyond it are never touched, and partial:true says so."
    },
    "earliest_before": {
      "type": "string",
      "format": "date-time",
      "description": "Exact ISO 8601 instant the window closes (default: earliest_after + 14 days). Must be after earliest_after and at most 14 days after it (invalid_earliest_before)."
    },
    "max_price_cents": {
      "type": "integer",
      "maximum": 10000000,
      "minimum": 0,
      "description": "Only candidate services with a parseable price at or under this amount are considered."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "required": [
    "tenant",
    "booking_ref",
    "grant"
  ],
  "properties": {
    "grant": {
      "type": "string",
      "maxLength": 2048,
      "minLength": 1,
      "description": "The capability token from this booking's create_booking response (confirmation.grant). Required: without it there is no way to establish that you are the agent that made this booking. Tampered, wrong-booking, wrong-tenant and revoked grants all answer invalid_grant, indistinguishably; an authentic grant past the appointment start answers expired_grant. These are the GRANT codes, not the payment page's invalid_token/expired_token — through contract 2.11 this action answered the latter, whose prose wrongly told callers their payment link was broken."
    },
    "limit": {
      "type": "integer",
      "default": 2,
      "maximum": 5,
      "minimum": 1,
      "description": "How many options to return. Default 2, hard maximum 5; a larger value is CLAMPED to 5 rather than rejected. The ceiling is deliberate: the primary consumer is a voice agent reading options aloud, and five spoken times is more than a caller can hold in their head."
    },
    "latest": {
      "type": "string",
      "format": "date-time",
      "description": "Optional exact ISO 8601 instant — the latest replacement time to consider. Default: now + 14 days. Must be after `earliest` and at most 31 days after it; anything else answers invalid_latest. Supply it explicitly whenever `earliest` is more than 14 days out."
    },
    "tenant": {
      "type": "string",
      "maxLength": 253,
      "description": "The tenant to operate on: the provider.tenant_slug value from the tenant's /.well-known/kirah.json manifest (the tenant's full domain, e.g. <slug>.kirah.ai)."
    },
    "earliest": {
      "type": "string",
      "format": "date-time",
      "description": "Optional exact ISO 8601 instant — the earliest replacement time to consider. Default: now + 2 hours (a slot the customer cannot physically reach is not an option). Natural-language times are not accepted."
    },
    "booking_ref": {
      "type": "string",
      "maxLength": 200,
      "minLength": 16,
      "description": "The reference create_booking returned (its idempotency key). It must be the SAME booking the supplied grant was issued for; a mismatch answers invalid_grant, indistinguishably from a forged grant."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "required": [
    "tenant",
    "booking_ref",
    "grant",
    "start_iso",
    "idempotency_key"
  ],
  "properties": {
    "grant": {
      "type": "string",
      "maxLength": 2048,
      "minLength": 1,
      "description": "The capability token from this booking's create_booking response (confirmation.grant). Required: without it there is no way to establish that you are the agent that made this booking. It must carry the `booking:reschedule` scope. Tampered, wrong-booking, wrong-tenant, revoked and insufficiently-scoped grants all answer invalid_grant, indistinguishably; an authentic grant past the appointment start answers expired_grant. These are the GRANT codes, not the payment page's invalid_token/expired_token — through contract 2.11 this action answered the latter, whose prose wrongly told callers their payment link was broken."
    },
    "tenant": {
      "type": "string",
      "maxLength": 253,
      "description": "The tenant to operate on: the provider.tenant_slug value from the tenant's /.well-known/kirah.json manifest (the tenant's full domain, e.g. <slug>.kirah.ai)."
    },
    "start_iso": {
      "type": "string",
      "format": "date-time",
      "description": "The exact ISO 8601 instant to move the appointment to. Natural-language times are not accepted. You may supply it DIRECTLY — calling get_reschedule_options first is optional, not required — because the instant is validated against real availability by the same slot engine create_booking uses. A time that is not genuinely open answers slot_taken with the original booking untouched; a time further ahead than this business books answers beyond_booking_horizon."
    },
    "booking_ref": {
      "type": "string",
      "maxLength": 200,
      "minLength": 16,
      "description": "The reference create_booking returned for the booking you want to MOVE. It must be the SAME booking the supplied grant was issued for; a mismatch answers invalid_grant, indistinguishably from a forged grant. A successful move does not change it."
    },
    "provider_id": {
      "type": "string",
      "maxLength": 200,
      "description": "OPTIONAL. Move the booking to a different provider. Omit it and the booking keeps the provider it is already on — the customer booked a person, not a room. An explicit provider is honored only when that provider exists in this tenant's catalog (else unknown_provider) AND performs the booked service (else provider_service_mismatch). The service and its duration never change."
    },
    "agent_metadata": {
      "type": "object",
      "properties": {
        "source": {
          "type": "string",
          "maxLength": 120
        },
        "request_id": {
          "type": "string",
          "maxLength": 120
        }
      },
      "additionalProperties": false
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "minLength": 16,
      "description": "REQUIRED — unlike create_booking, this action cannot derive one, because \"move booking X to time T\" is byte-identical whether it is a retry or a deliberate second move. Omitting it answers missing_idempotency_key. Reuse the SAME key when retrying the SAME move: the replay returns the original result with idempotent_replay:true and moves nothing. The same key with a different start_iso or provider_id answers idempotency_conflict."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "anyOf": [
    {
      "required": [
        "query"
      ]
    },
    {
      "required": [
        "agent_address"
      ]
    }
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 5,
      "maximum": 10,
      "minimum": 1
    },
    "query": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The consumer's need in plain words (e.g. 'lower back tightness', 'prenatal massage'). Matched deterministically against real service catalogs, expanded by the discovery ontology."
    },
    "cursor": {
      "type": "string",
      "maxLength": 300,
      "description": "Opaque next_cursor value from a previous search_businesses response with the SAME query/filters: resumes after that tenant in the stable ordering. A cursor that does not decode, or that names a tenant not present in the current ordering, is invalid_cursor."
    },
    "location": {
      "type": "string",
      "maxLength": 120,
      "description": "Optional place text ('City, ST', ZIP, bare city/state) OR explicit coordinates 'lat,lng'. With resolvable coordinates, radius_miles applies as real distance; otherwise matching is city/ZIP/metro-market text equality."
    },
    "tenant_mode": {
      "enum": [
        "real_only",
        "include_demos",
        "demos_only"
      ],
      "type": "string",
      "default": "include_demos",
      "description": "The authoritative eligibility filter for demo tenants. include_demos (default) returns real and demo businesses together; every demo is flagged demo:true and carries a clear notice. real_only excludes every demo business; demos_only returns ONLY demo businesses. A discovery-disabled, inactive, or otherwise ineligible tenant never appears in any mode — not even when its catalog uniquely matches the query."
    },
    "include_demo": {
      "type": "boolean",
      "description": "Back-compat alias: true is equivalent to tenant_mode 'include_demos' and false to 'real_only'. When omitted, tenant_mode defaults to include_demos. Every demo result carries demo:true and a demo_notice. Supplying both include_demo and tenant_mode with disagreeing demo-inclusion is invalid_tenant_mode."
    },
    "radius_miles": {
      "type": "integer",
      "maximum": 500,
      "minimum": 1,
      "description": "Radius in miles (default 25) — OPERATIVE when the location resolves to coordinates (2.6); otherwise answered with a truthful distance_note instead of a fabricated distance."
    },
    "agent_address": {
      "type": "string",
      "pattern": "^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?@[Kk][Ii][Rr][Aa][Hh]\\.[Aa][Ii]$",
      "maxLength": 253,
      "description": "Exact public locator `<handle>@kirah.ai`; case-insensitive ASCII only. A locator, never authentication or owner authority. Reserved, malformed, unlisted, disabled, non-bookable, and tenant_mode-ineligible addresses do not resolve. Exact mode never fuzzy-matches a near miss."
    },
    "max_price_cents": {
      "type": "integer",
      "maximum": 10000000,
      "minimum": 0,
      "description": "Only services with a parseable price at or under this amount are returned; unpriced services are excluded when this is set."
    }
  },
  "additionalProperties": false
}