SimpleFunctions Developer Manual

Use Query API when a user or agent asks a natural-language market question.

curl "https://simplefunctions.dev/api/public/query?q=Fed%20rate%20cut&limit=3"

sf query "Fed rate cut" --json --limit 3

const res = await fetch(
  `https://simplefunctions.dev/api/public/query?q=${encodeURIComponent('Fed rate cut')}&limit=3`,
  { headers: { Authorization: `Bearer ${process.env.SF_API_KEY}` } }
)
const data = await res.json()

import os, requests
res = requests.get(
    'https://simplefunctions.dev/api/public/query',
    params={'q': 'Fed rate cut', 'limit': 3},
    headers={'Authorization': f"Bearer {os.environ['SF_API_KEY']}"}
)
data = res.json()

Endpoint

GET /api/public/query

Auth: optional. Anonymous calls work for mode=full with the cheap model. Authenticated calls (Authorization: Bearer sf_live_...) unlock the model parameter and raise the rate limit. Rate limits:

Anonymous: 10 requests / minute / IP
Authenticated: 60 requests / minute / key
Cached queries (recent identical q+params) bypass the rate-limit counter and return immediately.

Query parameters

Required

Parameter	Type	Notes
`q`	string	Natural-language event question or topic. Minimum 2 characters after trim.

Optional

Parameter	Type	Default	Values	Notes
`mode`	string	`full`	`full`, `raw`	`full` uses LLM-expanded recall and adds an LLM-synthesised `answer`. `raw` uses deterministic retrieval and skips both query-understanding and synthesis LLM calls.
`sources`	comma list	all	`kalshi`, `polymarket`, `x`, `content`, `traditional`	Restrict which source clusters appear in the response.
`limit`	int	`10`	`1` – `20`	Max markets returned per venue. Values > 20 are clamped to 20.
`model`	string	`cheap`	`cheap`, `medium`, `heavy`	Synthesis model tier. Requires auth for any value other than `cheap`.
`depth`	boolean string	`false`	`true`	Enrich the top Kalshi markets with orderbook depth fields. Adds latency.
`nextActions`	string	included	`off`	Omit the `nextActions` block (inspect / related URLs) when set to `off`.

Examples

Full answer:

curl "https://simplefunctions.dev/api/public/query?q=Fed%20rate%20cut&limit=3"

Fast deterministic retrieval:

curl "https://simplefunctions.dev/api/public/query?q=Fed%20rate%20cut&mode=raw&limit=5"

Only prediction venues:

curl "https://simplefunctions.dev/api/public/query?q=US%20recession&sources=kalshi,polymarket&limit=5"

Include orderbook enrichment:

curl "https://simplefunctions.dev/api/public/query?q=Fed%20rate%20cut&depth=true"

Response

Show Full response shape

{
  "query": "Fed rate cut",
  "answer": "Prediction markets are pricing...",
  "keyFactors": [],
  "kalshi": [
    {
      "title": "Will the Federal Reserve cut rates before 2027?",
      "ticker": "KXRATECUT-26DEC31",
      "price": 49,
      "volume": 102746.28,
      "pageUrl": "https://simplefunctions.dev/markets/KXRATECUT-26DEC31",
      "apiUrl": "https://simplefunctions.dev/api/public/market/KXRATECUT-26DEC31",
      "inspectUrl": "https://simplefunctions.dev/api/agent/inspect/KXRATECUT-26DEC31"
    }
  ],
  "polymarket": [],
  "traditional": [],
  "x": [],
  "content": [],
  "theses": [],
  "legislation": [],
  "meta": {
    "sources": ["kalshi", "polymarket", "traditional"],
    "mode": "full",
    "latencyMs": 0
  },
  "nextActions": {
    "inspect": [],
    "related": []
  }
}

Fields appear only when the corresponding source has results. nextActions is absolute-URL’d to https://simplefunctions.dev/... so an agent can follow links directly.

Errors

Status	Body	Cause
`400`	`{ "error": "Query parameter \"q\" is required (min 2 chars)" }`	Missing `q` or fewer than 2 chars.
`401`	`{ "error": "Custom model tier requires a valid API key. Add header: Authorization: Bearer sf_live_xxx" }`	`model=medium` or `model=heavy` without auth.
`429`	`{ "error": "Rate limit exceeded. Try again in a minute." }`	Hit per-minute limit (10 anon / 60 authed).
`500`	`{ "error": "..." }`	Upstream model or DB failure. Retry with `mode=raw` to bypass query-understanding and synthesis LLM calls.

Use in an agent

curl "https://simplefunctions.dev/api/public/query?q=Fed%20rate%20cut&mode=raw&limit=3"
curl "https://simplefunctions.dev/api/agent/inspect/KXRATECUT-26DEC31"
curl "https://simplefunctions.dev/api/public/screen?keyword=Fed%20rate%20cut"

Use query to find candidate markets. Use inspect before acting on one ticker. Use screen when the agent needs a broader ranked market list.

Start with the API

Public market APIs

Authenticated APIs

Tools and events

Query API

Endpoint

Query parameters

Examples

Response

Errors

Use in an agent

​Endpoint

​Query parameters

​Examples

​Response

​Errors

​Use in an agent

Endpoint

Query parameters

Examples

Response

Errors

Use in an agent