Realask - verified answers from the physical world

Get a free, immutable price quote for verifying a current fact about a US local business (stock, price, availability, capability, policy, wait time). Returns quote_id, price in integer minor units, scope, expected_completion_seconds and expires_at. Use purchase_quote to buy it.

{
  "type": "object",
  "properties": {
    "request": {
      "type": "string",
      "minLength": 8,
      "maxLength": 2000,
      "description": "Natural-language question, e.g. 'Does ABC Tire in 33312 have two Michelin Pilot Sport 4S 235/40R19 in stock today and what is the installed price?'"
    },
    "location": {
      "type": "object",
      "properties": {
        "postal_code": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "region": {
          "type": "string"
        },
        "country": {
          "default": "US",
          "type": "string"
        },
        "lat": {
          "type": "number"
        },
        "lng": {
          "type": "number"
        },
        "radius_miles": {
          "type": "number"
        }
      }
    },
    "limits": {
      "type": "object",
      "properties": {
        "max_businesses": {
          "type": "integer",
          "minimum": 1,
          "maximum": 5
        },
        "deadline_seconds": {
          "type": "integer",
          "minimum": 60,
          "maximum": 600
        },
        "max_call_attempts_per_target": {
          "type": "integer",
          "minimum": 1,
          "maximum": 2
        }
      }
    },
    "verification_mode": {
      "description": "auto reuses fresh cached facts when safe; live_verified forces a new call",
      "type": "string",
      "enum": [
        "digital_fast",
        "live_verified",
        "auto"
      ]
    },
    "callback_url": {
      "type": "string",
      "format": "uri"
    }
  },
  "required": [
    "request",
    "location"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get a free price to ARRANGE something at a specific US local business: book an appointment, hold an item, request a formal quote, or cancel a prior booking. This creates a real obligation, so it needs explicit authorization, the customer's name and callback number, and a maximum price the caller may agree to. The caller never negotiates, never pays, and never substitutes something different. Purchase the returned quote with purchase_quote.

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "book",
        "hold",
        "request_quote",
        "cancel"
      ]
    },
    "what": {
      "type": "string",
      "minLength": 3,
      "maxLength": 500,
      "description": "Exactly what to arrange, e.g. 'two Michelin Pilot Sport 4S 235/40R19 installed'"
    },
    "business_name": {
      "type": "string",
      "description": "The business to act on"
    },
    "place_id": {
      "description": "Google place_id, if known - more reliable than a name",
      "type": "string"
    },
    "postal_code": {
      "type": "string"
    },
    "when": {
      "description": "Time window, e.g. 'tomorrow afternoon'",
      "type": "string"
    },
    "quantity": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "max_price_minor": {
      "description": "Ceiling in cents the caller may agree to. Required for book and hold.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "customer_name": {
      "type": "string",
      "description": "Name to hold the booking under. Shared with the business."
    },
    "customer_callback_phone": {
      "type": "string",
      "description": "Number the business can call back. Shared with the business."
    },
    "reference": {
      "description": "Existing confirmation reference. Required for cancel.",
      "type": "string"
    },
    "notes": {
      "description": "Constraints the caller must honour",
      "type": "string"
    },
    "authorized": {
      "type": "boolean",
      "const": true,
      "description": "You confirm the end user authorized this commitment on their behalf"
    }
  },
  "required": [
    "action",
    "what",
    "business_name",
    "postal_code",
    "customer_name",
    "customer_callback_phone",
    "authorized"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The single purchase path: pays for a quote from EITHER quote_real_world_answer or quote_real_world_action and starts the job. There is no separate action-purchase tool. Returns job_id and job_token (keep it; it is shown once), then poll get_verification_status and read get_verification_result. If this server has no payment capability, returns the x402 payment requirements (HTTP 402 body) so you can pay with your own payment tool and retry the POST /v1/jobs request with a PAYMENT-SIGNATURE header.

{
  "type": "object",
  "properties": {
    "quote_id": {
      "type": "string"
    },
    "idempotency_key": {
      "description": "Client-generated UUID; reuse it when retrying",
      "type": "string"
    }
  },
  "required": [
    "quote_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read-only progress check on a job bought with purchase_quote. Free, changes nothing, and safe to call repeatedly. Returns the state plus a progress object (businesses discovered, call attempts made). States are queued, discovering, calling or extracting while the job is still running, and completed, partial, failed, timed_out or canceled once it is final. Poll every 15-30 seconds; live calls take minutes. Use this to decide WHEN to read the answer; use get_verification_result to read the answer itself. If you only intend to poll until the job is done, get_verification_result can be polled directly instead - it returns a provisional 202 until the job is final.

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "job_id returned by purchase_quote, e.g. 'job_gf8t5wwfrtgpjcdc'"
    },
    "job_token": {
      "type": "string",
      "description": "job_token returned once by purchase_quote; the bearer token for this job. Not recoverable if lost - a new job would have to be purchased."
    }
  },
  "required": [
    "job_id",
    "job_token"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read-only. The answer itself: typed facts, evidence excerpts, timestamps, confidence scores, freshness, and an explicit list of what could not be verified. Free, and safe to call repeatedly. If the job is not final yet the response is provisional (http_status 202) - poll until 200, or watch get_verification_status for a terminal state first. A completed job answers every required criterion; a partial one answers some and says so in limitations.

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "job_id returned by purchase_quote, e.g. 'job_gf8t5wwfrtgpjcdc'"
    },
    "job_token": {
      "type": "string",
      "description": "job_token returned once by purchase_quote; the bearer token for this job. Not recoverable if lost - a new job would have to be purchased."
    }
  },
  "required": [
    "job_id",
    "job_token"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}