Params

Task params let you pass input values into a script at run time. They are defined per task version via a JSON Schema and validated before execution starts.

Defining a params schema

On the task detail page, use the Params schema editor alongside the DSL script. The schema follows JSON Schema conventions:

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "Customer email address"
    },
    "orderId": {
      "type": "string",
      "description": "Order ID to look up"
    },
    "items": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["email"]
}

Each version can have its own params schema. Changing the schema creates a new version.

Using params in DSL

Params are available as $params.* anywhere in the script:

flow {
  in portal {
    fill { css "#search" } $params.orderId
    click { css "button[type='submit']" }
    wait visible { css ".results" } timeout 15000
    extract { css ".status" } as status
  }
}

Iterating over param arrays

flow {
  for item in $params.items {
    click { text item }
    wait visible { css ".detail" } timeout 5000
  }
}

Conditional logic

flow {
  if $params.mode == "fast" {
    click { css "#skip-wizard" }
  } else {
    click { css "#full-wizard" }
  }
}

Remember: comparisons use ==, not =.

Manual runs (UI)

When you click Run on a task:

1. reArray renders a form from the params schema
2. Required fields must be filled before queuing
3. Values are validated against the schema
4. Valid params are passed to the execution as $params.*

API runs

When creating an execution via the Integration API, pass params in the request body:

curl -X POST https://your-app.example.com/api/v1/integrations/executions \
  -H "Authorization: Bearer ra_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "uuid",
    "task_id": "uuid",
    "params": {
      "email": "user@example.com",
      "orderId": "ORD-12345"
    }
  }'

Invalid params return a 422 validation error before an execution is created.

Use validate_only=true to check params without queuing:

curl -X POST "https://your-app.example.com/api/v1/integrations/executions?validate_only=true" \
  -H "Authorization: Bearer ra_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "uuid", "task_id": "uuid", "params": { ... } }'

Fetching the params schema via API

Retrieve the schema for integration UIs or dynamic form builders:

GET /api/v1/integrations/tasks/{task_id}/params-schema
GET /api/v1/integrations/tasks/{task_id}/params-schema?version=3

Store schema

Tasks can also define a store schema describing expected $store.* output shape. This is optional and used for validation and documentation — extracted values populate $store during execution regardless of whether a store schema is defined.