Moving from v4 to v5 V5 (beta)

The order for switching v4 calls to v5, and what changed.

v4 keeps working as it is (no end date is set, and we will tell you first when one is). There is no rush to move, but you need v5 to give a bot several plans or to read which plan made a collection. The same API key is used.

First of all: the default of save_to_settings flipped

The default of v4 settings.param_save was false (apply to this collection only). The default of v5 save_to_settings is true: the inputs you send are saved to the bot settings, and the automatic conditions of the plan that follows the bot settings change too (the same behavior as the screen). Code that used the v4 "this once" behavior must add save_to_settings: false explicitly when you move it.

Path mapping

v4v5
GET /v4/api/health, /meGET /v5/api/health, /me (same)
GET /schedulesGET /bots
(none)GET /bots/{bot_id}: one bot
GET /schedules/{id}/param_infoGET /bots/{bot_id}/inputs (field definitions) + GET /bots/{bot_id}/settings (current values)
PATCH /schedules/{id}: paramsPATCH /bots/{bot_id}/settings: inputs
PATCH /schedules/{id}: settings.unionPATCH /bots/{bot_id}/settings: union
PATCH /schedules/{id}: settings.periodPlans /bots/{bot_id}/plans, /plans/{plan_id}
PUT /schedules/{id}/excel_paramPUT /bots/{bot_id}/settings/excel
POST /schedules/{id}/collectionsPOST /bots/{bot_id}/collections
POST /collections/bulkPOST /collections/bulk
GET /schedules/{id}/schedule_resultsGET /datasets?bot_id={bot_id}
GET /schedule_results/{id}GET /datasets/{dataset_id}
POST /schedule_results/{id}/retry, /cancelPOST /datasets/{dataset_id}/retry, /cancel
GET /schedule_results/{id}/resultsGET /datasets/{dataset_id}/results
GET /schedules/{id}/resultsNo matching path. Find the latest dataset with GET /datasets?bot_id=…&limit=1 and read /datasets/{dataset_id}/results.
POST /commerce/schedulesNot in v5 (keep using it on v4).

Resource and field name mapping

v4v5Note
schedules, schedule_idbots, bot_id (id in responses)The bot ID value is the same.
schedule_results, schedule_result_iddatasets, dataset_id (id in responses)The number is the same.
param_infoinputsDefinitions are at /inputs and values at /settings.
paramsinputsKeys stay paramN or alias.
settings.param_savesave_to_settingsDefault flips from false to true
settings.periodplans (when)See the table below.
sr_statusstatusThe values changed too. See the table below.
SCHEDULE_NOT_FOUND, SCHEDULE_RESULT_NOT_FOUNDBOT_NOT_FOUND, DATASET_NOT_FOUNDOther error code names are unchanged.

settings.period → plans

In v4 a bot had a single plan (manual, hour or day). In v5 you create plans as plans and give when the schedule.

v4 <code>settings.period</code>v5
manualTurn the plan off with PATCH { "enabled": false }.
hour{ "type": "interval", "minutes": 60 }
day{ "type": "daily", "times": ["00:00"] }

Status value mapping

v5 returns one English code only. The Korean and English labels that v4 sometimes returned (완료, Complete and so on) are gone.

v4 <code>sr_status</code>v5 <code>status</code>
readywaiting
runningrunning
retryretrying
finish, completedone (attention when a notice is attached)
canceling, canceledcanceling, canceled
(failed collection)failed: newly distinguished in v5.

What changed

  1. There are several plans. The single settings.period of v4 became several plans. Each plan runs with its own conditions, and only plan 1 follows the bot settings. Datasets and webhooks tell you which plan it was (trigger, plan) and the conditions used (inputs). Multiple plans are opened per account, so when they are not open the plan paths return 404.
  2. An idempotency key is required. Starting a collection, running a plan now, bulk collection, creating a plan and retry give 400 without the Idempotency-Key header. See the rules.
  3. There is no Excel collection yet. Uploading Excel (PUT /bots/{bot_id}/settings/excel) works, but collecting for a bot with input_mode: excel gives EXCEL_NOT_SUPPORTED_YET. Keep using v4 for bots that collect with Excel.
  4. Fields always have the same shape. A missing value arrives as null or an empty array instead of being left out.
  5. A new collection can overlap. You can start a new collection even if the previous one has not finished (ALREADY_RUNNING is for retry only).

Example of changing a call

The same "collect this once with this keyword" written in v4 and in v5.

v4 
# v4
curl -X POST 'https://www.hashscraper.com/v4/api/schedules/8f3a7c1e9b5d24f6/collections' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "params": { "param1": "sneakers" }, "settings": { "param_save": false } }'
v5 
curl -X POST 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/collections' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "inputs": {
    "param1": "sneakers"
  },
  "save_to_settings": false
}'
v4 
# v4
curl 'https://www.hashscraper.com/v4/api/schedule_results/239758028' \
  -H 'Authorization: Bearer YOUR_API_KEY'
v5 
curl 'https://www.hashscraper.com/v5/api/datasets/239758028' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Checklist when you move

  • Did you change the address /v4/api → /v5/api and the paths and field names as in the tables above?
  • Did you add save_to_settings: false to collection requests that used the "this once" behavior?
  • Do collection starts, plan creation and retry send a new Idempotency-Key per request, reusing a key only inside the retry loop?
  • Do you branch on the new status values (done, waiting, retrying, attention, failed)?
  • Do you branch errors on code and handle the new error codes?
  • Can the side that receives your webhook handle the new fields (trigger, plan, inputs)? (Existing fields are unchanged.)

Related guides