api.socialfetch.dev

{
  "description": "Standard success response envelope.",
  "properties": {
    "data": {
      "description": "Endpoint-specific response payload.",
      "properties": {
        "page": {
          "description": "Pagination state for the current response.",
          "properties": {
            "currentPage": {
              "description": "1-based page number for this response.",
              "minimum": 1,
              "type": "integer"
            },
            "hasMore": {
              "description": "Whether more product pages are likely available for this search.",
              "type": "boolean"
            },
            "nextPage": {
              "description": "Next page number to request when more results are available; otherwise null.",
              "minimum": 1,
              "nullable": true,
              "type": "integer"
            }
          },
          "required": [
            "currentPage",
            "nextPage",
            "hasMore"
          ],
          "type": "object"
        },
        "products": {
          "description": "Products returned for the requested page.",
          "items": {
            "description": "A normalized TikTok Shop search result product.",
            "properties": {
              "description": {
                "description": "Product description, when available.",
                "nullable": true,
                "type": "string"
              },
              "id": {
                "description": "TikTok Shop product identifier.",
                "minLength": 1,
                "type": "string"
              },
              "image": {
                "description": "Structured image size metadata when the image URL is available.",
                "nullable": true,
                "properties": {
                  "height": {
                    "description": "Image height in pixels, when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "url": {
                    "anyOf": [
                      {
                        "minLength": 1,
                        "type": "string"
                      },
                      {
                        "nullable": true
                      }
                    ],
                    "description": "Primary product image URL."
                  },
                  "width": {
                    "description": "Image width in pixels, when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  }
                },
                "required": [
                  "width",
                  "height",
                  "url"
                ],
                "type": "object"
              },
              "imageUrl": {
                "description": "Primary product image URL, when available.",
                "minLength": 1,
                "nullable": true,
                "type": "string"
              },
              "labels": {
                "description": "Promotional, shipping, and trust labels for the product card.",
                "items": {
                  "description": "A promotional, shipping, or trust label for a product card.",
                  "properties": {
                    "text": {
                      "description": "Label text shown for the product.",
                      "type": "string"
                    },
                    "type": {
                      "description": "TikTok Shop label type code, when available.",
                      "nullable": true,
                      "type": "integer"
                    }
                  },
                  "required": [
                    "text",
                    "type"
                  ],
                  "type": "object"
                },
                "type": "array"
              },
              "metrics": {
                "description": "Rating and sales metrics for the product.",
                "properties": {
                  "rating": {
                    "description": "Average product rating, when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "number"
                  },
                  "reviews": {
                    "description": "Number of product reviews, when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "sold": {
                    "description": "Approximate units sold, when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  }
                },
                "required": [
                  "sold",
                  "reviews",
                  "rating"
                ],
                "type": "object"
              },
              "price": {
                "description": "Displayed price data.",
                "properties": {
                  "currencyCode": {
                    "description": "Currency name or code for displayed prices, when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "currencySymbol": {
                    "description": "Currency symbol for the listed price, when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "current": {
                    "description": "Current sale price for the product, when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "discountText": {
                    "description": "Human-readable discount label, when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "original": {
                    "description": "Original or list price before discount, when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "savingText": {
                    "description": "Human-readable savings line, when available.",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "currencyCode",
                  "currencySymbol",
                  "current",
                  "original",
                  "discountText",
                  "savingText"
                ],
                "type": "object"
              },
              "shipFrom": {
                "description": "Reported ship-from location text, when available.",
                "nullable": true,
                "type": "string"
              },
              "shop": {
                "description": "Selling shop for the product.",
                "properties": {
                  "id": {
                    "description": "TikTok Shop seller identifier, when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "logoUrl": {
                    "description": "Shop logo image URL, when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "name": {
                    "description": "Shop display name, when available.",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "name",
                  "logoUrl"
                ],
                "type": "object"
              },
              "title": {
                "description": "Product title text.",
                "minLength": 1,
                "type": "string"
              },
              "trustLabel": {
                "description": "TikTok Shop trust badge label, when available.",
                "nullable": true,
                "type": "string"
              },
              "url": {
                "description": "Canonical public URL for the product page, when available.",
                "minLength": 1,
                "nullable": true,
                "type": "string"
              }
            },
            "required": [
              "id",
              "title",
              "description",
              "url",
              "imageUrl",
              "shipFrom",
              "trustLabel",
              "labels",
              "price",
              "metrics",
              "shop"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "query": {
          "description": "Search query that was evaluated for this response.",
          "type": "string"
        },
        "totalProducts": {
          "description": "Total matching products reported for the search, when available.",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "query",
        "products",
        "totalProducts",
        "page"
      ],
      "type": "object"
    },
    "meta": {
      "description": "Metadata describing the request and billing outcome.",
      "properties": {
        "cached": {
          "description": "True when served from shared response cache. Credits still apply (full endpoint price); Age header may be present.",
          "type": "boolean"
        },
        "creditsCharged": {
          "description": "Credits charged for this request.",
          "minimum": 0,
          "type": "integer"
        },
        "requestId": {
          "description": "Unique request identifier for tracing this API call.",
          "minLength": 1,
          "type": "string"
        },
        "version": {
          "description": "Public API version that served the response.",
          "enum": [
            "v1"
          ],
          "type": "string"
        }
      },
      "required": [
        "requestId",
        "creditsCharged",
        "version"
      ],
      "type": "object"
    }
  },
  "required": [
    "data",
    "meta"
  ],
  "type": "object"
}