Developer API

Build with the
AdVessel API

Integrate advertising operations directly into your applications. Automate orders, manage creatives, and access analytics programmatically.

Quick Start

Get up and running in minutes with our simple API.

1

Create an API Key

Navigate to Settings → API Keys in your dashboard and create a new key with the scopes you need.

2

Add the Header

Include your API key in the X-API-Key header of every request.

3

Make Requests

Start making API calls to list publications, create orders, upload creatives, and more.

Authentication Methods

Choose the authentication method that best fits your use case.

API Keys

Best for server-to-server integrations and automated workflows.

  • Long-lived tokens (configurable expiration)
  • Fine-grained scope control
  • Usage tracking and rate limiting
  • Easy rotation and revocation
Header: X-API-Key: mbos_live_...

JWT (Bearer Token)

Best for user-facing applications and short-lived sessions.

  • User-specific authentication
  • Access to all user's organizations
  • Refresh token support
  • Google OAuth integration
Header: Authorization: Bearer eyJ...

Code Examples

Get started quickly with these examples in your favorite language.

cURL
curl -X GET "https://api.mbos.com/api/v1/publications/" \
  -H "X-API-Key: mbos_live_abc12345_your_secret_key_here" \
  -H "Content-Type: application/json"
Python
import requests

API_KEY = "mbos_live_abc12345_your_secret_key_here"
BASE_URL = "https://api.mbos.com/api/v1"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# List publications
response = requests.get(f"{BASE_URL}/publications/", headers=headers)
publications = response.json()

# Create an order
order_data = {
    "publication_id": "pub_123",
    "ad_unit_id": "unit_456",
    "issue_date": "2024-03-15"
}
response = requests.post(f"{BASE_URL}/orders/", json=order_data, headers=headers)
JavaScript / TypeScript
const API_KEY = 'mbos_live_abc12345_your_secret_key_here';
const BASE_URL = 'https://api.mbos.com/api/v1';

async function fetchPublications() {
  const response = await fetch(`${BASE_URL}/publications/`, {
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    }
  });
  return response.json();
}

async function createOrder(orderData) {
  const response = await fetch(`${BASE_URL}/orders/`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(orderData)
  });
  return response.json();
}

Available Scopes

Control exactly what each API key can access with fine-grained scopes.

Read Scopes

ScopeDescription
organizations:readRead organization details and settings
publications:readRead publication information and rate cards
ratecards:readRead rate card pricing and availability
orders:readRead order details and history
creatives:readRead creative files and metadata
payments:readRead payment and invoice information
analytics:readRead analytics and reporting data

Write Scopes

ScopeDescription
orders:writeCreate and modify orders
creatives:writeUpload and modify creatives
payments:writeProcess payments and refunds

Admin Scopes

ScopeDescription
admin:teamManage team members and invitations
admin:settingsModify organization settings
admin:integrationsManage integrations and webhooks

Rate Limits

Rate limits vary by plan. Upgrade for higher limits.

PlanRequests / MinuteRequests / Hour
Free10100
Starter601,000
Professional3005,000
Enterprise1,00020,000

Rate Limit Headers

All API responses include rate limit headers to help you track usage:

  • X-RateLimit-Limit-Minute - Max requests per minute
  • X-RateLimit-Remaining-Minute - Remaining requests this minute
  • X-RateLimit-Limit-Hour - Max requests per hour
  • X-RateLimit-Remaining-Hour - Remaining requests this hour

API Reference

Explore the complete API documentation with interactive examples.

Sample Endpoints
MethodEndpointDescriptionScopes
GET/organizations/List organizations
organizations:read
GET/publications/List publications
publications:read
GET/ratecards/Get rate card pricing
ratecards:read
POST/orders/Create an order
orders:write
GET/orders/List orders
orders:read
POST/creatives/Upload creative files
creatives:write

Ready to Start Building?

Create your account and generate your first API key in minutes.