openapi: 3.1.0
info:
  title: Envato Market API
  version: "3.0.0"
  description: >-
    Envato Market REST API. Provides catalog discovery, item detail, search,
    item downloads (for buyers), user account info, badges, collections, and
    author earnings/sales across Envato's per-asset marketplaces
    (ThemeForest, CodeCanyon, AudioJungle, VideoHive, GraphicRiver, 3DOcean,
    PhotoDune). Best-effort spec derived from publicly documented
    surfaces; not exhaustive.
  contact:
    name: Envato Build
    url: https://build.envato.com/api/
  license:
    name: Proprietary
servers:
  - url: https://api.envato.com
    description: Envato API production base URL
security:
  - bearerAuth: []
  - oauth2: [default]
tags:
  - name: Catalog
  - name: Items
  - name: Downloads
  - name: User
  - name: Author
  - name: Search
paths:
  /v1/market/popular:json:
    get:
      tags: [Catalog]
      summary: List popular items by site
      operationId: getPopularItems
      parameters:
        - in: query
          name: site
          required: true
          schema:
            type: string
            example: themeforest.net
      responses:
        "200":
          description: Popular items grouped by week, month, last quarter
          content:
            application/json:
              schema:
                type: object
                properties:
                  popular:
                    type: object
  /v1/market/new-files:json:
    get:
      tags: [Catalog]
      summary: List newest files for a site and category
      operationId: getNewFiles
      parameters:
        - in: query
          name: site
          required: true
          schema:
            type: string
        - in: query
          name: category
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Newest files
  /v3/market/catalog/item:
    get:
      tags: [Items]
      summary: Get item detail by ID
      operationId: getItemById
      parameters:
        - in: query
          name: id
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Item record
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Item"
  /v1/discovery/search/search/item:
    get:
      tags: [Search]
      summary: Search items in the marketplace catalog
      operationId: searchItems
      parameters:
        - in: query
          name: term
          schema:
            type: string
        - in: query
          name: site
          schema:
            type: string
        - in: query
          name: category
          schema:
            type: string
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: page_size
          schema:
            type: integer
            default: 20
        - in: query
          name: sort_by
          schema:
            type: string
            enum: [relevance, rating, sales, price, date, updated, category, name, trending]
      responses:
        "200":
          description: Paged search results
  /v3/market/buyer/download:
    get:
      tags: [Downloads]
      summary: Generate a download link for a purchased item
      operationId: getBuyerDownload
      parameters:
        - in: query
          name: item_id
          required: true
          schema:
            type: integer
            format: int64
        - in: query
          name: purchase_code
          schema:
            type: string
      responses:
        "200":
          description: Download link payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  download_url:
                    type: string
                    format: uri
  /v3/market/buyer/list-purchases:
    get:
      tags: [User]
      summary: List the authenticated buyer's purchases
      operationId: listPurchases
      parameters:
        - in: query
          name: include_all_purchases
          schema:
            type: boolean
      responses:
        "200":
          description: Purchases list
  /v1/market/private/user/account.json:
    get:
      tags: [User]
      summary: Get the authenticated user's account info
      operationId: getUserAccount
      responses:
        "200":
          description: User account
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserAccount"
  /v1/market/user:username.json:
    get:
      tags: [User]
      summary: Get a public user profile
      operationId: getUserProfile
      parameters:
        - in: query
          name: username
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Public user profile
  /v1/market/user/items-by-site:json:
    get:
      tags: [User]
      summary: Count items per site for a user
      operationId: getUserItemsBySite
      parameters:
        - in: query
          name: username
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Per-site item counts
  /v1/market/private/user/earnings-and-sales-by-month.json:
    get:
      tags: [Author]
      summary: Get the authenticated author's earnings and sales by month
      operationId: getEarningsAndSalesByMonth
      responses:
        "200":
          description: Earnings/sales history
  /v1/market/private/user/total-deposits.json:
    get:
      tags: [Author]
      summary: Get the authenticated author's total deposits
      operationId: getTotalDeposits
      responses:
        "200":
          description: Total deposits
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Personal Token
      description: >-
        Envato personal token issued from build.envato.com. Sent as
        `Authorization: Bearer <token>`.
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.envato.com/authorization
          tokenUrl: https://api.envato.com/token
          scopes:
            default: Default Envato Market scope set
  schemas:
    Item:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        site:
          type: string
        url:
          type: string
          format: uri
        author_username:
          type: string
        author_url:
          type: string
          format: uri
        author_image:
          type: string
          format: uri
        price_cents:
          type: integer
        number_of_sales:
          type: integer
        rating:
          type: number
        rating_count:
          type: integer
        published_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        tags:
          type: array
          items:
            type: string
        classification:
          type: string
        classification_url:
          type: string
          format: uri
    UserAccount:
      type: object
      properties:
        image:
          type: string
          format: uri
        firstname:
          type: string
        surname:
          type: string
        available_earnings:
          type: string
        total_deposits:
          type: string
        balance:
          type: string
        country:
          type: string