Thrive Developers

Reference

API Reference

Every Thrive API endpoint on one page.

Retrieve the key owner

GET /v1/me

Returns the Thrive user that owns the API key. Only the id and display name are exposed — never email or other personal data.

Authentication: API key · Required scope: profile:read

curl "https://jointhrive.org/api/public/v1/me" \
  -H "Authorization: Bearer $THRIVE_API_KEY"
Response · 200
{
  "object": "user",
  "id": "8b0c…",
  "display_name": "Grant"
}

Errors: invalid_api_key, missing_scope, rate_limited

Try it

Sign in to test this endpoint with one of your keys.

Get a quote

GET /v1/markets/quote

Latest price for a stock, ETF, crypto asset or index, from the same live market feed that powers Thrive Markets.

Authentication: API key · Required scope: markets:read

Parameters · Get a quote

symbolstringrequired

Ticker, e.g. AAPL, NVDA, BTC.

kindstring

stock (default), etf, bond, crypto, commodity or index.

curl "https://jointhrive.org/api/public/v1/markets/quote?symbol=AAPL" \
  -H "Authorization: Bearer $THRIVE_API_KEY"
Response · 200
{
  "object": "quote",
  "symbol": "AAPL",
  "price": 341.07,
  "prevClose": 335.92,
  "changeAbs": 5.15,
  "changePct": 1.53,
  "source": "live",
  "asOf": 1790366400000
}

Errors: parameter_missing, parameter_invalid, symbol_not_found, market_data_unavailable

Try it

Sign in to test this endpoint with one of your keys.

Get price history

GET /v1/markets/history

Daily closing bars for the last N days.

Authentication: API key · Required scope: markets:read

Parameters · Get price history

symbolstringrequired

Ticker symbol.

kindstring

Asset kind, default stock.

daysinteger

1–3650, default 30.

curl "https://jointhrive.org/api/public/v1/markets/history?symbol=AAPL&days=30" \
  -H "Authorization: Bearer $THRIVE_API_KEY"
Response · 200
{
  "object": "list",
  "symbol": "AAPL",
  "data": [
    { "d": "2026-09-24", "o": 336.72, "h": 338.91, "l": 334.3, "c": 335.92 },
    { "d": "2026-09-25", "o": 336.04, "h": 341.67, "l": 334.53, "c": 341.07 }
  ]
}

Errors: parameter_missing, parameter_invalid, symbol_not_found

Try it

Sign in to test this endpoint with one of your keys.

List simulations

GET /v1/simulations

The full catalog of Thrive life simulations, from the same registry that powers the app. Each includes a link that launches it in Thrive.

Authentication: API key · Required scope: simulations:read

curl "https://jointhrive.org/api/public/v1/simulations" \
  -H "Authorization: Bearer $THRIVE_API_KEY"
Response · 200
{
  "object": "list",
  "data": [
    {
      "id": "first-paycheck",
      "title": "Spend Your First Paycheck",
      "category": "Budgeting",
      "difficulty": "Starter",
      "minutes": 15,
      "url": "https://jointhrive.org/simulations/first-paycheck"
    }
  ]
}

Errors: invalid_api_key, missing_scope

Try it

Sign in to test this endpoint with one of your keys.

List projects

GET /v1/projects

The key owner's Agent Projects, most recently updated first (up to 100).

Authentication: API key · Required scope: projects:read

curl "https://jointhrive.org/api/public/v1/projects" \
  -H "Authorization: Bearer $THRIVE_API_KEY"
Response · 200
{
  "object": "list",
  "data": [
    {
      "id": "3f1e…",
      "title": "My First Car",
      "goal": "Buy a reliable car under $15,000",
      "template": "car",
      "status": "active"
    }
  ]
}

Errors: invalid_api_key, missing_scope

Try it

Sign in to test this endpoint with one of your keys.

Retrieve a project

GET /v1/projects/{id}

One project with its saved items (simulations, lessons, conversations, notes). Only the key owner's projects are reachable.

Authentication: API key · Required scope: projects:read

Parameters · Retrieve a project

iduuidrequired

Project id (path parameter).

curl "https://jointhrive.org/api/public/v1/projects/PROJECT_ID" \
  -H "Authorization: Bearer $THRIVE_API_KEY"
Response · 200
{
  "object": "project",
  "id": "3f1e…",
  "title": "My First Car",
  "items": [ … ]
}

Errors: resource_missing, missing_scope

Try it

Sign in to test this endpoint with one of your keys.

Create a project

POST /v1/projects

Creates an Agent Project owned by the key owner. Retrying with the same Idempotency-Key returns the first result.

Authentication: API key · Required scope: projects:write · Supports Idempotency-Key

Parameters · Create a project

titlestringrequired

1–120 characters.

goalstring

Up to 500 characters.

curl -X POST "https://jointhrive.org/api/public/v1/projects" \
  -H "Authorization: Bearer $THRIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"Emergency fund","goal":"Save $3,000"}'
Response · 200
{
  "object": "project",
  "id": "3f1e…",
  "title": "Emergency fund",
  "status": "active"
}

Errors: missing_scope, parameter_invalid, project_limit, idempotency_conflict

Get the virtual portfolio

GET /v1/portfolio

The key owner's VIRTUAL practice portfolio — simulated cash and positions. No real money is involved.

Authentication: API key · Required scope: portfolio:read

curl "https://jointhrive.org/api/public/v1/portfolio" \
  -H "Authorization: Bearer $THRIVE_API_KEY"
Response · 200
{
  "object": "portfolio",
  "virtual": true,
  "cash": 91234.5,
  "positions": [ { "symbol": "AAPL", "quantity": 20, "avg_cost": 331.2, "current_price": 341.07, "market_value": 6821.4 } ],
  "total_value": 98055.9
}

Errors: invalid_api_key, missing_scope

Try it

Sign in to test this endpoint with one of your keys.

List virtual trades

GET /v1/trades

Recent virtual transactions, newest first.

Authentication: API key · Required scope: trading:read

Parameters · List virtual trades

limitinteger

1–200, default 50.

curl "https://jointhrive.org/api/public/v1/trades" \
  -H "Authorization: Bearer $THRIVE_API_KEY"
Response · 200
{
  "object": "list",
  "virtual": true,
  "data": [ { "symbol": "AAPL", "side": "buy", "quantity": 20, "price": 331.2 } ]
}

Errors: missing_scope, parameter_invalid

Try it

Sign in to test this endpoint with one of your keys.

Place a virtual trade

POST /v1/trades

Buys or sells in the key owner's VIRTUAL practice portfolio at the live price. The server checks cash and holdings and updates positions itself — callers can never set cash, quantity or cost basis. Send an Idempotency-Key so a retry never trades twice.

Authentication: API key · Required scope: trading:write · Supports Idempotency-Key

Parameters · Place a virtual trade

symbolstringrequired

Ticker.

kindstring

stock (default), etf, bond, crypto, commodity, index.

sidestringrequired

buy or sell.

quantitynumber

Shares. Provide this or dollar_amount.

dollar_amountnumber

Dollars to trade. Provide this or quantity.

curl -X POST "https://jointhrive.org/api/public/v1/trades" \
  -H "Authorization: Bearer $THRIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"symbol":"AAPL","side":"buy","quantity":2}'
Response · 200
{
  "object": "trade",
  "virtual": true,
  "symbol": "AAPL",
  "side": "buy",
  "price": 341.07,
  "quantity": 2,
  "newCash": 90552.36
}

Errors: missing_scope, parameter_invalid, trade_rejected, idempotency_conflict, rate_limited

Get learning progress

GET /v1/progress

How many lessons and simulations the key owner has started and completed.

Authentication: API key · Required scope: progress:read

curl "https://jointhrive.org/api/public/v1/progress" \
  -H "Authorization: Bearer $THRIVE_API_KEY"
Response · 200
{
  "object": "progress",
  "lessons": { "started": 12, "completed": 9 },
  "simulations": { "started": 4, "completed": 3 }
}

Errors: missing_scope

Try it

Sign in to test this endpoint with one of your keys.

Get credit usage

GET /v1/usage

Agent credit balance and the 20 most recent credit changes. Read-only: credits, billing and plans can't be changed through the API.

Authentication: API key · Required scope: usage:read

curl "https://jointhrive.org/api/public/v1/usage" \
  -H "Authorization: Bearer $THRIVE_API_KEY"
Response · 200
{
  "object": "usage",
  "balance": 84,
  "plan_id": "credits_100",
  "recent": [ { "amount": -1, "type": "usage", "source": "developer_api" } ]
}

Errors: missing_scope

Try it

Sign in to test this endpoint with one of your keys.

Get connected-app status

GET /v1/connections

Which outside apps (Gmail, Plaid, …) the owner has connected, and their status. Data from those apps is never available through the API or MCP.

Authentication: API key · Required scope: connections:read

curl "https://jointhrive.org/api/public/v1/connections" \
  -H "Authorization: Bearer $THRIVE_API_KEY"
Response · 200
{
  "object": "list",
  "data": [ { "provider": "gmail", "status": "connected" } ]
}

Errors: missing_scope

Try it

Sign in to test this endpoint with one of your keys.

List Agent chats

GET /v1/agent/chats

Titles of the owner's saved Agent chats, most recent first.

Authentication: API key · Required scope: agent:read

Parameters · List Agent chats

limitinteger

1–100, default 20.

curl "https://jointhrive.org/api/public/v1/agent/chats" \
  -H "Authorization: Bearer $THRIVE_API_KEY"
Response · 200
{
  "object": "list",
  "data": [ { "id": "…", "title": "Can I afford a $20k car?" } ]
}

Errors: missing_scope

Try it

Sign in to test this endpoint with one of your keys.

Ask the Agent

POST /v1/agent/ask

Asks the Thrive Agent a money question and returns a text answer. Costs 1 Agent credit from the owner's normal balance, charged once per Idempotency-Key — retries never double charge. Returns 402 when the balance is empty.

Authentication: API key · Required scope: agent:write · Supports Idempotency-Key

Parameters · Ask the Agent

questionstringrequired

1–2000 characters.

curl -X POST "https://jointhrive.org/api/public/v1/agent/ask" \
  -H "Authorization: Bearer $THRIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"question":"How does an emergency fund work?"}'
Response · 200
{
  "object": "agent_answer",
  "answer": "An emergency fund is…",
  "credits_charged": 1,
  "credits_remaining": 83
}

Errors: missing_scope, insufficient_credits, agent_unavailable, idempotency_conflict