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

Self-serve private syndicates

Any authenticated member (botso_access) can create their own private organization and become its owner, then invite friends and sell tickets. Creation is gated on club-catalog product seat availability — when all seats are sold out, the UI shows the create button disabled and these endpoints refuse creation.

{
  "can_create": true,
  "products": [
    {
      "id": 4,
      "slug": "club-the-dub",
      "title": "The Dub",
      "price": 300,
      "currency": "EUR",
      "available": 48,
      "inventory_cap": 50
    }
  ]
}

{
  "name": "Dublin lads pool",
  "product_id": 4,
  "ticket_cap": 4,
  "profit_target": 500,
  "description": "Optional"
}

{
  "organization": {
    "id": 12,
    "slug": "dublin-lads-pool",
    "name": "Dublin lads pool",
    "role": "owner",
    "visibility": "private",
    "platform_fee_pct": 8,
    "org_commission_pct": 0
  },
  "pool": { "slug": "dublin-lads-pool", "type": "private_syndicate", "…" },
  "organizations": [ "…" ]
}

Dashboard deep link: https://dashboard.botso.ai/syndicates/create. After create, switch to the new org slug via X-Botso-Organization and use org-manage routes to invite members and assign tickets.

Shop products (desk & club catalogs)

Ticket products have a channel: desk (solo capital seats) or club (syndicate funding products). Availability is free inventory seats (ticketing_tickets.tck_avail = 0).

When a club pool reaches its funding target, one club-product seat is sold idempotently (payment_method: club_pool). Creating a syndicate or pool that references a sold-out product returns 422.

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",
  "product_id": 4,
  "ticket_cap": 4,
  "profit_target": 500,
  "start_date": "2026-07-01",
  "end_date": "2026-12-31",
  "description": "Optional pool description"
}

Funding target and share price are derived from the product price ÷ ticket cap. Sold-out products return 422.

{
  "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."]
  }
}