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/