Simple Standby
Pricing
Pay per usage
Simple Standby Actor with a few requests - this is used for demo purposes, specifically to show the OpenAPI rendering features.
Pricing
Pay per usage
Rating
0.0
(0)
Developer
Nishad Manerikar
Maintained by CommunityActor stats
0
Bookmarked
5
Total users
3
Monthly active users
15 days ago
Last modified
Categories
Share
{ "actorSpecification": 1, "name": "my-actor-2", "title": "Standby Actor in TypeScript", "description": "Standby Actor in TypeScript.", "version": "0.0", "buildTag": "latest", "usesStandbyMode": true, "meta": { "templateId": "ts-standby", "generatedBy": "<FILL-IN-MODEL>" }, "dockerfile": "../Dockerfile", "webServerSchema": { "openapi": "3.0.3", "info": { "title": "Standby Demo Actor API", "description": "A simple demonstration API for Apify Standby Actors that provides math operations and string manipulation", "version": "1.0.0" }, "servers": [ { "url": "/", "description": "Actor standby server" } ], "paths": { "/": { "get": { "summary": "Health check / readiness probe", "description": "Returns a simple greeting message. Used for readiness probes.", "responses": { "200": { "description": "Successful response", "content": { "text/plain": { "schema": { "type": "string", "example": "Hello from Standby Demo Actor!" } } } } } }, "post": { "summary": "Echo posted message", "description": "Accepts a JSON body with a 'message' field and echoes it back.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "responses": { "200": { "description": "Echoed message", "content": { "application/json": { "schema": { "type": "object", "properties": { "echo": { "type": "string" } } } } } }, "400": { "description": "Bad request - missing message", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "put": { "summary": "Update greeting message", "description": "Updates the greeting message for health check.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "greeting": { "type": "string" } }, "required": [ "greeting" ] } } } }, "responses": { "200": { "description": "Greeting updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "type": "string" } } } } } }, "400": { "description": "Bad request - missing greeting", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "summary": "Delete greeting message", "description": "Deletes the greeting message for health check.", "responses": { "200": { "description": "Greeting deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } } } }, "/hello": { "get": { "summary": "Simple greeting", "description": "Returns a simple greeting message from the standby actor", "responses": { "200": { "description": "Successful response", "content": { "text/plain": { "schema": { "type": "string", "example": "Hello, I am a standby Actor" } } } } } } }, "/math/add": { "get": { "summary": "Add two numbers", "description": "Takes two numbers via query parameters and returns their sum", "parameters": [ { "name": "a", "in": "query", "required": true, "description": "First number to add", "schema": { "type": "number" } }, { "name": "b", "in": "query", "required": true, "description": "Second number to add", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Successful addition", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "number", "description": "The sum of the two numbers" }, "operation": { "type": "string", "example": "addition" } } } } } }, "400": { "description": "Bad request - invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/string/concat": { "get": { "summary": "Concatenate two strings", "description": "Takes two strings via query parameters and returns their concatenation", "parameters": [ { "name": "str1", "in": "query", "required": true, "description": "First string to concatenate", "schema": { "type": "string" } }, { "name": "str2", "in": "query", "required": true, "description": "Second string to concatenate", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful concatenation", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "description": "The concatenated string" }, "operation": { "type": "string", "example": "concatenation" } } } } } }, "400": { "description": "Bad request - invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } } } }}1import http from 'http';2import url from 'url';3import { Actor } from 'apify';4
5Actor.init();6
7// Check if we're running in standby mode (either from Actor config or environment variable)8const isStandbyMode = Actor.config.get('metaOrigin') === 'STANDBY' || process.env.APIFY_META_ORIGIN === 'STANDBY';9
10if (!isStandbyMode) {11 console.log('⚠️ This Actor is designed to run in Standby mode only.');12 console.log(' Please enable Standby mode or set APIFY_META_ORIGIN=STANDBY environment variable.');13 console.log(' For local development, use: npm run dev');14 await Actor.pushData({ foo: "bar" });15 await Actor.exit("Early exit - not in Standby mode");16}17
18console.log('🚀 Running in STANDBY mode');19
20// Interface definitions for API requests21interface AddRequest {22 a: number;23 b: number;24}25
26interface ConcatRequest {27 str1: string;28 str2: string;29}30
31interface ApiResponse<T> {32 result: T;33 operation: string;34}35
36interface ErrorResponse {37 error: string;38}39
40// Helper function to parse JSON body from request41async function parseJsonBody(req: http.IncomingMessage): Promise<any> {42 return new Promise((resolve, reject) => {43 let body = '';44 req.on('data', chunk => {45 body += chunk.toString();46 });47 req.on('end', () => {48 try {49 resolve(JSON.parse(body));50 } catch (error) {51 reject(new Error('Invalid JSON'));52 }53 });54 req.on('error', reject);55 });56}57
58// Helper function to send JSON response59function sendJsonResponse(res: http.ServerResponse, statusCode: number, data: any): void {60 res.writeHead(statusCode, { 'Content-Type': 'application/json' });61 res.end(JSON.stringify(data));62}63
64// Helper function to send text response65function sendTextResponse(res: http.ServerResponse, statusCode: number, text: string): void {66 res.writeHead(statusCode, { 'Content-Type': 'text/plain' });67 res.end(text);68}69
70// Main Actor function71async function main() {72 console.log('Starting Standby Demo Actor...');73
74 // Shared greeting state for both servers75 let greetingMessage: string | undefined;76
77 // Create HTTP server78 const server = http.createServer(async (req: http.IncomingMessage, res: http.ServerResponse) => {79 const parsedUrl = url.parse(req.url || '', true);80 const pathname = parsedUrl.pathname || '/';81 const method = req.method || 'GET';82 /*83 // Set CORS headers for all responses84 res.setHeader('Access-Control-Allow-Origin', '*');85 res.setHeader('Access-Control-Allow-Methods', 'GET, PUT, POST, DELETE, OPTIONS');86 res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Apify-Authorization');87
88 // Handle OPTIONS preflight89 if (method === 'OPTIONS') {90 res.writeHead(204);91 res.end();92 return;93 }*/94 console.log(`${method} ${pathname}`);95
96 try {97 // Handle readiness probe98 if (req.headers['x-apify-container-server-readiness-probe']) {99 console.log('Readiness probe received');100 sendTextResponse(res, 200, 'Hello, readiness probe!');101 return;102 }103
104 // Route handling105 if (pathname === '/' && method === 'GET') {106 sendTextResponse(res, 200, greetingMessage || 'Hello from Standby Demo Actor!');107 return;108 }109
110 if (pathname === '/' && method === 'PUT') {111 let body: any;112 try {113 body = await parseJsonBody(req);114 } catch {115 sendJsonResponse(res, 400, { error: 'Invalid JSON' });116 return;117 }118 if (!body || typeof body.greeting !== 'string') {119 sendJsonResponse(res, 400, { error: 'Missing or invalid "greeting" field' });120 return;121 }122 greetingMessage = body.greeting;123 sendJsonResponse(res, 200, { updated: greetingMessage });124 return;125 }126
127 if (pathname === '/' && method === 'POST') {128 let body: any;129 try {130 body = await parseJsonBody(req);131 } catch {132 sendJsonResponse(res, 400, { error: 'Invalid JSON' });133 return;134 }135 if (!body || typeof body.message !== 'string') {136 sendJsonResponse(res, 400, { error: 'Missing or invalid "message" field' });137 return;138 }139 sendJsonResponse(res, 200, { echo: body.message });140 return;141 }142
143 if (pathname === '/' && method === 'DELETE') {144 greetingMessage = undefined;145 sendJsonResponse(res, 200, { deleted: true });146 return;147 }148
149 if (pathname === '/hello' && method === 'GET') {150 sendTextResponse(res, 200, 'Hello, I am a standby Actor');151 return;152 }153
154 if (pathname === '/math/add' && method === 'GET') {155 const query = parsedUrl.query;156 const a = parseFloat(query.a as string);157 const b = parseFloat(query.b as string);158
159 // Validate input160 if (isNaN(a) || isNaN(b)) {161 sendJsonResponse(res, 400, { error: 'Both "a" and "b" must be valid numbers' } as ErrorResponse);162 return;163 }164
165 const result = a + b;166 const response: ApiResponse<number> = {167 result,168 operation: 'addition'169 };170
171 sendJsonResponse(res, 200, response);172 console.log(`Math operation: ${a} + ${b} = ${result}`);173 return;174 }175
176 if (pathname === '/string/concat' && method === 'GET') {177 const query = parsedUrl.query;178 const str1 = query.str1 as string;179 const str2 = query.str2 as string;180
181 // Validate input182 if (!str1 || !str2) {183 sendJsonResponse(res, 400, { error: 'Both "str1" and "str2" query parameters are required' } as ErrorResponse);184 return;185 }186
187 const result = str1 + str2;188 const response: ApiResponse<string> = {189 result,190 operation: 'concatenation'191 };192
193 sendJsonResponse(res, 200, response);194 console.log(`String operation: "${str1}" + "${str2}" = "${result}"`);195 return;196 }197
198 // Handle 404 for unknown routes199 sendJsonResponse(res, 404, { error: 'Endpoint not found' } as ErrorResponse);200
201 } catch (error) {202 console.error('Server error:', error);203 sendJsonResponse(res, 500, { error: 'Internal server error' } as ErrorResponse);204 }205 });206
207 // Get the port from Actor configuration (for standby mode) or use default for local dev208 const port = Actor.config.get('standbyPort') || parseInt(process.env.LOCAL_DEV_PORT || '3005', 10);209
210 server.listen(port, () => {211 console.log(`🌐 Standby Demo Actor HTTP server listening on port ${port}`);212 console.log('📋 Available endpoints:');213 console.log(' GET / - Health check');214 console.log(' GET /hello - Simple greeting');215 console.log(' GET /math/add?a=5&b=3 - Add two numbers');216 console.log(' GET /string/concat?str1=Hello&str2=World - Concatenate two strings');217
218 // Show local development URLs if using local port219 console.log(`\n🔗 Test URLs (local development):`);220 console.log(` http://localhost:${port}/`);221 console.log(` http://localhost:${port}/hello`);222 console.log(` http://localhost:${port}/math/add?a=5&b=3`);223 console.log(` http://localhost:${port}/string/concat?str1=Hello,%20&str2=World!`);224 });225
226 // Handle graceful shutdown227 process.on('SIGTERM', () => {228 console.log('Received SIGTERM, shutting down gracefully...');229 server.close(() => {230 console.log('HTTP server closed');231 process.exit(0);232 });233 });234
235 process.on('SIGINT', () => {236 console.log('Received SIGINT, shutting down gracefully...');237 server.close(() => {238 console.log('HTTP server closed');239 process.exit(0);240 });241 });242}243
244await main();# configurations.idea.vscode.zed
# crawlee and apify storage foldersapify_storagecrawlee_storagestorage
# installed filesnode_modules
# git folder.git
# dist folderdistroot = true
[*]indent_style = spaceindent_size = 4charset = utf-8trim_trailing_whitespace = trueinsert_final_newline = trueend_of_line = lf# This file tells Git which files shouldn't be added to source control
.idea.vscode.zedstorageapify_storagecrawlee_storagenode_modulesdisttsconfig.tsbuildinfo.prettierignore{ "printWidth": 120, "singleQuote": true, "tabWidth": 4}1# Apify Actors Development Guide2
3Important: Before you begin, fill in the `generatedBy` property in the meta section of `.actor/actor.json`. Replace it with the model you're currently using. This helps Apify monitor and improve AGENTS.md for specific LLM models.4
5## What are Apify Actors?6
7- Actors are serverless programs that run in the cloud. They're inspired by the UNIX philosophy - programs that do one thing well and can be easily combined to build complex systems.8- Actors are programs packaged as Docker images that run in isolated containers9
10## Core Concepts11
12- Accept well-defined JSON input13- Perform isolated tasks (web scraping, automation, data processing)14- Produce structured JSON output to datasets and/or store data in key-value stores15- Can run from seconds to hours or even indefinitely16- Persist state and can be restarted17
18## Do19
20- accept well-defined JSON input and produce structured JSON output21- use Apify SDK (`apify`) for code running ON Apify platform22- validate input early with proper error handling and fail gracefully23- use CheerioCrawler for static HTML content (10x faster than browsers)24- use PlaywrightCrawler only for JavaScript-heavy sites and dynamic content25- use router pattern (createCheerioRouter/createPlaywrightRouter) for complex crawls26- implement retry strategies with exponential backoff for failed requests27- use proper concurrency settings (HTTP: 10-50, Browser: 1-5)28- set sensible defaults in `.actor/input_schema.json` for all optional fields29- set up output schema in `.actor/output_schema.json`30- clean and validate data before pushing to dataset31- use semantic CSS selectors and fallback strategies for missing elements32- respect robots.txt, ToS, and implement rate limiting with delays33- check which tools (cheerio/playwright/crawlee) are installed before applying guidance34- use `apify/log` package for logging (censors sensitive data)35- implement readiness probe handler for standby Actors36- handle the `aborting` event to gracefully shut down when Actor is stopped37
38## Don't39
40- do not rely on `Dataset.getInfo()` for final counts on Cloud platform41- do not use browser crawlers when HTTP/Cheerio works (massive performance gains with HTTP)42- do not hard code values that should be in input schema or environment variables43- do not skip input validation or error handling44- do not overload servers - use appropriate concurrency and delays45- do not scrape prohibited content or ignore Terms of Service46- do not store personal/sensitive data unless explicitly permitted47- do not use deprecated options like `requestHandlerTimeoutMillis` on CheerioCrawler (v3.x)48- do not use `additionalHttpHeaders` - use `preNavigationHooks` instead49- do not disable standby mode (`usesStandbyMode: false`) without explicit permission50
51## Logging52
53- **ALWAYS use the `apify/log` package for logging** - This package contains critical security logic including censoring sensitive data (Apify tokens, API keys, credentials) to prevent accidental exposure in logs54
55### Available Log Levels in `apify/log`56
57The Apify log package provides the following methods for logging:58
59- `log.debug()` - Debug level logs (detailed diagnostic information)60- `log.info()` - Info level logs (general informational messages)61- `log.warning()` - Warning level logs (warning messages for potentially problematic situations)62- `log.warningOnce()` - Warning level logs (same warning message logged only once)63- `log.error()` - Error level logs (error messages for failures)64- `log.exception()` - Exception level logs (for exceptions with stack traces)65- `log.perf()` - Performance level logs (performance metrics and timing information)66- `log.deprecated()` - Deprecation level logs (warnings about deprecated code)67- `log.softFail()` - Soft failure logs (non-critical failures that don't stop execution, e.g., input validation errors, skipped items)68- `log.internal()` - Internal level logs (internal/system messages)69
70**Best practices:**71
72- Use `log.debug()` for detailed operation-level diagnostics (inside functions)73- Use `log.info()` for general informational messages (API requests, successful operations)74- Use `log.warning()` for potentially problematic situations (validation failures, unexpected states)75- Use `log.error()` for actual errors and failures76- Use `log.exception()` for caught exceptions with stack traces77
78## Graceful Abort Handling79
80Handle the `aborting` event to terminate the Actor quickly when stopped by user or platform, minimizing costs especially for PPU/PPE+U billing.81
82```typescript83Actor.on('aborting', async () => {84 // Persist any state, do any cleanup you need, and terminate the Actor using `await Actor.exit()` explicitly as soon as possible85 // This will help ensure that the Actor is doing best effort to honor any potential limits on costs of a single run set by the user86 // Wait 1 second to allow Crawlee/SDK useState and other state persistence operations to complete87 // This is a temporary workaround until SDK implements proper state persistence in the aborting event88 await new Promise((resolve) => setTimeout(resolve, 1000));89 await Actor.exit();90});91```92
93## Standby Mode94
95- **NEVER disable standby mode (`usesStandbyMode: false`) in `.actor/actor.json` without explicit permission** - Actor Standby mode solves this problem by letting you have the Actor ready in the background, waiting for the incoming HTTP requests. In a sense, the Actor behaves like a real-time web server or standard API server instead of running the logic once to process everything in batch. Always keep `usesStandbyMode: true` unless there is a specific documented reason to disable it96- **ALWAYS implement readiness probe handler for standby Actors** - Handle the `x-apify-container-server-readiness-probe` header at GET / endpoint to ensure proper Actor lifecycle management97
98You can recognize a standby Actor by checking the `usesStandbyMode` property in `.actor/actor.json`. Only implement the readiness probe if this property is set to `true`.99
100### Readiness Probe Implementation Example101
102```typescript103// Apify standby readiness probe at root path104app.get('/', (req: Request, res: Response) => {105 res.writeHead(200, { 'Content-Type': 'text/plain' });106 if (req.headers['x-apify-container-server-readiness-probe']) {107 res.end('Readiness probe OK\n');108 } else {109 res.end('Actor is ready\n');110 }111});112```113
114Key points:115
116- Detect the `x-apify-container-server-readiness-probe` header in incoming requests117- Respond with HTTP 200 status code for both readiness probe and normal requests118- This enables proper Actor lifecycle management in standby mode119
120## Commands121
122```bash123# Local development124apify run # Run Actor locally125
126# Authentication & deployment127apify login # Authenticate account128apify push # Deploy to Apify platform129
130# Help131apify help # List all commands132```133
134## Safety and Permissions135
136Allowed without prompt:137
138- read files with `Actor.getValue()`139- push data with `Actor.pushData()`140- set values with `Actor.setValue()`141- enqueue requests to RequestQueue142- run locally with `apify run`143
144Ask first:145
146- npm/pip package installations147- apify push (deployment to cloud)148- proxy configuration changes (requires paid plan)149- Dockerfile changes affecting builds150- deleting datasets or key-value stores151
152## Project Structure153
154.actor/155├── actor.json # Actor config: name, version, env vars, runtime settings156├── input_schema.json # Input validation & Console form definition157└── output_schema.json # Specifies where an Actor stores its output158src/159└── main.js # Actor entry point and orchestrator160storage/ # Local storage (mirrors Cloud during development)161├── datasets/ # Output items (JSON objects)162├── key_value_stores/ # Files, config, INPUT163└── request_queues/ # Pending crawl requests164Dockerfile # Container image definition165AGENTS.md # AI agent instructions (this file)166
167## Actor Input Schema168
169The input schema defines the input parameters for an Actor. It's a JSON object comprising various field types supported by the Apify platform.170
171### Structure172
173```json174{175 "title": "<INPUT-SCHEMA-TITLE>",176 "type": "object",177 "schemaVersion": 1,178 "properties": {179 /* define input fields here */180 },181 "required": []182}183```184
185### Example186
187```json188{189 "title": "E-commerce Product Scraper Input",190 "type": "object",191 "schemaVersion": 1,192 "properties": {193 "startUrls": {194 "title": "Start URLs",195 "type": "array",196 "description": "URLs to start scraping from (category pages or product pages)",197 "editor": "requestListSources",198 "default": [{ "url": "https://example.com/category" }],199 "prefill": [{ "url": "https://example.com/category" }]200 },201 "followVariants": {202 "title": "Follow Product Variants",203 "type": "boolean",204 "description": "Whether to scrape product variants (different colors, sizes)",205 "default": true206 },207 "maxRequestsPerCrawl": {208 "title": "Max Requests per Crawl",209 "type": "integer",210 "description": "Maximum number of pages to scrape (0 = unlimited)",211 "default": 1000,212 "minimum": 0213 },214 "proxyConfiguration": {215 "title": "Proxy Configuration",216 "type": "object",217 "description": "Proxy settings for anti-bot protection",218 "editor": "proxy",219 "default": { "useApifyProxy": false }220 },221 "locale": {222 "title": "Locale",223 "type": "string",224 "description": "Language/country code for localized content",225 "default": "cs",226 "enum": ["cs", "en", "de", "sk"],227 "enumTitles": ["Czech", "English", "German", "Slovak"]228 }229 },230 "required": ["startUrls"]231}232```233
234## Actor Output Schema235
236The Actor output schema builds upon the schemas for the dataset and key-value store. It specifies where an Actor stores its output and defines templates for accessing that output. Apify Console uses these output definitions to display run results.237
238### Structure239
240```json241{242 "actorOutputSchemaVersion": 1,243 "title": "<OUTPUT-SCHEMA-TITLE>",244 "properties": {245 /* define your outputs here */246 }247}248```249
250### Example251
252```json253{254 "actorOutputSchemaVersion": 1,255 "title": "Output schema of the files scraper",256 "properties": {257 "files": {258 "type": "string",259 "title": "Files",260 "template": "{{links.apiDefaultKeyValueStoreUrl}}/keys"261 },262 "dataset": {263 "type": "string",264 "title": "Dataset",265 "template": "{{links.apiDefaultDatasetUrl}}/items"266 }267 }268}269```270
271### Output Schema Template Variables272
273- `links` (object) - Contains quick links to most commonly used URLs274- `links.publicRunUrl` (string) - Public run url in format `https://console.apify.com/view/runs/:runId`275- `links.consoleRunUrl` (string) - Console run url in format `https://console.apify.com/actors/runs/:runId`276- `links.apiRunUrl` (string) - API run url in format `https://api.apify.com/v2/actor-runs/:runId`277- `links.apiDefaultDatasetUrl` (string) - API url of default dataset in format `https://api.apify.com/v2/datasets/:defaultDatasetId`278- `links.apiDefaultKeyValueStoreUrl` (string) - API url of default key-value store in format `https://api.apify.com/v2/key-value-stores/:defaultKeyValueStoreId`279- `links.containerRunUrl` (string) - URL of a webserver running inside the run in format `https://<containerId>.runs.apify.net/`280- `run` (object) - Contains information about the run same as it is returned from the `GET Run` API endpoint281- `run.defaultDatasetId` (string) - ID of the default dataset282- `run.defaultKeyValueStoreId` (string) - ID of the default key-value store283
284## Dataset Schema Specification285
286The dataset schema defines how your Actor's output data is structured, transformed, and displayed in the Output tab in the Apify Console.287
288### Example289
290Consider an example Actor that calls `Actor.pushData()` to store data into dataset:291
292```typescript293import { Actor } from 'apify';294// Initialize the JavaScript SDK295await Actor.init();296
297/**298 * Actor code299 */300await Actor.pushData({301 numericField: 10,302 pictureUrl: 'https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_92x30dp.png',303 linkUrl: 'https://google.com',304 textField: 'Google',305 booleanField: true,306 dateField: new Date(),307 arrayField: ['#hello', '#world'],308 objectField: {},309});310
311// Exit successfully312await Actor.exit();313```314
315To set up the Actor's output tab UI, reference a dataset schema file in `.actor/actor.json`:316
317```json318{319 "actorSpecification": 1,320 "name": "book-library-scraper",321 "title": "Book Library Scraper",322 "version": "1.0.0",323 "storages": {324 "dataset": "./dataset_schema.json"325 }326}327```328
329Then create the dataset schema in `.actor/dataset_schema.json`:330
331```json332{333 "actorSpecification": 1,334 "fields": {},335 "views": {336 "overview": {337 "title": "Overview",338 "transformation": {339 "fields": [340 "pictureUrl",341 "linkUrl",342 "textField",343 "booleanField",344 "arrayField",345 "objectField",346 "dateField",347 "numericField"348 ]349 },350 "display": {351 "component": "table",352 "properties": {353 "pictureUrl": {354 "label": "Image",355 "format": "image"356 },357 "linkUrl": {358 "label": "Link",359 "format": "link"360 },361 "textField": {362 "label": "Text",363 "format": "text"364 },365 "booleanField": {366 "label": "Boolean",367 "format": "boolean"368 },369 "arrayField": {370 "label": "Array",371 "format": "array"372 },373 "objectField": {374 "label": "Object",375 "format": "object"376 },377 "dateField": {378 "label": "Date",379 "format": "date"380 },381 "numericField": {382 "label": "Number",383 "format": "number"384 }385 }386 }387 }388 }389}390```391
392### Structure393
394```json395{396 "actorSpecification": 1,397 "fields": {},398 "views": {399 "<VIEW_NAME>": {400 "title": "string (required)",401 "description": "string (optional)",402 "transformation": {403 "fields": ["string (required)"],404 "unwind": ["string (optional)"],405 "flatten": ["string (optional)"],406 "omit": ["string (optional)"],407 "limit": "integer (optional)",408 "desc": "boolean (optional)"409 },410 "display": {411 "component": "table (required)",412 "properties": {413 "<FIELD_NAME>": {414 "label": "string (optional)",415 "format": "text|number|date|link|boolean|image|array|object (optional)"416 }417 }418 }419 }420 }421}422```423
424**Dataset Schema Properties:**425
426- `actorSpecification` (integer, required) - Specifies the version of dataset schema structure document (currently only version 1)427- `fields` (JSONSchema object, required) - Schema of one dataset object (use JsonSchema Draft 2020-12 or compatible)428- `views` (DatasetView object, required) - Object with API and UI views description429
430**DatasetView Properties:**431
432- `title` (string, required) - Visible in UI Output tab and API433- `description` (string, optional) - Only available in API response434- `transformation` (ViewTransformation object, required) - Data transformation applied when loading from Dataset API435- `display` (ViewDisplay object, required) - Output tab UI visualization definition436
437**ViewTransformation Properties:**438
439- `fields` (string[], required) - Fields to present in output (order matches column order)440- `unwind` (string[], optional) - Deconstructs nested children into parent object441- `flatten` (string[], optional) - Transforms nested object into flat structure442- `omit` (string[], optional) - Removes specified fields from output443- `limit` (integer, optional) - Maximum number of results (default: all)444- `desc` (boolean, optional) - Sort order (true = newest first)445
446**ViewDisplay Properties:**447
448- `component` (string, required) - Only `table` is available449- `properties` (Object, optional) - Keys matching `transformation.fields` with ViewDisplayProperty values450
451**ViewDisplayProperty Properties:**452
453- `label` (string, optional) - Table column header454- `format` (string, optional) - One of: `text`, `number`, `date`, `link`, `boolean`, `image`, `array`, `object`455
456## Key-Value Store Schema Specification457
458The key-value store schema organizes keys into logical groups called collections for easier data management.459
460### Example461
462Consider an example Actor that calls `Actor.setValue()` to save records into the key-value store:463
464```typescript465import { Actor } from 'apify';466// Initialize the JavaScript SDK467await Actor.init();468
469/**470 * Actor code471 */472await Actor.setValue('document-1', 'my text data', { contentType: 'text/plain' });473
474await Actor.setValue(`image-${imageID}`, imageBuffer, { contentType: 'image/jpeg' });475
476// Exit successfully477await Actor.exit();478```479
480To configure the key-value store schema, reference a schema file in `.actor/actor.json`:481
482```json483{484 "actorSpecification": 1,485 "name": "data-collector",486 "title": "Data Collector",487 "version": "1.0.0",488 "storages": {489 "keyValueStore": "./key_value_store_schema.json"490 }491}492```493
494Then create the key-value store schema in `.actor/key_value_store_schema.json`:495
496```json497{498 "actorKeyValueStoreSchemaVersion": 1,499 "title": "Key-Value Store Schema",500 "collections": {501 "documents": {502 "title": "Documents",503 "description": "Text documents stored by the Actor",504 "keyPrefix": "document-"505 },506 "images": {507 "title": "Images",508 "description": "Images stored by the Actor",509 "keyPrefix": "image-",510 "contentTypes": ["image/jpeg"]511 }512 }513}514```515
516### Structure517
518```json519{520 "actorKeyValueStoreSchemaVersion": 1,521 "title": "string (required)",522 "description": "string (optional)",523 "collections": {524 "<COLLECTION_NAME>": {525 "title": "string (required)",526 "description": "string (optional)",527 "key": "string (conditional - use key OR keyPrefix)",528 "keyPrefix": "string (conditional - use key OR keyPrefix)",529 "contentTypes": ["string (optional)"],530 "jsonSchema": "object (optional)"531 }532 }533}534```535
536**Key-Value Store Schema Properties:**537
538- `actorKeyValueStoreSchemaVersion` (integer, required) - Version of key-value store schema structure document (currently only version 1)539- `title` (string, required) - Title of the schema540- `description` (string, optional) - Description of the schema541- `collections` (Object, required) - Object where each key is a collection ID and value is a Collection object542
543**Collection Properties:**544
545- `title` (string, required) - Collection title shown in UI tabs546- `description` (string, optional) - Description appearing in UI tooltips547- `key` (string, conditional) - Single specific key for this collection548- `keyPrefix` (string, conditional) - Prefix for keys included in this collection549- `contentTypes` (string[], optional) - Allowed content types for validation550- `jsonSchema` (object, optional) - JSON Schema Draft 07 format for `application/json` content type validation551
552Either `key` or `keyPrefix` must be specified for each collection, but not both.553
554## Apify MCP Tools555
556If MCP server is configured, use these tools for documentation:557
558- `search-apify-docs` - Search documentation559- `fetch-apify-docs` - Get full doc pages560
561Otherwise, reference: `@https://mcp.apify.com/`562
563## Resources564
565- [docs.apify.com/llms.txt](https://docs.apify.com/llms.txt) - Quick reference566- [docs.apify.com/llms-full.txt](https://docs.apify.com/llms-full.txt) - Complete docs567- [crawlee.dev](https://crawlee.dev) - Crawlee documentation568- [whitepaper.actor](https://raw.githubusercontent.com/apify/actor-whitepaper/refs/heads/master/README.md) - Complete Actor specification# 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:22 AS builder
# 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 all dependencies. Don't audit to speed up the installation.RUN npm install --include=dev --audit=false
# Next, copy the source files using the user set# in the base image.COPY . ./
# Install all dependencies and build the project.# Don't audit to speed up the installation.RUN npm run build
# Create final imageFROM apify/actor-node:22
# 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
# Copy built JS files from builder imageCOPY /usr/src/app/dist ./dist
# 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", "dist/main.js"]1import prettier from 'eslint-config-prettier';2
3import apify from '@apify/eslint-config/ts.js';4import globals from 'globals';5import tsEslint from 'typescript-eslint';6
7// eslint-disable-next-line import/no-default-export8export default [9 { ignores: ['**/dist', 'eslint.config.mjs'] },10 ...apify,11 prettier,12 {13 languageOptions: {14 parser: tsEslint.parser,15 parserOptions: {16 project: 'tsconfig.json',17 },18 globals: {19 ...globals.node,20 ...globals.jest,21 },22 },23 plugins: {24 '@typescript-eslint': tsEslint.plugin,25 },26 rules: {27 'no-console': 0,28 },29 },30];{ "name": "ts-standby-project", "version": "0.0.1", "type": "module", "description": "This is an example of an Apify Actor that uses Standby mode.", "engines": { "node": ">=20.0.0" }, "dependencies": { "apify": "^3.5.2" }, "devDependencies": { "@apify/eslint-config": "^1.0.0", "@apify/tsconfig": "^0.1.1", "@types/node": "^22.15.32", "eslint": "^9.29.0", "eslint-config-prettier": "^10.1.5", "globals": "^16.2.0", "prettier": "^3.5.3", "tsx": "^4.20.3", "typescript": "^5.9.3", "typescript-eslint": "^8.34.1" }, "scripts": { "start": "npm run start:dev", "start:prod": "node dist/main.js", "start:dev": "tsx src/main.ts", "build": "tsc", "lint": "eslint", "lint:fix": "eslint --fix", "format": "prettier --write .", "format:check": "prettier --check .", "test": "echo \"Error: oops, the Actor has no tests yet, sad!\" && exit 1" }, "author": "It's not you it's me", "license": "ISC"}{ "extends": "@apify/tsconfig", "compilerOptions": { "module": "NodeNext", "moduleResolution": "NodeNext", "target": "ES2022", "outDir": "dist", "noUnusedLocals": false, "skipLibCheck": true, "lib": ["DOM"] }, "include": ["./src/**/*"]}