botso.ai API Documentation

Overview

The botso.ai platform API is a Laravel REST service. The hostname is api.botso.ai; Laravel mounts all JSON routes under an /api prefix, so the client base URL is https://api.botso.ai/api and paths look like /v1/auth/login (full URL: https://api.botso.ai/api/v1/auth/login). Authentication uses Laravel Passport (OAuth2 bearer tokens).

Core concepts

Authentication

Password grant (user apps)

For SPAs and mobile apps where a user signs in with email and password.

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "admin@botso.ai",
  "password": "password",
  "client_id": "YOUR_OAUTH_CLIENT_ID"
}

{
  "token_type": "Bearer",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "expires_at": "2026-06-08 12:00:00",
  "scopes": ["botso:read"],
  "user": {
    "id": 1,
    "name": "Club Admin",
    "email": "admin@botso.ai",
    "permissions": ["botso_access", "botso_manage"],
    "organizations": [{ "id": 1, "name": "Demo Club", "slug": "botso-ai" }]
  }
}

Client credentials (machine-to-machine)

For server-side integrations and service accounts. Use the botso Service Client OAuth client.

{
  "client_id": "SERVICE_CLIENT_ID",
  "client_secret": "SERVICE_CLIENT_SECRET",
  "scope": "botso:read"
}

Session endpoints

Required headers

Organization resolution order: subdomain ({slug}.botso.ai) → X-Botso-Organization header → ?org= query → auto-select if user has one org.

Organizations

Pools — read (members & admins)

Requires botso_access and organization context. Members only see pools they belong to or hold tickets in.

{
  "has_financial_data": true,
  "month": "2026-06",
  "first_trade_date": "2026-06-06",
  "available_months": [
    { "value": "2026-06", "label": "June 2026" }
  ],
  "series": [
    { "date": "2026-06-06", "daily_pnl": 56.44, "cumulative_pnl": 56.44 },
    { "date": "2026-06-07", "daily_pnl": 116.29, "cumulative_pnl": 172.73 },
    { "date": "2026-06-08", "daily_pnl": 104.59, "cumulative_pnl": 277.32 }
  ],
  "point_count": 3,
  "month_total_pnl": 277.32,
  "pool": {
    "slug": "sim-trial",
    "name": "Trial Pool"
  }
}

When the pool has no financial data or primary bot, returns has_financial_data: false with empty series and available_months.

Pools — manage (org admin)

Requires botso.org.manage — organization admin or owner, or platform botso_manage.

{
  "name": "Summer Syndicate",
  "type": "club",
  "ticket_cap": 20,
  "ticket_price": 50,
  "funding_target": 1000,
  "start_date": "2026-07-01",
  "end_date": "2026-12-31",
  "description": "Optional pool description"
}

{
  "user_id": 42,
  "member_name": "Jane Smith",
  "target_pool_slug": "late90s-club",
  "entry_method": "ticketing",
  "payment_note": "FT-order-88421"
}

entry_method: admin | cash | transfer | revolut | ticketing | usdc

Payment processor (coming soon)

Member ticket purchase will move to a dedicated payment processor integrated with the ticketing platform API. Partners and mobile apps will use the same OAuth login and users table — no separate auth system.

Until then, club admins assign tickets via POST /v1/botso/pools/{slug}/tickets after off-platform payment, or record payments with POST .../payments.

Payments & funding

{
  "amount": 500,
  "method": "transfer",
  "reference": "REV-2026-001"
}

Payouts & earnings

Notifications (Twilio & WhatsApp)

Analytics & trading (operator)

Requires botso_manage and user_management_access.

Separate trading API

Operator trading endpoints at /v1/trading/* require scope trading:read.

Errors & status codes

{
  "message": "Validation error.",
  "errors": {
    "entry_method": ["The selected entry method is invalid."]
  }
}