API Documentation
Complete reference for the Appizer REST API
Contents
Base URL
https://api.appizer.com/v1
AI-Powered Events & Push Notifications Quickstart
A step-by-step guide to integrate WonderPush with Appizer for automated, AI-generated push notifications.
Quick Steps:
- Integrate WonderPush with your app or website
- Configure Appizer with your WonderPush credentials
- Send user events to Appizer
- Configure AI-generated push notifications
Appizer uses OpenAI's gpt-3.5-turbo model to generate engaging push notifications under 150 characters, optimized for user engagement.
Authentication
All API requests require authentication using your API key in the Authorization header.
Authorization: Bearer YOUR_API_KEY
Keep your API keys secure and never expose them in client-side code. Use environment variables or secure configuration management.
Events
Track Event
Record a custom event for analytics and audience segmentation.
Request
POST /events
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
{
"event_name": "purchase_completed",
"user_id": "user_123",
"properties": {
"amount": 29.99,
"currency": "USD",
"product_id": "premium_plan"
},
"ip": "192.168.1.1",
"ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
}
Parameters
- event_name (string, required): Name of the event to track
- user_id (string, required): Your unique identifier for the user
- properties (object, optional): Additional event attributes as key-value pairs
- ip (string, optional): User's IP address for analytics tracking
- ua (string, optional): User agent string for device/browser tracking
Parameters
- events (array, required): Array of event objects to track
- event_name (string, required): Name of the event to track
- user_id (string, required): Your unique identifier for the user
- properties (object, optional): Additional event attributes as key-value pairs
- ip (string, optional): User's IP address for analytics tracking
- ua (string, optional): User agent string for device/browser tracking
Response
{
"success": true,
"event_id": "evt_789",
"message": "Event tracked successfully"
}
Batch Track Events
Track multiple events in a single request for better performance.
Request
POST /events/batch
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
{
"events": [
{
"event_name": "page_view",
"user_id": "user_123",
"properties": {
"page": "/dashboard"
},
"ip": "192.168.1.1",
"ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
},
{
"event_name": "button_click",
"user_id": "user_123",
"properties": {
"button_id": "cta_button"
}
}
]
}
Response
{
"success": true,
"processed_count": 2,
"message": "Batch events tracked successfully"
}
User Management
Create or Update User
Create or update user profile information. If a user with the same user_id exists, their information will be updated.
Request
POST /users
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
{
"user_id": "user_123",
"email": "user@example.com",
"phone": "+1234567890",
"properties": {
"name": "John Doe",
"plan": "premium",
"signup_date": "2023-06-15"
}
}
Parameters
- user_id (string, required): Your unique identifier for the user
- email (string, optional): User's email address
- phone (string, optional): User's phone number with country code (e.g., +1234567890)
- properties (object, optional): Additional user attributes as key-value pairs
Response
{
"success": true,
"user_id": "usr_789",
"external_id": "user_123",
"message": "User created/updated successfully"
}
Create User Alias
Add an alternative identifier that references an existing user. After creating an alias, you can pass either ID in future API calls.
Request
POST /users/aliases
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
{
"user_id": "user_123",
"alias_id": "legacy_999"
}
Parameters
- user_id (string, required): ID of the existing user (you may instead supply
primary_user_idUUID). - alias_id (string, required): New alias to associate.
Response
{
"success": true,
"alias_id": "legacy_999",
"user_id": "user_123",
"message": "Alias created"
}
Replace User ID
Update an existing user_id to a new identifier.
Request
POST /users/replace-id
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
{
"user_id": "user_123",
"new_user_id": "user_456"
}
Parameters
- user_id (string, required): Current user identifier.
- new_user_id (string, required): Desired new identifier.
Response
{
"success": true,
"user_id": "user_456",
"message": "User ID updated"
}
Analytics
Query Analytics
Run analytics queries using natural language or SQL.
Get Metrics
Retrieve pre-calculated metrics and KPIs.
Audiences
Create Audience
Create a smart audience segment using natural language.
List Audiences
Get all audiences for an app.
Push Notifications
Send Push
Send a push notification to users or audiences.
Get Campaign Status
Check the status and performance of a push campaign.
Model Context Protocol (MCP) Server
The Model Context Protocol (MCP) is a standard that connects AI systems with Appizer's data and functionality. MCP allows external AI models to access your organization's data in a secure and controlled manner.
Overview
MCP provides a standardized way for AI systems to:
- Access app data, events, and user information
- Query audience segments
- Retrieve analytics and insights
- Perform operations based on contextual understanding
Authentication
MCP uses a dedicated API key for authentication. This key is separate from your regular Appizer API keys and can be managed in your organization settings.
X-MCP-API-Key: YOUR_MCP_API_KEY
MCP API keys have broad access to your organization's data. Keep them secure and rotate them regularly.
Base URL
https://api.appizer.com/mcp
Available Endpoints
/mcp
Server Information
Returns information about the MCP server implementation.
Response
{
"name": "Appizer MCP Server",
"version": "1.0",
"status": "active",
"timestamp": "2025-07-19T22:37:38-05:00"
}
/mcp/auth
Validate Authentication
Validates the MCP API key and returns organization information.
Response
{
"authenticated": true,
"organization": {
"id": "org_123",
"name": "Acme Corp",
"description": "Enterprise solutions",
"timezone": "America/New_York"
},
"permissions": ["read", "write"],
"protocol_version": "1.0"
}
/mcp/resources
List Available Resources
Returns a list of resources available through the MCP server.
Response
{
"resources": {
"apps": [
{
"id": "app_123",
"name": "Mobile App",
"description": "iOS and Android app",
"type": "app",
"uri": "/mcp/resources/apps/app_123"
}
],
"audiences": [
{
"id": "aud_456",
"name": "Active Users",
"description": "Users active in the last 30 days",
"type": "audience",
"app_id": "app_123",
"uri": "/mcp/resources/audiences/aud_456"
}
]
}
}
/mcp/resources/apps/:appId
Get App Details
Returns detailed information about a specific app.
Response
{
"id": "app_123",
"name": "Mobile App",
"description": "iOS and Android app",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-07-01T14:22:10Z",
"stats": {
"users": 15420,
"events": 982345,
"last_activity": "2025-07-19T21:15:33Z"
},
"top_events": [
{ "name": "app_open", "count": 45678 },
{ "name": "purchase", "count": 2341 }
]
}
/mcp/events
Query Events
Allows querying events with various filters.
Parameters
app_id- Filter by app IDevent_name- Filter by event nameuser_id- Filter by user IDlimit- Maximum number of results (default: 100, max: 1000)offset- Pagination offset (default: 0)
Response
{
"events": [
{
"id": "evt_789",
"app_id": "app_123",
"user_id": "user_456",
"event_name": "purchase",
"properties": { "amount": 49.99, "item": "Premium Plan" },
"created_at": "2025-07-19T20:15:33Z"
}
],
"pagination": {
"total": 982345,
"limit": 100,
"offset": 0,
"has_more": true
}
}
MCP Use Cases & Implementation Guides
The Model Context Protocol can be utilized in various scenarios. Here are detailed guides for common use cases:
Agentic Coding Assistant
Implement an AI coding assistant that can access your app's event data to suggest code improvements or debug issues.
Setup Steps:
- Enable MCP in your organization settings
- Generate a dedicated MCP API key for your coding assistant
- Implement the following integration code in your development environment
Example Implementation:
# Python example for VSCode extension or Jupyter notebook
import os
from openai import OpenAI
import requests
class AppizerDevAgent:
def __init__(self, mcp_api_key, openai_api_key):
self.mcp_api_key = mcp_api_key
self.mcp_base_url = "https://api.appizer.com/mcp"
self.mcp_headers = {"X-MCP-API-Key": mcp_api_key}
self.client = OpenAI(api_key=openai_api_key)
def get_event_data(self, app_id, event_name=None, limit=10):
"""Fetch recent events from the app"""
params = {"app_id": app_id, "limit": limit}
if event_name:
params["event_name"] = event_name
response = requests.get(
f"{self.mcp_base_url}/events",
headers=self.mcp_headers,
params=params
)
return response.json()
def analyze_code_with_context(self, code_snippet, issue_description):
"""Analyze code with context from app events"""
# Get event data for context
events_data = self.get_event_data(app_id="YOUR_APP_ID")
# Create prompt with code and event context
prompt = f"""
Analyze this code snippet:
```
{code_snippet}
```
Issue description: {issue_description}
Recent app events for context:
{events_data}
Please provide suggestions to fix the issue based on the code and event data.
"""
# Get AI analysis
response = self.client.chat.completions.create(
model="gpt-4",
messages=[
{"role": "system", "content": "You are a coding assistant with access to app event data."},
{"role": "user", "content": prompt}
]
)
return {
"visualizations": [],
"insights": response.choices[0].message.content
}
# Usage
agent = AppizerDevAgent(
mcp_api_key="YOUR_MCP_API_KEY",
openai_api_key="YOUR_OPENAI_API_KEY"
)
# Example analysis
code = """
function processUserPurchase(userId, itemId) {
// Implementation with potential issues
const user = getUser(userId);
const item = getItem(itemId);
if (user.credits >= item.price) {
user.credits -= item.price;
user.items.push(item);
trackEvent('purchase', { userId, itemId });
}
}
"""
analysis = agent.analyze_code_with_context(
code,
"Users report purchases sometimes fail even with sufficient credits"
)
print(analysis["insights"])
Key Benefits:
- AI coding assistance with real-time app data context
- Debug issues with actual event data from your application
- Generate code suggestions based on user behavior patterns
- Automate repetitive development tasks with app-aware AI
Customer Support AI
Build a support chatbot that can access user data and event history to provide personalized assistance.
Example Implementation:
// Node.js example for a customer support chatbot
const axios = require('axios');
const { OpenAI } = require('openai');
class AppizerSupportBot {
constructor(mcpApiKey, openaiApiKey) {
this.mcpApiKey = mcpApiKey;
this.mcpBaseUrl = 'https://api.appizer.com/mcp';
this.openai = new OpenAI({ apiKey: openaiApiKey });
}
async getUserData(userId) {
try {
const response = await axios.get(`${this.mcpBaseUrl}/users/${userId}`, {
headers: { 'X-MCP-API-Key': this.mcpApiKey }
});
return response.data;
} catch (error) {
console.error('Error fetching user data:', error);
return null;
}
}
async getUserEvents(userId, limit = 10) {
try {
const response = await axios.get(`${this.mcpBaseUrl}/events`, {
headers: { 'X-MCP-API-Key': this.mcpApiKey },
params: { user_id: userId, limit }
});
return response.data.events;
} catch (error) {
console.error('Error fetching user events:', error);
return [];
}
}
async handleSupportQuery(userId, query) {
// Get user context
const userData = await this.getUserData(userId);
const userEvents = await this.getUserEvents(userId);
// Create context-aware prompt
const systemPrompt = `You are a helpful customer support assistant for our app.
You have access to the following user data: ${JSON.stringify(userData)}
Recent user activity: ${JSON.stringify(userEvents)}
Based on this context, provide a helpful, personalized response.`;
// Generate AI response
const completion = await this.openai.chat.completions.create({
model: "gpt-4",
messages: [
{ role: "system", content: systemPrompt },
{ role: "user", content: query }
]
});
return completion.choices[0].message.content;
}
}
// Usage example
const supportBot = new AppizerSupportBot(
'YOUR_MCP_API_KEY',
'YOUR_OPENAI_API_KEY'
);
async function handleCustomerQuery(userId, query) {
const response = await supportBot.handleSupportQuery(userId, query);
console.log(`Response for user ${userId}: ${response}`);
return response;
}
// Example usage
handleCustomerQuery('user_123', 'Why was I charged twice for my subscription?');
AI-Powered Analytics
Generate insights and visualizations from your app data using AI.
Example Implementation:
# Python example for data analysis with pandas and matplotlib
import os
import requests
import pandas as pd
import matplotlib.pyplot as plt
from openai import OpenAI
class AppizerAnalytics:
def __init__(self, mcp_api_key, openai_api_key):
self.mcp_api_key = mcp_api_key
self.mcp_base_url = "https://api.appizer.com/mcp"
self.mcp_headers = {"X-MCP-API-Key": mcp_api_key}
self.client = OpenAI(api_key=openai_api_key)
def get_event_data(self, app_id, event_name=None, days=30, limit=1000):
"""Fetch event data for analysis"""
params = {"app_id": app_id, "limit": limit}
if event_name:
params["event_name"] = event_name
response = requests.get(
f"{self.mcp_base_url}/events",
headers=self.mcp_headers,
params=params
)
return response.json()["events"]
def analyze_events(self, app_id, event_name):
"""Analyze specific event patterns"""
# Get event data
events = self.get_event_data(app_id, event_name)
# Convert to DataFrame for analysis
df = pd.DataFrame(events)
# Extract timestamps and convert to datetime
df['created_at'] = pd.to_datetime(df['created_at'])
df['date'] = df['created_at'].dt.date
# Group by date and count events
daily_counts = df.groupby('date').size().reset_index(name='count')
# Create visualization
plt.figure(figsize=(10, 6))
plt.plot(daily_counts['date'], daily_counts['count'])
plt.title(f'{event_name} Events Over Time')
plt.xlabel('Date')
plt.ylabel('Event Count')
plt.xticks(rotation=45)
plt.tight_layout()
# Save visualization
viz_path = f"{event_name}_trend.png"
plt.savefig(viz_path)
# Generate AI insights
prompt = f"""
Analyze this event data for {event_name} events:
{daily_counts.to_string()}
Provide 3-5 key insights about user behavior patterns, anomalies,
and recommendations based on this data.
"""
response = self.client.chat.completions.create(
model="gpt-4",
messages=[
{"role": "system", "content": "You are a data analyst providing insights on app usage patterns."},
{"role": "user", "content": prompt}
]
)
return {
"visualization_path": viz_path,
"insights": response.choices[0].message.content,
"raw_data": daily_counts.to_dict()
}
# Usage
analytics = AppizerAnalytics(
mcp_api_key="YOUR_MCP_API_KEY",
openai_api_key="YOUR_OPENAI_API_KEY"
)
# Example analysis
results = analytics.analyze_events("app_123", "purchase")
print(results["insights"])
Environment Setup Best Practices
Follow these best practices when setting up MCP in your environment:
Environment Configuration
API Key Management:
- Create dedicated API keys for each integration
- Store keys in environment variables, never hardcode them
- Implement a key rotation schedule (e.g., quarterly)
- Set up access logging for all MCP API calls
Example .env File:
# Development environment
APPIZER_MCP_API_KEY=your_dev_mcp_key_here
APPIZER_MCP_BASE_URL=https://api.appizer.com/mcp
APPIZER_ORG_ID=your_org_id_here
# For production, use a different key with appropriate permissions
# APPIZER_MCP_API_KEY_PROD=your_prod_mcp_key_here
# For AI integrations
OPENAI_API_KEY=your_openai_key_here
Monitoring MCP Usage:
// Node.js example for logging MCP API access
const winston = require('winston');
const axios = require('axios');
// Configure logger
const logger = winston.createLogger({
level: 'info',
format: winston.format.combine(
winston.format.timestamp(),
winston.format.json()
),
defaultMeta: { service: 'mcp-client' },
transports: [
new winston.transports.File({ filename: 'mcp-access.log' })
]
});
// Create axios instance with interceptors
const mcpClient = axios.create({
baseURL: process.env.APPIZER_MCP_BASE_URL,
headers: { 'X-MCP-API-Key': process.env.APPIZER_MCP_API_KEY }
});
// Log all requests
mcpClient.interceptors.request.use(request => {
logger.info('MCP API Request', {
method: request.method,
url: request.url,
params: request.params
});
return request;
});
// Log all responses
mcpClient.interceptors.response.use(
response => {
logger.info('MCP API Response', {
status: response.status,
data: response.data ? 'Data received' : 'No data'
});
return response;
},
error => {
logger.error('MCP API Error', {
status: error.response?.status,
message: error.message
});
return Promise.reject(error);
}
);
// Example usage
async function fetchApps() {
try {
const response = await mcpClient.get('/resources');
return response.data;
} catch (error) {
console.error('Error fetching resources:', error);
return null;
}
}
Integration with AI Systems
MCP is designed to work with various AI systems and frameworks. Here are some common integration patterns:
LangChain Integration
Example of integrating MCP with LangChain:
# Python example with LangChain
from langchain.tools import BaseTool
from langchain.agents import initialize_agent
from langchain.chat_models import ChatOpenAI
import requests
class AppizerMCPTool(BaseTool):
name = "appizer_mcp"
description = "Access Appizer data through MCP"
def __init__(self, api_key):
self.api_key = api_key
self.base_url = "https://api.appizer.com/mcp"
self.headers = {"X-MCP-API-Key": api_key}
def _run(self, query):
# Example: Get app resources
response = requests.get(
f"{self.base_url}/resources",
headers=self.headers
)
return response.json()
# Initialize the tool and language model
mcp_tool = AppizerMCPTool(api_key="YOUR_MCP_API_KEY")
llm = ChatOpenAI(model="gpt-4")
# Use with an agent
agent = initialize_agent([mcp_tool], llm, agent="zero-shot-react-description")
result = agent.run("What apps are available in my Appizer account?")
Code Editor Integration
Enable Appizer MCP in AI-powered code editors like Cursor and Windsurf to enhance your development workflow:
Cursor Integration
// In Cursor, add this to your settings.json file
{
"mcp": {
"appizer": {
"enabled": true,
"apiKey": "YOUR_MCP_API_KEY",
"baseUrl": "https://api.appizer.com/mcp"
}
}
}
Windsurf Integration
// In Windsurf, create a .windsurf/config.js file in your project root
module.exports = {
mcp: {
providers: [
{
name: 'appizer',
enabled: true,
apiKey: process.env.APPIZER_MCP_API_KEY,
baseUrl: 'https://api.appizer.com/mcp'
}
]
}
};
Editor Features
- Access your Appizer resources directly from your editor
- Generate code based on your Appizer data models
- Debug MCP integrations with inline suggestions
- Receive contextual documentation while coding
Security Best Practices
- Rotate your MCP API keys regularly
- Monitor MCP usage for unusual patterns
- Limit MCP access to trusted AI systems
- Review the data accessible through MCP
- Disable MCP when not in use
MCP provides AI systems with access to your organization's data. Always review what data is being shared and with which systems.
Error Codes
| Code | Description |
|---|---|
| 400 | Bad Request - The request was invalid or cannot be served |
| 401 | Unauthorized - Authentication failed or user doesn't have permissions |
| 404 | Not Found - The specified resource could not be found |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Something went wrong on our end |
Rate Limits
Rate Limits
API requests are rate limited to prevent abuse and ensure service quality:
- Events API: 1,000 requests per minute
- Analytics API: 100 requests per minute
- Other APIs: 500 requests per minute
- Batch Events: 100 requests per minute (up to 100 events per batch)