Jump to

Data models

Reference documentation for data models and schemas used in the Vectorly API.

Routine

A routine represents a reusable web automation workflow.

JSON

Fields

Field	Type	Description
`id`	string	Unique routine identifier
`name`	string	Machine-readable routine name
`description`	string	Human-readable description
`created_by`	string	User ID of the user who created the routine
`organization_id`	string	Organization ID that the routine belongs to
`is_public`	boolean	Whether the routine is publicly viewable
`routine_status`	string	Status: `"draft"`, `"active"`, `"archived"`
`incognito`	boolean	Whether to use incognito mode when executing
`tags`	string[]	Tags for categorizing the routine (e.g., `["travel", "api"]`)
`parameters`	Parameter[]	List of parameter definitions (see Parameter model)
`operations`	Operation[]	List of operations to execute
`created_at`	integer	Unix timestamp (seconds) when routine was created
`updated_at`	integer	Unix timestamp (seconds) when routine was last updated

Parameter

Defines an input parameter for a routine.

JSON

Fields

Field	Type	Description
`name`	string	Parameter name (used in API calls)
`type`	string	Data type: `"string"`, `"number"`, `"boolean"`, `"date"`, `"enum"`
`required`	boolean	Whether the parameter is required
`description`	string	Human-readable description
`default`	any	Default value if not provided
`validation`	object	Type-specific validation rules

Operations

Operations define the individual steps in a routine workflow. Each operation has a type field that determines its behavior and additional fields specific to that operation type.

Navigate

Navigates the browser to a specified URL.

JSON

Field	Type	Description
`type`	string	Must be `"navigate"`
`url`	string	The URL to navigate to

Sleep

Pauses execution for a specified duration.

JSON

Field	Type	Description
`type`	string	Must be `"sleep"`
`timeout_seconds`	number	Number of seconds to pause

Fetch

Makes an HTTP request to an endpoint and optionally stores the result.

JSON

Field	Type	Description
`type`	string	Must be `"fetch"`
`endpoint`	Endpoint	The endpoint configuration to fetch
`session_storage_key`	string \| null	Key to store the result in session storage (optional)
`data_sanitizer`	object \| null	Data sanitizer configuration (optional)

Return

Returns a value from session storage as the routine result.

JSON

Field	Type	Description
`type`	string	Must be `"return"`
`session_storage_key`	string	The session storage key containing the value to return

Click

Clicks on an element identified by a CSS selector.

Note: This operation automatically validates element visibility to avoid clicking hidden honeypot traps. Only visible, interactable elements will be clicked.

JSON

Field	Type	Description
`type`	string	Must be `"click"`
`selector`	string	CSS selector to find the element to click
`button`	string	Mouse button: `"left"`, `"right"`, or `"middle"` (default: `"left"`)
`click_count`	integer	Number of clicks to perform (default: `1`)
`timeout_ms`	integer	Maximum wait time in milliseconds (default: `20000`)
`ensure_visible`	boolean	Whether to scroll element into view before clicking (default: `true`)

Input Text

Types text into an input element.

Note: This operation automatically validates element visibility to avoid typing into hidden honeypot inputs. Only visible, interactable elements will receive input.

JSON

Field	Type	Description
`type`	string	Must be `"input_text"`
`selector`	string	CSS selector to find the input element
`text`	string	Text to type into the element
`clear`	boolean	Whether to clear existing text before typing (default: `false`)
`timeout_ms`	integer	Maximum wait time in milliseconds (default: `20000`)

Press

Presses a keyboard key.

JSON

Field	Type	Description
`type`	string	Must be `"press"`
`key`	string	Keyboard key to press (e.g., `"Enter"`, `"Tab"`, `"Escape"`)

Wait for URL

Waits for the current URL to match a regex pattern.

JSON

Field	Type	Description
`type`	string	Must be `"wait_for_url"`
`url_regex`	string	Regex pattern to match against `window.location.href`
`timeout_ms`	integer	Maximum wait time in milliseconds (default: `20000`)

Scroll

Scrolls the page or a specific element.

JSON

Field	Type	Description
`type`	string	Must be `"scroll"`
`selector`	string \| null	CSS selector for element to scroll. If `null`, scrolls the window
`x`	integer \| null	Absolute x position to scroll to (window only)
`y`	integer \| null	Absolute y position to scroll to (window only)
`delta_x`	integer \| null	Relative x scroll amount
`delta_y`	integer \| null	Relative y scroll amount
`behavior`	string	Scroll behavior: `"auto"` or `"smooth"` (default: `"auto"`)
`timeout_ms`	integer	Maximum wait time for element in milliseconds (default: `20000`)

Return HTML

Returns HTML content from the page or a specific element.

JSON

Field	Type	Description
`type`	string	Must be `"return_html"`
`scope`	string	Either `"page"` (returns `document.documentElement.outerHTML`) or `"element"` (returns selected element's HTML) (default: `"page"`)
`selector`	string \| null	CSS selector for element (required if `scope` is `"element"`)
`timeout_ms`	integer	Maximum wait time in milliseconds (default: `20000`)

Get Cookies

Get all cookies (including HttpOnly) via CDP and store them in session storage.

This operation uses the Chrome DevTools Protocol's Network.getAllCookies() method to retrieve all cookies, including HttpOnly cookies that are not accessible via document.cookie in JavaScript.

JSON

Field	Type	Description
`type`	string	Must be `"get_cookies"`
`session_storage_key`	string	The session storage key to save the cookies to
`domain_filter`	string	Domain to filter cookies by. Use wildcard `""` to get all cookies (default: `""`)

Download

Downloads a file from an endpoint and returns it as base64 in the routine result.

This operation fetches a binary file (PDF, image, audio, etc.) from an endpoint, converts it to base64, and directly sets it as the routine's result. This is typically the last operation in a routine.

JSON

Field	Type	Description
`type`	string	Must be `"download"`
`endpoint`	Endpoint	The endpoint configuration to download from
`filename`	string	Filename for the downloaded file (e.g., `"report.pdf"`, `"image.png"`)

JS Evaluate

Evaluates JavaScript code in the browser context.

Note: The JavaScript code must be wrapped in an IIFE (Immediately Invoked Function Expression): (function() { ... })() or (() => { ... })(). This is validated at the data model level.

Allowed:

Promises and async/await (e.g., new Promise(), .then(), await)
setTimeout/setInterval (useful for polling)
Loops (while, for, do) - timeout prevents infinite loops
Synchronous JavaScript operations
DOM manipulation

Not allowed:

Dynamic code generation: eval, Function
Network / exfiltration: fetch, XMLHttpRequest, WebSocket, sendBeacon
Persistent event hooks: addEventListener, MutationObserver, IntersectionObserver
Navigation / lifecycle control: window.close

JSON

Field	Type	Description
`type`	string	Must be `"js_evaluate"`
`js`	string	JavaScript code in IIFE format: `(function() { ... })()` or `(() => { ... })()`
`timeout_seconds`	number	Maximum execution time in seconds (default: `5.0`, max: `10.0`)
`session_storage_key`	string \| null	Optional session storage key to store the evaluation result

Execution

Represents the result of executing a routine.

JSON

Fields

Field	Type	Description
`execution_id`	string	Unique execution identifier (UUID)
`routine_id`	string	ID of the executed routine
`routine_name`	string	Name of the executed routine
`status`	string	Execution status: `"pending"`, `"running"`, `"completed"`, `"failed"`
`result`	Result \| null	Execution result (see Result below)
`error`	string \| null	Error message if execution failed
`created_at`	string	Execution start time (ISO 8601)
`completed_at`	string \| null	Execution completion time (ISO 8601)
`duration_seconds`	number \| null	Total execution time in seconds

Result

Represents the output of a routine.

Field	Type	Description
`ok`	boolean	Whether the routine execution was successful
`error`	string \| null	Error message from the routine execution
`warnings`	string[]	Warnings from the routine execution
`operations_metadata`	OperationMetadata[]	Per-operation execution metadata (see below)
`placeholder_resolution`	object	Resolved placeholder values from the execution
`is_base64`	boolean	Whether `data` is base64-encoded binary content
`content_type`	string \| null	MIME type of the data (e.g., `"application/pdf"`)
`filename`	string \| null	Suggested filename for binary data
`data`	object \| array \| string \| null	Data returned by the routine

OperationMetadata

Metadata collected during each operation's execution.

Field	Type	Description
`type`	string	The operation type (e.g., `"navigate"`, `"fetch"`, `"click"`)
`duration_seconds`	number	How long the operation took to execute
`details`	object	Operation-specific data (e.g., HTTP status codes)
`error`	string \| null	Error message if the operation failed

Validation result

Returned by validation endpoints.

Valid response

JSON

Invalid response

JSON

Fields

Field	Type	Description
`valid`	boolean	Whether validation passed
`errors`	array	List of validation errors (empty if valid)

Pagination

List endpoints support pagination via query parameters.

Query parameters

Parameter	Type	Default	Description
`limit`	integer	20	Maximum items to return (1-100)
`offset`	integer	0	Number of items to skip

Paginated response

JSON