API Documentation

Overview

The Cubemobi API provides programmatic access to our mobile advertising platform, enabling you to create and manage campaigns, upload creatives, retrieve performance data, and integrate with your existing marketing technology stack.

Our REST API uses standard HTTP methods and returns JSON responses. All API requests must be made over HTTPS.

Base URL

https://api.cubemobi.com/v2

API Versioning

The current API version is v2. We recommend always specifying the version in your requests. Previous versions will be supported for at least 12 months after a new version is released.

Authentication

All API requests require authentication using an API key. You can obtain your API key from the Cubemobi dashboard under Settings > API Access.

API Key Authentication

Include your API key in the Authorization header of every request:

# Example request with authentication
curl -X GET "https://api.cubemobi.com/v2/campaigns" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
                    

Security Best Practices

Never expose your API key in client-side code or public repositories
Rotate your API keys periodically
Use environment variables to store API keys
Set up IP whitelisting for additional security

Rate Limits

To ensure fair usage and platform stability, we enforce rate limits on API requests:

Endpoint Type	Rate Limit	Window
Standard endpoints	1,000 requests	per minute
Reporting endpoints	100 requests	per minute
Bulk operations	10 requests	per minute

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
                    

Error Handling

The API uses standard HTTP response codes to indicate success or failure:

200 OK

Request succeeded

201 Created

Resource created successfully

400 Bad Request

Invalid request parameters

401 Unauthorized

Invalid or missing API key

403 Forbidden

Insufficient permissions

429 Too Many Requests

Rate limit exceeded

500 Server Error

Internal server error

Error Response Format

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The 'budget' field must be a positive number",
    "field": "budget",
    "request_id": "req_abc123xyz"
  }
}
                    

Create Campaign

Create a new advertising campaign with targeting options and budget settings.

POST /campaigns

Request Parameters

Parameter	Type	Description
`name` required	string	Campaign name (max 100 characters)
`daily_budget` required	number	Daily budget in USD (minimum $10)
`total_budget`	number	Total campaign budget in USD
`bid_type` required	string	Bidding type: `CPC`, `CPM`, `CPI`, `CPA`
`bid_amount` required	number	Bid amount in USD
`countries` required	array	List of ISO 3166-1 alpha-2 country codes
`platforms`	array	Target platforms: `ios`, `android`
`start_date`	string	Campaign start date (ISO 8601 format)
`end_date`	string	Campaign end date (ISO 8601 format)

Example Request

curl -X POST "https://api.cubemobi.com/v2/campaigns" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Game Launch 2024",
    "daily_budget": 500,
    "total_budget": 15000,
    "bid_type": "CPI",
    "bid_amount": 2.50,
    "countries": ["US", "CA", "GB"],
    "platforms": ["ios", "android"],
    "start_date": "2024-06-01T00:00:00Z"
  }'
                    

Example Response

{
  "id": "camp_abc123xyz",
  "name": "Summer Game Launch 2024",
  "status": "pending_review",
  "daily_budget": 500,
  "total_budget": 15000,
  "spent": 0,
  "bid_type": "CPI",
  "bid_amount": 2.50,
  "countries": ["US", "CA", "GB"],
  "platforms": ["ios", "android"],
  "start_date": "2024-06-01T00:00:00Z",
  "created_at": "2024-05-15T10:30:00Z"
}
                    

List Campaigns

Retrieve a paginated list of all campaigns in your account.

GET /campaigns

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status: `active`, `paused`, `pending`, `completed`
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (default: 20, max: 100)
`sort`	string	Sort field: `created_at`, `name`, `spent`

Example Response

{
  "data": [
    {
      "id": "camp_abc123",
      "name": "Summer Campaign",
      "status": "active",
      "daily_budget": 500,
      "spent": 1250.50,
      "impressions": 125000,
      "clicks": 3750,
      "installs": 500
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 45,
    "total_pages": 3
  }
}
                    

Update Campaign

Update an existing campaign's settings, targeting, or budget.

PUT /campaigns/{campaign_id}

Example Request

curl -X PUT "https://api.cubemobi.com/v2/campaigns/camp_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "daily_budget": 750,
    "bid_amount": 2.75,
    "status": "active"
  }'
                    

Campaign Statistics

Retrieve detailed performance statistics for a specific campaign.

GET /campaigns/{campaign_id}/stats

Query Parameters

Parameter	Type	Description
`start_date` required	string	Start date (YYYY-MM-DD)
`end_date` required	string	End date (YYYY-MM-DD)
`granularity`	string	Data granularity: `hourly`, `daily`, `weekly`
`group_by`	string	Group results by: `country`, `platform`, `creative`

Example Response

{
  "campaign_id": "camp_abc123",
  "period": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  },
  "summary": {
    "impressions": 2500000,
    "clicks": 75000,
    "installs": 5000,
    "spend": 12500.00,
    "ctr": 3.0,
    "cvr": 6.67,
    "cpi": 2.50
  },
  "daily_data": [
    {
      "date": "2024-01-01",
      "impressions": 85000,
      "clicks": 2550,
      "installs": 170,
      "spend": 425.00
    }
  ]
}
                    

Upload Creative

Upload a new creative asset (image, video, or playable ad) to use in your campaigns.

POST /creatives

Request (multipart/form-data)

Parameter	Type	Description
`file` required	file	The creative file to upload
`name` required	string	Creative name
`type` required	string	`banner`, `interstitial`, `video`, `playable`
`click_url` required	string	Destination URL when creative is clicked

Creative Specifications

Supported creative formats and specifications:

Banner Ads

Size	Format	Max File Size
320x50	PNG, JPG, GIF	150 KB
300x250	PNG, JPG, GIF	200 KB
728x90	PNG, JPG, GIF	200 KB
320x480	PNG, JPG, GIF	300 KB

Video Ads

Aspect Ratio	Format	Duration	Max File Size
16:9 or 9:16	MP4, MOV	15-60 seconds	50 MB

Generate Reports

Generate detailed performance reports with customizable dimensions and metrics.

POST /reports

Example Request

{
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "dimensions": ["date", "campaign", "country"],
  "metrics": ["impressions", "clicks", "installs", "spend", "cpi"],
  "filters": {
    "campaign_ids": ["camp_abc123"],
    "countries": ["US", "CA"]
  },
  "format": "csv"
}
                    

Real-time Data

Access real-time campaign performance data with minimal latency.

GET /campaigns/{campaign_id}/realtime

Real-time data is updated every 5 minutes and includes:

Current hour impressions, clicks, and installs
Spend pacing vs. daily budget
Top performing creatives and countries
Delivery status and any issues

Postback Setup

Configure server-to-server postbacks to receive real-time conversion notifications.

POST /postbacks

Postback URL Macros

Macro	Description
`{click_id}`	Unique click identifier
`{campaign_id}`	Campaign ID
`{creative_id}`	Creative ID
`{country}`	User country code
`{platform}`	Device platform (ios/android)
`{device_id}`	IDFA or GAID
`{payout}`	Payout amount
`{event_name}`	Event name

Event Types

Supported postback event types:

Event	Description
`install`	App installation completed
`registration`	User completed registration
`purchase`	In-app purchase made
`level_achieved`	User reached specific level
`tutorial_complete`	Tutorial completed
`custom`	Custom event (specify event_name)