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

# REST API

> HTTP surfaces for prediction-market query, world state, market detail, account data, and portfolio memory.

SimpleFunctions APIs expose prediction markets as structured state.

For a build-oriented walkthrough with curl, TypeScript, and Python examples, start with [Direct API access](/build/direct-api-access).

Base URL:

```text theme={null}
https://simplefunctions.dev
```

## Surface groups

| Group                    | Prefix                                                     | Auth                     | Purpose                                                    |
| ------------------------ | ---------------------------------------------------------- | ------------------------ | ---------------------------------------------------------- |
| Query and public markets | `/api/public/*`                                            | no auth for public reads | Search, screens, market detail, index, gov/econ context    |
| Agent world              | `/api/agent/*`                                             | no auth for core reads   | Compact world state, deltas, feed, inspect                 |
| Account                  | `/api/thesis`, `/api/feed`, `/api/intents`, `/api/keys`    | API key                  | User-owned theses, feed, intents, API keys                 |
| Portfolio                | `/api/portfolio/*`                                         | API key                  | Portfolio state, ticks, trades, config, views, strategies  |
| Workflow state           | `/api/watch`, `/api/alert-rules`, `/api/webhook-endpoints` | API key                  | User-owned watched objects, alert rules, webhook endpoints |

## First calls

```bash theme={null}
curl "https://simplefunctions.dev/api/public/query?q=Fed%20rate%20cut&limit=3"
curl "https://simplefunctions.dev/api/agent/world"
curl "https://simplefunctions.dev/api/public/market/KXRATECUT-26DEC31"
curl "https://simplefunctions.dev/api/contracts/tools"
```

## Authentication

Public market and world-state endpoints do not require auth for core reads. On supported routes, auth may unlock higher rate limits, higher model tiers, or user-specific overlays.

Authenticated endpoints use a SimpleFunctions API key:

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

Authenticated reads are scoped to the authenticated user. Do not pass arbitrary `userId` fields from the client for normal account or portfolio reads.

## Common response style

Public endpoints generally return the documented object directly.

Account and portfolio surfaces use a stable envelope where appropriate:

```json theme={null}
{
  "ok": true,
  "data": {},
  "meta": {}
}
```

Errors should be structured:

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Unauthorized",
    "status": 401
  }
}
```

## Choosing the right endpoint

| User question                                                   | Endpoint                                                               |
| --------------------------------------------------------------- | ---------------------------------------------------------------------- |
| "What markets match this real-world event?"                     | `GET /api/public/query?q=`                                             |
| "What should an agent know about the world right now?"          | `GET /api/agent/world`                                                 |
| "What changed since the last loop?"                             | `GET /api/agent/world/delta?since=`                                    |
| "What is the full state of this ticker?"                        | `GET /api/public/market/{ticker}` or `GET /api/agent/inspect/{ticker}` |
| "What official economic/government context maps to this topic?" | `GET /api/public/query-econ?q=` or `GET /api/public/query-gov?q=`      |
| "What user-owned portfolio history can this agent see?"         | `GET /api/portfolio/ticks` and related portfolio endpoints             |
| "What canonical SDK/Agent tools exist?"                         | `GET /api/contracts/tools`                                             |
| "What broad hosted compatibility tools exist?"                  | `GET /api/tools`                                                       |
| "How do I call the API from my service?"                        | [Direct API access](/build/direct-api-access)                          |

## Tool catalogs

Use the right catalog for the job:

| Catalog                    | Meaning                                                                                                                                |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/contracts/tools` | Strict SDK/Agent contract truth: canonical dotted tools, auth, access, `sideEffect`, `costEffect`, Agent callability, replay metadata. |
| `GET /api/tools`           | Broad hosted compatibility inventory for HTTP-native and MCP-adjacent clients.                                                         |
| `sf describe --all --json` | Local installed CLI command manifest.                                                                                                  |

SDK and Agent SDK code should use `/api/contracts/tools`. Broad names such as
`get_world_state` are compatibility names, not SDK/Agent canonical tool names.