DOCS · GETTING STARTED

Build on Aiva

Everything Aiva knows about a store, you can reach in code: a keyed REST API with interactive Swagger docs, a full MCP server that turns her data into tools for Claude, Cursor and any MCP client, and automation recipes for n8n, Zapier and Make. Grab an API key and merchant ID from your merchant dashboard and you’re querying real data in five minutes.

On the packages. The MCP server is published and installable as @getaiva/mcp, and the app scaffolder as @getaiva/create-app. There is no published JavaScript or Python SDK yet, so the examples below call the REST API directly, which is the supported integration path today.

REST API

AIVA Merchant API endpoints over JSON - customers, orders, subscriptions, affiliates, conversations. X-API-Key auth, interactive Swagger reference.

Read the docs →

MCP SERVER

npx -y @getaiva/mcp - ten tools that give Claude, Cursor, Windsurf and friends live access to your store data and AIVA's analysis.

Read the docs →

AUTOMATIONS

Prebuilt recipes for n8n, Zapier and Make, plus the HighLevel workflows Aiva herself runs in production.

Read the docs →

API quickstart

Send a customer message to Aiva and get her reply - with confidence score and an escalation flag, so your app knows when a human should step in:

POST /V1/CONVERSATIONS

const res = await fetch("https://api.getaiva.ai/api/aiva/message", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.AIVA_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    clientId: process.env.AIVA_MERCHANT_ID,
    message: "Where's my order?",
    channel: "WebChat",
    customerEmail: "customer@example.co.nz"
  })
});
const { message, confidence, requiresEscalation } = await res.json();

Full endpoint reference, channels (WebChat, WhatsApp, Email, SMS, Messenger, Instagram DM) and response shapes: API Documentation.

The MCP server

One config block connects your AI assistant to your store. Works with Claude Desktop, Claude Code, Cursor, Windsurf, Zed, Continue - anything that speaks MCP:

claude_desktop_config.jsonNPX · @GETAIVA/MCP

{
  "mcpServers": {
    "aiva": {
      "command": "npx",
      "args": ["-y", "@getaiva/mcp"],
      "env": {
        "AIVA_API_KEY": "YOUR_API_KEY",
        "AIVA_MERCHANT_ID": "YOUR_MERCHANT_ID",
        "AIVA_API_BASE_URL": "https://api.getaiva.ai"
      }
    }
  }
}

get_merchant_infoStore profile, plan and connection status

get_customersCustomer list with RFM segments attached

search_customersSearch customers by RFM segment

get_customerOne customer, in full detail

get_ordersOrders in a date range

get_subscriptionSubscription details

get_affiliateAffiliate details

analyze_customer_healthAI-powered customer health analysis

get_marketing_intelligenceObjective-based marketing insights

get_strategy_recommendationsBusiness strategy recommendations

Setup walkthroughs per tool: Claude Desktop · the full getting-started guide.