{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Semantic Search & Audit",
    "description": "Find TikTok videos that match your topic with AI-powered relevance analysis, explanations and verified text excerpts. Collect live candidates, reuse datasets, or audit campaign URLs. Export JSON, CSV and a visual report.",
    "version": "1.0",
    "x-build-id": "UpidGjRvlqcF1GN9R"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/heiman~tiktok-semantic-search-audit/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-heiman-tiktok-semantic-search-audit",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/heiman~tiktok-semantic-search-audit/runs": {
      "post": {
        "operationId": "runs-sync-heiman-tiktok-semantic-search-audit",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/heiman~tiktok-semantic-search-audit/run-sync": {
      "post": {
        "operationId": "run-sync-heiman-tiktok-semantic-search-audit",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "mode": {
            "title": "Task",
            "enum": [
              "search",
              "audit"
            ],
            "type": "string",
            "description": "Search ranks and filters candidates. Audit checks every supplied canonical video URL and preserves collected records even when they fail filters.",
            "default": "search"
          },
          "query": {
            "title": "Topic to find",
            "maxLength": 2000,
            "type": "string",
            "description": "Describe the topic in your language. Required for search; optional for a coverage-only URL audit."
          },
          "source": {
            "title": "Data source",
            "enum": [
              "live",
              "dataset",
              "inline"
            ],
            "type": "string",
            "description": "Live collects TikTok candidates under your Apify account. Clockworks collection is billed separately. Reuse an existing dataset to avoid another collection charge.",
            "default": "live"
          },
          "searchQueries": {
            "title": "TikTok search terms",
            "maxItems": 10,
            "type": "array",
            "description": "Optional search variants. AI automatically creates up to three variants when this is empty. Other methods use the topic as entered. Collection stays within the candidate limit.",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 300
            },
            "default": []
          },
          "videoUrls": {
            "title": "Video URLs to audit",
            "maxItems": 200,
            "type": "array",
            "description": "Full https://www.tiktok.com/@creator/video/123... URLs. Short share links and profile URLs are rejected. Required for audit; maximum 200 distinct videos.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "datasetId": {
            "title": "Source dataset",
            "type": "string",
            "description": "Choose the existing Apify dataset to analyze. Only read access is requested. Required when source is dataset."
          },
          "videos": {
            "title": "Video records",
            "maxItems": 1000,
            "type": "array",
            "description": "Paste TikTok video objects. Supports nested Clockworks fields and flattened exports. Required when source is inline. Strings, profile objects, and error records are reported as invalid.",
            "items": {
              "type": "object"
            },
            "default": []
          },
          "maxCandidates": {
            "title": "Maximum candidates",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Maximum source rows loaded. Live search may return fewer. For audits this must cover the number of distinct requested URLs.",
            "default": 30
          },
          "maxResults": {
            "title": "Maximum search results",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Maximum ranked videos returned in search. Audit returns every requested URL unless the Actor's charge limit stops delivery.",
            "default": 20
          },
          "minRelevance": {
            "title": "Minimum relevance",
            "minimum": 0,
            "maximum": 1,
            "type": "number",
            "description": "0.7 selects directly relevant topics with AI analysis. Lower this to explore broader matches. Audit keeps every requested URL and marks filter failures.",
            "default": 0.65
          },
          "rankingEngine": {
            "title": "Ranking method",
            "enum": [
              "deepseek",
              "semantic",
              "lexical"
            ],
            "type": "string",
            "description": "AI analysis provides relevance explanations and verified text excerpts, with no API key required in the hosted Actor's default configuration. Local semantic AI works without an external key. Lexical matches words only.",
            "default": "deepseek"
          },
          "deepseekApiKey": {
            "title": "Optional AI API key",
            "type": "string",
            "description": "Leave empty to use the hosted Actor's default AI. Advanced option: a DeepSeek API key, sent only to api.deepseek.com. Usage on your own key is paid by you. Never paste a key into captions or search terms."
          },
          "includeKeywords": {
            "title": "Must contain any of these terms",
            "maxItems": 50,
            "type": "array",
            "description": "At least one term must occur in caption, hashtags, or supplied transcript. Matching ignores case and accents.",
            "items": {
              "type": "string",
              "minLength": 1
            },
            "default": []
          },
          "excludeKeywords": {
            "title": "Exclude these terms",
            "maxItems": 50,
            "type": "array",
            "description": "Reject search candidates containing any listed term. Audits retain the row with a filter reason.",
            "items": {
              "type": "string",
              "minLength": 1
            },
            "default": []
          },
          "language": {
            "title": "Caption language",
            "maxLength": 20,
            "type": "string",
            "description": "Optional source-supplied language code, such as pt or en. Unknown language fails this filter. The Actor does not guess language."
          },
          "minViews": {
            "title": "Minimum views",
            "minimum": 0,
            "type": "integer",
            "description": "Unknown view counts fail this filter when it is greater than zero. Missing metrics remain null, never invented as zero.",
            "default": 0
          },
          "publishedAfter": {
            "title": "Published on or after",
            "type": "string",
            "description": "Optional inclusive calendar date in UTC, YYYY-MM-DD. Unknown dates fail this filter."
          },
          "publishedBefore": {
            "title": "Published on or before",
            "type": "string",
            "description": "Optional inclusive calendar date in UTC, YYYY-MM-DD. Unknown dates fail this filter."
          },
          "upstreamMaxCostUsd": {
            "title": "Clockworks maximum charge (USD)",
            "minimum": 0.5,
            "maximum": 50,
            "type": "number",
            "description": "Maximum pay-per-event charge passed to the child Clockworks run. Its platform usage/storage may be additional. This is separate from the charge limit for this Actor.",
            "default": 1
          },
          "upstreamTimeoutSecs": {
            "title": "Collection timeout (seconds)",
            "minimum": 30,
            "maximum": 1800,
            "type": "integer",
            "description": "Maximum collection time. Timed-out, failed, and aborted child runs are reported as partial; their results are never claimed to be complete.",
            "default": 600
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}