API v1.0

Black Umbrella API

Build powerful advertising campaigns with our AI-powered API. Create brands, manage offers, and generate creative content programmatically.

Secure by Design

API key authentication with rate limiting and comprehensive error handling

Lightning Fast

Optimized endpoints with sub-second response times for all operations

Well Documented

Comprehensive examples and best practices for every endpoint

Getting Started

Overview

The Black Umbrella API provides programmatic access to our AI-powered advertising and marketing platform. Create campaigns, manage brands and offers, and generate creative content using our powerful AI tools.

Base URL

https://api.blackumbrella.app

Authentication

All API requests require authentication using either an API key or a Bearer token.

API Key Authentication

Include your API key in the request headers:

Request Headerhttp

X-API-Key: bumb_sk_your_api_key_here

For endpoints that require user context, also include:

Additional Headerhttp

X-User-ID: your_user_id

Bearer Token Authentication

Alternatively, use a Bearer token:

Authorization Headerhttp

Authorization: Bearer your_access_token

Rate Limiting

All endpoints implement rate limiting. Rate limit information is included in response headers:

X-RateLimit-RemainingNumber of requests remaining
X-RateLimit-ResetTime when the rate limit resets (ISO 8601 format)
Retry-AfterSeconds to wait before retrying (included in 429 responses)

Error Responses

All errors follow a consistent format:

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": {}
  }
}

Common Error Codes

unauthorizedAuthentication failed

validation_errorInvalid request parameters

not_foundResource not found

rate_limit_exceededToo many requests

insufficient_creditsNot enough credits for operation

internal_errorServer error

Brands

GET/api/v1/brands

Get all brands for the authenticated user.

Query Parameters

Name	Type	Required	Description
`id`	string	Optional	Get a specific brand by ID
`include_offers`	boolean	Optional	Include related offers(default: `true`)

{
  "success": true,
  "data": {
    "brands": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "My Brand",
        "description": "Brand description",
        "logo_url": "https://example.com/logo.png",
        "created_at": "2024-01-01T00:00:00Z",
        "offers": [
          {
            "id": "223e4567-e89b-12d3-a456-426614174000",
            "name": "Summer Sale",
            "unique_selling_proposition": "50% off all items",
            "ideal_buyer": "Bargain hunters",
            "landing_page_url": "https://example.com/sale"
          }
        ]
      }
    ]
  },
  "metadata": {
    "request_id": "...",
    "timestamp": "2024-01-01T00:00:00Z",
    "response_time_ms": 150
  }
}

Try It Out

POST/api/v1/brands

Create a new brand.

Request Body

Name	Type	Required	Description
`name`	string	Required	The name of your brand
`description`	string	Required	A description of your brand
`logo_url`	string	Optional	URL to your brand logo

{
  "success": true,
  "data": {
    "brand": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "My New Brand",
      "description": "This is my brand description",
      "logo_url": "https://example.com/logo.png",
      "created_at": "2024-01-01T00:00:00Z"
    }
  },
  "metadata": {
    "request_id": "...",
    "timestamp": "2024-01-01T00:00:00Z",
    "response_time_ms": 200
  }
}

Try It Out

Offers

POST/api/v1/brands/offers

Create a new offer for a brand.

Request Body

Name	Type	Required	Description
`brand_id`	string	Required	The ID of the brand
`name`	string	Required	The name of the offer
`unique_selling_proposition`	string	Required	What makes this offer special
`ideal_buyer`	string	Required	Description of your target audience
`offer_type`	string	Optional	Type of offer: lead_generation, digital_product, or e_commerce
`landing_page_url`	string	Optional	URL where customers will be directed

{
  "success": true,
  "data": {
    "offer": {
      "id": "223e4567-e89b-12d3-a456-426614174000",
      "brand_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Black Friday Sale",
      "unique_selling_proposition": "Exclusive 70% discount for 24 hours only",
      "ideal_buyer": "Tech enthusiasts looking for premium gadgets at unbeatable prices",
      "offer_type": "e_commerce",
      "landing_page_url": "https://example.com/black-friday",
      "created_at": "2024-01-01T00:00:00Z"
    }
  },
  "metadata": {
    "request_id": "...",
    "timestamp": "2024-01-01T00:00:00Z",
    "response_time_ms": 180
  }
}

Try It Out

Campaign Generation

POST/api/v1/ads/generate-campaign

Generate a new AI-powered advertising campaign. This endpoint uses credits.

Credit Cost

Base: 50 credits (includes 3 creatives)
Additional: 8 credits per creative beyond 3

Request Body

Name	Type	Required	Description
`brand_id`	string	Required	The ID of the brand
`offer_id`	string	Required	The ID of the offer
`platform`	string	Required	Advertising platform (currently only "meta" is supported)
`category`	string	Required	Campaign category: leadgen, e-commerce, or sales
`social_proof`	string	Required	Social proof text (e.g., "Join 10,000+ happy customers")
`call_to_action`	string	Required	Primary call to action text
`number_of_creatives`	string	Required	Number of creatives to generate (3-10)
`special_instructions`	string	Optional	Additional instructions for the AI
`creative_instructions`	string	Optional	Specific creative guidelines
`ad_template_id`	string	Optional	ID of a template to use
`products`	array	Optional	Product image URLs (max 3)
`aspect_ratio`	string	Optional	Aspect ratio: 1:1 or 4:5

{
  "success": true,
  "data": {
    "generation_id": "423e4567-e89b-12d3-a456-426614174000",
    "status": "processing",
    "estimated_completion_time": 120
  },
  "metadata": {
    "credits_charged": 66,
    "credits_remaining": 934,
    "request_id": "...",
    "timestamp": "2024-01-01T00:00:00Z",
    "response_time_ms": 300
  }
}

Try It Out

POST/api/v1/ads/generate-extra-creatives

Generate additional creatives for an existing campaign.

Credit Cost

8 credits per creative

Request Body

Name	Type	Required	Description
`campaign_id`	string	Required	The ID of the existing campaign
`number_of_creatives`	string	Required	Number of creatives to generate (1-10)
`creative_instructions`	string	Optional	Specific creative guidelines
`ad_template_id`	string	Optional	ID of a template to use
`products`	array	Optional	Product image URLs (max 3)
`aspect_ratio`	string	Optional	Aspect ratio: 1:1 or 4:5

{
  "success": true,
  "data": {
    "generation_id": "523e4567-e89b-12d3-a456-426614174000",
    "status": "processing",
    "estimated_completion_time": 60
  },
  "metadata": {
    "credits_charged": 24,
    "credits_remaining": 910,
    "request_id": "...",
    "timestamp": "2024-01-01T00:00:00Z",
    "response_time_ms": 250,
    "campaign_id": "423e4567-e89b-12d3-a456-426614174000"
  }
}

Manual Campaign Management

POST/api/v1/ads/create-manual-campaign

Create a campaign manually without AI generation. No credits required.

Request Body

Name	Type	Required	Description
`brand_id`	string	Required	The ID of the brand
`offer_id`	string	Required	The ID of the offer
`platform`	string	Required	Advertising platform (currently only "meta" is supported)
`category`	string	Required	Campaign category: leadgen, e-commerce, or sales
`title`	string	Required	Campaign title
`hooks`	object	Required	Hook variations (hook_1, hook_2, etc.)
`body_copy`	object	Required	Body copy variations (body_1, body_2, etc.)
`cta`	object	Required	Call to action variations (cta_1, cta_2, etc.)
`creatives`	object	Required	Creative assets (creative_1, creative_2, etc.)

Creative Object Format

Creatives can be either simple image URLs or complex objects for videos:

Creative Formatsjavascript

// Simple image
"creative_1": "https://example.com/image.jpg"

// Video object
"creative_2": {
  "type": "video",
  "url": "https://example.com/video.mp4",
  "thumbnail": "https://example.com/thumb.jpg",
  "aspectRatio": "16:9"
}

{
  "success": true,
  "data": {
    "generation_id": "623e4567-e89b-12d3-a456-426614174000",
    "campaign_data": {
      "hooks": {
        "hook_1": "🌞 New Summer Collection Just Dropped!",
        "hook_2": "Beat the Heat with Style",
        "hook_3": "Limited Time: Summer Sale Inside"
      },
      "body_copy": {
        "body_1": "Discover our exclusive summer collection...",
        "body_2": "From breezy dresses to cool tees..."
      },
      "creatives": {
        "creative_1": {
          "type": "single",
          "url": "https://example.com/summer-dress.jpg",
          "aspectRatio": "1:1"
        },
        "creative_2": {
          "type": "video",
          "url": "https://example.com/summer-promo.mp4",
          "thumbnail": "https://example.com/video-thumb.jpg",
          "aspectRatio": "16:9"
        }
      },
      "cta": {
        "cta_1": "Shop Now",
        "cta_2": "View Collection",
        "cta_3": "Get 20% Off"
      }
    },
    "generation_parameters": {},
    "status": "completed",
    "created_at": "2024-01-01T00:00:00Z",
    "statistics": {
      "hooks_count": 3,
      "body_texts_count": 2,
      "creatives_count": 2,
      "ctas_count": 3,
      "total_combinations": 36
    }
  },
  "metadata": {
    "credits_charged": 0,
    "request_id": "...",
    "timestamp": "2024-01-01T00:00:00Z",
    "response_time_ms": 350
  }
}

POST/api/v1/ads/edit-campaign

Update an existing campaign's content. No credits required.

Only include the sections you want to update. Existing content will be preserved for omitted sections.

Request Body

Name	Type	Required	Description
`generation_id`	string	Required	The ID of the campaign to edit
`hooks`	object	Optional	Hook variations to update
`body_copy`	object	Optional	Body copy variations to update
`cta`	object	Optional	Call to action variations to update
`creatives`	object	Optional	Creative assets to update

{
  "success": true,
  "data": {
    "generation_id": "623e4567-e89b-12d3-a456-426614174000",
    "campaign_data": {},
    "updated_at": "2024-01-01T12:00:00Z",
    "updated_fields": [
      "hooks",
      "body_copy",
      "cta",
      "creatives"
    ]
  },
  "metadata": {
    "request_id": "...",
    "timestamp": "2024-01-01T12:00:00Z",
    "response_time_ms": 200
  }
}

Campaign Library

GET/api/v1/ads/library

Get campaigns from your library with pagination and filtering.

Query Parameters

Name	Type	Required	Description
`brand_id`	string	Required	Filter by brand
`offer_id`	string	Optional	Filter by offer
`limit`	number	Optional	Results per page (1-100)(default: `50`)
`offset`	number	Optional	Pagination offset(default: `0`)
`sort`	string	Optional	Sort field: created_at, updated_at, or campaign_title(default: `created_at`)
`order`	string	Optional	Sort order: asc or desc(default: `desc`)

{
  "success": true,
  "data": {
    "campaigns": [
      {
        "id": "623e4567-e89b-12d3-a456-426614174000",
        "brand_id": "123e4567-e89b-12d3-a456-426614174000",
        "offer_id": "223e4567-e89b-12d3-a456-426614174000",
        "status": "completed",
        "campaign_title": "Summer Collection Launch",
        "is_manual": true,
        "credits_deducted": 0,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T12:00:00Z",
        "completed_at": "2024-01-01T00:00:00Z",
        "brand": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "My Brand",
          "logo_url": "https://example.com/logo.png"
        },
        "offer": {
          "id": "223e4567-e89b-12d3-a456-426614174000",
          "name": "Summer Sale"
        }
      }
    ],
    "pagination": {
      "total": 25,
      "limit": 50,
      "offset": 0,
      "has_more": false
    }
  },
  "metadata": {
    "request_id": "...",
    "timestamp": "2024-01-01T00:00:00Z",
    "response_time_ms": 180
  }
}

Try It Out

GET/api/v1/ads/library/detail

Get detailed information about a specific campaign.

Query Parameters

Name	Type	Required	Description
`id`	string	Required	Campaign ID

{
  "success": true,
  "data": {
    "campaign": {
      "id": "623e4567-e89b-12d3-a456-426614174000",
      "brand_id": "123e4567-e89b-12d3-a456-426614174000",
      "offer_id": "223e4567-e89b-12d3-a456-426614174000",
      "status": "completed",
      "campaign_title": "Summer Collection Launch",
      "is_manual": true,
      "is_shared": false,
      "share_url": null,
      "credits_deducted": 0,
      "campaign_data": {
        "hooks": {},
        "body_copy": {},
        "creatives": {},
        "cta": {}
      },
      "generation_parameters": {},
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T12:00:00Z",
      "completed_at": "2024-01-01T00:00:00Z",
      "brand": {},
      "offer": {}
    }
  },
  "metadata": {
    "request_id": "...",
    "timestamp": "2024-01-01T00:00:00Z",
    "response_time_ms": 150
  }
}

Best Practices

Error Handling

Always check the success field in responses and handle errors appropriately:

Error Handling Examplejavascript

const response = await fetch('https://api.blackumbrella.app/api/v1/brands', {
  headers: {
    'X-API-Key': 'your_api_key'
  }
});

const data = await response.json();

if (!data.success) {
  console.error(`Error: ${data.error.code} - ${data.error.message}`);
  // Handle specific error codes
  switch (data.error.code) {
    case 'insufficient_credits':
      // Prompt user to purchase more credits
      break;
    case 'rate_limit_exceeded':
      // Implement exponential backoff
      break;
    // ... handle other cases
  }
}

Rate Limiting

Respect rate limits by implementing retry logic with exponential backoff:

Rate Limiting Examplejavascript

async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  }

  throw new Error('Max retries exceeded');
}

Pagination

When listing campaigns, use pagination to handle large datasets efficiently:

Pagination Examplejavascript

async function getAllCampaigns(brandId) {
  const campaigns = [];
  let offset = 0;
  const limit = 100;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://api.blackumbrella.app/api/v1/ads/library?brand_id=${brandId}&limit=${limit}&offset=${offset}`,
      { headers: { 'X-API-Key': 'your_api_key' } }
    );

    const data = await response.json();
    campaigns.push(...data.data.campaigns);

    hasMore = data.data.pagination.has_more;
    offset += limit;
  }

  return campaigns;
}

Webhook Integration

For asynchronous operations (AI campaign generation), implement webhook handling or polling:

Polling Examplejavascript

// Option 1: Polling
async function waitForCampaignCompletion(generationId) {
  const maxAttempts = 60; // 5 minutes with 5-second intervals

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.blackumbrella.app/api/v1/ads/library/detail?id=${generationId}`,
      { headers: { 'X-API-Key': 'your_api_key' } }
    );

    const data = await response.json();

    if (data.data.campaign.status === 'completed') {
      return data.data.campaign;
    }

    if (data.data.campaign.status === 'failed') {
      throw new Error('Campaign generation failed');
    }

    await new Promise(resolve => setTimeout(resolve, 5000));
  }

  throw new Error('Campaign generation timeout');
}

Credit Management

Monitor credit usage and implement appropriate limits:

Credit Management Examplejavascript

// Check credits before expensive operations
async function generateCampaignWithCreditCheck(params) {
  // Calculate required credits
  const baseCredits = 50;
  const extraCreatives = Math.max(0, params.number_of_creatives - 3);
  const requiredCredits = baseCredits + (extraCreatives * 8);

  // You should implement an endpoint to check current credit balance
  // For now, the credits_remaining is returned in generation responses

  const response = await fetch(
    'https://api.blackumbrella.app/api/v1/ads/generate-campaign',
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'your_api_key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(params)
    }
  );

  const data = await response.json();

  if (!data.success && data.error.code === 'insufficient_credits') {
    console.log(`Need ${requiredCredits} credits, but only have ${data.error.details.available}`);
    // Handle insufficient credits
  }

  return data;
}

Changelog

Version 1.0 (Current)

Initial API release
Brand and offer management
AI campaign generation
Manual campaign creation
Campaign editing
Campaign library with pagination
Credit-based billing system

API v1.0

Black Umbrella API

Build powerful advertising campaigns with our AI-powered API. Create brands, manage offers, and generate creative content programmatically.

Secure by Design

API key authentication with rate limiting and comprehensive error handling

Lightning Fast

Optimized endpoints with sub-second response times for all operations

Well Documented

Comprehensive examples and best practices for every endpoint

Getting Started

Overview

Base URL

https://api.blackumbrella.app

Authentication

All API requests require authentication using either an API key or a Bearer token.

API Key Authentication

Include your API key in the request headers:

Request Headerhttp

X-API-Key: bumb_sk_your_api_key_here

For endpoints that require user context, also include:

Additional Headerhttp

X-User-ID: your_user_id

Bearer Token Authentication

Alternatively, use a Bearer token:

Authorization Headerhttp

Authorization: Bearer your_access_token

Rate Limiting

All endpoints implement rate limiting. Rate limit information is included in response headers:

X-RateLimit-RemainingNumber of requests remaining
X-RateLimit-ResetTime when the rate limit resets (ISO 8601 format)
Retry-AfterSeconds to wait before retrying (included in 429 responses)

Error Responses

All errors follow a consistent format:

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": {}
  }
}

Common Error Codes

unauthorizedAuthentication failed

validation_errorInvalid request parameters

not_foundResource not found

rate_limit_exceededToo many requests

insufficient_creditsNot enough credits for operation

internal_errorServer error

Brands

GET/api/v1/brands

Get all brands for the authenticated user.

Query Parameters

Name	Type	Required	Description
`id`	string	Optional	Get a specific brand by ID
`include_offers`	boolean	Optional	Include related offers(default: `true`)

{
  "success": true,
  "data": {
    "brands": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "My Brand",
        "description": "Brand description",
        "logo_url": "https://example.com/logo.png",
        "created_at": "2024-01-01T00:00:00Z",
        "offers": [
          {
            "id": "223e4567-e89b-12d3-a456-426614174000",
            "name": "Summer Sale",
            "unique_selling_proposition": "50% off all items",
            "ideal_buyer": "Bargain hunters",
            "landing_page_url": "https://example.com/sale"
          }
        ]
      }
    ]
  },
  "metadata": {
    "request_id": "...",
    "timestamp": "2024-01-01T00:00:00Z",
    "response_time_ms": 150
  }
}

Try It Out

POST/api/v1/brands

Create a new brand.

Request Body

Name	Type	Required	Description
`name`	string	Required	The name of your brand
`description`	string	Required	A description of your brand
`logo_url`	string	Optional	URL to your brand logo

{
  "success": true,
  "data": {
    "brand": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "My New Brand",
      "description": "This is my brand description",
      "logo_url": "https://example.com/logo.png",
      "created_at": "2024-01-01T00:00:00Z"
    }
  },
  "metadata": {
    "request_id": "...",
    "timestamp": "2024-01-01T00:00:00Z",
    "response_time_ms": 200
  }
}

Try It Out

Offers

POST/api/v1/brands/offers

Create a new offer for a brand.

Request Body

Name	Type	Required	Description
`brand_id`	string	Required	The ID of the brand
`name`	string	Required	The name of the offer
`unique_selling_proposition`	string	Required	What makes this offer special
`ideal_buyer`	string	Required	Description of your target audience
`offer_type`	string	Optional	Type of offer: lead_generation, digital_product, or e_commerce
`landing_page_url`	string	Optional	URL where customers will be directed

{
  "success": true,
  "data": {
    "offer": {
      "id": "223e4567-e89b-12d3-a456-426614174000",
      "brand_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Black Friday Sale",
      "unique_selling_proposition": "Exclusive 70% discount for 24 hours only",
      "ideal_buyer": "Tech enthusiasts looking for premium gadgets at unbeatable prices",
      "offer_type": "e_commerce",
      "landing_page_url": "https://example.com/black-friday",
      "created_at": "2024-01-01T00:00:00Z"
    }
  },
  "metadata": {
    "request_id": "...",
    "timestamp": "2024-01-01T00:00:00Z",
    "response_time_ms": 180
  }
}

Try It Out

Campaign Generation

POST/api/v1/ads/generate-campaign

Generate a new AI-powered advertising campaign. This endpoint uses credits.

Credit Cost

Base: 50 credits (includes 3 creatives)
Additional: 8 credits per creative beyond 3

Request Body

Name	Type	Required	Description
`brand_id`	string	Required	The ID of the brand
`offer_id`	string	Required	The ID of the offer
`platform`	string	Required	Advertising platform (currently only "meta" is supported)
`category`	string	Required	Campaign category: leadgen, e-commerce, or sales
`social_proof`	string	Required	Social proof text (e.g., "Join 10,000+ happy customers")
`call_to_action`	string	Required	Primary call to action text
`number_of_creatives`	string	Required	Number of creatives to generate (3-10)
`special_instructions`	string	Optional	Additional instructions for the AI
`creative_instructions`	string	Optional	Specific creative guidelines
`ad_template_id`	string	Optional	ID of a template to use
`products`	array	Optional	Product image URLs (max 3)
`aspect_ratio`	string	Optional	Aspect ratio: 1:1 or 4:5

{
  "success": true,
  "data": {
    "generation_id": "423e4567-e89b-12d3-a456-426614174000",
    "status": "processing",
    "estimated_completion_time": 120
  },
  "metadata": {
    "credits_charged": 66,
    "credits_remaining": 934,
    "request_id": "...",
    "timestamp": "2024-01-01T00:00:00Z",
    "response_time_ms": 300
  }
}

Try It Out

POST/api/v1/ads/generate-extra-creatives

Generate additional creatives for an existing campaign.

Credit Cost

8 credits per creative

Request Body

Name	Type	Required	Description
`campaign_id`	string	Required	The ID of the existing campaign
`number_of_creatives`	string	Required	Number of creatives to generate (1-10)
`creative_instructions`	string	Optional	Specific creative guidelines
`ad_template_id`	string	Optional	ID of a template to use
`products`	array	Optional	Product image URLs (max 3)
`aspect_ratio`	string	Optional	Aspect ratio: 1:1 or 4:5

{
  "success": true,
  "data": {
    "generation_id": "523e4567-e89b-12d3-a456-426614174000",
    "status": "processing",
    "estimated_completion_time": 60
  },
  "metadata": {
    "credits_charged": 24,
    "credits_remaining": 910,
    "request_id": "...",
    "timestamp": "2024-01-01T00:00:00Z",
    "response_time_ms": 250,
    "campaign_id": "423e4567-e89b-12d3-a456-426614174000"
  }
}

Manual Campaign Management

POST/api/v1/ads/create-manual-campaign

Create a campaign manually without AI generation. No credits required.

Request Body

Name	Type	Required	Description
`brand_id`	string	Required	The ID of the brand
`offer_id`	string	Required	The ID of the offer
`platform`	string	Required	Advertising platform (currently only "meta" is supported)
`category`	string	Required	Campaign category: leadgen, e-commerce, or sales
`title`	string	Required	Campaign title
`hooks`	object	Required	Hook variations (hook_1, hook_2, etc.)
`body_copy`	object	Required	Body copy variations (body_1, body_2, etc.)
`cta`	object	Required	Call to action variations (cta_1, cta_2, etc.)
`creatives`	object	Required	Creative assets (creative_1, creative_2, etc.)

Creative Object Format

Creatives can be either simple image URLs or complex objects for videos:

Creative Formatsjavascript

// Simple image
"creative_1": "https://example.com/image.jpg"

// Video object
"creative_2": {
  "type": "video",
  "url": "https://example.com/video.mp4",
  "thumbnail": "https://example.com/thumb.jpg",
  "aspectRatio": "16:9"
}

{
  "success": true,
  "data": {
    "generation_id": "623e4567-e89b-12d3-a456-426614174000",
    "campaign_data": {
      "hooks": {
        "hook_1": "🌞 New Summer Collection Just Dropped!",
        "hook_2": "Beat the Heat with Style",
        "hook_3": "Limited Time: Summer Sale Inside"
      },
      "body_copy": {
        "body_1": "Discover our exclusive summer collection...",
        "body_2": "From breezy dresses to cool tees..."
      },
      "creatives": {
        "creative_1": {
          "type": "single",
          "url": "https://example.com/summer-dress.jpg",
          "aspectRatio": "1:1"
        },
        "creative_2": {
          "type": "video",
          "url": "https://example.com/summer-promo.mp4",
          "thumbnail": "https://example.com/video-thumb.jpg",
          "aspectRatio": "16:9"
        }
      },
      "cta": {
        "cta_1": "Shop Now",
        "cta_2": "View Collection",
        "cta_3": "Get 20% Off"
      }
    },
    "generation_parameters": {},
    "status": "completed",
    "created_at": "2024-01-01T00:00:00Z",
    "statistics": {
      "hooks_count": 3,
      "body_texts_count": 2,
      "creatives_count": 2,
      "ctas_count": 3,
      "total_combinations": 36
    }
  },
  "metadata": {
    "credits_charged": 0,
    "request_id": "...",
    "timestamp": "2024-01-01T00:00:00Z",
    "response_time_ms": 350
  }
}

POST/api/v1/ads/edit-campaign

Update an existing campaign's content. No credits required.

Only include the sections you want to update. Existing content will be preserved for omitted sections.

Request Body

Name	Type	Required	Description
`generation_id`	string	Required	The ID of the campaign to edit
`hooks`	object	Optional	Hook variations to update
`body_copy`	object	Optional	Body copy variations to update
`cta`	object	Optional	Call to action variations to update
`creatives`	object	Optional	Creative assets to update

{
  "success": true,
  "data": {
    "generation_id": "623e4567-e89b-12d3-a456-426614174000",
    "campaign_data": {},
    "updated_at": "2024-01-01T12:00:00Z",
    "updated_fields": [
      "hooks",
      "body_copy",
      "cta",
      "creatives"
    ]
  },
  "metadata": {
    "request_id": "...",
    "timestamp": "2024-01-01T12:00:00Z",
    "response_time_ms": 200
  }
}

Campaign Library

GET/api/v1/ads/library

Get campaigns from your library with pagination and filtering.

Query Parameters

Name	Type	Required	Description
`brand_id`	string	Required	Filter by brand
`offer_id`	string	Optional	Filter by offer
`limit`	number	Optional	Results per page (1-100)(default: `50`)
`offset`	number	Optional	Pagination offset(default: `0`)
`sort`	string	Optional	Sort field: created_at, updated_at, or campaign_title(default: `created_at`)
`order`	string	Optional	Sort order: asc or desc(default: `desc`)

{
  "success": true,
  "data": {
    "campaigns": [
      {
        "id": "623e4567-e89b-12d3-a456-426614174000",
        "brand_id": "123e4567-e89b-12d3-a456-426614174000",
        "offer_id": "223e4567-e89b-12d3-a456-426614174000",
        "status": "completed",
        "campaign_title": "Summer Collection Launch",
        "is_manual": true,
        "credits_deducted": 0,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T12:00:00Z",
        "completed_at": "2024-01-01T00:00:00Z",
        "brand": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "My Brand",
          "logo_url": "https://example.com/logo.png"
        },
        "offer": {
          "id": "223e4567-e89b-12d3-a456-426614174000",
          "name": "Summer Sale"
        }
      }
    ],
    "pagination": {
      "total": 25,
      "limit": 50,
      "offset": 0,
      "has_more": false
    }
  },
  "metadata": {
    "request_id": "...",
    "timestamp": "2024-01-01T00:00:00Z",
    "response_time_ms": 180
  }
}

Try It Out

GET/api/v1/ads/library/detail

Get detailed information about a specific campaign.

Query Parameters

Name	Type	Required	Description
`id`	string	Required	Campaign ID

{
  "success": true,
  "data": {
    "campaign": {
      "id": "623e4567-e89b-12d3-a456-426614174000",
      "brand_id": "123e4567-e89b-12d3-a456-426614174000",
      "offer_id": "223e4567-e89b-12d3-a456-426614174000",
      "status": "completed",
      "campaign_title": "Summer Collection Launch",
      "is_manual": true,
      "is_shared": false,
      "share_url": null,
      "credits_deducted": 0,
      "campaign_data": {
        "hooks": {},
        "body_copy": {},
        "creatives": {},
        "cta": {}
      },
      "generation_parameters": {},
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T12:00:00Z",
      "completed_at": "2024-01-01T00:00:00Z",
      "brand": {},
      "offer": {}
    }
  },
  "metadata": {
    "request_id": "...",
    "timestamp": "2024-01-01T00:00:00Z",
    "response_time_ms": 150
  }
}

Best Practices

Error Handling

Always check the success field in responses and handle errors appropriately:

Error Handling Examplejavascript

const response = await fetch('https://api.blackumbrella.app/api/v1/brands', {
  headers: {
    'X-API-Key': 'your_api_key'
  }
});

const data = await response.json();

if (!data.success) {
  console.error(`Error: ${data.error.code} - ${data.error.message}`);
  // Handle specific error codes
  switch (data.error.code) {
    case 'insufficient_credits':
      // Prompt user to purchase more credits
      break;
    case 'rate_limit_exceeded':
      // Implement exponential backoff
      break;
    // ... handle other cases
  }
}

Rate Limiting

Respect rate limits by implementing retry logic with exponential backoff:

Rate Limiting Examplejavascript

async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  }

  throw new Error('Max retries exceeded');
}

Pagination

When listing campaigns, use pagination to handle large datasets efficiently:

Pagination Examplejavascript

async function getAllCampaigns(brandId) {
  const campaigns = [];
  let offset = 0;
  const limit = 100;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://api.blackumbrella.app/api/v1/ads/library?brand_id=${brandId}&limit=${limit}&offset=${offset}`,
      { headers: { 'X-API-Key': 'your_api_key' } }
    );

    const data = await response.json();
    campaigns.push(...data.data.campaigns);

    hasMore = data.data.pagination.has_more;
    offset += limit;
  }

  return campaigns;
}

Webhook Integration

For asynchronous operations (AI campaign generation), implement webhook handling or polling:

Polling Examplejavascript

// Option 1: Polling
async function waitForCampaignCompletion(generationId) {
  const maxAttempts = 60; // 5 minutes with 5-second intervals

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.blackumbrella.app/api/v1/ads/library/detail?id=${generationId}`,
      { headers: { 'X-API-Key': 'your_api_key' } }
    );

    const data = await response.json();

    if (data.data.campaign.status === 'completed') {
      return data.data.campaign;
    }

    if (data.data.campaign.status === 'failed') {
      throw new Error('Campaign generation failed');
    }

    await new Promise(resolve => setTimeout(resolve, 5000));
  }

  throw new Error('Campaign generation timeout');
}

Credit Management

Monitor credit usage and implement appropriate limits:

Credit Management Examplejavascript

// Check credits before expensive operations
async function generateCampaignWithCreditCheck(params) {
  // Calculate required credits
  const baseCredits = 50;
  const extraCreatives = Math.max(0, params.number_of_creatives - 3);
  const requiredCredits = baseCredits + (extraCreatives * 8);

  // You should implement an endpoint to check current credit balance
  // For now, the credits_remaining is returned in generation responses

  const response = await fetch(
    'https://api.blackumbrella.app/api/v1/ads/generate-campaign',
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'your_api_key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(params)
    }
  );

  const data = await response.json();

  if (!data.success && data.error.code === 'insufficient_credits') {
    console.log(`Need ${requiredCredits} credits, but only have ${data.error.details.available}`);
    // Handle insufficient credits
  }

  return data;
}

Changelog

Version 1.0 (Current)

Initial API release
Brand and offer management
AI campaign generation
Manual campaign creation
Campaign editing
Campaign library with pagination
Credit-based billing system