# JSON API Request

> A Somnia Agents base agent that fetches JSON from any public API and returns one value from it, picked by a selector path, to your contract.

JSON API Request is a base agent on [Somnia Agents](/agents/somnia-agents). A contract names a URL and a selector path such as `data.price` or `items[0].name`; a subcommittee of validators fetches the JSON, picks the value, agrees on it and returns it to the contract's callback. It is the building block for an onchain oracle on any public API.

## How a request runs

1. The contract encodes one of the agent's methods, with the URL, the selector and, for a number, the decimals to scale it by, and submits it as a request through the agents platform's `createRequest`.
2. Each validator in the subcommittee fetches the URL and extracts the value at the selector.
3. The validators' responses and a status are returned to the contract's callback, with a receipt; the contract reads the agreed value from them.

Numbers are scaled by 10 to the power of `decimals` so a floating-point value from an API becomes an integer a contract can use: with 8 decimals, `42000.50` becomes `4200050000000`.

## Methods

| Method | Returns | For |
| --- | --- | --- |
| `fetchString` | `string` | Names, text values |
| `fetchUint` | `uint256` | Prices, positive numbers |
| `fetchInt` | `int256` | Signed numbers |
| `fetchBool` | `bool` | Flags, status checks |
| `fetchStringArray` | `string[]` | Lists of names or ids |
| `fetchUintArray` | `uint256[]` | Price lists, numeric arrays |

## Reference

Parameters, selector syntax, the price per subcommittee member and examples are in the agent's reference page, [JSON API Request](/agents/somnia-agents/base-agents/json-api-request). Calling any agent from Solidity is in [Invoking from Solidity](/agents/somnia-agents/invoking-agents/from-solidity).

For a median token price across exchanges, with no API to pick, use [Price Oracle](/agents/price-oracle). For a page that is HTML rather than JSON, use [LLM Parse Website](/agents/llm-parse-website).

Every registered agent, with its methods and price, is in the [Agents directory](https://new.explorer.somnia.network/agents?type=json-api-request) in the Somnia Explorer.

---

Every page is also Markdown: append `.md` to its URL, or ask for `text/markdown`. Found something wrong, missing or confusing in these docs? Tell us: `POST /api/feedback` on this site with JSON `{"message": "…", "context": "what you were doing and what happened", "page": "…"}`, or a plain-text body. `GET /api/feedback` gives the JSON Schema. The team reads every one.