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

# Direct API access

> Call SimpleFunctions over HTTP from curl, TypeScript, Python, services, and agents.

Use direct API access when a service, dashboard, research notebook, or agent runtime needs stable HTTP calls instead of shelling out to `sf`.

Prefer the CLI when a local agent wants tool discovery, local config, command policy tags, or `sf describe --all --json` as its control plane. Use MCP only as the final adapter when the host requires Model Context Protocol.

## Base URLs

| Surface        | URL                                   |
| -------------- | ------------------------------------- |
| Core API       | `https://simplefunctions.dev`         |
| Data REST      | `https://data.simplefunctions.dev/v1` |
| Data WebSocket | `wss://app.simplefunctions.dev/ws`    |

Do not use `wss://data.simplefunctions.dev/v1/ws` as the public WebSocket URL unless the [real-time data page](/reference/realtime-data) says it has moved.

## Auth matrix

| Surface                                                    | Auth                                           | Notes                                                                                    |
| ---------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `/api/public/*`                                            | Usually no auth for public reads               | Auth may unlock higher limits, higher model tiers, or user overlays on supported routes. |
| `/api/agent/world`, `/api/agent/inspect/*`                 | No auth for core reads                         | Compact payloads for agents.                                                             |
| `/api/contracts/tools`                                     | No auth                                        | Strict SDK/Agent contract manifest.                                                      |
| `/api/tools`                                               | No auth                                        | Broad hosted compatibility inventory.                                                    |
| `/api/thesis/*`, `/api/feed`, `/api/intents`, `/api/keys`  | `Authorization: Bearer sf_live_...`            | User-owned data.                                                                         |
| `/api/portfolio/*`                                         | `Authorization: Bearer sf_live_...`            | User-scoped portfolio memory and config.                                                 |
| `/api/watch`, `/api/alert-rules`, `/api/webhook-endpoints` | `Authorization: Bearer sf_live_...`            | User-owned workflow state.                                                               |
| `data.simplefunctions.dev/v1`                              | See [Real-time data](/reference/realtime-data) | Data API auth is documented separately.                                                  |

## First curl calls

Public reads:

```bash theme={null}
curl "https://simplefunctions.dev/api/public/query?q=Fed%20rate%20cut&limit=3"
curl "https://simplefunctions.dev/api/agent/world?format=json"
curl "https://simplefunctions.dev/api/agent/world/delta?since=1h&format=json"
curl "https://simplefunctions.dev/api/public/market/KXRATECUT-26DEC31"
curl "https://simplefunctions.dev/api/agent/inspect/KXRATECUT-26DEC31"
curl "https://simplefunctions.dev/api/public/query-econ?q=unemployment%20rate&includeMarkets=true"
curl "https://simplefunctions.dev/api/public/query-gov?q=SAVE%20Act&limit=3"
curl "https://simplefunctions.dev/api/contracts/tools"
```

Authenticated user-owned reads:

```bash theme={null}
curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://simplefunctions.dev/api/thesis"

curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://simplefunctions.dev/api/portfolio/state"
```

## TypeScript

```ts theme={null}
type SfFetchOptions = RequestInit & { apiKey?: string }

async function sfFetch<T>(path: string, options: SfFetchOptions = {}): Promise<T> {
  const { apiKey, headers, ...init } = options
  const res = await fetch(`https://simplefunctions.dev${path}`, {
    ...init,
    headers: {
      ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
      ...headers,
    },
  })

  const text = await res.text()
  const body = text ? JSON.parse(text) : null

  if (!res.ok) {
    throw new Error(body?.error?.message ?? body?.message ?? `SimpleFunctions HTTP ${res.status}`)
  }

  return body as T
}

const markets = await sfFetch('/api/public/query?q=Fed%20rate%20cut&limit=3')

const portfolio = await sfFetch('/api/portfolio/state', {
  apiKey: process.env.SF_API_KEY,
})
```

## Python

```python theme={null}
import os
import requests

BASE = "https://simplefunctions.dev"

query = requests.get(
    f"{BASE}/api/public/query",
    params={"q": "Fed rate cut", "limit": 3},
    timeout=20,
)
query.raise_for_status()
print(query.json())

portfolio = requests.get(
    f"{BASE}/api/portfolio/state",
    headers={"Authorization": f"Bearer {os.environ['SF_API_KEY']}"},
    timeout=20,
)
portfolio.raise_for_status()
print(portfolio.json())
```

## Responses and errors

Public endpoints generally return endpoint-specific JSON directly.

Account, portfolio, and workflow endpoints often use `{ ok, ... }` envelopes where documented. Always branch on HTTP status first. Do not scrape prose from rendered docs or terminal output. Prefer `format=json` where a route supports it.

## Endpoint chooser

| Need                                      | Endpoint                                                   |
| ----------------------------------------- | ---------------------------------------------------------- |
| Find markets for a natural-language event | `GET /api/public/query?q=`                                 |
| Get compact world context                 | `GET /api/agent/world?format=json`                         |
| Get changes since last loop               | `GET /api/agent/world/delta?since=1h&format=json`          |
| Inspect one ticker                        | `GET /api/agent/inspect/{ticker}`                          |
| Get one market detail                     | `GET /api/public/market/{ticker}`                          |
| Search official econ context              | `GET /api/public/query-econ?q=`                            |
| Search gov or legislative context         | `GET /api/public/query-gov?q=`                             |
| Discover canonical SDK/Agent tools        | `GET /api/contracts/tools`                                 |
| Discover broad hosted compatibility tools | `GET /api/tools`                                           |
| Read user portfolio memory                | `GET /api/portfolio/state`, `/ticks`, `/trades`            |
| Create user workflow notifications        | `/api/watch`, `/api/alert-rules`, `/api/webhook-endpoints` |

## SDK and Agent contract note

If you are building against the TypeScript SDK or Agent SDK packages, use
`/api/contracts/tools` for canonical tools. `/api/tools` remains a broad hosted
inventory for compatibility and remote HTTP discovery.

## Safety notes

API keys are secrets. Do not paste them into prompts, public logs, or client-side bundles.

Execution endpoints can mutate real account state. Prediction markets are probabilities, not guarantees. User-owned endpoints are scoped to the authenticated user; do not pass `userId` for normal reads.