Bulk add via API

Use the API when your system regularly produces new links to capture. It reuses a configuration and submits new tasks. For occasional pasted links, use Bulk add directly. Your collectors’ browser extensions execute the tasks.

Open the full API reference

Requirements

Bulk tasks require a Team plan, team write access and active collector seats. Complete one manual capture with the same configuration first. Collectors need the latest extension and a signed-in session on the source website. Tasks wait when all collectors are offline. Expired logins and verification prompts need attention in the relevant browser.

Get an API Key and App ID

Open Settings → API in the target team and copy your API Key and App ID. Keep the key on your server, out of web or mobile clients. Exchange it for a short-lived token:

curl -X POST 'https://api.scoutary.ai/api/open-auth/token' \
  -H 'Content-Type: application/json' \
  -d '{"apiKey":"YOUR_API_KEY","appId":"YOUR_APP_ID","scope":["open-scout:bulk-add"]}'

Read data.accessToken and send it as Authorization: Bearer on subsequent requests. Use the same App ID throughout. For development or testing, use the server address shown in that environment’s API settings and configuration dialog.

Export a reusable configuration

In Bulk add, finish selecting links, a recipe and business settings. For dataset capture, choose a saved write rule first.

1. At confirmation, select “Add the same tasks through the API”.

2. Copy the template from “Get API configuration” and save it as task.json. Exporting does not create tasks. The template contains no API Key, cookies or recipe implementation.

For each new batch, fill urls and generate a new requestKey. Each entry must be one complete HTTP(S) URL; a batch accepts up to 500. Mixed share text is not accepted by the API. Keep the exported recipe key, write rule and other settings. Submit different recipes or write rules separately.

Submit and track progress

Watch, Discover and Extract use the same submission endpoint:

curl -X POST 'https://api.scoutary.ai/api/open/scout/bulk-add/create?appId=YOUR_APP_ID' \
  -H 'Authorization: Bearer YOUR_SHORT_LIVED_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-binary @task.json

New templates use templateVersion: 2. Common parameters are requestKey, urls and optional collectorUserIds; business settings are stored in config.

Watch / Discover: keep the exported config.kind, recipeKey and options. If the selected recipe has no key, opening API configuration prepares it on demand. Wait until the complete JSON is available; retry if preparation fails. Ordinary saving and collection do not allocate a key.
For an exact version, use config.recipeId instead of recipeKey; revision is optional and, when supplied, must match that ID. If both ID and key are supplied, an available ID takes priority. Only a missing or retired ID can fall back to the supplied key; permission, input and revision errors do not select another recipe.
Extract: config contains only kind: "extract", ruleId and configVersion. The server resolves the target dataset and exact source recipe from the saved rule. Export a fresh configuration if the rule changes. A recipe key moving to a newer version does not update this rule; review the new source and field mappings before saving an explicit rule upgrade.

A new key-only task resolves the current binding when accepted. Replaying the same requestKey and identical body, waiting for it or retrying its failed items keeps the accepted recipe and rule snapshots. Create a new task with a new request key to resolve the current binding. Callers do not look up replacement recipe IDs.

All three task types return the batch ID in data.id and a progress page in data.progressUrl. Extract also returns the target data.datasetId. Create datasets and configure field mappings in the UI first.

HTTP 202 means accepted, not captured or written. Save data.progressUrl and offer a “View capture progress” link in your system. That page shows each URL’s results and failure reasons.

Retry and recover

Situation	Action
No response after submission	Retry the identical body with the same `requestKey` to avoid creating another batch. Reusing the key with a different body returns 409.
New batch of links	Use a new `requestKey`. Split batches larger than 500 URLs.
Offline collector, expired login or verification	Resolve it in the collector’s browser, then follow the progress page’s recovery or retry action.
Recipe, rule or destination settings changed	Review the settings and export a fresh configuration.
Insufficient access or quota	Restore team access, seats or quota, then follow the progress page’s instructions.
HTTP 429	Wait for the number of seconds in `Retry-After` before retrying.

See the API reference above for complete request fields, response schemas and error codes.