Reddit Ads API

openapi: 3.1.0
info:
  title: Reddit Account Ads API
  description: The Reddit Ads API allows advertisers and their partners to programmatically create, edit, and manage advertising campaigns and audiences on the Reddit platform. It provides endpoints for managing ad accounts, campaigns, ad groups, ads, creatives, targeting, custom audiences, conversion pixels, and reporting. Authentication is handled via OAuth 2.0, and rate limits are set at one request per second.
  version: '3'
  contact:
    name: Reddit Ads Support
    url: https://business.reddithelp.com/s/article/Reddit-Ads-API
  termsOfService: https://business.reddithelp.com/s/article/Reddit-Ads-API-Terms
servers:
- url: https://ads-api.reddit.com/api/v3
  description: Reddit Ads API v3 Production Server
security:
- oauth2: []
tags:
- name: Ads
  description: Endpoints for creating and managing individual ads and their associated creative content.
paths:
  /accounts/{account_id}/ads:
    get:
      operationId: listAds
      summary: List Ads
      description: Lists ads in a Reddit Ads account or ad group, returning ad IDs, names, status, creative content, and review status.
      tags:
      - Ads
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/cursor'
      - name: ad_group_id
        in: query
        description: Filter ads by ad group ID.
        schema:
          type: string
      responses:
        '200':
          description: List of ads
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Ad'
                  cursor:
                    type: string
                    description: Pagination cursor for the next page.
        '401':
          description: Authentication required
    post:
      operationId: createAd
      summary: Create an Ad
      description: Creates a new ad with creative content within an ad group.
      tags:
      - Ads
      parameters:
      - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdInput'
      responses:
        '201':
          description: Ad created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ad'
        '400':
          description: Invalid ad data
  /accounts/{account_id}/ads/{ad_id}:
    get:
      operationId: getAd
      summary: Get an Ad
      description: Fetches detailed information about a specific ad including creative content, status, and review information.
      tags:
      - Ads
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/adId'
      responses:
        '200':
          description: Ad details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ad'
        '404':
          description: Ad not found
    put:
      operationId: updateAd
      summary: Update an Ad
      description: Updates an existing ad's creative content and configuration.
      tags:
      - Ads
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/adId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdInput'
      responses:
        '200':
          description: Ad updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ad'
        '400':
          description: Invalid ad data
    delete:
      operationId: deleteAd
      summary: Delete an Ad
      description: Deletes an ad from an ad group.
      tags:
      - Ads
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/adId'
      responses:
        '204':
          description: Ad deleted successfully
        '404':
          description: Ad not found
components:
  parameters:
    adId:
      name: ad_id
      in: path
      required: true
      description: The unique identifier of the ad.
      schema:
        type: string
    accountId:
      name: account_id
      in: path
      required: true
      description: The unique identifier of the Reddit Ads account.
      schema:
        type: string
    pageSize:
      name: page_size
      in: query
      description: The maximum number of items to return per page (default 25, max 100).
      schema:
        type: integer
        default: 25
        minimum: 1
        maximum: 100
    cursor:
      name: cursor
      in: query
      description: A pagination cursor for retrieving the next page of results.
      schema:
        type: string
  schemas:
    Ad:
      type: object
      description: An individual ad with creative content and review status.
      properties:
        id:
          type: string
          description: The unique identifier of the ad.
        ad_group_id:
          type: string
          description: The ad group this ad belongs to.
        name:
          type: string
          description: The name of the ad.
        status:
          type: string
          description: The current status of the ad.
          enum:
          - ACTIVE
          - PAUSED
          - DRAFT
          - PENDING_REVIEW
          - APPROVED
          - REJECTED
        post_id:
          type: string
          description: The Reddit post ID used as the ad creative.
        post_url:
          type: string
          format: uri
          description: The URL of the Reddit post serving as the ad.
        click_url:
          type: string
          format: uri
          description: The destination URL when the ad is clicked.
        review_status:
          type: string
          description: The ad review status.
          enum:
          - PENDING
          - APPROVED
          - REJECTED
        rejection_reason:
          type: string
          description: The reason for ad rejection, if applicable.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the ad was created.
    AdInput:
      type: object
      description: Input for creating or updating an ad.
      required:
      - ad_group_id
      - name
      properties:
        ad_group_id:
          type: string
          description: The ad group to create the ad in.
        name:
          type: string
          description: The name of the ad.
        post_id:
          type: string
          description: The Reddit post ID to use as the ad creative.
        click_url:
          type: string
          format: uri
          description: The destination URL when the ad is clicked.
        status:
          type: string
          description: The desired status.
          enum:
          - ACTIVE
          - PAUSED
          - DRAFT
  securitySchemes:
    oauth2:
      type: oauth2
      description: Reddit Ads API uses OAuth 2.0 for authentication. Access tokens are obtained via the authorization code flow.
      flows:
        authorizationCode:
          authorizationUrl: https://www.reddit.com/api/v1/authorize
          tokenUrl: https://www.reddit.com/api/v1/access_token
          scopes:
            ads: Access to ads management endpoints
externalDocs:
  description: Reddit Ads API Documentation
  url: https://ads-api.reddit.com/docs/