Product UpdatesStatus PageAutomation Institute
▼ 日本語
Developer API
Resources

# Recipes

# Quick reference

Type Resource Description
GET /api/recipes/:id Get recipe details.
POST /api/recipes Create a recipe.
POST /api/recipes/:id/copy Copy a recipe.
PUT /api/recipes/:id Update a recipe.
GET /api/recipes List recipes belonging to user.
PUT /api/recipes/:id/start Start recipe.
PUT /api/recipes/:id/stop Stop recipe.
DELETE /api/recipes/:id Delete recipe.
POST /api/recipes/:recipe_id/reset_trigger Reset recipe trigger.
PUT /api/recipes/:recipe_id/connect Update connection for an Application in a stopped recipe.
POST /api/recipes/:recipe_id/poll_now Start a poll-now recipe.

# Get recipe details

Returns details about a recipe object. Lifetime task count has task data starting from March 19, 2021.

GET /api/recipes/:id

# URL parameters

Name Type Description
id integer
required		 Recipe ID.

# Sample request

curl  -X GET 'https://www.workato.com/api/recipes/12389' \
      -H 'Authorization: Bearer <api_token>'

# Response

{
    "id": 12389,
    "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": "Kevin Smith",
    "version_author_name": "Jennifer Diaz"    
}

# Create a recipe

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

POST /api/recipes

# 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

# Sample request

curl  -X POST https://www.workato.com/api/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": 116
}

# Update a recipe

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

PUT /api/recipes/:id

# URL parameters

Name Type Description
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

# Sample request

curl  -X PUT 'https://www.workato.com/api/recipes/123421' \
      -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
}

You cannot update a running recipe

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

# Copy a recipe

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

POST /api/recipes/:id/copy

# URL parameters

Name Type Description
id integer
required		 Recipe ID.

# Payload

Name Type Description
folder_id string
optional		 Folder id for the copied recipe

# Sample request

curl  -X POST 'https://www.workato.com/api/recipes/123421/copy' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json'

# Response

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

# List recipes belonging to a user

Returns a list of recipes belonging to the authenticated user. Recipes are returned in descending ID order.

GET /api/recipes

# URL parameters

Name Type Description
adapter_names_any string
optional		 List of adapters names, separated by commas. Resulting recipes should use at least one of given adapters.
adapter_names_all string
optional		 List of adapters names, separated by commas. 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
order string
optional		 Set ordering method. Possible options: activity, default.

# Sample request

curl  -X GET https://www.workato.com/api/recipes/?adapter_names_any=custom_adapter,custom_adapter1 \
      -H 'Authorization: Bearer <api_token>'

# Response

{
    "items": [
        {
            "id": 1913515,
            "user_id": 4848,
            "name": "Callable service: JIRA ticket sync",
            "created_at": "2021-11-25T07:07:38.568-08:00",
            "updated_at": "2021-11-25T07:14:40.822-08:00",
            "copy_count": 1,
            "trigger_application": "workato_service",
            "action_applications": [
                "jira"
            ],
            "applications": [
                "workato_service",
                "jira"
            ],
            "description": "When there is a new call for callable recipe, do action",
            "parameters_schema": [],
            "parameters": {},
            "folder_id": 241557,
            "running": false,
            "job_succeeded_count": 1,
            "job_failed_count": 0,
            "lifetime_task_count": 1,
            "last_run_at": "2021-11-25T07:10:27.424-08:00",
            "stopped_at": "2021-11-25T07:11:06.346-08:00",
            "version_no": 3,
            "webhook_url": null,
            "stop_cause": null,
            "config": [
                {
                    "keyword": "application",
                    "name": "workato_service",
                    "provider": "workato_service",
                    "skip_validation": false,
                    "account_id": null
                },
                {
                    "keyword": "application",
                    "name": "jira",
                    "provider": "jira",
                    "skip_validation": false,
                    "account_id": null
                }
            ],
            "code": "...truncated..."
        }
      ]
}

# Start a recipe

Starts a recipe specified by recipe ID.

PUT /api/recipes/:id/start

# URL parameters

Name Type Description
id integer
optional		 Recipe ID.

# Sample request

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

# Response

{
  "success": true
}

# Stop a recipe

Stops a recipe specified by a recipe ID.

PUT /api/recipes/:id/stop

# URL parameters

Name Type Description
id integer
optional		 Recipe ID.

# Sample request

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

# Response

{
  "success": true
}

# Delete a recipe

Delete a recipe specified by ID.

DELETE /api/recipes/:id

# URL parameters

Name Type Description
id integer
optional		 Recipe ID.

# Sample request

curl  -X DELETE https://www.workato.com/api/recipes/<recipe_id> \
      -H 'Authorization: Bearer <api_token>'

# Response

{
  "success": true
}

# Reset recipe trigger

Reset recipe trigger cursor by recipe ID. 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 you reset the trigger of an active recipe, Workato completes all jobs with a running, deferred, or pending status first. Then, it proceeds 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
  • Deprecated Kafka triggers (compatible with latest triggers)
POST /api/recipes/:recipe_id/reset_trigger

# URL parameters

Name Type Description
recipe_id integer
required		 ID of the recipe to reset.

# Sample request

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

# Response

{
    "success": true
}

# Update a connection for a recipe

Updates the chosen connection for a specific connector in a stopped recipe.

PUT /api/recipes/:recipe_id/connect

# URL parameters

Name Type Description
recipe_id integer
required		 ID of the recipe.

# Payload

Name Type Description
adapter_name string
required		 The internal name of the connector. e.g. salesforce
connection_id integer
required		 The ID of the connection that replaces the existing one.

# Sample request

curl  -X PUT 'https://www.workato.com/api/recipes/123421/connect' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
          "adapter_name": "salesforce",
          "connection_id": 772461
      }'

# 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/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/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"}
← Publish batch of messages
Recipe Lifecycle Management →


Last updated: 10/18/2023, 7:14:53 PM

On this page