{
  "openapi": "3.0.1",
  "info": {
    "title": "OLX Jobs Scraper — 7 countries (PL, RO, PT, UA, UZ, BG, KZ)",
    "description": "Scrape jobs from 7 OLX country sites (olx.pl, olx.ro, olx.pt, olx.ua, olx.uz, olx.bg, olx.kz). Pick country via input. City names in local Cyrillic or Latin. Structured salary, GPS, contract type, work mode, experience, employer, incremental change tracking.",
    "version": "0.1",
    "x-build-id": "8TKLL3VClFXA8GsMV"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/blackfalcondata~olx-jobs-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-blackfalcondata-olx-jobs-scraper",
        "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/blackfalcondata~olx-jobs-scraper/runs": {
      "post": {
        "operationId": "runs-sync-blackfalcondata-olx-jobs-scraper",
        "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/blackfalcondata~olx-jobs-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-blackfalcondata-olx-jobs-scraper",
        "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",
        "required": [
          "country"
        ],
        "properties": {
          "country": {
            "title": "🌍 Country",
            "enum": [
              "PL",
              "RO",
              "PT",
              "UA",
              "UZ",
              "BG",
              "KZ"
            ],
            "type": "string",
            "description": "OLX country site to scrape.",
            "default": "PL"
          },
          "query": {
            "title": "🔍 Search Term(s)",
            "type": "string",
            "description": "Keyword(s) (e.g. \"developer\", \"programista\", \"vânzător\"). Use JSON array [\"q1\", \"q2\"] to iterate multiple keywords. Leave empty to browse all postings in the chosen category."
          },
          "startUrls": {
            "title": "🔗 Start URLs",
            "type": "array",
            "description": "Paste country-specific OLX job search URLs (e.g. olx.pl/praca/..., olx.ro/locuri-de-munca/..., olx.ua/uk/rabota/...). Each URL becomes its own task; results merged + deduped across all URLs.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "categoryId": {
            "title": "🏷️ Category ID",
            "type": "string",
            "description": "OLX category ID. PL/RO use parent ID 4, PT uses 190; UA/UZ/BG/KZ have fragmented taxonomy with multiple jobs subcategory IDs (the actor fans out across them automatically). Use JSON array to iterate multiple. Subcategory IDs (e.g. 2515 = IT on olx.pl) extend coverage beyond the 1000-offer cap per category. Leave empty for the country's default jobs scope."
          },
          "cityId": {
            "title": "📍 City ID (advanced)",
            "minimum": 0,
            "type": "integer",
            "description": "OLX numeric city ID (e.g. 17871=Warszawa, 1=Bucuresti, 268=Київ, 4=Toshkent, 8771=София, 1=Алматы). Trump card — when set, cityName, lat/lon, and country are ignored. City IDs are country-scoped — pair with the matching country. Most users should leave this empty and use cityName instead."
          },
          "cityName": {
            "title": "🏙️ City Name",
            "type": "string",
            "description": "City name in local script or Latin (e.g. \"Warszawa\", \"Bucuresti\", \"Київ\" / \"Kyiv\", \"Toshkent\", \"София\" / \"Sofia\", \"Алматы\" / \"Almaty\"). Resolved to OLX city ID via the chosen country's dictionary. Country-aware transliteration handles Cyrillic (Ukrainian National 2010, Bulgarian Streamlined 2009, Russian + Kazakh for KZ). Ignored if cityId is set."
          },
          "lat": {
            "title": "🌐 Latitude",
            "minimum": -90,
            "maximum": 90,
            "type": "number",
            "description": "GPS latitude. Pair with lon. Ignored if cityId or cityName is set. Resolved to nearest known OLX city by GPS-bbox or distance tiers (5/20/50km)."
          },
          "lon": {
            "title": "🌐 Longitude",
            "minimum": -180,
            "maximum": 180,
            "type": "number",
            "description": "GPS longitude. Pair with lat."
          },
          "radiusKm": {
            "title": "📏 Search Radius (km)",
            "minimum": 0,
            "maximum": 500,
            "type": "integer",
            "description": "Search radius in kilometers around the resolved city. 0–500. OLX-native unit. Mutually exclusive with radiusMiles."
          },
          "radiusMiles": {
            "title": "📏 Search Radius (miles)",
            "minimum": 0,
            "maximum": 310,
            "type": "integer",
            "description": "Search radius in miles. Converted to OLX km internally. Mutually exclusive with radiusKm."
          },
          "allowLowConfidence": {
            "title": "🔓 Allow Low-Confidence Resolutions",
            "type": "boolean",
            "description": "When true, accept fuzzy-match or GPS-within-50km city resolutions instead of failing. Default false (fail loudly to prevent silent wrong-city results).",
            "default": false
          },
          "compactKeepResolvedLocation": {
            "title": "🗺️ Keep resolvedLocation in Compact Mode",
            "type": "boolean",
            "description": "By default, compact mode omits resolvedLocation. Set true to keep it for audit even in compact output.",
            "default": false
          },
          "distance": {
            "title": "🎯 Distance — DEPRECATED (use radiusKm)",
            "minimum": 0,
            "maximum": 500,
            "type": "integer",
            "description": "Legacy distance field in km. Deprecated — use radiusKm instead. Kept for back-compat with existing runs."
          },
          "maxResults": {
            "title": "💯 Max Results",
            "minimum": 0,
            "maximum": 1000,
            "type": "integer",
            "description": "Maximum total items to emit (0 = unlimited). API hard-caps at 1000 per categoryId.",
            "default": 50
          },
          "maxPages": {
            "title": "📄 Max Pages",
            "minimum": 0,
            "maximum": 50,
            "type": "integer",
            "description": "Cap pagination at this many SERP pages (0 = unlimited).",
            "default": 0
          },
          "includeDetails": {
            "title": "📋 Include Full Details",
            "type": "boolean",
            "description": "No-op for this actor — OLX SERP already returns full job data identical to detail endpoint. Kept for input-schema compatibility.",
            "default": false
          },
          "includeKeywords": {
            "title": "✅ Include Keywords",
            "type": "object",
            "description": "Post-fetch filter: only emit jobs whose title or description contains at least one of these keywords. Example: { \"keywords\": [\"react\", \"node\"], \"matchTitle\": true, \"matchDescription\": true }."
          },
          "excludeKeywords": {
            "title": "❌ Exclude Keywords",
            "type": "object",
            "description": "Post-fetch filter: drop jobs whose title or description contains any of these keywords. Same shape as includeKeywords."
          },
          "fromDate": {
            "title": "📅 From Date",
            "type": "string",
            "description": "ISO date (YYYY-MM-DD) — drop jobs posted before this date."
          },
          "toDate": {
            "title": "📅 To Date",
            "type": "string",
            "description": "ISO date (YYYY-MM-DD) — drop jobs posted after this date."
          },
          "maxAgeMinutes": {
            "title": "⏱️ Max Age (minutes)",
            "minimum": 0,
            "type": "integer",
            "description": "Drop jobs older than N minutes (0 = no limit). Useful for tight monitoring loops.",
            "default": 0
          },
          "customFilters": {
            "title": "🔧 Custom Filters",
            "type": "array",
            "description": "Array of {field, op, value} rules applied to each output record. Operators: includes, notIncludes, equals, notEquals, gt, gte, lt, lte.",
            "default": []
          },
          "descriptionMaxLength": {
            "title": "✂️ Description Max Length",
            "minimum": 0,
            "type": "integer",
            "description": "Truncate description to N chars. 0 = no truncation.",
            "default": 0
          },
          "descriptionFormat": {
            "title": "📝 Description Format",
            "enum": [
              "all",
              "text",
              "html",
              "markdown"
            ],
            "type": "string",
            "description": "`all` keeps every variant (default). `text` / `html` / `markdown` keep only one.",
            "default": "all"
          },
          "compact": {
            "title": "📦 Compact Output",
            "type": "boolean",
            "description": "Emit only core fields (for AI-agent / MCP workflows).",
            "default": false
          },
          "excludeEmptyFields": {
            "title": "🧹 Exclude Empty Fields",
            "type": "boolean",
            "description": "Drop null / empty-string / empty-array fields from each record.",
            "default": false
          },
          "incrementalMode": {
            "title": "♻️ Incremental Mode",
            "type": "boolean",
            "description": "Track changes between runs. Compares prior state and emits only NEW / UPDATED / EXPIRED entries.",
            "default": false
          },
          "stateKey": {
            "title": "🔑 State Key",
            "type": "string",
            "description": "Stable identifier for the tracked search universe. Auto-generated if empty."
          },
          "emitUnchanged": {
            "title": "♻️ Emit Unchanged",
            "type": "boolean",
            "description": "Also emit unchanged jobs (incrementalMode only).",
            "default": false
          },
          "emitExpired": {
            "title": "⚰️ Emit Expired",
            "type": "boolean",
            "description": "Also emit expired jobs (incrementalMode only).",
            "default": false
          },
          "skipReposts": {
            "title": "🚫 Skip Reposts",
            "type": "boolean",
            "description": "Skip jobs whose content matches an expired job from a prior run.",
            "default": false
          },
          "telegramToken": {
            "title": "🔑 Telegram Bot Token",
            "type": "string",
            "description": "Bot token from @BotFather."
          },
          "telegramChatId": {
            "title": "💬 Telegram Chat ID",
            "type": "string",
            "description": "Chat or channel ID."
          },
          "discordWebhookUrl": {
            "title": "🎮 Discord Webhook URL",
            "type": "string",
            "description": "Discord incoming webhook URL."
          },
          "slackWebhookUrl": {
            "title": "💼 Slack Webhook URL",
            "type": "string",
            "description": "Slack incoming webhook URL."
          },
          "whatsappAccessToken": {
            "title": "📱 WhatsApp Access Token",
            "type": "string",
            "description": "WhatsApp Cloud API token."
          },
          "whatsappPhoneNumberId": {
            "title": "📞 WhatsApp Phone Number ID",
            "type": "string",
            "description": "Your WhatsApp Business phone-number ID."
          },
          "whatsappTo": {
            "title": "📲 WhatsApp Recipient",
            "type": "string",
            "description": "Recipient phone in E.164 without +."
          },
          "webhookUrl": {
            "title": "🪝 Generic Webhook URL",
            "type": "string",
            "description": "Receives JSON POST with {metadata, items} after each run."
          },
          "webhookHeaders": {
            "title": "📋 Webhook Headers",
            "type": "object",
            "description": "Custom headers, e.g. {\"Authorization\":\"Bearer ...\"}."
          },
          "notificationLimit": {
            "title": "📊 Max Jobs Per Notification",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Maximum jobs per notification message.",
            "default": 5
          },
          "notifyOnlyChanges": {
            "title": "🔄 Notify Only New/Updated",
            "type": "boolean",
            "description": "In incremental mode, only notify for NEW + UPDATED.",
            "default": false
          },
          "includeRunMetadata": {
            "title": "🧾 Include Run Metadata",
            "type": "boolean",
            "description": "Add matchedStartUrls provenance to each record (when startUrls mode).",
            "default": false
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}