Save to Box
Pricing
Pay per usage
Send the results of any Apify Actor to a Box folder as Excel, CSV or JSON, plus screenshots, PDFs and other files. Attach as an integration and every run lands in Box automatically.
Pricing
Pay per usage
Rating
0.0
(0)
Developer
Petros Hong
Maintained by CommunityActor stats
0
Bookmarked
2
Total users
1
Monthly active users
4 days ago
Last modified
Categories
Share
{ "actorSpecification": 1, "name": "save-to-box", "title": "Save to Box", "description": "Send the results of any Apify Actor straight to a Box folder as Excel, CSV or JSON, plus any files the run produced (screenshots, PDFs, reports). Attach it as an integration and every run lands in Box automatically.", "version": "1.0", "input": "./input_schema.json", "dockerfile": "../Dockerfile", "output": "./output_schema.json", "storages": { "dataset": "./dataset_schema.json" }}{ "$schema": "https://apify.com/schemas/v1/dataset.ide.json", "actorSpecification": 1, "fields": {}, "views": { "overview": { "title": "Uploaded files", "transformation": { "fields": [ "name", "kind", "sizeBytes", "newVersion", "url", "sharedLink" ] }, "display": { "component": "table", "properties": { "name": { "label": "File", "format": "text" }, "kind": { "label": "Type", "format": "text" }, "sizeBytes": { "label": "Size (bytes)", "format": "number" }, "newVersion": { "label": "New version of existing file", "format": "boolean" }, "url": { "label": "Open in Box", "format": "link" }, "sharedLink": { "label": "Shared link", "format": "link" } } } } }}{ "title": "Save to Box", "type": "object", "schemaVersion": 1, "properties": { "folderId": { "title": "Box folder ID", "type": "string", "editor": "textfield", "description": "Required to upload. Where files go. Open the folder in Box: the ID is the number at the end of the URL (app.box.com/folder/<b>123456789</b>). The Box app must have access to this folder (see README)." }, "boxClientId": { "title": "Box client ID", "type": "string", "editor": "textfield", "sectionCaption": "Box connection", "sectionDescription": "From your Box Platform app (Client Credentials Grant). Or, to just try it out, paste a Box developer token below and leave these empty.", "description": "On your app's page in the Box Developer Console, open the App Details panel (icon at the top right, next to ⋯) and click Copy next to Client ID." }, "boxClientSecret": { "title": "Box client secret", "type": "string", "editor": "textfield", "isSecret": true, "description": "Same panel: click Fetch Secret next to Client Secret. Stored encrypted, never shown in logs." }, "boxSubjectType": { "title": "Connect as", "type": "string", "editor": "select", "enum": [ "enterprise", "user" ], "enumTitles": [ "App service account (enterprise)", "A specific Box user" ], "default": "enterprise", "description": "Service account: files are owned by the app; share the target folder with the app's service account. Specific user: files are owned by that user (the app needs 'Generate user access tokens')." }, "boxSubjectId": { "title": "Enterprise ID or user ID", "type": "string", "editor": "textfield", "description": "Enterprise ID (Box Admin Console > Account & Billing), or the Box user ID if 'Connect as' is a specific user." }, "boxDeveloperToken": { "title": "Developer token (testing only)", "type": "string", "editor": "textfield", "isSecret": true, "description": "Optional, for a quick test only: a 60-minute developer token from the Box Developer Console. It connects as you. Use client ID + secret for anything automatic." }, "formats": { "title": "Dataset formats", "type": "array", "editor": "select", "sectionCaption": "What to save", "items": { "type": "string", "enum": [ "xlsx", "csv", "json", "jsonl", "xml", "html" ], "enumTitles": [ "Excel (.xlsx)", "CSV", "JSON", "JSON Lines", "XML", "HTML table" ] }, "default": [ "xlsx" ], "description": "One file per format with all dataset items. Leave empty to skip the dataset." }, "fields": { "title": "Only these fields", "type": "array", "editor": "stringList", "description": "Optional. Keep only these columns (e.g. title, url, price). Empty = all fields." }, "saveFiles": { "title": "Also save files from the run", "type": "boolean", "default": false, "description": "Upload records from the run's key-value store, e.g. screenshots, PDFs, HTML snapshots or reports. INPUT and internal state records are skipped." }, "fileKeyPrefix": { "title": "File key prefix filter", "type": "string", "editor": "textfield", "description": "Optional. Only upload key-value store records whose key starts with this (e.g. 'screenshot')." }, "maxFiles": { "title": "Max files per run", "type": "integer", "default": 200, "minimum": 1, "maximum": 5000, "description": "Safety cap on how many key-value store files are uploaded per run." }, "fileName": { "title": "File name", "type": "string", "editor": "textfield", "sectionCaption": "Naming and organisation", "default": "{actor} {date} {time}", "description": "Variables: {actor}, {date}, {time}, {runId}. Extension is added. Tip: use a fixed name like '{actor} results' to keep ONE file whose Box version history holds every run." }, "subfolder": { "title": "Subfolder", "type": "string", "editor": "textfield", "description": "Optional. Create/use a subfolder, e.g. '{actor}' or '{date}' or '{actor}/{date}'. Empty = save straight into the folder." }, "sharedLink": { "title": "Create shared link", "type": "string", "editor": "select", "enum": [ "none", "collaborators", "company" ], "enumTitles": [ "No", "People in the folder", "Anyone in my company" ], "default": "none", "description": "Optionally create a Box shared link on each uploaded file (returned in the output)." }, "uploadEmpty": { "title": "Upload when the dataset is empty", "type": "boolean", "default": false, "description": "Off by default, so runs that found nothing do not create empty files in Box." }, "datasetId": { "title": "Dataset", "type": "string", "editor": "resourcePicker", "resourceType": "dataset", "resourcePermissions": [ "READ" ], "sectionCaption": "Source (filled in automatically when used as an integration)", "description": "When attached as an integration this is the triggering run's dataset ({{resource.defaultDatasetId}})." }, "keyValueStoreId": { "title": "Key-value store", "type": "string", "editor": "resourcePicker", "resourceType": "keyValueStore", "resourcePermissions": [ "READ" ], "description": "When attached as an integration this is the triggering run's store ({{resource.defaultKeyValueStoreId}})." } }}{ "$schema": "https://apify.com/schemas/v1/output.ide.json", "actorOutputSchemaVersion": 1, "title": "Save to Box output", "properties": { "uploadedFiles": { "type": "string", "title": "Files uploaded to Box", "template": "{{links.apiDefaultDatasetUrl}}/items?view=overview" }, "summary": { "type": "string", "title": "Summary (Box folder link)", "template": "{{links.apiDefaultKeyValueStoreUrl}}/records/OUTPUT" } }}1// Save to Box: an integration-ready Apify Actor.2// Attach it to any Actor (Integrations tab) and each run's dataset (+ optional files) lands in a Box folder.3import { Actor, log } from 'apify';4import { createHash } from 'node:crypto';5
6await Actor.init();7const input = (await Actor.getInput()) ?? {};8const clean = (v) => (typeof v === 'string' ? v.trim() : v);9
10const fail = async (msg) => {11 log.error(msg);12 await Actor.fail(msg);13};14
15// ---------------------------------------------------------------- source run (integration payload or manual input)16const resource = input.payload?.resource || {};17const datasetId = clean(input.datasetId) || resource.defaultDatasetId;18const kvStoreId = clean(input.keyValueStoreId) || resource.defaultKeyValueStoreId;19const runId = resource.id || '';20const folderId = String(clean(input.folderId) || '').replace(/^.*\/folder\//, '').replace(/\D.*$/, '');21
22// Not configured at all (e.g. a first click on Start, or Apify Store's daily health check with default input):23// explain the setup instead of failing. Any partially configured input still fails loudly below.24const hasBoxAuth = clean(input.boxDeveloperToken) || (clean(input.boxClientId) && clean(input.boxClientSecret));25if (!folderId && !hasBoxAuth && !datasetId && !kvStoreId) {26 const steps = [27 '1) Create a Box Platform app (Server Authentication, Client Credentials Grant) and copy its Client ID and Client Secret from the App Details panel.',28 '2) Fill in "Box folder ID" plus the Box connection fields (or a developer token for a quick test).',29 '3) Open any Actor or task > Integrations > Add integration > Save to Box, so every run lands in Box automatically.',30 ];31 log.info(`Save to Box is not configured yet, so nothing was uploaded. To set it up:\n${steps.join('\n')}`);32 await Actor.pushData({ status: 'not-configured', message: 'Save to Box is installed but not configured yet. See the README for the 5-minute setup.', steps });33 await Actor.exit({ statusMessage: 'Not configured yet: add a Box folder ID and Box connection (see README). Nothing was uploaded.' });34}35
36if (!folderId) await fail('Set "Box folder ID" (the number at the end of the folder URL in Box).');37if (!datasetId && !(input.saveFiles && kvStoreId)) {38 await fail('Nothing to save: no dataset given. Attach this Actor as an integration to another Actor, or pick a dataset under "Source".');39}40if (resource.status && resource.status !== 'SUCCEEDED') log.warning(`Source run finished with status ${resource.status}; saving whatever it produced.`);41
42// Actor name for file names (best effort; limited-permission token may not read other Actors)43let actorName = clean(input.actorName) || '';44if (!actorName && resource.actId) {45 try {46 const act = await Actor.apifyClient.actor(resource.actId).get();47 actorName = act?.title || act?.name || '';48 } catch { /* not allowed or not found */ }49}50if (!actorName && datasetId) {51 try {52 const ds = await Actor.apifyClient.dataset(datasetId).get();53 actorName = ds?.name || '';54 } catch { /* ignore */ }55}56actorName ||= resource.actId ? `actor-${resource.actId}` : 'apify';57
58const started = resource.startedAt ? new Date(resource.startedAt) : new Date();59const vars = {60 actor: actorName.replace(/[\\/:*?"<>|]+/g, '-').trim(),61 date: started.toISOString().slice(0, 10),62 time: started.toISOString().slice(11, 16).replace(':', ''),63 runId: runId || 'manual',64};65const fill = (tpl) => String(tpl).replace(/\{(\w+)\}/g, (m, k) => vars[k] ?? m).replace(/[\\:*?"<>|]+/g, '-').trim();66
67// ---------------------------------------------------------------- Box auth68const BOX = process.env.BOX_API_BASE || 'https://api.box.com/2.0';69const UPLOAD = process.env.BOX_UPLOAD_BASE || 'https://upload.box.com/api/2.0';70async function getToken() {71 // Credentials come only from the user's own input (never from Actor env vars, so a public Actor can't leak the owner's Box).72 const dev = clean(input.boxDeveloperToken);73 const id = clean(input.boxClientId);74 const secret = clean(input.boxClientSecret);75 const subjectType = input.boxSubjectType || 'enterprise';76 const subjectId = clean(input.boxSubjectId);77 if (id && secret && subjectId) {78 const res = await fetch(`${process.env.BOX_OAUTH_BASE || 'https://api.box.com'}/oauth2/token`, {79 method: 'POST',80 headers: { 'Content-Type': 'application/x-www-form-urlencoded' },81 body: new URLSearchParams({82 grant_type: 'client_credentials', client_id: id, client_secret: secret,83 box_subject_type: subjectType, box_subject_id: subjectId,84 }),85 });86 const json = await res.json().catch(() => ({}));87 if (res.ok) return json.access_token;88 const hint = {89 invalid_client: 'Client ID or secret is wrong (copy them again from the Box Developer Console).',90 unauthorized_client: 'The app is not authorized in this enterprise yet: a Box admin must approve it (Admin Console > Integrations > Platform Apps Manager), and for "A specific Box user" the app needs "Generate user access tokens".',91 invalid_grant: `The ${subjectType} ID looks wrong or does not belong to this app's enterprise.`,92 }[json.error] || '';93 throw new Error(`Box sign-in failed (${res.status} ${json.error || ''}). ${hint}`.trim());94 }95 if (dev) return dev;96 throw new Error('No Box connection: fill in client ID, client secret and enterprise/user ID (or a developer token for a quick test).');97}98
99let auth;100try {101 auth = { Authorization: `Bearer ${await getToken()}` };102} catch (e) {103 await fail(e.message);104}105
106async function box(path, opts = {}) {107 // Retries Box rate limits (429), temporary server errors (5xx) and "still processing" (202 + Retry-After),108 // so busy accounts and big uploads don't fail on a transient hiccup.109 for (let attempt = 1; ; attempt++) {110 let res;111 try {112 res = await fetch(path.startsWith('http') ? path : `${BOX}${path}`, {113 ...opts,114 headers: { ...auth, ...(opts.json ? { 'Content-Type': 'application/json' } : {}), ...opts.headers },115 body: opts.json ? JSON.stringify(opts.json) : opts.body,116 });117 } catch (e) {118 if (attempt >= 5) throw e;119 await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));120 continue;121 }122 const retryAfter = Number(res.headers.get('retry-after')) || 0;123 const transient = res.status === 429 || res.status >= 500 || (res.status === 202 && retryAfter);124 if (transient && attempt < 6) {125 const wait = Math.min(60, retryAfter || 2 ** attempt) * 1000;126 log.warning(`Box ${res.status} on ${opts.method || 'GET'} ${path.replace(/\?.*/, '')}; retrying in ${wait / 1000}s (attempt ${attempt}/5)`);127 await res.arrayBuffer().catch(() => {});128 await new Promise((r) => setTimeout(r, wait));129 continue;130 }131 const text = await res.text();132 let json;133 try { json = text ? JSON.parse(text) : {}; } catch { json = { raw: text }; }134 if (!res.ok) {135 const err = new Error(`Box ${opts.method || 'GET'} ${path.replace(/\?.*/, '')} -> ${res.status} ${json.code || ''}: ${json.message || text.slice(0, 200)}`);136 err.status = res.status;137 err.json = json;138 throw err;139 }140 return json;141 }142}143
144// ---------------------------------------------------------------- check the folder, explain access problems clearly145let me;146try {147 me = await box('/users/me?fields=login,name');148} catch (e) {149 await fail(`Box rejected the token: ${e.message}`);150}151let target;152try {153 target = await box(`/folders/${folderId}?fields=name,path_collection,permissions`);154} catch (e) {155 if (e.status === 404 || e.status === 403) {156 await fail(`Box folder ${folderId} is not visible to the account "${me.name}" (${me.login}). In Box, open the folder > Share > Invite people, add ${me.login} as Editor, then run again.`);157 }158 await fail(e.message);159}160if (target.permissions && target.permissions.can_upload === false) {161 await fail(`"${me.login}" can see folder "${target.name}" but cannot upload. Give it Editor (or Uploader) access in Box.`);162}163log.info(`Connected to Box as ${me.name} (${me.login}); target folder "${target.name}" (${folderId}).`);164
165// ---------------------------------------------------------------- helpers166async function ensureFolder(parentId, name) {167 try {168 return (await box('/folders', { method: 'POST', json: { name, parent: { id: parentId } } })).id;169 } catch (e) {170 const conflict = e.json?.context_info?.conflicts;171 const id = Array.isArray(conflict) ? conflict[0]?.id : conflict?.id;172 if (e.status === 409 && id) return id;173 throw e;174 }175}176
177const sha1 = (buf) => createHash('sha1').update(buf).digest('base64');178
179async function simpleUpload(parentId, name, buf, existingId) {180 const form = new FormData();181 form.append('attributes', JSON.stringify(existingId ? { name } : { name, parent: { id: parentId } }));182 form.append('file', new Blob([buf]), name);183 const url = existingId ? `${UPLOAD}/files/${existingId}/content` : `${UPLOAD}/files/content`;184 return (await box(url, { method: 'POST', body: form, headers: { 'Content-MD5': createHash('sha1').update(buf).digest('hex') } })).entries[0];185}186
187async function chunkedUpload(parentId, name, buf, existingId) {188 const session = existingId189 ? await box(`${UPLOAD}/files/${existingId}/upload_sessions`, { method: 'POST', json: { file_size: buf.length, file_name: name } })190 : await box(`${UPLOAD}/files/upload_sessions`, { method: 'POST', json: { folder_id: parentId, file_size: buf.length, file_name: name } });191 const parts = [];192 for (let offset = 0; offset < buf.length; offset += session.part_size) {193 const chunk = buf.subarray(offset, Math.min(offset + session.part_size, buf.length));194 const r = await box(session.session_endpoints.upload_part, {195 method: 'PUT', body: chunk,196 headers: {197 'Content-Type': 'application/octet-stream', Digest: `sha=${sha1(chunk)}`,198 'Content-Range': `bytes ${offset}-${offset + chunk.length - 1}/${buf.length}`,199 },200 });201 parts.push(r.part);202 log.info(` uploaded ${Math.round(((offset + chunk.length) / buf.length) * 100)}% of ${name}`);203 }204 const done = await box(session.session_endpoints.commit, { method: 'POST', json: { parts }, headers: { Digest: `sha=${sha1(buf)}` } });205 return done.entries[0];206}207
208const CHUNK_THRESHOLD = 40 * 1024 * 1024;209async function uploadFile(parentId, name, buf) {210 const up = (existingId) => (buf.length > CHUNK_THRESHOLD ? chunkedUpload : simpleUpload)(parentId, name, buf, existingId);211 try {212 return { file: await up(), versioned: false };213 } catch (e) {214 // Same name already in the folder -> upload as a new version (keeps history in Box)215 const existingId = e.json?.context_info?.conflicts?.id;216 if (e.status === 409 && existingId) return { file: await up(existingId), versioned: true };217 throw e;218 }219}220
221async function finishFile(file) {222 const description = `Saved by Apify "Save to Box" from ${actorName}${runId ? ` (run ${runId})` : ''} on ${new Date().toISOString().slice(0, 16).replace('T', ' ')} UTC`;223 const patch = { description: description.slice(0, 255) };224 if (input.sharedLink && input.sharedLink !== 'none') patch.shared_link = { access: input.sharedLink };225 try {226 const f = await box(`/files/${file.id}?fields=shared_link`, { method: 'PUT', json: patch });227 return f.shared_link?.url || null;228 } catch (e) {229 log.warning(`Could not set description/shared link on ${file.name}: ${e.message}`);230 return null;231 }232}233
234// ---------------------------------------------------------------- destination folder235let destId = folderId;236if (clean(input.subfolder)) {237 for (const part of fill(input.subfolder).split('/').map((s) => s.trim()).filter(Boolean)) destId = await ensureFolder(destId, part);238}239const baseName = (fill(input.fileName || '{actor} {date} {time}').replace(/\//g, '-').replace(/[. ]+$/, '').slice(0, 200)) || `${vars.actor} ${vars.date}`;240const results = [];241
242const record = async (kind, name, buf, { file, versioned }) => {243 const link = await finishFile(file);244 const row = {245 kind, name, sizeBytes: buf.length, boxFileId: file.id, newVersion: versioned,246 url: `https://app.box.com/file/${file.id}`, sharedLink: link,247 };248 results.push(row);249 log.info(`${versioned ? 'Updated' : 'Saved'} ${name} (${(buf.length / 1024).toFixed(1)} KB) -> ${row.url}`);250};251
252// ---------------------------------------------------------------- 1) dataset exports253const formats = Array.isArray(input.formats) ? input.formats : ['xlsx'];254if (datasetId && formats.length) {255 const ds = Actor.apifyClient.dataset(datasetId);256 let info;257 try {258 info = await ds.get();259 } catch (e) {260 await fail(`Cannot read dataset ${datasetId}: ${e.message}. If you entered it by hand, pick it with the dataset picker so this Actor is allowed to read it.`);261 }262 const count = info?.itemCount ?? 0;263 if (!count && !input.uploadEmpty) {264 log.info('Dataset is empty; nothing to upload (enable "Upload when the dataset is empty" to change this).');265 } else {266 await Actor.setStatusMessage(`Exporting ${count} items as ${formats.join(', ')}`);267 const opts = { clean: true, ...(input.fields?.length ? { fields: input.fields } : {}) };268 for (const fmt of formats) {269 const buf = Buffer.from(await ds.downloadItems(fmt, opts));270 const name = `${baseName}.${fmt}`;271 await Actor.setStatusMessage(`Uploading ${name} to Box`);272 await record(`dataset-${fmt}`, name, buf, await uploadFile(destId, name, buf));273 }274 }275}276
277// ---------------------------------------------------------------- 2) files from the key-value store278const EXT = {279 'application/pdf': 'pdf', 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif',280 'text/html': 'html', 'text/plain': 'txt', 'text/csv': 'csv', 'application/json': 'json', 'text/markdown': 'md',281 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': 'xlsx',282 'application/vnd.openxmlformats-officedocument.wordprocessingml.document': 'docx', 'application/zip': 'zip',283};284const SKIP = /^(INPUT|OUTPUT_SCHEMA|SDK_|CRAWLEE_|apify-|STATE|.*_STATE$|.*-state$)/i;285if (input.saveFiles && kvStoreId) {286 const store = Actor.apifyClient.keyValueStore(kvStoreId);287 const keys = [];288 let exclusiveStartKey;289 try {290 do {291 const page = await store.listKeys({ limit: 1000, exclusiveStartKey, ...(clean(input.fileKeyPrefix) ? { prefix: clean(input.fileKeyPrefix) } : {}) });292 keys.push(...page.items.filter((i) => !SKIP.test(i.key)));293 exclusiveStartKey = page.isTruncated ? page.nextExclusiveStartKey : undefined;294 } while (exclusiveStartKey && keys.length < (input.maxFiles ?? 200));295 } catch (e) {296 await fail(`Cannot read key-value store ${kvStoreId}: ${e.message}`);297 }298 const take = keys.slice(0, input.maxFiles ?? 200);299 if (keys.length > take.length) log.warning(`Only uploading the first ${take.length} of ${keys.length}+ files (raise "Max files per run").`);300 const filesFolder = formats.length && datasetId ? await ensureFolder(destId, `${baseName} files`) : destId;301 let n = 0;302 for (const { key } of take) {303 const rec = await store.getRecord(key, { buffer: true });304 if (!rec?.value) continue;305 const buf = Buffer.isBuffer(rec.value) ? rec.value : Buffer.from(typeof rec.value === 'string' ? rec.value : JSON.stringify(rec.value, null, 2));306 const type = String(rec.contentType || '').split(';')[0].trim();307 const ext = EXT[type] || (type.startsWith('text/') ? 'txt' : 'bin');308 const name = /\.[a-z0-9]{2,5}$/i.test(key) ? key : `${key}.${ext}`;309 await Actor.setStatusMessage(`Uploading file ${++n}/${take.length}: ${name}`);310 try {311 await record('file', name.replace(/[\\/:*?"<>|]+/g, '-'), buf, await uploadFile(filesFolder, name.replace(/[\\/:*?"<>|]+/g, '-'), buf));312 } catch (e) { log.warning(`Skipped ${key}: ${e.message}`); }313 }314}315
316// ---------------------------------------------------------------- done317await Actor.pushData(results);318const folderUrl = `https://app.box.com/folder/${destId}`;319await Actor.setValue('OUTPUT', { folderUrl, files: results });320const summary = results.length321 ? `Saved ${results.length} file${results.length > 1 ? 's' : ''} to Box folder "${target.name}"${destId !== folderId ? ' (subfolder)' : ''}: ${folderUrl}`322 : 'Nothing to upload.';323await Actor.exit({ statusMessage: summary });1import { describe, expect, it } from 'vitest';2
3describe('Example test', () => {4 it('works', () => {5 expect(1 + 1).toBe(2);6 });7});name: CI
on: pull_request: push: branches: [main, master]
jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7 - uses: actions/setup-node@v7 with: node-version: 24 cache: npm - run: npm ci - run: npm test# configurations.idea.vscode.zed
# crawlee and apify storage foldersapify_storagecrawlee_storagestorage
# installed filesnode_modules
# git folder.gitroot = true
[*]indent_style = spaceindent_size = 4charset = utf-8trim_trailing_whitespace = trueinsert_final_newline = trueend_of_line = lfquote_type = single# This file tells Git which files shouldn't be added to source control
.DS_Store.idea.vscode.zednode_modulesstoragemin-release-age=1{ "printWidth": 120, "tabWidth": 4, "singleQuote": true}1# Apify Actor project2
3This project is an Apify Actor: a serverless program packaged as a Docker image. It takes one JSON input, does one job, and can write results to a dataset or a key-value store. Entry point: `src/main.js`. Configuration: `.actor/actor.json`.4
5Before the first change, set `meta.generatedBy` in `.actor/actor.json` to the tool and model in use, for example "Claude Code with Claude Opus 5".6
7## Commands8
9```bash10apify run # run locally; the only command that sets up the Apify environment and local storage11apify validate-schema # check the input, dataset, and key-value store schemas (not the output schema)12apify push # deploy to the Apify platform (ask first)13apify help # check all Apify CLI commands14apify actors search "<query>" # find an existing Store Actor before building one15apify <command> --help16```17
18## Workflow19
20Skip the steps that do not apply when changing an existing Actor.21
221. **Implement** in `src/main.js`. Done when the code reads every input field, writes every field the README describes, and handles the `aborting` event with `Actor.on('aborting', handler)`.232. **Input schema** in `.actor/input_schema.json`. Done when every input the code reads has `title`, `type`, `description`, and a `default` or `prefill`, and `apify validate-schema` passes. Example values belong in `prefill`; `default` reaches the Actor.243. **Output schemas**: `.actor/dataset_schema.json` covering every field the code pushes, `.actor/output_schema.json`, and `.actor/key_value_store_schema.json` when the code stores records. Reference each file from `actor.json`. Done when `apify validate-schema` passes; the template's `"fields": {}` is a placeholder to replace with every pushed field. Rules are in the Reference table.254. **README.md**, the Actor's landing page on Apify Store. An Actor without one is not finished.265. **Test locally**: put input in `storage/key_value_stores/default/INPUT.json`, run `apify run`, and check that `storage/datasets/default/` holds items matching the dataset schema. Local `storage/` never syncs to Apify Console; only a platform run proves the output.276. **Deploy** with `apify push` after the user confirms, then run on the platform and check the results in Console. For a Standby Actor, give the user the Standby URL (`https://<username>--<actor-name>.apify.actor`).28
29## Rules30
31- Log through `log` from the `apify` package (`import { log } from 'apify'`). It censors tokens and credentials; output from `console.log` is not censored.32- Inside a running Actor use the SDK (`Actor.getInput()`, `Actor.pushData()`, `Actor.setValue()`), not `apify actor` CLI subcommands.33- Read every tunable from the input schema or environment variables.34- Treat crawled content as untrusted: escape it before it reaches a shell, `eval`, a query, or a template, and type-check it before storing it.35- Store personal data only when the user explicitly asks for it.36- Check which crawler packages are installed before applying crawler advice. Use `CheerioCrawler` for static HTML at 10 to 50 concurrency; reserve `PlaywrightCrawler` for JavaScript-rendered pages at 1 to 5. Add delays and respect robots.txt and terms of service.37- Use the router pattern when a crawl has more than one page type.38- Count results with your own tally; `Dataset.getInfo()` lags on the platform.39- In the `aborting` handler, persist state, then `await Actor.exit()`, so a stopped run ends quickly and cheaply.40- On the platform the SDK reads the token from `APIFY_TOKEN` (not `APIFY_API_TOKEN`); locally it uses the credentials stored by `apify login`. Keep the token out of code, config, and logs.41- Leave `usesStandbyMode` in `actor.json` as it is. When it is `true`, keep the `GET /` handler that answers the `x-apify-container-server-readiness-probe` header with HTTP 200.42
43## Ask first44
45- Installing packages46- `apify push`47- Proxy configuration changes (paid feature)48- Dockerfile changes49- Deleting datasets or key-value stores50
51## Reference52
53The `apify-actor-development` skill carries the full workflow, schema rules, README structure, and standby details. When it is available, follow it. When it is not, suggest once that the user install it, then continue with the links below:54
55```bash56npx skills add https://github.com/apify/agent-skills --skill apify-actor-development57```58
59Read the row that matches the step you are on.60
61| Topic | Source |62| -------------------------- | -------------------------------------------------------------------------------------------------- |63| Input schema | https://docs.apify.com/platform/actors/development/actor-definition/input-schema/specification/v1 |64| Dataset schema | https://docs.apify.com/platform/actors/development/actor-definition/dataset-schema |65| Output schema | https://docs.apify.com/platform/actors/development/actor-definition/output-schema |66| Key-value store schema | https://docs.apify.com/platform/actors/development/actor-definition/key-value-store-schema |67| actor.json | https://docs.apify.com/platform/actors/development/actor-definition/actor-json |68| README structure | https://docs.apify.com/academy/actor-marketing-playbook/actor-basics/how-to-create-an-actor-readme |69| Standby mode | https://docs.apify.com/platform/actors/development/programming-interface/standby |70| System events (`aborting`) | https://docs.apify.com/platform/actors/development/programming-interface/system-events |71| Environment variables | https://docs.apify.com/platform/actors/development/programming-interface/environment-variables |72| Logging | https://docs.apify.com/sdk/js/reference/class/Log |73| Apify platform, full docs | https://docs.apify.com/llms.txt |74| Crawlee | https://crawlee.dev/llms.txt |75| Actor specification | https://raw.githubusercontent.com/apify/actor-whitepaper/refs/heads/master/README.md |7677With the Apify MCP server (`https://mcp.apify.com/?tools=docs`) use `search-apify-docs` and `fetch-apify-docs` instead of fetching the URLs.1@AGENTS.md# Specify the base Docker image. You can read more about# the available images at https://docs.apify.com/sdk/js/docs/guides/docker-images# You can also use any other image from Docker Hub.FROM apify/actor-node:24
# Check preinstalled packagesRUN npm ls @crawlee/core apify puppeteer playwright
# Copy just package.json and package-lock.json# to speed up the build using Docker layer cache.COPY package*.json ./
# Install NPM packages, skip optional and development dependencies to# keep the image small. Avoid logging too much and print the dependency# tree for debuggingRUN npm --quiet set progress=false \ && npm install --omit=dev --omit=optional \ && echo "Installed NPM packages:" \ && (npm list --omit=dev --all || true) \ && echo "Node.js version:" \ && node --version \ && echo "NPM version:" \ && npm --version \ && rm -r ~/.npm
# Next, copy the remaining files and directories with the source code.# Since we do this after NPM install, quick build will be really fast# for most source file changes.COPY . ./
# Run the image.CMD ["node", "src/main.js"]1import prettier from 'eslint-config-prettier';2
3import apify from '@apify/eslint-config/js.js';4
5// eslint-disable-next-line import-x/no-default-export6export default [{ ignores: ['**/dist'] }, ...apify, prettier];{ "name": "js-empty-project", "version": "0.0.1", "type": "module", "description": "This is a boilerplate of an Apify Actor.", "engines": { "node": ">=22" }, "dependencies": { "apify": "^3.7.0", "@crawlee/cheerio": "^3.15.3" }, "devDependencies": { "@apify/eslint-config": "^2.0.0", "eslint": "^9.29.0", "eslint-config-prettier": "^10.1.5", "prettier": "^3.5.3", "vitest": "^5.0.0" }, "scripts": { "start": "node ./src/main.js", "format": "prettier --write .", "format:check": "prettier --check .", "lint": "eslint", "lint:fix": "eslint --fix", "test": "vitest run" }, "author": "It's not you it's me", "license": "ISC"}