Product UpdatesStatus PageAutomation Institute
English
Embedded API
Resources

# Recipes

# Quick reference

Type Resource Description
GET /api/managed_users/:id/recipes List recipes belonging to a customer.
GET /api/managed_users/:id/recipes/:recipe_id Get details of a recipe belonging to a customer.
GET /api/recipes/search Search for public recipes.
POST /api/managed_users/:managed_user_id/recipes Create a recipe in a customer workspace.
PUT /api/managed_users/:id/recipes/:recipe_id Update a recipe in a customer workspace.
POST /api/managed_users/:id/recipes/:recipe_id/copy Copy a recipe in a customer workspace.
DELETE /api/managed_users/:id/recipes/:recipe_id Delete a recipe in a customer workspace.
PUT /api/managed_users/:id/recipes/:recipe_id/start Start a recipe in a customer workspace.
PUT /api/managed_users/:managed_user_id/recipes/
:recipe_id/stop		 Stop a recipe in a customer workspace.
POST /api/managed_users/:managed_user_id/recipes/
:recipe_id/reset_trigger		 Reset recipe trigger.
POST /api/managed_users/:managed_user_id/recipes/
:recipe_id/poll_now		 Start a poll-now recipe.

# List recipes in a customer workspace

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		 Embedded customer ID/external ID.
External ID must be prefixed with an E (for example, EA2300) and the resulting ID should be URL encoded.

# Query parameters

Name Type Description
adapter_names_all string
optional		 List of adapter names, separated by commas. Resulting recipes should use all of given adapters.
adapter_names_any string
optional		 List of adapter names, separated by commas. Resulting recipes should use at least one of the given adapters.
folder_id string
optional		 Return the recipes in the specified folder.
page integer
optional		 Page number (defaults to 1).
per_page integer
optional		 Page size (defaults to 10, maximum allowed is 100 per page).
running boolean
optional		 If true, returns running recipes.
since_id integer
optional		 Use this parameter to retrieve recipes with IDs lower than the ID you provided in the request. For example, if since_id=15500, Workato returns all recipes in the customer workspace with IDs lower than 15500 (0-14999).
stopped_after string
optional		 Filter out recipes that were stopped after the date and time you specify. The date and time must be provided in ISO 8601 format according to the following pattern: YYYY-MM-DDTHH:MM:SSZ.
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
updated_after string
optional		 Filter the list of recipes to include only those updated after the date and time you specify. The date and time must be provided in ISO 8601 format according to the following pattern: YYYY-MM-DDTHH:MM:SSZ.

# Sample request

curl  -X GET https://www.workato.com/api/managed_users/91829/recipes?active=true \
      -H 'Authorization: Bearer <api_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",
            "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\"}",
            "version_no": 2,
            "author_name": "Kevin Smith",
            "version_author_name": "Jennifer Diaz",
            "version_author_email": "jennifer.diaz@example.com"
        }
    ]
}

# Get recipe in a customer workspace

Returns details of a specified recipe.

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

# URL parameters

Name Type Description
id string
required		 Embedded customer ID/external ID.
External ID must be prefixed with an E (for example, EA2300) and the resulting ID should be URL encoded.
recipe_id integer
required		 Recipe ID.

# Sample request

curl  -X GET https://www.workato.com/api/managed_users/91829/recipes?active=true \
      -H 'Authorization: Bearer <api_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",
          "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...",
          "version_no": 2,
          "version_author_name": "Jennifer Diaz",
          "version_author_email": "jennifer.diaz@example.com",
          "author_name": "Kevin Smith"
      }
    ]
}

# 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

# Query parameters

Name Type Description
applications string
required		 Comma separated connector identifiers (e.g: salesforce,service_now).
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.

# Sample request

curl  -X GET https://www.workato.com/api/recipes/search?per_page=1 \
      -H 'Authorization: Bearer <api_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 workspace

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		 Embedded customer ID/external ID.
External ID must be prefixed with an E (for example, EA2300) and the resulting ID should be URL encoded.

# Payload

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

# Sample request

curl  -X POST https://www.workato.com/api/managed_users/17829/recipes \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
             "recipe": {
               "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\"}]",
               "folder_id": "17254"
             }
          }'

# Response

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

# Update recipe in a customer workspace

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		 Embedded customer ID/external ID.
External ID must be prefixed with anE (for example, 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.
recipe[folder_id] string
optional		 Folder for the recipe
recipe[description] string
optional		 Description of the recipe.

# Sample request

curl  -X PUT 'https://www.workato.com/api/managed_users/17829/recipes/1389' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "recipe": {
              "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\"}]",
              "folder_id": "17254"
             }
          }'

# Response

{
  "success": true
}

You cannot update a running recipe

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

# Copy recipe in a customer workspace

Copies an existing recipe in Workato based on its recipe ID.

POST /api/managed_users/:id/recipes/:recipe_id/copy

# URL parameters

Name Type Description
id string
required		 Embedded customer ID/external ID.
The External ID must be URL encoded and prefixed with an E (for example, EA2300).
recipe_id integer
required		 Recipe ID.

# Payload

Name Type Description
folder_id string
optional		 ID of the folder you plan to copy the recipe to.

# Sample request

curl  -X POST 'https://www.workato.com/api/managed_users/12345/recipes/234567/copy' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{"folder_id": "98765"}'

# Response

{
  "success": true,
  "new_flow_id": 345678
}

# Delete recipe in a customer workspace

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		 Embedded customer ID/external ID.
External ID must be prefixed with an E (for example, 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 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json'

# Response

{
  "success": true
}

# Start recipe in a customer workspace

Starts a recipe in a customer workspace 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		 Embedded customer ID/external ID.
External ID must be prefixed with an E (for example, EA2300) and the resulting ID should be URL encoded.
recipe_id integer
required		 The ID of the recipe you plan to start.

# Sample request

curl  -X PUT https://www.workato.com/api/managed_users/91929/recipes/1028949/start \
      -H 'Authorization: Bearer <api_token>'

# Response

{
  "success": true
}

# Stop recipe in a customer workspace

Stops a recipe in a customer workspace 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		 Embedded customer ID/external ID.
External ID must be prefixed with an E (for example, EA2300) and the resulting ID should be URL encoded.
recipe_id integer
required		 The ID of the recipe you plan to stop.

# Sample request

curl  -X PUT https://www.workato.com/api/managed_users/91929/recipes/1028949/stop \
      -H 'Authorization: Bearer <api_token>'

# Response

{
  "success": true
}

# Reset recipe trigger

Reset recipe trigger cursor by recipe ID for a customer. Use this endpoint to re-sync data from the source application. The recipe should be designed to handle duplicate records because a re-sync processes every record again. Using this endpoint outside data integration scenarios may result in unintended behaviors, including data loss or corruption. Resetting a recipe trigger retains job history and records an event in the recipe's Activity audit log.

If the trigger is reset on an active recipe, running, deferred, and pending jobs run and complete before proceeding to the new jobs created by the reset trigger.

Trigger compatibility

This endpoint is only compatible with polling and scheduled triggers. Resetting other triggers may have no effect, or cause unintended behaviors. These triggers include:

  • New CSV file in folder triggers
  • Function triggers
  • API triggers
  • RecipeOps triggers
  • Workbot triggers
  • Kafka triggers
POST /api/managed_users/:managed_user_id/recipes/:recipe_id/reset_trigger

# Path parameters

Name Type Description
managed_user_id string
required		 Embedded customer ID/external ID.
External ID must be prefixed with an E (for example, EA2300) and the resulting ID should be URL encoded.
recipe_id integer
required		 ID of the recipe to reset.

# Sample request

curl  -X POST https://www.workato.com/api/managed_users/E1234/recipes/91929/reset_trigger \
      -H 'Authorization: Bearer <api_token>'

# Response

{
    "success": true
}

# Start a poll-now recipe

Start a poll-now recipe in real-time by providing the recipe ID.

Use the jobs APIs to check the status of a particular recipe.

POST /api/managed_users/:managed_user_id/recipes/:recipe_id/poll_now

# Path parameters

Name Type Description
recipe_id integer
required		 The ID of the recipe you plan to start.

# Sample request

curl  -X POST https://www.workato.com/api/managed_users/E1234/recipes/12345/poll_now \
      -H 'Authorization: Bearer <api_token>'

# Response

# Job started

{
    "success": true
}

# Job already in progress

{ 
    "message": "Recipe is currently in trigger back off mode till 2023-06-23T23:02" }
}

# Error codes

Name Description Sample reply
404 Not found {"success": false, "message": "Not Found"}
429 Too many requests. A Retry-After header (opens new window) specifies how long to wait before making a new request. {"message": "Recipe is currently in trigger back off mode till 2023-06-23T11:02"}, or {"message": "Not enough transaction credit"}, or {"message": "Not enough action quota"}
400 Bad request {"message":"Trial has expired"}
← Upsert project properties
Recipe lifecycle management →


Last updated: 4/25/2024, 5:58:27 PM

On this page