API Reference
Developers
Help
search docs
Edit

Actor input schema

Learn how to define and easily validate a schema for your actor's input with code examples. Provide an autogenerated input UI to your actor's users.

Specification version 1

An actor's input schema defines the input that the actor accepts and the UI components used for input in Apify Console. Using input schema, you can provide and easy-to-use UI for your actor's users and also ensure that the input provided is valid.

Input schema can be embedded as an object in the .actor/actor.json file under the input field. Alternatively, you can store a path to a JSON file in that field. If the input field or .actor/actor.json are omitted, the input schema from .actor/INPUT_SCHEMA.json is used. In the absence of that file, the INPUT_SCHEMA.json file stored in the actor's root directory is used. The file's maximum size is 100 kB. If the input schema is provided, then input is always validated to fulfill the schema when an actor is being started (via API or from Apify Console).

You can also use our visual input schema editor to guide you through creation of the INPUT_SCHEMA.json file.

If you need to validate your input schemas, you can use the apify vis command in the Apify CLI.

Example

Imagine you are building a simple crawler whose inputs are an array of start URLs and a JavaScript function that will be executed at each page the crawler visits. Its input schema will look like this:

{
    "title": "Cheerio Crawler input",
    "description": "To update crawler to another site,
        you need to change startUrls and
        pageFunction options!",
    "type": "object",
    "schemaVersion": 1,
    "properties": {
        "startUrls": {
            "title": "Start URLs",
            "type": "array",
            "description": "URLs to start with",
            "prefill": [
                { "url": "http://example.com" },
                { "url": "http://example.com/some-path" }
            ],
            "editor": "requestListSources"
        },
        "pageFunction": {
            "title": "Page function",
            "type": "string",
            "description": "Function executed for each request",
            "prefill": "async () => { return $('title').text(); }",
            "editor": "javascript"
        }
    },
    "required": ["startUrls", "pageFunction"]
}

And generated the input UI will be:

Apify actor input schema example

If you switch the input to the JSON display using the toggle, then you will see the entered input stringified to JSON, as it will be passed to the actor:

{
    "startUrls": [
    {
        "url": "http://example.com"
    },
    {
        "url": "http://example.com/some-path"
    }
    ],
    "pageFunction": "async () => { return $('title').text(); }"
}

Structure

The input schema is a JSON file named INPUT_SCHEMA.json, placed in the root directory of an actor with the following structure:

{
    "title": "Cheerio Crawler input",
    "type": "object",
    "schemaVersion": 1,
    "properties": { /* define input fields here */ },
    "required": []
}
Property Type Required Description
title String Yes Any text describing your input schema.
description String No Help text for the input that will be
displayed above the UI fields.
type String Yes This is fixed and must be set
to string object.
schemaVersion Integer Yes The version of the input schema
specification against which
your schema is written.
Currently, only version 1 is out.
properties Object Yes This is an object mapping each field key
to its specification.
required [String] No An array of field keys that are required.

Fields

Each field of your input is described under its key in inputSchema.properties object. The field might have integer, string, array, object or boolean type and its specification contains the following properties:

Property Value Required Description
type One of
string,
array,
object,
boolean,
integer		 Yes Allowed type for the input value.
Cannot be mixed.
title String Yes Title of the field in UI.
description String Yes Description of the field that will be
displayed as help text in Actor input UI.
default Must match
type property.		 No Default value that will be
used when no value is provided.
prefill Must match
type property.		 No Value that will be prefilled
in the actor input interface.
Only the boolean type doesn't
support prefill property.
example Must match
type property.		 No Sample value of this field
for the actor to be displayed when
actor is published in Apify Store.
sectionCaption String No If this property is set,
then all fields following this field
(this field included) will be separated
into a collapsible section
with the value set as its caption.
The section ends at the last field
or the next field which has the
sectionCaption property set.
sectionDescription String No If the sectionCaption property is set,
then you can use this property to
provide additional description to the section.
The description will be visible right under
the caption when the section is open.

Additional properties

In addition to the properties listed above, most of the types support also additional properties defining, for example, the UI input editor.

String

Example of a code input:

{
    "title": "Page function",
    "type": "string",
    "description": "Function executed for each request",
    "editor": "javascript",
    "prefill": "async () => { return $('title').text(); }"
}

Rendered input:

Apify actor input schema page function

Example of country selection using a select input:

{
    "title": "Country",
    "type": "string",
    "description": "Select your country",
    "editor": "select",
    "default": "us",
    "enum": ["us", "de", "fr"],
    "enumTitles": ["USA", "Germany", "France"]
}

Rendered input:

Apify actor input schema - country input

Properties:

Property Value Required Description
editor One of
textfield,
textarea,
javascript,
select,
datepicker,
hidden		 Yes Visual editor used for
the input field.
pattern String No Regular expression that will be
used to validate the input.
If validation fails,
the actor will not run.
minLength Integer No Minimum length of the string.
maxLength Integer No Maximum length of the string.
enum [String] Required if
editor
is select		 Using this field, you can limit values
to the given array of strings.
Input will be displayed as select box.
enumTitles [String] No Titles for the enum keys described.
nullable Boolean No Specifies whether null
is an allowed value.
isSecret Boolean No Specifies whether the input field
will be stored encrypted.
Only available
with textfield and textarea editors.

When using escape characters \ for the regular expression in the pattern field, be sure to escape them to avoid invalid JSON issues. For example, the regular expression https:\/\/(www\.)?apify\.com\/.+ would become https:\\/\\/(www\\.)?apify\\.com\\/.+.

Boolean

Beware that the boolean input type doesn't support the prefill property, since there is no way to display the pre-filled value in the user interface.

Example options with group caption:

{
    "verboseLog": {
        "title": "Verbose log",
        "type": "boolean",
        "description": "Debug messages will be included
            in the log.",
        "default": true,
        "groupCaption": "Options",
        "groupDescription": "Various options for this actor"
    },
    "lightspeed": {
        "title": "Lightspeed",
        "type": "boolean",
        "description": "If checked then actors runs at the
            speed of light.",
        "default": true
    }
}

Rendered input:

Apify actor input schema options

Properties:

Property Value Required Description
editor One of
checkbox,
hidden		 No Visual editor used for the input field.
groupCaption String No If you want to group
multiple checkboxes together,
add this option to the first
of the group.
groupDescription String No Description displayed as help text
displayed of group title.
nullable Boolean No Specifies whether null is
an allowed value.

Integer

Example:

{
    "title": "Memory",
    "type": "integer",
    "description": "Select memory in megabytes",
    "default": 64,
    "maximum": 1024,
    "unit": "MB"
}

Rendered input:

Apify actor input schema memory

Properties:

Property Value Required Description
editor One of
number,
hidden		 No Visual editor used for input field.
maximum Integer No Maximum allowed value.
minimum Integer No Minimum allowed value.
unit String No Unit displayed next to the field in UI,
for example second, MB, etc.
nullable Boolean No Specifies whether null is an allowed value.

Object

Example of proxy configuration:

{
    "title": "Proxy configuration",
    "type": "object",
    "description": "Select proxies to be used by your crawler.",
    "prefill": { "useApifyProxy": true },
    "editor": "proxy"
}

Rendered input:

Apify actor input schema proxy

The object where the proxy configuration is stored has the following structure:

{
    // Indicates whether Apify Proxy was selected.
    "useApifyProxy": Boolean,

    // Array of Apify Proxy groups. Is missing or null if
    // Apify Proxy's automatic mode was selected
    // or if proxies are not used.
    "apifyProxyGroups": String[],

    // Array of custom proxy URLs.
    // Is missing or null if custom proxies were not used.
    "proxyUrls": String[],
}

Example of a blackbox object:

{
    "title": "User object",
    "type": "object",
    "description": "Enter object representing user",
    "prefill": {
        "name": "John Doe",
        "email": "janedoe@gmail.com"
    },
    "editor": "json"
}

Rendered input:

Apify actor input schema user object

Properties:

Property Value Required Description
editor One of
json,
proxy,
hidden		 Yes UI editor used for input.
patternKey String No Regular expression that will be used
to validate the keys of the object.
patternValue String No Regular expression that will be used
to validate the values of object.
maxProperties Integer No Maximum number of properties
the object can have.
minProperties Integer No Minimum number of properties
the object can have.
nullable Boolean No Specifies whether null is
an allowed value.

Array

Example of request list sources configuration:

{
    "title": "Start URLs",
    "type": "array",
    "description": "URLs to start with",
    "prefill": [{ "url": "http://example.com" }],
    "editor": "requestListSources"
}

Rendered input:

Apify actor input schema start urls array

Example of an array:

{
    "title": "Colors",
    "type": "array",
    "description": "Enter colors you know",
    "prefill": ["Red", "White"],
    "editor": "json"
}

Rendered input:

Apify actor input schema colors array

Properties:

Property Value Required Description
editor One of
json,
requestListSources,
pseudoUrls,
globs,
keyValue,
stringList,
hidden		 Yes UI editor used for input.
placeholderKey String No Placeholder displayed for
key field when no value is specified.
Works only with keyValue editor.
placeholderValue String No Placeholder displayed in value field
when no value is provided.
Works only with keyValue and
stringList editors.
patternKey String No Regular expression that
will be used to validate
the keys of items in the array.
Works only with keyValue
editor.
patternValue String No Regular expression that
will be used to validate the values
of items in the array.
Works only with keyValue and
stringList editors.
maxItems Integer No Maximum number of items
the array can contain.
minItems Integer No Minimum number of items
the array can contain.
uniqueItems Boolean No Specifies whether the array
should contain only unique values.
nullable Boolean No Specifies whether null is
an allowed value.

Usage of this field is based on the selected editor:

  • requestListSources - value from this field can be used as input of RequestList class from Crawlee.
  • pseudoUrls - is intended to be used with a combination of the PseudoUrl class and the enqueueLinks() function from Crawlee.

Editor type requestListSources supports input in formats defined by the sources property of RequestListOptions.

Editor type globs maps to the Crawlee's GlobInput used by the UrlPatterObject.