Quickstart

This walkthrough takes one short conversation from the first call to a settled place. The examples are real answers from a position at 17th and Folsom Street in San Francisco.

1. Get a key

Open api.kviria.com/key and create a key. It is shown once, so copy it. Every call carries it in the Authorization header. In the examples below it is $KVIRIA_KEY. An MCP client can connect with OAuth instead: see Connect and pay. Every call also names your agent with ?agent= in the URL. The name keeps your agent’s context apart from other agents’. It is not a secret.

2. Send the request

Your agent parses the user’s words into the request’s fields. The user asks “is there a cafe near here”: that is search with the kind cafe. Send it with an empty state and the user’s position as anchor:

curl -X POST "https://api.kviria.com/v1/agent?agent=my-agent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KVIRIA_KEY" \
  -d '{
    "request": "search",
    "kind": "cafe",
    "state": "",
    "anchor": { "lat": 37.76326, "lng": -122.4152 }
  }'

Three cafes match, so the decision is many:

{
  "decision": "many",
  "candidates": [
    {
      "gers": "892a9bcb-67d4-4d18-b126-5f6fd6619ccb",
      "name": "Stable Cafe",
      "category": "cafe",
      "confidence": 0.9933089017868042,
      "location": {
        "lat": 37.76322884,
        "lng": -122.41527846
      },
      "distanceM": 8
    },
    {
      "gers": "cf88d374-1b13-4128-aaef-fbaea1aa704e",
      "name": "Rite Spot Cafe",
      "category": "cafe",
      "confidence": 0.9749269485473633,
      "location": {
        "lat": 37.76377118,
        "lng": -122.41501821
      },
      "distanceM": 59
    },
    {
      "gers": "a7d8d6bf-a4d5-422b-a61b-16c8f7adbed2",
      "name": "Robin's Cafe",
      "category": "coffee_shop",
      "confidence": 0.9902192950248718,
      "location": {
        "lat": 37.76350333,
        "lng": -122.41631976
      },
      "distanceM": 102
    }
  ],
  "evidence": [
    {"test": "kind", "result": "pass", "reasonCode": "kind.floor", "detail": {"labels": ["cafe", "coffee_shop"], "decidedBy": "floor:kind-word-rule", "steps": [{"step": "floor", "adapter": "floor:kind-word-rule", "note": "the words name cafe"}]}},
    {"test": "entry_path", "result": "pass", "reasonCode": "structured_intent"},
    {"test": "resolve", "result": "pass", "reasonCode": "multiple_candidates"}
  ],
  "state": "AQFAQuGygPEsKMBempKjBVMmAwCJKpvLZ9RNGLEmX2_WYZzLAM-I03QbE0Eoqu_7rqGqcE4Ap9jWv6TVQiumGxbI962-0gBnu9O7Uwh6ZmFT6TkVscdZ"
}

Ask the user which one, with the names and distances: “Stable Cafe, 8 m away, Rite Spot Cafe, 59 m away, or Robin’s Cafe, 102 m away?“

3. Send the choice with the state

The user says “the second one”: that is pick with the number 2. Send it with the state from the last response. The user has not moved, so leave anchor out:

curl -X POST "https://api.kviria.com/v1/agent?agent=my-agent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KVIRIA_KEY" \
  -d '{
    "request": "pick",
    "pick": 2,
    "state": "AQFAQuGygPEsKMBempKjBVMmAwCJKpvLZ9RNGLEmX2_WYZzLAM-I03QbE0Eoqu_7rqGqcE4Ap9jWv6TVQiumGxbI962-0gBnu9O7Uwh6ZmFT6TkVscdZ"
  }'

The place is settled:

{
  "decision": "one",
  "target": {
    "gers": "cf88d374-1b13-4128-aaef-fbaea1aa704e",
    "name": "Rite Spot Cafe",
    "category": "cafe",
    "confidence": 0.9749269485473633,
    "location": {
      "lat": 37.76377118,
      "lng": -122.41501821
    },
    "distanceM": 59
  },
  "evidence": [
    {"test": "entry_path", "result": "pass", "reasonCode": "structured_intent"},
    {"test": "resolve", "result": "pass", "reasonCode": "single_survivor"}
  ],
  "state": "AQFAQuGygPEsKMBempKjBVMmAAEAz4jTdBsTQSiq7_uuoapwTvbCY-C2QX-Zog9T8SPJdL0"
}

Keep calling on the user’s next turns with the newest state. “What’s across the street from it” is now across with the place’s ref, the gers of Rite Spot Cafe. The states shown here are examples. Yours come from your own responses, so always send back the one you received.

4. Confirm a place named in part

A new conversation starts with an empty state and the position again. The user says “take me to rite spot”: that is find with the place’s name as the user said it, { "name": "rite spot" }. It names Rite Spot Cafe only in part, so the answer waits for the user’s yes, and its target has no location yet:

{
  "decision": "one_unconfirmed",
  "target": {
    "gers": "cf88d374-1b13-4128-aaef-fbaea1aa704e",
    "name": "Rite Spot Cafe",
    "category": "cafe",
    "confidence": 0.9749269485473633,
    "distanceM": 59
  },
  "evidence": [
    {"test": "entry_path", "result": "pass", "reasonCode": "structured_intent"},
    {"test": "name_match", "result": "warn", "reasonCode": "partial_name"},
    {"test": "confirm_gate", "result": "warn", "reasonCode": "awaiting_user_verification"},
    {"test": "resolve", "result": "pass", "reasonCode": "single_survivor_pending"}
  ],
  "state": "AQVAQuGygPEsKMBempKjBVMmAQDPiNN0GxNBKKrv-66hqnBOAIiaeXwWMnnaSOhjfr2Viy0"
}

Ask the user to confirm the place, and send the answer as confirm with "answer": "yes" or "no". A yes comes back as one with the location and "confirmed": true. A no comes back as unclear here, so ask the user to say more. See Confirmation.

5. Let your agent answer small talk

When the user’s words are not about a place, such as “thanks, that’s all”, do not call Kviria. Reply to the user yourself.

Before you build

Give your agent Kviria’s system prompt. It is in the skill.
An account gets free turns every day, and pays per turn from a balance after them. See Rate limits and Payments.
Coverage is the contiguous United States.
Your agent speaks MCP? Connect the MCP server instead.
Each error and what to do about it: Errors.

Get started

Guides

Concepts

Reference

1. Get a key

2. Send the request

3. Send the choice with the state

4. Confirm a place named in part

5. Let your agent answer small talk

Before you build

​1. Get a key

​2. Send the request

​3. Send the choice with the state

​4. Confirm a place named in part

​5. Let your agent answer small talk

​Before you build

1. Get a key

2. Send the request

3. Send the choice with the state

4. Confirm a place named in part

5. Let your agent answer small talk

Before you build