OpenAPI Specification
openapi: 3.0.3
info:
title: Brave Ads campaigns API
description: 'API for managing and reporting on Brave Ads campaigns. Enables advertisers to retrieve campaign details and performance data for privacy-preserving native browser ads and search ads. Supports customizable reporting dimensions and metrics including impressions, clicks, spend, and conversion tracking. Authentication uses API keys generated from the Brave Ads dashboard.
'
version: 3.0.0
contact:
name: Brave Ads
url: https://brave.com/brave-ads/
email: adsales@brave.com
termsOfService: https://brave.com/terms-of-use/
servers:
- url: https://ads-serve.brave.com
description: Brave Ads API
security:
- ApiKeyAuth: []
tags:
- name: campaigns
description: Campaign management and hierarchy endpoints
paths:
/v1/api/campaigns:
get:
operationId: listCampaigns
summary: List Campaigns
description: 'Retrieve campaign hierarchies with associated ad sets and ads for the authenticated advertiser account. Returns a structured view of campaigns, their ad sets, and individual ads with configuration details.
'
tags:
- campaigns
responses:
'200':
description: Successful campaigns list response
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignsResponse'
example:
campaigns:
- id: camp_abc123
name: Q4 Brand Awareness
status: active
budget:
daily: 50.0
total: 1500.0
currency: USD
start_date: '2026-10-01'
end_date: '2026-12-31'
ad_sets:
- id: adset_xyz789
name: Desktop Users
status: active
targeting:
countries:
- US
- CA
- GB
platforms:
- desktop
ads:
- id: ad_def456
name: Hero Banner Ad
status: active
creative_url: https://example.com/ad-creative.png
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
schemas:
Targeting:
type: object
description: Targeting configuration for an ad set.
properties:
countries:
type: array
items:
type: string
description: List of 2-character country codes to target.
platforms:
type: array
items:
type: string
enum:
- desktop
- mobile
- tablet
description: Device platform targets.
channels:
type: array
items:
type: string
enum:
- search
- native
description: Ad channel types.
Ad:
type: object
description: An individual ad creative within an ad set.
properties:
id:
type: string
description: Unique identifier for the ad.
name:
type: string
description: Display name of the ad.
status:
type: string
enum:
- active
- paused
- draft
- rejected
description: Current status of the ad.
creative_url:
type: string
format: uri
description: URL to the ad creative asset.
headline:
type: string
description: Ad headline text.
body:
type: string
description: Ad body copy.
destination_url:
type: string
format: uri
description: Destination URL for ad clicks.
CampaignsResponse:
type: object
description: Response containing the list of campaigns with their hierarchies.
properties:
campaigns:
type: array
items:
$ref: '#/components/schemas/Campaign'
ErrorResponse:
type: object
description: API error response.
properties:
error:
type: object
properties:
code:
type: string
description: Error code.
message:
type: string
description: Human-readable error message.
AdSet:
type: object
description: An ad set within a campaign containing targeting configuration.
properties:
id:
type: string
description: Unique identifier for the ad set.
name:
type: string
description: Display name of the ad set.
status:
type: string
enum:
- active
- paused
- draft
description: Current status of the ad set.
targeting:
$ref: '#/components/schemas/Targeting'
ads:
type: array
items:
$ref: '#/components/schemas/Ad'
Campaign:
type: object
description: A Brave Ads campaign with associated ad sets and ads.
properties:
id:
type: string
description: Unique identifier for the campaign.
name:
type: string
description: Display name of the campaign.
status:
type: string
description: Current status of the campaign.
enum:
- active
- paused
- completed
- draft
budget:
$ref: '#/components/schemas/Budget'
start_date:
type: string
format: date
description: Campaign start date.
end_date:
type: string
format: date
description: Campaign end date.
ad_sets:
type: array
items:
$ref: '#/components/schemas/AdSet'
Budget:
type: object
description: Campaign budget configuration.
properties:
daily:
type: number
format: float
description: Daily budget amount.
total:
type: number
format: float
description: Total campaign budget.
currency:
type: string
description: ISO 4217 currency code.
example: USD
responses:
Unauthorized:
description: Unauthorized — missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
TooManyRequests:
description: Too Many Requests — rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Forbidden:
description: Forbidden — API key does not have access to this resource.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-Api-Key
description: 'API key generated from the Brave Ads dashboard at https://ads.brave.com.
'
externalDocs:
description: Brave Ads API Documentation
url: https://ads-help.brave.com/campaign-performance/API/