MarketSDK Moderation API

openapi: 3.2.0
info:
  title: Marketsdk Moderation API
  version: 1.0.0
  contact: {}
  description: 'Operations tagged Moderation across 2 of this provider''s published API definitions: marketsdk-openapi.json, marketsdk-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.marketsdk.com
tags:
- name: Moderation
paths:
  /v1/flags:
    post:
      description: On behalf of the end user who reported it.
      operationId: createFlag
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFlagDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Flag a listing, a seller, or a review
      tags:
      - Moderation
    get:
      operationId: listFlags
      parameters:
      - name: limit
        required: false
        in: query
        schema:
          minimum: 1
          maximum: 100
          default: 20
          type: number
      - name: starting_after
        required: false
        in: query
        description: The `next_cursor` of the previous page.
        schema:
          type: string
      - name: status
        required: false
        in: query
        schema:
          type: string
          enum:
          - open
          - resolved
      - name: target
        required: false
        in: query
        description: Only flags on this listing, seller, or review.
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagList'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: List flags, newest first
      tags:
      - Moderation
    servers:
    - url: https://api.marketsdk.com
  /v1/flags/{id}:
    get:
      operationId: getFlag
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Retrieve a flag
      tags:
      - Moderation
    servers:
    - url: https://api.marketsdk.com
  /v1/moderation/queue:
    get:
      operationId: getModerationQueue
      parameters:
      - name: target_type
        required: false
        in: query
        schema:
          type: string
          enum:
          - listing
          - seller
          - review
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModerationQueueObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: 'The review queue: everything with open flags, the longest waiting first'
      tags:
      - Moderation
    servers:
    - url: https://api.marketsdk.com
  /v1/moderation/actions:
    post:
      description: Resolves the target's open flags and logs who acted and why.
      operationId: createModerationAction
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateModerationActionDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModerationActionObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: The object is not in a state that allows this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Act on a flagged target
      tags:
      - Moderation
    get:
      operationId: listModerationActions
      parameters:
      - name: limit
        required: false
        in: query
        schema:
          minimum: 1
          maximum: 100
          default: 20
          type: number
      - name: starting_after
        required: false
        in: query
        description: The `next_cursor` of the previous page.
        schema:
          type: string
      - name: target
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModerationActionList'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: The moderation log, newest first
      tags:
      - Moderation
    servers:
    - url: https://api.marketsdk.com
components:
  schemas:
    CreateModerationActionDto:
      type: object
      properties:
        target:
          type: string
          description: The listing, seller, or review acted on.
        action:
          type: string
          enum:
          - dismiss
          - remove_content
          - suspend_seller
          - reinstate_seller
          description: '`dismiss` closes the open flags and changes nothing else. `remove_content` removes a listing or a review; a removed review stops counting toward reputation. `suspend_seller` suspends the seller, or the seller of a listing, or a seller who wrote a review: they cannot publish or take orders, and their listings leave search. `reinstate_seller` lifts a suspension.'
        reason:
          type: string
          maxLength: 2000
          description: Why. Kept with the action.
        actor:
          type: string
          maxLength: 200
          description: Who on your team took the action, for the log.
      required:
      - target
      - action
      - reason
      - actor
    ModerationQueueObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          description: Targets with open flags, the longest waiting first. At most 100.
          type: array
          items:
            $ref: '#/components/schemas/QueueItemObject'
      required:
      - object
      - data
    ErrorEnvelope:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      required:
      - error
    FlagObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - flag
        id:
          type: string
          example: flg_034XtPDs7UJ0TXzTsdaHZa
        target_type:
          type: string
          enum:
          - listing
          - seller
          - review
        target:
          type: string
        reporter:
          type: string
        reason:
          type: string
          enum:
          - prohibited_item
          - counterfeit
          - scam
          - offensive
          - spam
          - other
        note:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - open
          - resolved
        resolution:
          type:
          - string
          - 'null'
          enum:
          - dismissed
          - content_removed
          - seller_suspended
          - null
        action:
          type:
          - string
          - 'null'
          description: The moderation action that resolved it.
        created_at:
          type: string
          format: date-time
        resolved_at:
          type:
          - string
          - 'null'
          format: date-time
      required:
      - object
      - id
      - target_type
      - target
      - reporter
      - reason
      - note
      - status
      - resolution
      - action
      - created_at
      - resolved_at
    QueueItemObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - moderation_queue_item
        target_type:
          type: string
          enum:
          - listing
          - seller
          - review
        target:
          type: string
        open_flags:
          type: number
        reasons:
          type: object
          additionalProperties:
            type: integer
          description: Open flags by reason.
        first_flagged_at:
          type: string
          format: date-time
        last_flagged_at:
          type: string
          format: date-time
      required:
      - object
      - target_type
      - target
      - open_flags
      - reasons
      - first_flagged_at
      - last_flagged_at
    FlagList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/FlagObject'
        has_more:
          type: boolean
          description: Whether another page follows.
        next_cursor:
          type:
          - string
          - 'null'
          description: Pass as `starting_after` (or `cursor` for search) to get the next page.
      required:
      - object
      - data
      - has_more
      - next_cursor
    CreateFlagDto:
      type: object
      properties:
        target:
          type: string
          description: A listing, seller, or review id.
          example: lst_034XtPDs7UJ0TXzTsdaHZa
        reporter:
          type: string
          description: 'The end user reporting it: a buyer id or a seller id.'
          example: buy_034XtPDs7UJ0TXzTsdaHZa
        reason:
          type: string
          enum:
          - prohibited_item
          - counterfeit
          - scam
          - offensive
          - spam
          - other
        note:
          type: string
          maxLength: 2000
          description: The reporter's own words.
      required:
      - target
      - reporter
      - reason
    ErrorBody:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable. Never changes once published.
          example: resource_missing
        message:
          type: string
          description: For people.
          example: No seller has that id.
        param:
          type: string
          description: The request field at fault.
          example: seller
        request_id:
          type: string
          example: req_7Gq0mR2s9xVbN4kT1pLc
      required:
      - code
      - message
      - request_id
    ModerationActionList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/ModerationActionObject'
        has_more:
          type: boolean
          description: Whether another page follows.
        next_cursor:
          type:
          - string
          - 'null'
          description: Pass as `starting_after` (or `cursor` for search) to get the next page.
      required:
      - object
      - data
      - has_more
      - next_cursor
    ModerationActionObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - moderation_action
        id:
          type: string
          example: mod_034XtPDs7UJ0TXzTsdaHZa
        target_type:
          type: string
          enum:
          - listing
          - seller
          - review
        target:
          type: string
        action:
          type: string
          enum:
          - dismiss
          - remove_content
          - suspend_seller
          - reinstate_seller
        reason:
          type: string
        actor:
          type: string
        flags_resolved:
          type: number
          description: Open flags this action resolved.
        created_at:
          type: string
          format: date-time
      required:
      - object
      - id
      - target_type
      - target
      - action
      - reason
      - actor
      - flags_resolved
      - created_at
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: API key
      type: http
      description: 'An API key: msk_test_sk_…, msk_live_sk_…, or a publishable msk_…_pk_… key where allowed.'
x-refined-from:
- marketsdk-openapi.json
- marketsdk-openapi.json
x-stripe-permissions:
- permission: accounts
  category: Core
  resource: Accounts
  level: Write
  used_for: Create sellers' connected accounts and read their status
- permission: account_links
  category: Connect
  resource: Account Links
  level: Write
  used_for: Onboarding links for sellers
- permission: transfers
  category: Connect
  resource: Transfers
  level: Write
  used_for: Release funds to a seller, and reverse them on a refund
- permission: payment_intents
  category: Core
  resource: Payment Intents
  level: Write
  used_for: Buyer payments, and cancelling unpaid ones
- permission: charges_and_refunds
  category: Core
  resource: Charges and Refunds
  level: Write
  used_for: Refunds, full and partial
- permission: checkout_sessions
  category: Checkout
  resource: Checkout Sessions
  level: Write
  used_for: Hosted checkout, and expiring unpaid sessions
- permission: identity_verification_sessions
  category: Identity
  resource: Verification Sessions and Reports
  level: Write
  used_for: Seller identity verification
- permission: disputes
  category: Core
  resource: Disputes
  level: Read
  used_for: Reading card disputes, to link them to orders
- permission: webhook_endpoints
  category: Webhook Endpoints
  resource: Webhook Endpoints
  level: Write
  used_for: Registering our endpoint on your account