Input schema

The input schema is a JSON object that describes the input of your actor. Lantfly uses it to:

• build the run form in the Console;
• fill in default values the caller left out, before the run starts;
• refuse inputs that do not match, with 422 validation_failed and a message per field;
• describe the actor's arguments to AI clients through MCP.

Put it in .actor/input_schema.json (or point input in actor.json at it). lantfly push uploads it with the actor and the version.

Structure

.actor/input_schema.json

{
  "title": "Web Scraper input",
  "type": "object",
  "schemaVersion": 1,
  "properties": {
    "startUrls": {
      "title": "Start URLs",
      "type": "array",
      "editor": "requestListSources",
      "description": "Pages to start from."
    },
    "maxPagesPerCrawl": {
      "title": "Max pages",
      "type": "integer",
      "default": 50,
      "minimum": 1
    },
    "proxyConfiguration": {
      "title": "Proxy",
      "type": "object",
      "editor": "proxy",
      "default": { "useLantflyProxy": false }
    }
  },
  "required": ["startUrls"]
}

Top-level key	Meaning
title	Title of the input.
type	Always object.
schemaVersion	Always 1.
properties	One entry per input field.
required	Names of fields that must be present.

Field properties

Key	Applies to	Meaning
title	all	Label in the form. Default: the field name.
description	all	Help text under the field.
type	all	string, integer, number, boolean, array or object.
default	all	Value used when the caller leaves the field out.
minimum, maximum	integer, number	Allowed range.
enum	string, integer, number	Allowed values. The form shows a select.
enumTitles	with enum	Labels of the enum values, in the same order.
editor	see below	Which control the form uses.
isSecret	string	Shows a password field in the form.

Editors

editor	Type	Form control	Value
textfield (default)	string	One-line text field	a string
textarea	string	Multi-line text	a string
javascript, python	string	Multi-line text in a monospace font	a string
datepicker	string	Date picker	a date string such as 2026-11-01
stringList (default for arrays)	array	List of strings: Enter adds an entry, pasted lines are split	["a", "b"]
requestListSources	array	List of URLs	[{"url": "https://…"}]
proxy	object	JSON editor for proxy settings	{"useLantflyProxy": true, "groups": ["RESIDENTIAL"], "country": "VN"}

Other array and object fields get a JSON editor. boolean fields get a switch. Callers can always switch the form to raw JSON.

Validation rules

The API checks the input when a run starts:

• A required field that is missing, null, an empty string or an empty list is an error.
• type is checked strictly: integer must be a whole number (not "5"), array must be a JSON list and object a JSON object.
• minimum, maximum and enum are checked when the field is present.
• Fields that are not in properties are passed through unchanged.

A refused input answers 422 with the field messages in error.fields, for example Field count must be at most 1000. See Errors.

tip

Keep defaults in the schema, not only in your code. The platform writes the defaults into the run's INPUT record, so the input is complete when you look at the run later, and AI clients see the defaults too.

Proxy field

By convention, actors take their proxy settings in a proxyConfiguration object with the proxy editor:

Proxy field

"proxyConfiguration": {
  "title": "Proxy",
  "type": "object",
  "editor": "proxy",
  "default": { "useLantflyProxy": true, "groups": ["DATACENTER"] }
}

Key	Meaning
useLantflyProxy	false: no proxy.
groups	Proxy groups in order of preference.
country	Two-letter country code of the exit IP.

Pass the object to the SDK: Actor.createProxyConfiguration(input.proxyConfiguration) in Node.js, Actor.create_proxy_configuration(actor_proxy_input=actor_input.get("proxyConfiguration")) in Python. See Proxy.

Example input

Give the actor an example_input (in the Console or with PATCH /api/v3/actors/{actor}) so people see a working input on the actor's page.