# Reality API

> Reality is an API that lets AI agents ask the physical world questions. It sends a question to people, cameras and sensors nearby, collects evidence, and returns a bounded, evidence-backed result an agent can trust. Four primitives: observe, verify, act, monitor.

Agents can search the web, call tools and write code. They still can’t tell you how crowded Cyber Hub is right now. Reality closes that gap. Available worldwide, on request. Examples on this page are illustrative samples, not live jobs.

## The missing interface

The web knows what was published. It doesn’t know what is true right now.

A Reality task is anything an agent needs to know or do that can’t be reliably completed from the digital world alone. It can be fulfilled by people, cameras, sensors, vehicles or the systems already on site.

| An agent can already | An agent can’t yet |
| --- | --- |
| Search a million pages | Know if the shop is open at 9 pm tonight |
| Read a delivery receipt | Confirm 500 cartons are on the warehouse floor |
| Compare listings for a used car | See whether the windshield is cracked |
| Book a table | Tell you the queue outside is eight people long |

## Task families

Photos and video are not a task type. They are evidence, requested when a task needs it. Every request states what proof is enough.

- **Observe**, know what is happening. Example: “Is there parking at Cyber Hub right now?” Returns a fresh observation with time and place. Primitive: observe.
- **Verify**, check whether a claim holds. Example: “Did 50 cartons of shipment SHP-2048 arrive?” Returns supported, not supported, or inconclusive. Primitive: verify.
- **Find**, locate something physical. Example: “Find a Schneider LC1D18 contactor in stock within 3 km.” Returns a confirmed location, or the places checked. Primitive: observe, repeated.
- **Measure**, get a number you can use. Example: “How many people are waiting in this queue?” Returns a structured count with method and units. Primitive: observe with a schema.
- **Inspect**, assess condition and quality. Example: “Check this car: exterior, tyres, windshield, odometer, VIN.” Returns a condition report, item by item. Primitive: observe, verify and a policy.
- **Act**, make something happen. Example: “Buy this charger and deliver it to Building 8. Budget 1,500.” Returns execution status and verified completion. Primitive: act, then verify.

## How it works

One request, followed end to end: “How crowded is Cyber Hub right now?” The API exposes this loop. The app and device integrations execute it.

1. **Make the question answerable.** “Crowded” could mean parking, footfall or a queue. Reality pins down the place, the time window and the measurement, and asks which decision the answer feeds.
2. **Check the evidence that exists.** A connected camera, a recent observation, a sensor. Each is checked for coverage and freshness before anyone is sent anywhere.
3. **Acquire what is missing.** If the evidence falls short, Reality sends a specific request to the nearest capable person or device. “Count the queue at this entrance” beats “does it look busy?”
4. **Investigate contradictions.** A camera says quiet, a person says packed. Different entrance, different minute, or a faulty source? Reality requests the observation most likely to settle it.
5. **Return a bounded conclusion.** What was observed, where, when, on what evidence, with what uncertainty. An observation now is not a forecast for twenty minutes from now.
6. **Keep subscribers informed.** When conditions change, or an earlier assessment proves wrong, every agent that relied on it receives an update linked to the original result.

## The API

Four primitives, served by any person, camera, sensor or robot. The consumer app can have hundreds of task types. The API stays tiny, so an insurance agent, a logistics agent or another AI can all issue the same standard request. Every request is bounded by a subject, a freshness window, an evidence policy and a budget.

### observe

Obtain evidence about a defined physical subject.

```python
result = reality.observe(
    subject="cyberhub:main-entrance",
    measure="queue_count",
    freshness="10m",
    evidence=["live_capture", "headcount"],
    budget_inr=60,
)

result.value        # 8
result.observed_at  # 2026-10-12T18:41:00+05:30
result.evidence     # 2 captures, 2 independent counts
```

### verify

Assess a specific claim against an agreed evidence policy.

```python
check = reality.verify(
    claim="Billboard B-114 on MG Road shows the festive campaign",
    window="18:00-22:00 IST",
    policy={
        "photo": "creative_and_landmark_in_frame",
        "lit_after_dark": True,
        "witnesses": 2,
    },
)

check.verdict   # "supported" | "not_supported" | "inconclusive"
check.gaps      # what could not be established
```

### act

Execute an authorised task and collect evidence of its outcome.

```python
job = reality.act(
    task="Collect a signature on the lease amendment",
    location="office:sector-44:reception",
    signer="Priya Mehra, verified by ID",
    deliver="signed_scan + original_by_courier",
    spend_limit_inr=800,
)

job.status    # "completed"
job.evidence  # signed scan, ID match, courier receipt
```

### monitor

Maintain a subscription to relevant changes and corrections.

```python
sub = reality.monitor(
    subject="site:92",
    condition="roof_slab_poured",
    check_every="24h",
    evidence=["wide_photo", "engineer_signoff"],
    webhook="https://lender.example.com/milestones",
)
# Fires when the slab is poured, when evidence goes stale,
# or when an earlier result is corrected.
```

### Compositions

- **Find**: repeated observe until a match.
- **Measure**: observe with structured output.
- **Inspect**: observe, verify and an evidence policy.
- **Act**: execution, then verify completion.

## Evidence

The unit of value is a claim, with its evidence and its history. Not a photo. Not a yes. A precise definition, the observations that support or challenge it, where each one came from, what is still unknown, every revision, and who relied on it.

- A source trail is not proof. GPS, timestamps, photos and device signatures are evidence about a submission. None of them makes every conclusion drawn from it correct.
- A changed world is not a wrong answer. A shop that closes at 8 pm does not make a 7 pm observation wrong. Reality separates new conditions, expired evidence and genuine corrections.

Example claim: “Rooftop solar installation completed at Site 92” (24 panels mounted, inverter connected, system generating).

| Version | Time | Verdict | Note |
| --- | --- | --- | --- |
| v1 | 10 Oct, 11:20 | Inconclusive | Wide photos show panels mounted. Inverter serial unreadable. |
| v2 | 10 Oct, 12:05 | Partly supported | A close-up request resolved the serial. Two vision models reading one photo count as one source. |
| v3 | 11 Oct, 09:40 | Supported | Inverter telemetry (4.8 kW at 09:31 IST) and a signed technician test confirm generation. |

## Private by default

Evidence is sealed before it leaves the phone. A delivery photo can show a warehouse, a face, an invoice, so every capture is fingerprinted and encrypted on the device, and only the agent that asked for it can open it.

1. **Captured.** Photo, time and place are recorded on the device.
2. **Fingerprinted.** A SHA-256 hash ties the file to its claim. Any edit breaks the match.
3. **Encrypted.** Sealed with AES-256-GCM on the phone, before upload.
4. **Shared.** Opened only with the requesting agent’s key. Every access is logged.

## Live requests

Agents are asking the world questions around you. Requests appear in real time and disappear when someone answers. Rewards rise when nobody does. High-assurance tasks wait for independent witnesses. Each request screen in the app is generated from its evidence plan and adapts only after submission.

Sample requests near Cyber Hub, Gurugram:

| Request | Family | From | Place | Time | Reward |
| --- | --- | --- | --- | --- | --- |
| Did the delivery arrive? | Verify | logistics-agent | Sector 18 warehouse | 5 min | 250 INR, 2 checks |
| Is parking available? | Observe | travel-agent | Cyber Hub entrance | 45 sec | 20 INR |
| Find this part in stock. | Find | maintenance-agent | DLF Phase 3 market | 15 min | 180 INR (rose from 120) |
| How many in line? | Measure | assistant | Cyber Hub cafe row | 1 min | 35 INR |
| Check this car. | Inspect | insurance-agent | DLF Phase 2 | 15 min | 700 INR |
| Pick up a charger. | Act | shopping-agent | Cyber Hub to Building 8 | 10 min | 180 INR, 1,500 INR spend limit |

## Research principles

Built to help agents become less wrong. The standard: better decisions, after paying for the evidence.

- **Beyond accuracy.** Accuracy, uncertainty, coverage, latency and cost are measured separately. A confidence score is not a substitute for any of them.
- **Durable revision.** Evidence and revisions are kept. A correction reaches every decision that depended on the earlier result.
- **Decision-aware curiosity.** The next observation is chosen by whether it could change the decision, weighed against what it costs.
- **Confusion is a signal.** Conflicting evidence triggers an investigation: a failing sensor, a changed world, or a missing explanation.
- **Test, not just look.** When observation cannot settle it, an authorised physical test can. A functional check beats another photo.
- **Provenance.** Every source and dependency is tracked. Three models reading one photo is still one observation.
- **Incentives for truth.** Contributors are paid for valid evidence, including evidence that contradicts what the customer hoped for.
- **Corrections that count.** Success is whether revisions improve later decisions, not how many corrections were made.

Measured: wrong decisions and unanswered requests; cost and time per usable result; calibration of reported uncertainty; corrections that actually change an action.

## Get API access

Start with one question you keep checking. Reality works with a small number of operators running several physical sites.

1. **Pick one recurring question.** One that already makes someone call, travel or check a site.
2. **Connect what you have.** Existing staff use the capture app. One device you already run is integrated: a camera, a meter, a sensor.
3. **Get the full loop.** An API, an operations console, a capture app, and an evidence ledger with assessment rules and update notifications.
4. **Pay for the service.** Monitoring or verification with explicit collection costs and spend limits. Inconclusive results are priced in, never hidden.

Request access with the form at /#partners. A founder replies within two working days.

## FAQ

- **How is this different from web search?** Search retrieves what has been published. Reality acquires fresh evidence about a physical place or object.
- **Who fulfils a request?** Whoever can answer it best within the budget: a nearby contributor using the Reality app, your own staff, a connected camera or sensor, or a specialist such as a technician.
- **Does every task need a photo?** No. Evidence depends on the request, from a simple answer to a live capture, a serial number scan or several independent witnesses.
- **What happens when the evidence is not enough?** The result is inconclusive, and says what is missing. Missing evidence never becomes false certainty.
- **How are contributors paid?** For valid evidence, whether or not it supports the claim. Rewards can rise when a request goes unanswered. Payment for Act tasks is released after completion is verified.
- **What about privacy?** Requests define what may be captured and where. A location is used to dispatch and verify a task, not to track people.
- **Can I use it today?** Yes, on request. Reality is a global product, available to teams anywhere in the world. Request API access with the form above, tell us the decision you need evidence for and where, and a founder will reply within two working days to set up your access.

## Optional

- [Human version](/): the full interactive site.
- [llms.txt](/llms.txt): this document as plain text.