# Recipes

# Quick reference

Type Resource Description
GET /api/managed_users/:id/recipes List recipes belonging to a customer account.
GET /api/managed_users/:id/recipes/:recipe_id Get details of a recipe belonging to a customer account.
GET /api/recipes/search Search for public recipes.
POST /api/managed_users/:managed_user_id/recipes Create a recipe in a customer account.
PUT /api/managed_users/:id/recipes/:recipe_id Update a recipe in a customer account.
DELETE /api/managed_users/:id/recipes/:recipe_id Delete a recipe in a customer account.
PUT /api/managed_users/:id/recipes/:recipe_id/start Start a recipe in a customer account.
PUT /api/managed_users/:managed_user_id/recipes/:recipe_id/stop Stop a recipe in a customer account.

# List recipes in a customer account

Returns a list of recipes belonging to the authenticated user. Recipes are returned in descending ID order. Lifetime task count has task data starting from March 19, 2021.

Recipes can be filtered by state (running/stopped) and subsequently filtered by stopped date and reason.

GET /api/managed_users/:id/recipes

# URL parameters

Name Type Description
id string
required
Workato Embedded customer Account ID/External ID.
External ID must be prefixed with an E(eg: EA2300) and the resulting ID should be URL encoded.
adapter_names_any string
optional
List of adapters names. Resulting recipes should use at least one of given adapters.
adapter_names_all string
optional
List of adapters names. Resulting recipes should use all of given adapters.
page integer
optional
Page number (defaults to 1).
per_page integer
optional
Page size (defaults to 10, maximum allowed is 100 per page).
since_id integer
optional
Find recipes with ID less than the given ID.
folder_id string
optional
Return the recipes in the specified folder.
running boolean
optional
If true, returns running recipes.
stopped_after string
optional
Filter out recipes that were stopped after a specified date/time. Date and time should be given in ISO 8601 format.
stop_cause string
optional
Reason that the recipe stopped. Possible reasons include —
trigger_errors_limit: Recipe was stopped due to consecutive trigger errors
action_quota_limit: Customer exceeded plan's task limit
trial_expired: Customer's trial expired
txn_quota_limit: Customer exceeded plan's job limit

# Sample request

curl  -X GET https://www.workato.com/api/managed_users/91829/recipes?active=true \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>'

# Response

{
    "result": [
        {
            "id": 51554,
            "user_id": 4248,
            "name": "Send mail",
            "created_at": "2021-10-28T05:15:40.869-07:00",
            "updated_at": "2021-10-28T05:15:40.869-07:00",
            "copy_count": 1,
            "trigger_application": "clock",
            "action_applications": [
                "email"
            ],
            "applications": [
                "clock",
                "email"
            ],
            "description": "When there is a trigger on a specified interval, send email via Workato",
            "parameters_schema": [],
            "parameters": {},
            "folder_id": 4520,
            "running": true,
            "job_succeeded_count": 0,
            "job_failed_count": 0,
            "lifetime_task_count": 0,
            "last_run_at": "2016-08-03T11:06:51.481-07:00",
            "stopped_at": "2021-09-03T11:06:51.481-07:00",
            "version_no": 2,
            "webhook_url": null,
            "stop_cause": null,
            "config": [
                {
                    "keyword": "application",
                    "name": "clock",
                    "provider": "clock",
                    "account_id": null
                },
                {
                    "keyword": "application",
                    "name": "email",
                    "provider": "email",
                    "account_id": null
                }
            ],
            "code": "{\"number\":0,\"provider\":\"clock\",\"name\":\"timer\",\"as\":\"timer\",\"keyword\":\"trigger\",\"dynamicPickListSelection\":{},\"toggleCfg\":{},\"input\":{\"interval\":\"5\",\"start_at\":\"\"},\"block\":[{\"number\":1,\"provider\":\"email\",\"name\":\"send_mail\",\"as\":\"send_mail\",\"keyword\":\"action\",\"dynamicPickListSelection\":{},\"toggleCfg\":{},\"input\":{},\"uuid\":\"cd865246-ece7-4188-845e-33d021664be3\"}],\"uuid\":\"c4b0778d-5a23-4c52-a5bb-4a99ae5d25ae\"}"
        }
    ]
}

# Get recipe in a customer account

Returns details of a specified recipe.

GET /api/managed_users/:id/recipes/:recipe_id

# URL parameters

Name Type Description
id string
required
Workato Embedded customer Account ID/External ID.
External ID must be prefixed with an E(eg: EA2300) and the resulting ID should be URL encoded.
recipe_id integer
required
Recipe ID.

# Payload

Name Type Description
adapter_names_any string
optional
List of adapters names. Resulting recipes should use at least one of given adapters.
adapter_names_all string
optional
List of adapters names. Resulting recipes should use all of given adapters.
page integer
optional
Page number (defaults to 1).
per_page integer
optional
Page size (defaults to 10, maximum allowed is 100 per page).
since_id integer
optional
Find recipes with ID less than the given ID.
folder_id string
optional
Return the recipes in the specified folder.
running boolean
optional
If true, returns running recipes.
stopped_after string
optional
Filter out recipes that were stopped after a specified date/time. Date and time should be given in ISO 8601 format.
stop_cause string
optional
Reason that the recipe stopped. Possible reasons include —
trigger_errors_limit: Recipe was stopped due to consecutive trigger errors
action_quota_limit: Customer exceeded plan's task limit
trial_expired: Customer's trial expired
txn_quota_limit: Customer exceeded plan's job limit

# Sample request

curl  -X GET https://www.workato.com/api/managed_users/91829/recipes?active=true \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>'

# Response

{
    "result": [
      {
          "id": 281302,
          "user_id": 4848,
          "name": "New webhook call will get JIRA ticket information",
          "created_at": "2016-08-03T11:06:23.950-07:00",
          "updated_at": "2021-11-29T23:31:58.735-08:00",
          "copy_count": 3,
          "trigger_application": "workato_webhooks",
          "action_applications": [
              "jira"
          ],
          "applications": [
              "workato_webhooks",
              "jira"
          ],
          "description": "New webhook call will get JIRA ticket information",
          "parameters_schema": [],
          "parameters": {},
          "folder_id": 4724,
          "running": false,
          "job_succeeded_count": 0,
          "job_failed_count": 0,
          "lifetime_task_count": 0,
          "last_run_at": "2016-08-03T11:06:51.481-07:00",
          "stopped_at": "2016-08-03T11:22:57.285-07:00",
          "version_no": 2,
          "webhook_url": "https://www.workato.com/webhooks/rest/51b6a38f-0102-494d-8290-9d550aeeab3c/webhook_recipe",
          "stop_cause": null,
          "config": [
              {
                  "name": "jira",
                  "provider": "jira",
                  "keyword": "application",
                  "skip_validation": false,
                  "account_id": null
              },
              {
                  "keyword": "application",
                  "name": "workato_webhooks",
                  "provider": "workato_webhooks",
                  "skip_validation": false,
                  "account_id": null
              }
          ],
          "code": "...truncated...",
          "author_name": "Workato API"
      }
    ]
}

# Search for public recipes

Searches for public recipes and returns a list. Returns an empty list when no matching connectors are found.

GET /api/recipes/search

# URL parameters

Name Type Description
term string
optional
Search term.
boost_owned boolean
optional
If true, returned results will give priority to recipes in your account. Defaults to false.
page integer
optional
Page number. Defaults to 0.
per_page integer
optional
Page size. Defaults to 20, max 20.

# Payload

Name Type Description
applications string
required
Comma separated connector identifiers (e.g: salesforce,service_now).

# Sample request

curl  -X GET https://www.workato.com/api/recipes/search?per_page=1 \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "applications": "salesforce,service_now"
          }'

# Response

{
  "items": [
    {
      "id": 59,
      "user_id": 50,
      "name": "Recipe 58",
      "created_at": "2015-05-26T22:53:39.032Z",
      "updated_at": "2015-05-26T22:53:39.032Z",
      "copy_count": 1,
      "trigger_application": null,
      "action_applications": [
        "salesforce",
        "service_now"
      ],
      "applications": [
        "salesforce"
      ],
      "description": "Recipe description 58",
      "parameters_schema": []
    }
  ]
}

# Create recipe in a customer account

Creates a recipe in Workato based on parameters in the request.

POST /api/managed_users/:id/recipes

# URL parameters

Name Type Description
id string
required
Workato Embedded customer Account ID/External ID.
External ID must be prefixed with an E(eg: EA2300) and the resulting ID should be URL encoded.

# Payload

Name Type Description
name string
required
Name of the recipe.
code string
required
JSON string representing the recipe lines.
config string
required
JSON string representing the connection lines.
recipe object
optional
The recipe object.

# Sample request

curl  -X POST https://www.workato.com/api/managed_users/recipes \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \
      -d  '{
             "name":"Send mail",
             "code":"{\"number\":0,\"provider\":\"clock\",\"name\":\"scheduled_event\",\"as\":\"timer\",\"title\":null,\"description\":\"<span class=\\\"provider\\\">Trigger</span> on a <span class=\\\"provider\\\">specified schedule</span>\",\"keyword\":\"trigger\",\"dynamicPickListSelection\":{},\"toggleCfg\":{},\"input\":{\"time_unit\":\"minutes\",\"trigger_every\":\"5\"},\"extended_input_schema\":[{\"type\":\"string\",\"name\":\"trigger_every\",\"control_type\":\"integer\",\"label\":\"Trigger every\",\"hint\":\"Define repeating schedule. Enter whole numbers only.\\n                        This field can be set to a minimum of 5 minutes.\",\"default\":\"5\",\"optional\":false,\"extends_schema\":true},{\"type\":\"date_time\",\"name\":\"start_after\",\"control_type\":\"date_time\",\"label\":\"Start after\",\"hint\":\"Set date and time to start or leave blank to start immediately. <b>Once recipe has been run or tested, value cannot be changed.</b>\",\"optional\":true,\"extends_schema\":true,\"since_field\":true,\"render_input\":\"date_time_conversion\",\"parse_output\":\"date_time_conversion\"}],\"block\":[{\"number\":1,\"provider\":\"email\",\"name\":\"send_mail\",\"as\":\"send_mail\",\"keyword\":\"action\",\"dynamicPickListSelection\":{},\"toggleCfg\":{},\"input\":{\"email_type\":\"html\"},\"uuid\":\"cd865246-ece7-4188-845e-33d021664be3\"}],\"uuid\":\"c4b0778d-5a23-4c52-a5bb-4a99ae5d25ae\"}",
             "config":"[{\"keyword\":\"application\",\"name\":\"clock\",\"provider\":\"clock\"},{\"keyword\":\"application\",\"name\":\"email\",\"provider\":\"email\"}]"
          }'

# Response

{
  "success": true,
  "id": 11613
}

# Update recipe in a customer account

Updates an existing recipe in Workato specified based on recipe ID. Recipe details are defined based on parameters in the request.

PUT /api/managed_users/:id/recipes/:recipe_id

# URL parameters

Name Type Description
id string
required
Workato Embedded customer Account ID/External ID.
External ID must be prefixed with an E(eg: EA2300) and the resulting ID should be URL encoded.
recipe_id integer
required
Recipe ID.

# Payload

Name Type Description
recipe object
optional
The recipe object.
recipe[name] string
optional
Name of the recipe.
recipe[code] string
optional
JSON string representing the recipe lines.
recipe[config] string
optional
JSON string representing the connection lines.

# Sample request

curl  -X PUT 'https://www.workato.com/api/managed_users/17829/recipes/1389' \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "Send mail",
            "code": "{\"number\":0,\"provider\":\"clock\",\"name\":\"timer\",\"as\":\"timer\",\"keyword\":\"trigger\",\"dynamicPickListSelection\":{},\"toggleCfg\":{},\"input\":{\"interval\":\"5\",\"start_at\":\"\"},\"block\":[{\"number\":1,\"provider\":\"email\",\"name\":\"send_mail\",\"as\":\"send_mail\",\"keyword\":\"action\",\"dynamicPickListSelection\":{},\"toggleCfg\":{},\"input\":{},\"uuid\":\"cd865246-ece7-4188-845e-33d021664be3\"}],\"uuid\":\"c4b0778d-5a23-4c52-a5bb-4a99ae5d25ae\"}",
            "config": "[{\"keyword\":\"application\",\"name\":\"clock\",\"provider\":\"clock\"},{\"keyword\":\"application\",\"name\":\"email\",\"provider\":\"email\"}]"
          }'

# Response

{
  "success": true
}

You cannot update a running recipe

Any update call to a running recipe will return an error.

# Delete recipe in a customer account

Deletes an existing recipe in Workato specified based on recipe ID.

DELETE /api/managed_users/:id/recipes/:recipe_id

# URL parameters

Name Type Description
id string
required
Workato Embedded customer Account ID/External ID.
External ID must be prefixed with an E(eg: EA2300) and the resulting ID should be URL encoded.
recipe_id integer
required
Recipe ID.

# Sample request

curl  -X DELETE 'https://www.workato.com/api/managed_users/17829/recipes/1389' \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json'

# Response

{
  "success": true
}

# Start recipe in a customer account

Starts a recipe in a customer account specified by recipe ID.

PUT /api/managed_users/:managed_user_id/recipes/:recipe_id/start

# URL parameters

Name Type Description
managed_user_id string
required
Workato Embedded customer Account ID/External ID.
External ID must be prefixed with an E(eg: EA2300) and the resulting ID should be URL encoded.
recipe_id integer
optional
Recipe ID.

# Sample request

curl  -X PUT https://www.workato.com/api/managed_users/91929/recipes/1028949/start \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>'

# Response

{
  "success": true
}

# Stop recipe in a customer account

Stops a recipe in a customer account specified by recipe ID.

PUT /api/managed_users/:managed_user_id/recipes/:recipe_id/stop

# URL parameters

Name Type Description
managed_user_id string
required
Workato Embedded customer Account ID/External ID.
External ID must be prefixed with an E(eg: EA2300) and the resulting ID should be URL encoded.
recipe_id interger
optional
Recipe ID.

# Sample request

curl  -X PUT https://www.workato.com/api/managed_users/91929/recipes/1028949/stop \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>'

# Response

{
  "success": true
}