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


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