> ## Documentation Index
> Fetch the complete documentation index at: https://docs.presschain.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Bounty Read API

> Query current bounty proposals and evaluations from the read-only Rust API.

# Bounty read API

The current Rust API provides read-only access to bounty-engine proposal and evaluation state. It is useful for operations dashboards and services that need a bounded HTTP interface instead of reading engine state files directly.

## List proposals

```http theme={null}
GET /v1/bounty-proposals?limit=25&offset=0
```

The implementation defaults `limit` to `25`, clamps it between `1` and `100`, and defaults `offset` to `0`.

For a local process using the default bind:

```bash theme={null}
curl -s 'http://127.0.0.1:46331/v1/bounty-proposals?limit=25&offset=0'
```

Use the deployed gateway URL when the service sits behind a reverse proxy or authenticated edge.

## List evaluations

```http theme={null}
GET /v1/bounty-evaluations?limit=25&offset=0
```

```bash theme={null}
curl -s 'http://127.0.0.1:46331/v1/bounty-evaluations?limit=50&offset=0'
```

The same pagination bounds apply.

## Health

```http theme={null}
GET /health
```

The health handler attempts to read configured bounty state, so it checks more than whether the HTTP server is accepting connections. If state is unavailable, the service returns `503` with:

```json theme={null}
{
  "error": {
    "code": "bounty_state_unavailable"
  }
}
```

A load balancer or process monitor should treat that as unhealthy.

## Client pagination

A client can advance `offset` until a returned page contains fewer records than the requested limit. Adapt the exact collection field to the response type in the deployed `bounty_api` model.

```ts theme={null}
async function readPage(path: string, limit = 100, offset = 0) {
  const url = new URL(path, API_BASE_URL);
  url.searchParams.set("limit", String(limit));
  url.searchParams.set("offset", String(offset));

  const response = await fetch(url);
  if (!response.ok) throw await toApiError(response);
  return response.json();
}
```

## Read-only means read-only

The router explicitly rejects unsupported mutation methods. Do not build an administration client around an undocumented POST request. Bounty creation, claim, approval and settlement belong to their authorized engine and protocol paths.

## Operations use case

An internal dashboard can read evaluations, group them by trigger class, show proposals awaiting funding and link each record back to the relevant Capsule. It can remain read-only while higher-risk mutations stay behind separate authority.

That boundary reduces the blast radius of a public or broadly accessible monitoring interface.