Agent endpoint

POST https://api.kviria.com/v1/agent
Content-Type: application/json
Body limit: 16 KB

Every call carries your Kviria key, or an OAuth token:

Authorization: Bearer kvr_...

A call without one gets a 401 with unauthorized. To top up, add a PAYMENT-SIGNATURE header to a call. See Payments. Every call also names your agent, with the x-kviria-agent header or ?agent= in the URL: 3 to 64 characters of lowercase letters, digits and hyphens. The name keeps your agent’s context apart from other agents’. It is not a secret. The machine-readable contract is the tool definition. The OpenAPI document is at https://api.kviria.com/openapi.json.

The key

Get a key at api.kviria.com/key. It is shown once. The same key works on every call, and on the MCP server. Connect and pay covers keys, OAuth and replacing a key.

Request body

Your agent parses the user’s words into the request’s fields. Kviria never receives the words.

Field	Type	Required	What it holds
`request`	string	always	The request type: `find`, `search`, `near`, `across`, `next_to`, `corner`, `street_end`, `pick` or `confirm`
`place`	object	for `find`, `near`, `across`, `next_to`	`{ "name": string }` as the user said it, or `{ "ref": string }`, the `gers` of a place Kviria returned earlier
`kind`	string	for `search`	The kind of place, as a short plain-English category
`streets`	array	for `corner`	The two streets of a corner, as the user said them
`street`	string	no	A street the user named for `across`, `next_to` or `street_end`
`address`	object	no	`{ "number": string, "street": string }`, a street address the user gave
`side`	string	no	`"left"` or `"right"`, only if the user said it
`pick`	integer	for `pick`	The position in the last list, starting at 1
`answer`	string	for `confirm`	`"yes"` or `"no"`
`state`	string	from the second call	The `state` of the previous response. An empty string, or no field, on the first call
`anchor`	object	on the first call	`{ "lat": number, "lng": number }`, the user’s current position. After the first call, only when the user moves
`rangeM`	integer	no	The search radius in meters: 50 to 350, default 100
`confirmation`	string	no	`"on"` (the default) or `"off"`. See Confirmation

What each type needs: find a place, an address, the two streets of a corner, or a kind; search a kind; near a place or the two streets of a corner; across and next_to a place; corner the two streets; pick the number; confirm the answer. street_end needs nothing. A request without what its type needs gets 400 invalid_request, whose message names it. Any other field is refused with 400 unsupported_field. A body with transcript gets 400 transcript_removed. The fields intent, candidates, references and frame are no longer accepted, and the message says what replaced them. See Conversation state for state and anchor.

Response

Field	When	What it holds
`decision`	always	`one`, `one_unconfirmed`, `many`, `none` or `unclear`
`target`	`one`, `one_unconfirmed`	The place. On `one_unconfirmed` it has no `location`
`candidates`	`many`	The places to offer the user. Never send them back
`confirmed`	`one`	`true` when the user’s yes settled it
`category`	`none`	The kind of place that was asked for and is absent
`evidence`	always	The checks behind the decision. Never show it to the user
`state`	always	Send it back unchanged as `state` on the next call

A target, and each candidate, has these fields:

Field	What it holds
`gers`	A stable id for the place
`name`	The name. Say it exactly as returned
`category`	The category label, or null
`confidence`	How sure the map data is that the place exists, 0 to 1, or null
`location`	`{ lat, lng }`
`distanceM`	Straight-line meters from the user’s position
`direction`	The place’s quadrant from the user’s position: `northwest`, `northeast`, `southwest` or `southeast`. Absent when the place is at the user’s spot
`address`	`{ number, street }`, when the target is a door
`intersection`	`{ streets }`, when the target is a street corner. Its `category` and `confidence` are null
`acrossStreet`	The street the answer is across, when the user named one, or when the place is on a corner
`baseDistanceM`	When the answer is relative to a place (near, across, next to), the meters from that place

An exact address comes back as one, with the door’s facts in target.address. When one number matches several doors, they come back as many. The decisions and your move on each are in Narrowing. The evidence is in Determinism and evidence.

Response headers

x-request-id: the request’s id. Quote it if you write to us about a call.
x-kviria-balance-remaining: on a paid turn, the account’s remaining balance in USDC base units (millionths of a dollar).

Get started

Guides

Concepts

Reference

Agent endpoint

The key

Request body

Response

Response headers

​The key

​Request body

​Response

​Response headers

The key

Request body

Response

Response headers