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


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