---
title: api
canonical_url: https://ensurance.app/manual/api
markdown_url: https://ensurance.app/manual/api.md
subtitle: public reads and ask/act
section: reference
---

# api

*public reads and ask/act*

the public api is how a builder or an outside agent reads the protocol. a proposal that moves value is confirmed in the app. nothing moves until the signed-in person confirms it there.

:::johnson
**start at /llms.txt** — that file is the stable list of reads. This page is the shape of those reads.
:::

## base url

```
https://ensurance.app/api
```

reads return json and need no session.

## discovery reads

These are the reads /llms.txt advertises.

| Read | Method | Returns |
|------|--------|---------|
| search | `GET /api/search?q=` | matches across the site: `name`, `path`, `type` |
| catalog | `GET /api/catalog?fields=index` | `{ items }`. a coin is `contract_address`, `name`, `type: general`. a certificate is `tokenId`, `type: specific`. an agent is `full_account_name`, `token_id`, `group_name`, `type: account`. a group is `group_name`, `name_front`, `type: group` |
| guide | `GET /api/guide?fields=index` | the published guide index |
| manual | `GET /api/manual` | published manual entries |
| protocol stats | `GET /api/protocol/stats` | counts: `groups.groups`, `groups.agents`, `general.coins`, `specific.policies`, `proceeds.streams`, `proceeds.contracts` |
| accounts | `GET /api/accounts` | agents. optional `?group=` |
| coins | `GET /api/general` | the browsable coin list |
| certificates | `GET /api/specific/tokens` | `{ success, count, tokens }` |
| institutional finance | `GET /api/institutional` | institutional finance status |

One agent: `GET /api/accounts/{full_account_name}` — for example `GET /api/accounts/0xjoshua.basin`.

One coin: `GET /api/general/{contract}`.

A certificate is a `tokenId` inside the tokens list. There is no `/api/specific/tokens/{id}` path.

## ask / act

ask in the browser at /act. `/act?q=` opens on a question. the same conversation is `POST /api/act`.

a proposal that moves value comes back as a card. nothing moves until the signed-in person confirms that card in the app.

## other public reads

These work and are not on the discovery list. Prefer a discovery read when /llms.txt already covers the question.

| Read | Method | Returns |
|------|--------|---------|
| groups | `GET /api/groups` | an array. each group has `group_name`, `tagline`, `contract_address`, `total_supply` |
| proceeds | `GET /api/proceeds` | a map keyed by address. values have `name`, `type`, `description` |
| one proceeds address | `GET /api/proceeds/{address}` | the catalog entry, plus live split data when the address is a split |
| pools | `GET /api/pools` | `{ pools, count }`. each pool has `pool_address`, `name`, `pool_type`, and `dex_type`, plus the paired token or tokens |
| claims and evidence | `GET /api/agents/{address}/claims-evidence` | public claims next to holdings, activity, a linked geography, and attestations already on base |
| attestations | `GET /api/agents/{address}/attestations` | attestations on base to and from that account. writing a new protocol claim is not live |

Pool lookup is a query, not a path: `GET /api/pools?pool=0x…&source=catalog` or `GET /api/pools?token=0x…`.

These paths do not exist: `/api/groups/{slug}`, `/api/pools/{address}`, `/api/proceeds/agent/{address}`, `/api/specific/purchase`, `/api/contracts`, `/api/llms.txt`.

## swaps

swaps happen in the app, on base. there is no public swap-price path to integrate.

## errors

| Code | When |
|------|------|
| 400 | missing or invalid parameters |
| 401 | a signed-in call with no session, or a bad session |
| 404 | that record or path does not exist |
| 429 | rate limited |
| 500 | the server failed |

The body includes an `error` message. Routes do not share one error code.

## related

- for agents and operators — ask/act and the three modes
- agents — what an account is
- coins — general ensurance
- certificates — specific ensurance
- proceeds — how value is routed
- pools — where coins trade