> ## 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
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.