openapi: 3.1.0
info:
  title: Reddit Ads Account Links & Comments 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: Links & Comments
  description: Endpoints for interacting with submissions (links) and comments, including voting, saving, hiding, reporting, and submitting content.
paths:
  /comments/{article}:
    get:
      operationId: getComments
      summary: Get Comments for a Submission
      description: Returns comments for a given submission (article). The response includes both the submission data and a tree of comments. Use the sort parameter to control comment ordering.
      tags:
      - Links & Comments
      parameters:
      - name: article
        in: path
        required: true
        description: The ID36 of the submission to retrieve comments for.
        schema:
          type: string
      - name: sort
        in: query
        description: The sorting method for comments.
        schema:
          type: string
          enum:
          - confidence
          - top
          - new
          - controversial
          - old
          - random
          - qa
          - live
      - name: depth
        in: query
        description: Maximum depth of subtrees in the thread.
        schema:
          type: integer
      - name: context
        in: query
        description: Number of levels of parent comments to include for a comment permalink.
        schema:
          type: integer
          minimum: 0
          maximum: 8
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Submission and comment tree
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Listing'
  /api/morechildren:
    get:
      operationId: getMoreChildren
      summary: Retrieve Additional Comments
      description: Retrieves additional comments omitted from a base comment tree. Used to load more comments from a stub returned in a comment listing.
      tags:
      - Links & Comments
      parameters:
      - name: link_id
        in: query
        required: true
        description: The fullname (t3_ prefix) of the submission.
        schema:
          type: string
      - name: children
        in: query
        required: true
        description: A comma-delimited list of comment ID36s to be fetched.
        schema:
          type: string
      - name: sort
        in: query
        description: The sorting method for comments.
        schema:
          type: string
          enum:
          - confidence
          - top
          - new
          - controversial
          - old
          - random
          - qa
          - live
      - name: api_type
        in: query
        description: The string json to request JSON response.
        schema:
          type: string
          default: json
      responses:
        '200':
          description: Additional comment data
          content:
            application/json:
              schema:
                type: object
  /api/submit:
    post:
      operationId: submit
      summary: Submit a New Link or Self-post
      description: Submits a new link or self-post to a subreddit. Requires the submit OAuth scope.
      tags:
      - Links & Comments
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - sr
              - title
              - kind
              properties:
                sr:
                  type: string
                  description: The name of the subreddit to submit to.
                title:
                  type: string
                  description: The title of the submission (max 300 characters).
                  maxLength: 300
                kind:
                  type: string
                  description: The type of submission.
                  enum:
                  - link
                  - self
                  - image
                  - video
                  - videogif
                url:
                  type: string
                  format: uri
                  description: The URL for a link submission.
                text:
                  type: string
                  description: The body text for a self-post (markdown).
                richtext_json:
                  type: string
                  description: The rich text body as JSON for a self-post.
                flair_id:
                  type: string
                  description: The flair template ID to apply to the submission.
                flair_text:
                  type: string
                  description: The flair text to apply to the submission.
                nsfw:
                  type: boolean
                  description: Whether the submission is NSFW.
                spoiler:
                  type: boolean
                  description: Whether the submission is a spoiler.
                resubmit:
                  type: boolean
                  description: Whether to allow resubmitting a URL that has already been submitted.
                sendreplies:
                  type: boolean
                  description: Whether to send replies to the user's inbox.
                api_type:
                  type: string
                  default: json
      responses:
        '200':
          description: Submission created
          content:
            application/json:
              schema:
                type: object
        '403':
          description: Permission denied
  /api/comment:
    post:
      operationId: comment
      summary: Submit a New Comment
      description: Submits a new comment on a submission or in reply to another comment. Requires the submit OAuth scope.
      tags:
      - Links & Comments
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - thing_id
              - text
              properties:
                thing_id:
                  type: string
                  description: The fullname of the parent thing to comment on.
                text:
                  type: string
                  description: The body of the comment (markdown).
                richtext_json:
                  type: string
                  description: The rich text body as JSON.
                api_type:
                  type: string
                  default: json
      responses:
        '200':
          description: Comment created
          content:
            application/json:
              schema:
                type: object
        '403':
          description: Permission denied
  /api/vote:
    post:
      operationId: vote
      summary: Vote on a Submission or Comment
      description: Casts a vote on a submission or comment. Direction values are 1 for upvote, -1 for downvote, and 0 to remove the vote. Requires the vote OAuth scope.
      tags:
      - Links & Comments
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - id
              - dir
              properties:
                id:
                  type: string
                  description: The fullname of the thing to vote on.
                dir:
                  type: integer
                  description: 'Vote direction: 1 (upvote), -1 (downvote), 0 (unvote).'
                  enum:
                  - 1
                  - 0
                  - -1
                rank:
                  type: integer
                  description: An integer greater than 1 (deprecated).
      responses:
        '200':
          description: Vote cast successfully
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Authentication required
  /api/save:
    post:
      operationId: save
      summary: Save a Submission or Comment
      description: Saves a submission or comment to the authenticated user's saved items. Requires the save OAuth scope.
      tags:
      - Links & Comments
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: The fullname of the thing to save.
                category:
                  type: string
                  description: A category name for the saved item (Reddit Gold feature).
      responses:
        '200':
          description: Item saved successfully
  /api/unsave:
    post:
      operationId: unsave
      summary: Unsave a Submission or Comment
      description: Removes a submission or comment from the authenticated user's saved items. Requires the save OAuth scope.
      tags:
      - Links & Comments
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: The fullname of the thing to unsave.
      responses:
        '200':
          description: Item unsaved successfully
  /api/hide:
    post:
      operationId: hide
      summary: Hide a Submission
      description: Hides a submission from the authenticated user's listings. Requires the report OAuth scope.
      tags:
      - Links & Comments
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: A comma-separated list of fullnames to hide.
      responses:
        '200':
          description: Submission hidden successfully
  /api/unhide:
    post:
      operationId: unhide
      summary: Unhide a Submission
      description: Unhides a previously hidden submission. Requires the report OAuth scope.
      tags:
      - Links & Comments
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: A comma-separated list of fullnames to unhide.
      responses:
        '200':
          description: Submission unhidden successfully
  /api/del:
    post:
      operationId: del
      summary: Delete a Submission or Comment
      description: Deletes a submission or comment authored by the authenticated user. Requires the edit OAuth scope.
      tags:
      - Links & Comments
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: The fullname of the thing to delete.
      responses:
        '200':
          description: Item deleted successfully
  /api/editusertext:
    post:
      operationId: editUserText
      summary: Edit a Self-post or Comment
      description: Edits the body text of a self-post or comment authored by the authenticated user. Requires the edit OAuth scope.
      tags:
      - Links & Comments
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - thing_id
              - text
              properties:
                thing_id:
                  type: string
                  description: The fullname of the thing to edit.
                text:
                  type: string
                  description: The new body text (markdown).
                api_type:
                  type: string
                  default: json
      responses:
        '200':
          description: Text edited successfully
          content:
            application/json:
              schema:
                type: object
  /api/report:
    post:
      operationId: report
      summary: Report a Submission or Comment
      description: Reports a submission or comment to the moderators of the subreddit. Requires the report OAuth scope.
      tags:
      - Links & Comments
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - thing_id
              properties:
                thing_id:
                  type: string
                  description: The fullname of the thing to report.
                reason:
                  type: string
                  description: The reason for reporting (max 100 characters).
                  maxLength: 100
                other_reason:
                  type: string
                  description: A custom reason for reporting (max 100 characters).
                  maxLength: 100
                site_reason:
                  type: string
                  description: A site rule violation reason.
                rule_reason:
                  type: string
                  description: A subreddit rule violation reason.
                api_type:
                  type: string
                  default: json
      responses:
        '200':
          description: Report submitted
components:
  schemas:
    Listing:
      type: object
      description: A Reddit listing is a paginated collection of things. Listings contain a data object with children and pagination information.
      properties:
        kind:
          type: string
          description: The kind identifier, always "Listing".
          enum:
          - Listing
        data:
          type: object
          properties:
            after:
              type: string
              nullable: true
              description: The fullname of the next item for forward pagination.
            before:
              type: string
              nullable: true
              description: The fullname of the previous item for backward pagination.
            dist:
              type: integer
              description: The number of items in this listing.
            modhash:
              type: string
              description: A modhash for CSRF protection.
            children:
              type: array
              description: The list of things in this listing.
              items:
                $ref: '#/components/schemas/Thing'
    Thing:
      type: object
      description: A Reddit thing is the base object type. All Reddit objects (comments, links, subreddits, etc.) are things with a kind and data payload.
      properties:
        kind:
          type: string
          description: The kind identifier (t1 for comment, t2 for account, t3 for link, t4 for message, t5 for subreddit, t6 for award).
          enum:
          - t1
          - t2
          - t3
          - t4
          - t5
          - t6
        data:
          type: object
          description: The thing's data payload, varying by kind.
  parameters:
    limit:
      name: limit
      in: query
      description: The maximum number of items to return (default 25, max 100).
      schema:
        type: integer
        default: 25
        minimum: 1
        maximum: 100
  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/