Quickstart

Kviria needs three things per call: the user’s words, their current anchor, and (from turn two on) the state Kviria handed you back. Your wallet is your account — a CAIP-122 sign-in header, no key to provision.

1. First call — raw transcript

Build a sign-in for your wallet (domain api.kviria.com, URI https://api.kviria.com, a fresh nonce — sign-ins are single-use; the exact construction is in the agent endpoint) and pass it as the SIGN-IN-WITH-X header:

curl -X POST "https://api.kviria.com/v1/agent?agent=my-agent" \
  -H "Content-Type: application/json" \
  -H "SIGN-IN-WITH-X: $SIWX" \
  -d '{
    "transcript": "I want to drink an espresso around here",
    "anchor": { "lat": 37.76326, "lng": -122.4152 }
  }'

transcript - the user’s raw message, typos and all. Never paraphrase it.
anchor - the user’s current position ({lat, lng}).
?agent=my-agent - a namespace label for your agent (not a secret).
SIGN-IN-WITH-X - your wallet’s sign-in. The first 50 turns each day are free.

A response with several matches looks like this:

{
  "decision": "candidates",
  "candidates": [
    { "gers": "...", "name": "Stable Cafe", "location": { "lat": 37.7633, "lng": -122.4150 }, "distanceM": 37 },
    { "gers": "...", "name": "Momi Cafe", "location": { "lat": 37.7628, "lng": -122.4148 }, "distanceM": 52 }
  ]
}

Ask the user which one - embedding their identities in a natural question works best: “Are you looking for Stable Cafe, or Momi Cafe?“

2. The pick — echo the state back

When the user answers (“the first one”), send their words plus the same candidates array back, verbatim (with a fresh sign-in — every request carries one):

curl -X POST "https://api.kviria.com/v1/agent?agent=my-agent" \
  -H "Content-Type: application/json" \
  -H "SIGN-IN-WITH-X: $SIWX" \
  -d '{
    "transcript": "the first one",
    "anchor": { "lat": 37.76326, "lng": -122.4152 },
    "candidates": [
      { "gers": "...", "name": "Stable Cafe" },
      { "gers": "...", "name": "Momi Cafe" }
    ]
  }'

The pick binds mechanically by position - Kviria never re-guesses.

3. The coordinate - through the confirm gate

With a single survivor, Kviria’s default is a confirm decision: it hands you the target and waits for the user’s yes/no before releasing the verified coordinate. Ask the user “Is it Stable Cafe (37 m)?” and send their bare answer back (echoing the candidates one more time):

{
  "decision": "resolved",
  "target": {
    "gers": "...",
    "name": "Stable Cafe",
    "category": "cafe",
    "location": { "lat": 37.7633, "lng": -122.4150 },
    "distanceM": 37
  },
  "evidence": [
    { "test": "resolve", "result": "pass", "reasonCode": "single_survivor" }
  ],
  "confirmed": true
}

That’s the whole loop: narrow, echo, confirm, done. For zero-touch agents, pass "confirmation": "off" to skip the gate.

What to try next

A specific address: "transcript": "2104 Folsom" -> a resolved decision with a house-level coordinate (the door facts ride target.address; exact addresses verify themselves - no confirm gate).
A relative reference: "the cafe across from Stable Cafe" -> Kviria resolves the place on the opposite side.
Your agent can do the mapping itself: read the structured intent format and skip the transcript entirely.
Your agent speaks MCP? Connect the MCP server instead of calling HTTP directly.

Limits to know up front

5 turns/minute per wallet; your first 50 turns each day are free. Beyond that, pay per turn.
Beta coverage: San Francisco. Outside the covered area you get an honest notFound, not a guess.
Full limits and error codes: Rate limits, Errors.

Getting Started

How it works

API

Reference

1. First call — raw transcript

2. The pick — echo the state back

3. The coordinate - through the confirm gate

What to try next

Limits to know up front

​1. First call — raw transcript

​2. The pick — echo the state back

​3. The coordinate - through the confirm gate

​What to try next

​Limits to know up front

1. First call — raw transcript

2. The pick — echo the state back

3. The coordinate - through the confirm gate

What to try next

Limits to know up front