Getting Started

WhaleTools is a commerce platform with AI-powered operations. It provides a unified API for managing every aspect of your retail business — from product catalog and inventory to orders, customers, and analytics — with built-in AI agents that can automate tasks and assist your team.

The API follows RESTful conventions with JSON request and response bodies. All list endpoints support cursor-based pagination. Real-time updates are available through webhooks and server-sent events (SSE) for AI agent conversations.

Sign up at whaletools.dev/auth/signup with your email or OAuth provider. Once registered, you will be prompted to create your first store.

Create a store

Each store is an isolated environment with its own products, orders, customers, and API keys. You can create multiple stores for different brands or environments (e.g., production and staging).

Get your API credentials

Navigate to Dashboard → API Keys to generate your first key. You will need two values for API access:

• •Store ID — your store's UUID, visible in the dashboard URL and settings page.
• •API Key — follows the format wk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx for production or wk_test_... for sandbox.

The official TypeScript SDK provides typed methods for every API endpoint. Install it via npm:

npm install @neowhale/api-client

Initialize the client with your credentials:

import { WhaleClient } from '@neowhale/api-client'

const whale = new WhaleClient({
  storeId: process.env.WHALE_STORE_ID,
  apiKey: process.env.WHALE_API_KEY,
})

Using REST directly

If you prefer raw HTTP calls, all endpoints are accessible via standard REST. The base URL for all requests is:

https://vm.whaletools.cloud/v1/stores/{storeId}

Example using fetch:

const response = await fetch(
  'https://vm.whaletools.cloud/v1/stores/{storeId}/products',
  {
    headers: {
      'x-api-key': process.env.WHALE_API_KEY,
      'Content-Type': 'application/json',
    },
  }
)

const { data } = await response.json()

Or using curl:

curl https://vm.whaletools.cloud/v1/stores/{storeId}/products \
  -H "x-api-key: wk_live_your_key_here"

Every API request must include your API key in the x-api-key header. Keys are scoped to control which resources they can access.

Request headers

GET /v1/stores/{storeId}/products HTTP/1.1
Host: vm.whaletools.cloud
x-api-key: wk_live_your_key_here
Content-Type: application/json

API key scopes

When creating an API key, you select which scopes to grant. Each scope follows the resource:action pattern. A key without a required scope receives a 403 Forbidden response.

For full authentication details including key rotation and security best practices, see the Authentication guide.

List products

Retrieve all products in your store:

curl https://vm.whaletools.cloud/v1/stores/{storeId}/products \
  -H "x-api-key: wk_live_your_key_here"

Response:

{
  "object": "list",
  "data": [
    {
      "object": "product",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Blue Dream Pre-Roll",
      "sku": "BD-PR-001",
      "status": "active",
      "stock_quantity": 142,
      "stock_status": "in_stock",
      "created_at": "2026-01-15T08:30:00Z"
    }
  ],
  "has_more": false,
  "url": "/v1/stores/{storeId}/products"
}

Create a product

Add a new product to your catalog with a POST request:

curl -X POST https://vm.whaletools.cloud/v1/stores/{storeId}/products \
  -H "x-api-key: wk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sunset Sherbet 3.5g",
    "sku": "SS-35",
    "type": "simple",
    "status": "draft",
    "pricing_data": { "retail": 45.00 }
  }'

Response (201 Created):

{
  "object": "product",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Sunset Sherbet 3.5g",
  "sku": "SS-35",
  "status": "draft",
  "type": "simple"
}

List orders

Retrieve recent orders with optional filters:

curl "https://vm.whaletools.cloud/v1/stores/{storeId}/orders?status=pending&limit=10" \
  -H "x-api-key: wk_live_your_key_here"

Response:

{
  "object": "list",
  "data": [
    {
      "object": "order",
      "id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
      "order_number": "ORD-1042",
      "status": "pending",
      "total": 135.00,
      "customer_id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
      "created_at": "2026-03-09T14:22:00Z"
    }
  ],
  "has_more": true,
  "url": "/v1/stores/{storeId}/orders"
}

Using the SDK

The same operations using the TypeScript SDK:

// List products
const products = await whale.products.list()

// Create a product
const product = await whale.products.create({
  name: 'Sunset Sherbet 3.5g',
  sku: 'SS-35',
  type: 'simple',
  status: 'draft',
  pricing_data: { retail: 45.00 },
})

// List orders with filters
const orders = await whale.orders.list({
  status: 'pending',
  limit: 10,
})

WhaleTools AI agents are configurable assistants with full access to your store data. They can answer questions about products and orders, perform actions like updating inventory, and integrate with your workflows.

Create an agent

Create an AI agent with a system prompt and tool configuration:

curl -X POST https://vm.whaletools.cloud/v1/stores/{storeId}/agents \
  -H "x-api-key: wk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Store Assistant",
    "model": "claude-sonnet-4-20250514",
    "system_prompt": "You are a helpful store assistant. Help customers find products, check order status, and answer questions about our catalog.",
    "tools": ["products", "orders", "customers", "inventory"],
    "channels": ["webchat", "api"],
    "is_default": true
  }'

Response:

{
  "object": "agent",
  "id": "72d7aaa8-2e8b-48a0-a38d-f332f69600bb",
  "name": "Store Assistant",
  "model": "claude-sonnet-4-20250514",
  "status": "active",
  "is_default": true,
  "channels": ["webchat", "api"]
}

Send a chat message (SSE streaming)

Agent responses are streamed via server-sent events (SSE). Send a message and receive the response in real time:

curl -N -X POST https://vm.whaletools.cloud/v1/stores/{storeId}/agents/{agentId}/chat \
  -H "x-api-key: wk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are our top-selling products this week?"
  }'

The response streams as SSE events:

data: {"type":"text","text":"Based on this week's"}
data: {"type":"text","text":" sales data, your top"}
data: {"type":"text","text":"-selling products are:\n\n"}
data: {"type":"tool_use","tool":"products","input":{"sort":"sales_desc","limit":5}}
data: {"type":"text","text":"1. Blue Dream Pre-Roll (142 units)\n2. ..."}
data: {"type":"end"}

Handling SSE in JavaScript:

const response = await fetch(
  `https://vm.whaletools.cloud/v1/stores/${storeId}/agents/${agentId}/chat`,
  {
    method: 'POST',
    headers: {
      'x-api-key': apiKey,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ message: 'What are our top sellers?' }),
  }
)

const reader = response.body.getReader()
const decoder = new TextDecoder()

while (true) {
  const { done, value } = await reader.read()
  if (done) break

  const chunk = decoder.decode(value)
  const lines = chunk.split('\n').filter(l => l.startsWith('data: '))

  for (const line of lines) {
    const event = JSON.parse(line.slice(6))
    if (event.type === 'text') {
      process.stdout.write(event.text)
    }
  }
}

Agent tools

Agents can use tools to read and write store data. Available tool categories:

Webhooks notify your server in real time when events occur in your store. Register an endpoint, subscribe to events, and WhaleTools will POST a signed JSON payload whenever something happens.

Register an endpoint

curl -X POST https://vm.whaletools.cloud/v1/stores/{storeId}/webhooks \
  -H "x-api-key: wk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/whale",
    "events": ["order.created", "order.paid", "inventory.adjusted"],
    "secret": "whsec_your_signing_secret"
  }'

Webhook payload

Each webhook delivery includes a JSON body with the event type, timestamp, and resource data:

{
  "id": "evt_a1b2c3d4e5f6",
  "object": "event",
  "type": "order.created",
  "created_at": "2026-03-10T12:00:00Z",
  "data": {
    "object": "order",
    "id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
    "order_number": "ORD-1043",
    "status": "pending",
    "total": 89.50
  }
}

Verify signatures

Every webhook request includes a x-whale-signature header containing an HMAC-SHA256 signature. Always verify this before processing the payload.

import crypto from 'crypto'

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

// In your webhook handler
app.post('/webhooks/whale', (req, res) => {
  const signature = req.headers['x-whale-signature']
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WHALE_WEBHOOK_SECRET
  )

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' })
  }

  const { type, data } = req.body

  switch (type) {
    case 'order.created':
      console.log('New order:', data.order_number)
      break
    case 'inventory.adjusted':
      console.log('Stock changed:', data.product_id)
      break
  }

  res.status(200).json({ received: true })
})

Available events

See the full event catalog in the Webhook Events reference.

The whale-code CLI gives you full terminal access to WhaleTools. Manage stores, chat with AI agents, and run a local MCP server for Claude Desktop or Cursor integration.

Install

npm install -g whale-code

Login and connect

Authenticate with your WhaleTools account. This opens a browser for OAuth login and stores the session locally.

# Authenticate
whale login

# Check status
whale status

# List your stores
whale stores

Output:

$ whale status
  Authenticated as: you@example.com
  Active store:     My Store (cd2e1122-...)
  Node status:      connected
  Uptime:           4h 23m

Chat with agents

Start an interactive terminal session with any AI agent in your store:

whale agent chat

MCP server for Claude and Cursor

Run a local MCP (Model Context Protocol) server so that Claude Desktop, Cursor, or any MCP-compatible client can access your WhaleTools store data directly.

# Start the MCP server
whale mcp

Add the following to your Claude Desktop or Cursor MCP configuration:

{
  "mcpServers": {
    "whale-code": {
      "command": "whale",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Once connected, your AI coding assistant can query products, check orders, manage inventory, and more — all through natural language. See the full MCP integration guide and CLI reference for details.

You now have the fundamentals. Explore the guides below to go deeper into each area of the platform.