Introduction

Welcome to the Marpany API documentation. Our API allows you to programmatically manage your advertising campaigns, analyze performance data, and integrate with your existing systems.

The Marpany API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL: https://api.marpany.com/v1

Authentication

The Marpany API uses API keys to authenticate requests. You can view and manage your API keys in the Developer Portal. Developer Portal.

API Key Authentication

Include your API key in the request headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Security Warning: Keep your API keys secure. Do not share them in publicly accessible areas.

Rate Limiting

API requests are limited by tier. The rate limits are as follows:

Tier Requests per Minute Daily Limit
free 60 1,000
basic 300 10,000
professional 1,000 100,000
enterprise Unlimited Unlimited

Rate Limit Headers

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

Error Handling

Marpany uses conventional HTTP response codes to indicate the success or failure of an API request.

Code Meaning
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid API key
403 Forbidden - Insufficient permissions
404 Not Found - Resource doesn't exist
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error

Error Response Example

{
  "error": {
    "code": "invalid_request",
    "message": "The campaign_id field is required.",
    "param": "campaign_id"
  }
}

Campaigns

List All Campaigns

GET /campaigns

Retrieves a list of all your advertising campaigns.

Parameters

Parameter Type Description
limit integer Number of campaigns to return (default: 50, max: 100)
offset integer Number of campaigns to skip (default: 0)
status string Filter by status: active, paused, ended

Response Example

{
  "data": [
    {
      "id": "camp_123abc",
      "name": "Summer Sale 2025",
      "status": "active",
      "budget": 5000.00,
      "spent": 3250.50,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 145,
    "limit": 50,
    "offset": 0
  }
}

Create Campaign

POST /campaigns

Creates a new advertising campaign.

Request Body

{
  "name": "My Campaign",
  "budget": 1000.00,
  "platform": "meta",
  "objective": "conversions",
  "start_date": "2025-01-20",
  "end_date": "2025-02-20"
}

Products

Sync Products

POST /products/sync

Synchronizes your product catalog with the advertising platforms.

Request Body

{
  "platform": "meta",
  "catalog_id": "catalog_123"
}

Analytics

Get Campaign Analytics

GET /analytics/campaigns/{campaign_id}

Retrieves detailed analytics for a specific campaign.

Parameters

Parameter Type Description
start_date date Start date (YYYY-MM-DD)
end_date date End date (YYYY-MM-DD)
metrics array Metrics to include: impressions, clicks, conversions

Webhooks

Webhooks allow you to receive real-time notifications about events in your account.

Configure Webhooks

POST /webhooks

Request Body

{
  "url": "https://your-domain.com/webhook",
  "events": ["campaign.created", "campaign.ended"],
  "secret": "your_webhook_secret"
}

Code Examples

PHP

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.marpany.com/v1/campaigns');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$campaigns = json_decode($response, true);
curl_close($ch);

JavaScript (Node.js)

const axios = require('axios');

const response = await axios.get('https://api.marpany.com/v1/campaigns', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

console.log(response.data);

Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.get('https://api.marpany.com/v1/campaigns', headers=headers)
campaigns = response.json()
print(campaigns)

Support

If you need help with the API or have questions: