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

# World State API

> Snapshot, drill, delta, feed, and inspect endpoints for market-aware agents — compact context for LLM windows.

Use these endpoints when an agent needs compact prediction-market context.

## Endpoints

| Endpoint                                          | Auth | Returns                           |
| ------------------------------------------------- | ---- | --------------------------------- |
| `GET /api/agent/world`                            | none | Markdown snapshot by default.     |
| `GET /api/agent/world?format=json`                | none | JSON world snapshot.              |
| `GET /api/agent/world/{path}?format=json`         | none | Drill snapshot for a topic path.  |
| `GET /api/agent/world/delta?since=1h&format=json` | none | Changes between stored snapshots. |
| `GET /api/agent/world/feed`                       | none | Atom feed of world snapshots.     |
| `GET /api/agent/inspect/{ticker}`                 | none | One-market inspection dossier.    |

## Snapshot

```http theme={null}
GET /api/agent/world?format=json
```

<CodeGroup>
  ```bash curl theme={null}
  curl "https://simplefunctions.dev/api/agent/world?format=json"
  ```

  ```bash CLI theme={null}
  sf world --json
  ```

  ```ts TypeScript theme={null}
  const res = await fetch('https://simplefunctions.dev/api/agent/world?format=json')
  const world = await res.json()
  ```

  ```python Python theme={null}
  import requests
  world = requests.get('https://simplefunctions.dev/api/agent/world?format=json').json()
  ```
</CodeGroup>

Parameters:

| Parameter | Values                     | Use                                      |
| --------- | -------------------------- | ---------------------------------------- |
| `format`  | `json`, `markdown`         | Response format. Default is markdown.    |
| `limit`   | `1` to `30`                | Number of salient items. Default `10`.   |
| `depth`   | `0` to `3`                 | Drill expansion depth. Default `1`.      |
| `since`   | `12h`, `3d`, ISO timestamp | Override baseline where supported.       |
| `focus`   | topic string               | Legacy alias for the first path segment. |

<Expandable title="JSON shape">
  ```json theme={null}
  {
    "region": {
      "path": [],
      "label": "World"
    },
    "regime": {
      "label": "neutral",
      "signals": {}
    },
    "salient": [],
    "index": {},
    "traditional": [],
    "movers": [],
    "opportunities": [],
    "marketCount": 0,
    "servedAt": "2026-04-30T00:00:00.000Z"
  }
  ```
</Expandable>

## Drill

```http theme={null}
GET /api/agent/world/iran/hormuz?format=json
```

```bash theme={null}
curl "https://simplefunctions.dev/api/agent/world/iran/hormuz?format=json&limit=8"
```

Use path segments to narrow the snapshot before sending it into an agent context window.

## Operations

| Operation    | Example                                                   |
| ------------ | --------------------------------------------------------- |
| `snapshot`   | `/api/agent/world?op=snapshot&format=json`                |
| `catalyst`   | `/api/agent/world/iran?op=catalyst&window=7d&format=json` |
| `dispersion` | `/api/agent/world/iran?op=dispersion&format=json`         |
| `history`    | `/api/agent/world/iran?op=history&dt=24h&format=json`     |
| `trail`      | `/api/agent/world?op=trail&from=KXHORMUZ&format=json`     |
| `explain`    | `/api/agent/world?op=explain&item=s-7&format=json`        |

Operation parameters:

| Parameter | Required for | Use                                |
| --------- | ------------ | ---------------------------------- |
| `window`  | `catalyst`   | Catalyst window, for example `7d`. |
| `dt`      | `history`    | History window, for example `24h`. |
| `from`    | `trail`      | Starting ticker for linkage walk.  |
| `item`    | `explain`    | Salient item id to explain.        |

## Delta

```http theme={null}
GET /api/agent/world/delta?since=1h&format=json
```

```bash theme={null}
curl "https://simplefunctions.dev/api/agent/world/delta?since=1h&format=json"
```

`since` accepts:

| Value         | Example                |
| ------------- | ---------------------- |
| Minutes       | `15m`                  |
| Hours         | `1h`                   |
| Days          | `3d`                   |
| ISO timestamp | `2026-04-30T08:00:00Z` |

<Expandable title="Delta response shape">
  ```json theme={null}
  {
    "from": "2026-04-30T08:00:00.000Z",
    "to": "2026-04-30T08:15:00.000Z",
    "changes": [],
    "markdown": "# World Delta — no changes since 1h",
    "latencyMs": 18
  }
  ```

  If there is no stored snapshot before the requested timestamp, the endpoint returns `404` with a suggestion to call `/api/agent/world`.
</Expandable>

## Inspect

```http theme={null}
GET /api/agent/inspect/{ticker}
```

```bash theme={null}
curl "https://simplefunctions.dev/api/agent/inspect/KXRATECUT-26DEC31"
```

Parameters:

| Parameter     | Values             | Use                                    |
| ------------- | ------------------ | -------------------------------------- |
| `format`      | `json`, `markdown` | Response format. Default `json`.       |
| `contagion`   | `false`            | Omit connected-market scan.            |
| `diff`        | `false`            | Omit cross/related diff work.          |
| `trend`       | `false`            | Omit trend work.                       |
| `nextActions` | `off`              | Omit follow-up URLs and intent bodies. |

Response fields:

| Field                                         | Use                                                                |
| --------------------------------------------- | ------------------------------------------------------------------ |
| `ticker`, `venue`, `title`, `price`, `status` | Market identity and current state.                                 |
| `suggestion`                                  | Action, confidence, reasoning, positives, warnings, and size hint. |
| `regime`                                      | Regime score and signals.                                          |
| `indicators`                                  | IY, CRI, EE, LAS, overround, and related computed fields.          |
| `edges[]`                                     | Thesis-derived edges.                                              |
| `contagion[]`                                 | Connected markets.                                                 |
| `trend7d[]`                                   | Recent price trend.                                                |
| `legislation`                                 | Linked government context when available.                          |
| `nextActions`                                 | Execution, watch, deeper inspection, and query follow-ups.         |
| `latencyMs`                                   | Server latency for the inspection.                                 |

Markdown example:

```bash theme={null}
curl "https://simplefunctions.dev/api/agent/inspect/KXRATECUT-26DEC31?format=markdown"
```

## Feed

```http theme={null}
GET /api/agent/world/feed
```

```bash theme={null}
curl "https://simplefunctions.dev/api/agent/world/feed"
```

Returns Atom XML with recent world-state snapshots. The feed includes up to 20 recent entries and is intended for RSS readers, automation tools, crawlers, and agent frameworks that support feed input.

## CLI equivalents

```bash theme={null}
sf world --json
sf world iran/hormuz --json
sf world --op catalyst --dt 48h --json
sf world --delta --json --since 1h
sf inspect KXRATECUT-26DEC31 --json
```