Product UpdatesStatus PageWorkato Academy
English
日本語
Get a trial
Embedded API
Resources

Recipes ​

Use these resources to programmatically manage customer recipes.

Rate limits ​

Recipe resources have the following rate limits:

TypeResourceQuota
POSTForce an on-demand run of a recipe:
/api/managed_users/:managed_user_id
/recipes/:recipe_id/force_run		1 request per second
GETList recipes in a customer workspace:
/api/managed_users/:id/recipes		2,000 requests per minute
GETGet recipe in a customer workspace:
/api/managed_users/:id/recipes
/:recipe_id		2,000 requests per minute
AllAll Recipe versions endpoints60 requests per minute
AllAll other Recipes endpoints1,000 requests per minute

Quick reference ​

TypeResourceDescription
GET/api/managed_users/:managed_user_id/recipesList recipes belonging to a customer.
GET/api/managed_users/:managed_user_id/recipes/job_countsGet job counts for one or more recipes belonging to a customer.
GET/api/managed_users/:managed_user_id/recipes/:recipe_idGet details of a recipe belonging to a customer.
POST/api/managed_users/:managed_user_id/recipesCreate a recipe in a customer workspace.
PUT/api/managed_users/:id/recipes/:recipe_idUpdate a recipe in a customer workspace.
POST/api/managed_users/:id/recipes/:recipe_id/copyCopy a recipe in a customer workspace.
DELETE/api/managed_users/:id/recipes/:recipe_idDelete a recipe in a customer workspace.
PUT/api/managed_users/:id/recipes/:recipe_id/startStart a recipe in a customer workspace.
PUT/api/managed_users/:managed_user_id/recipes/:recipe_id/stopStop a recipe in a customer workspace.
POST/api/managed_users/:managed_user_id/recipes/:recipe_id/reset_triggerReset recipe trigger.
POST/api/managed_users/:managed_user_id/recipes/:recipe_id/poll_nowStart a poll-now recipe.
POST/api/managed_users/:managed_user_id/recipes/:recipe_id/force_runForce a recipe to run on demand in a customer workspace.
GET/api/v2/managed_users/:managed_user_id/recipes/:recipe_id/versionsGet versions of a recipe belonging to a customer.
GET/api/v2/managed_users/:managed_user_id/recipes/:recipe_id/versions/:idGet details of a recipe version belonging to a customer.
PATCH/PUT/api/v2/managed_users/:managed_user_id/recipes/:recipe_id/versions/:idUpdate a recipe version comment in a customer workspace.

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 https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes

URL parameters ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID. External ID must be prefixed with an E and be URL encoded. For example, EA2300.

Query parameters ​

NameTypeDescription
adapter_names_allstring
optional		List of adapter names, separated by commas. Resulting recipes should use all of given adapters.
adapter_names_anystring
optional		List of adapter names, separated by commas. Resulting recipes should use at least one of the given adapters.
folder_idstring
optional		Return the recipes in the specified folder.
with_subfoldersboolean
optional		If true, includes recipes from subfolders of the folder specified by folder_id. The default is false.
pageinteger
optional		Page number (defaults to 1).
per_pageinteger
optional		Specifies the number of recipes to include per page. Defaults to 100. The maximum value is 100.
runningboolean
optional		If true, returns running recipes.
since_idinteger
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_afterstring
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_causestring
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 quota
trial_expired: Customer's trial expired
txn_quota_limit: Customer exceeded plan's job quota
updated_afterstring
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.
includes[]array of strings
optional		Specifies additional fields to include in the response. Accepts tags as a value. If tags is supplied in the request, the response includes a tags field for each recipe. This field contains an array of zero or more tag handles (strings).
project_idstring
optional		The ID of a specific project.

Sample request ​

shell
curl  -X GET 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes?folder_id=:folder_id&with_subfolders=:true_or_false&includes[]=tags' \
      -H 'Authorization: Bearer <api_token>'

Response ​

json
{
    "result": [
        {
            "id": 66876978,
            "user_id": 6471278,
            "name": "Sync new contacts from HubSpot to Mailchimp",
            "created_at": "2025-10-15T13:41:05.207-07:00",
            "updated_at": "2025-10-15T13:41:05.207-07:00",
            "copy_count": 1,
            "trigger_application": "hubspot",
            "action_applications": [
                "mailchimp"
            ],
            "applications": [
                "hubspot",
                "mailchimp"
            ],
            "description": "When a new contact is created in HubSpot, add them to the newsletter list in Mailchimp.",
            "project_id": 13595198,
            "parameters_schema": [],
            "parameters": {},
            "webhook_url": null,
            "folder_id": 27180381,
            "running": false,
            "job_succeeded_count": 0,
            "job_failed_count": 0,
            "lifetime_task_count": 0,
            "last_run_at": null,
            "stopped_at": null,
            "version_no": 1,
            "stop_cause": null,
            "config": [
                {
                    "keyword": "application",
                    "name": "hubspot",
                    "provider": "hubspot",
                    "account_id": 18253670,
                    "skip_validation": false
                },
                {
                    "keyword": "application",
                    "name": "mailchimp",
                    "provider": "mailchimp",
                    "account_id": 18253671,
                    "skip_validation": false
                }
            ],
            "trigger_closure": null,
            "code": "...truncated...",
            "author_name": "Sales",
            "version_author_name": "Alex",
            "version_author_email": "alex@workato.com",
            "version_comment": null,
            "tags": [
                "tag-BNgeffPL-4hxRwB"
            ]
        },
        {
            "id": 66870000,
            "user_id": 6471278,
            "name": "Post Slack notifications when new leads are created in Salesforce",
            "created_at": "2025-10-15T10:47:45.142-07:00",
            "updated_at": "2025-10-15T10:57:36.857-07:00",
            "copy_count": 1,
            "trigger_application": "salesforce",
            "action_applications": [
                "slack"
            ],
            "applications": [
                "salesforce",
                "slack"
            ],
            "description": "1. New lead is created in Salesforce.\n2. Workato posts a message in Slack with the lead details.",
            "project_id": 13595198,
            "parameters_schema": [],
            "parameters": {},
            "webhook_url": null,
            "folder_id": 27180380,
            "running": false,
            "job_succeeded_count": 1,
            "job_failed_count": 0,
            "lifetime_task_count": 3,
            "last_run_at": "2025-10-15T10:51:29.528-07:00",
            "last_job_started_at": "2025-10-15T10:50:00.000-07:00",
            "stopped_at": "2025-10-15T10:54:29.298-07:00",
            "version_no": 6,
            "stop_cause": null,
            "config": [
                {
                    "keyword": "application",
                    "name": "salesforce",
                    "provider": "salesforce",
                    "account_id": 18253669,
                    "skip_validation": false
                },
                {
                    "keyword": "application",
                    "name": "slack",
                    "provider": "slack",
                    "account_id": 18253665,
                    "skip_validation": false
                }
            ],
            "trigger_closure": null,
            "code": "...truncated...",
            "author_name": "Sales",
            "version_author_name": "Alex",
            "version_author_email": "alex@workato.com",
            "version_comment": null,
            "tags": [
                "tag-ANMNxAz9-oYDJRm",
                "tag-ANgeffPL-3gxQwA"
            ]
        }
    ],
    "count": 2,
    "page": 1,
    "per_page": 100
}

RESPONSE FIELDS

The last_run_at field returns the timestamp when the recipe most recently started. The last_job_started_at field returns the timestamp when the most recent job for the recipe started. The stopped_at field returns the timestamp when the recipe most recently stopped.

These fields show when the recipe or its most recent job started or stopped. They don't include timestamps for earlier jobs.

The code field returns a JSON string describing the configuration of each recipe step. You can use code as an input for the Create recipe and Update recipe endpoints.

Get recipe job counts in a customer workspace ​

Returns job success and failure counts for one or more recipes belonging to a customer. Statistics cover the most recent 90 days. Recipes that don't have jobs in the 90-day time period are excluded from the response.

GET https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/job_counts

URL parameters ​

NameTypeDescription
managed_user_idstring
required		The Embedded customer ID or external ID.
External IDs must be URL encoded and prefixed with an E, for example: EA2300.

Query parameters ​

NameTypeDescription
recipe_ids[]array of integers
required		Recipe IDs to retrieve job counts for. You can specify multiple recipe IDs, but the request URL can't exceed 10,240 characters.

Sample request ​

shell
curl  -X GET 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/job_counts?recipe_ids[]=56652213&recipe_ids[]=56652186' \
      -H 'Authorization: Bearer <api_token>'

Response ​

json
{
  "result": {
    "items": [
      {
        "recipe_id": 56652213,
        "job_succeeded_count": 3084,
        "job_failed_count": 12
      },
      {
        "recipe_id": 56652186,
        "job_succeeded_count": 246,
        "job_failed_count": 0
      }
    ]
  }
}

Get recipe in a customer workspace ​

Returns details of a specified recipe.

GET https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/:recipe_id

URL parameters ​

NameTypeDescription
managed_user_idstring
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_idinteger
required		Recipe ID.

Query parameters ​

NameTypeDescription
includes[]array of strings
optional		Specifies additional fields to include in the response. Accepts tags as a value. If tags is supplied in the request, the response includes a tags field for the recipe. This field contains an array of zero or more tag handles (strings).

Sample request ​

shell
curl  -X GET https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/:recipe_id?includes[]=tags&active=:true_or_false \
      -H 'Authorization: Bearer <api_token>'

Response ​

json
{
    "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",
          "last_job_started_at": "2016-08-03T11:06:45.000-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
              }
          ],
          "trigger_closure": null,
          "code": "...truncated...",
          "version_no": 2,
          "version_author_name": "Jennifer Diaz",
          "version_author_email": "jennifer.diaz@example.com",
          "version_comment": "Refactored webhook logic to improve error handling and added support for custom JIRA fields",
          "author_name": "Kevin Smith",
          "tags": [
                "tag-ANMNxAz9-oYDJRm",
                "tag-ANgeffPL-3gxQwA"
            ]
      }
    ]
}

RESPONSE FIELDS

The last_run_at field returns the timestamp when the recipe most recently started. The last_job_started_at field returns the timestamp when the most recent job for the recipe started. The stopped_at field returns the timestamp when the recipe most recently stopped.

These fields show when the recipe or its most recent job started or stopped. They don't include timestamps for earlier jobs.

The code field returns a JSON string describing the configuration of each recipe step. You can use code as an input for the Create recipe and Update recipe endpoints.

Create recipe in a customer workspace ​

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

POST https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes

URL parameters ​

NameTypeDescription
managed_user_idstring
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 ​

NameTypeDescription
recipeobject
required		The recipe object.
recipe[name]string
optional		Name of the recipe.
recipe[code]string
required		JSON string representing the recipe lines. You can retrieve the code for an existing recipe using the Get recipe in a customer workspace or List recipes in a customer workspace endpoint.
recipe[config]string
optional		JSON string representing the connection lines.
recipe[folder_id]string
required		Folder for the recipe
recipe[description]string
optional		Description of the recipe.

FOLDER_ID REQUIRED STARTING MAY 7, 2026

Starting May 7, 2026, the folder_id parameter is required on this endpoint. The value must reference a project or folder other than the Home assets folder. Requests that omit folder_id or target the Home assets folder will return an error.

Sample request ​

shell
curl  -X POST https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
             "recipe": {
               "name": ":name",
               "code": ":code",
               "config": ":config",
               "folder_id": ":folder_id"
             }
          }'

Response ​

json
{
  "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 https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/:recipe_id

URL parameters ​

NameTypeDescription
managed_user_idstring
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_idinteger
required		Recipe ID.

Payload ​

NameTypeDescription
recipeobject
optional		The recipe object.
recipe[name]string
optional		Name of the recipe.
recipe[code]string
optional		JSON string representing the recipe lines. You can retrieve the code for an existing recipe using the Get recipe in a customer workspace or List recipes in a customer workspace endpoint.
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 ​

shell
curl  -X PUT 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/:recipe_id' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "recipe": {
              "name": ":name",
              "code": ":code",
              "config": ":config",
              "folder_id": ":folder_id"
             }
          }'

Response ​

json
{
  "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 https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/:recipe_id/copy

URL parameters ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID.
The External ID must be URL encoded and prefixed with an E (for example, EA2300).
recipe_idinteger
required		Recipe ID.

Payload ​

NameTypeDescription
folder_idstring
required		ID of the folder you plan to copy the recipe to.

FOLDER_ID REQUIRED STARTING MAY 7, 2026

Starting May 7, 2026, the folder_id parameter is required on this endpoint. The value must reference a project or folder other than the Home assets folder. Requests that omit folder_id or target the Home assets folder will return an error.

Sample request ​

shell
curl  -X POST 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/:recipe_id/copy' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{"folder_id": ":folder_id"}'

Response ​

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

Delete recipe in a customer workspace ​

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

DELETE https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/:recipe_id

URL parameters ​

NameTypeDescription
managed_user_idstring
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_idinteger
required		Recipe ID.

Sample request ​

shell
curl  -X DELETE 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/:recipe_id' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json'

Response ​

json
{
  "success": true
}

Start recipe in a customer workspace ​

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

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

URL parameters ​

NameTypeDescription
managed_user_idstring
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_idinteger
required		The ID of the recipe you plan to start.

Sample request ​

shell
curl  -X PUT https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/:recipe_id/start \
      -H 'Authorization: Bearer <api_token>'

Response ​

If the request is successful, the API returns:

json
{
  "success": true
}

If the recipe can't be started due to errors, the API responds with "success": false and includes details in the code_errors or config_errors arrays:

  • code_errors: Issues found in the recipe logic, such as missing required fields or invalid attribute values.
  • config_errors: Issues in the recipe setup, such as missing or deleted connections.

For example, the following recipe can't be started due to missing required fields (code_errors) and an unestablished connection (config_errors):

json
{
    "success": false,
    "code_errors": [
        [
            1,
            [
                [
                    "Hire Date",
                    null,
                    "can't be blank",
                    "jobOffer_offerTerms_expectedStartDate"
                ],
                [
                    "Last Name",
                    null,
                    "can't be blank",
                    "applicant_person_legalName_familyName1"
                ]
            ]
        ]
    ],
    "config_errors": [
        [
            1,
            [
                [
                    "account_id",
                    null,
                    "can't be blank"
                ]
            ]
        ]
    ]
}

Stop recipe in a customer workspace ​

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

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

URL parameters ​

NameTypeDescription
managed_user_idstring
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_idinteger
required		The ID of the recipe you plan to stop.

Sample request ​

shell
curl  -X PUT https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/:recipe_id/stop \
      -H 'Authorization: Bearer <api_token>'

Response ​

json
{
  "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 orchestration 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 https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/:recipe_id/reset_trigger

Path parameters ​

NameTypeDescription
managed_user_idstring
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_idinteger
required		ID of the recipe to reset.

Sample request ​

shell
curl  -X POST https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/:recipe_id/reset_trigger \
      -H 'Authorization: Bearer <api_token>'

Response ​

json
{
    "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 https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/:recipe_id/poll_now

Path parameters ​

NameTypeDescription
recipe_idinteger
required		The ID of the recipe you plan to start.

Sample request ​

shell
curl  -X POST https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/:recipe_id/poll_now \
      -H 'Authorization: Bearer <api_token>'

Response ​

Job started ​

json
{
    "success": true
}

Job already in progress ​

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

Error codes ​

NameDescriptionSample reply
404Not found{"success": false, "message": "Not Found"}
429Too many requests. A Retry-After header 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"}
400Bad request{"message":"Trial has expired"}

Force an on-demand run of a recipe ​

Manually triggers an on-demand job for a recipe in a customer workspace, independent of its normal schedule. The recipe's schedule isn't affected. This call adds a one-time job without rescheduling the recipe's future runs.

This endpoint only supports recipes that are running and use the New recurring event trigger from the Scheduler by Workato connector. Calling this endpoint on a stopped recipe, or on a recipe using a different trigger, returns a 422 error.

POST https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/:recipe_id/force_run

Path parameters ​

NameTypeDescription
managed_user_idstring
required		Embedded customer ID/external ID.
External IDs must be URL encoded and prefixed with an E, for example: EA2300.
recipe_idstring
required		ID of the recipe to run.

Sample request ​

shell
curl  -X POST https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/recipes/:recipe_id/force_run \
      -H 'Authorization: Bearer <api_token>'

Response ​

Job enqueued ​

json
{
    "success": true,
    "job_handles": [
        "j-AagAcc43-6otazC-CD"
    ]
}

job_handles contains the handle of the on-demand job.

Error codes ​

CodeDescriptionSample reply
404Not found. The recipe doesn't exist.{"message": "Not found"}
422Unprocessable entity. The recipe isn't running.{"message": "Recipe is not running. Start the recipe before triggering an on-demand run."}
422Unprocessable entity. The recipe's trigger isn't the New recurring event trigger.{"message": "On-demand runs are only supported for recipes with the Workato Scheduler trigger."}
429Too many requests. The workspace's quota is exceeded, or the rate limit is exceeded. A Retry-After header specifies how long to wait before making a new request.{"message": "Too many requests"}

Get recipe versions in a customer workspace ​

Retrieve detailed information about all versions of a specified recipe in a customer workspace.

GET https://YOUR_DATA_CENTER/api/v2/managed_users/:managed_user_id/recipes/:recipe_id/versions

URL parameters ​

NameTypeDescription
managed_user_idstring
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_idstring
required		The ID of the recipe for which you plan to retrieve version details.

Query parameters ​

NameTypeDescription
pageinteger
optional		Page number. Defaults to 1.
per_pageinteger
optional		Page size. Defaults to 100. The maximum is 100.

Sample request ​

shell
curl  -X GET 'https://YOUR_DATA_CENTER/api/v2/managed_users/:managed_user_id/recipes/:recipe_id/versions' \
      -H 'Authorization: Bearer <api_token>'

Response ​

json
{
    "data": [
        {
            "id": 397103,
            "comment": "Updated the recipe to include new Slack channels for onboarding new employees based on their roles",
            "version_no": 2,
            "author_name": "Alex",
            "author_email": "alex@example.com",
            "created_at": "2024-08-03T11:06:23.950-07:00",
            "updated_at": "2024-08-04T23:31:58.735-07:00"
        },
        {
            "id": 392814,
            "comment": "Initial setup of Slack channels for onboarding new employees, including creating channels based on department and role",
            "version_no": 1,
            "author_name": "Alex",
            "author_email": "alex@example.com",
            "created_at": "2024-08-03T11:06:23.950-07:00",
            "updated_at": "2024-08-03T11:06:23.950-07:00"
        }
    ]
}

Get a specific recipe version in a customer workspace ​

Retrieve detailed information about a specific recipe version in a customer workspace.

GET https://YOUR_DATA_CENTER/api/v2/managed_users/:managed_user_id/recipes/:recipe_id/versions/:id

URL parameters ​

NameTypeDescription
managed_user_idstring
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_idstring
required		The ID of the recipe for which you plan to retrieve version details.
idstring
required		The ID of the recipe version for which you plan to retrieve details.

Sample request ​

shell
curl  -X GET 'https://YOUR_DATA_CENTER/api/v2/managed_users/:managed_user_id/recipes/:recipe_id/versions/:id' \
      -H 'Authorization: Bearer <api_token>'

Responses ​

200 OK

If successful, the API returns a 200 OK status and a JSON response with the recipe version details:

json
{
    "data": [
        {
            "id": 397103,
            "comment": "Updated the recipe to include new Slack channels for onboarding new employees based on their roles",
            "version_no": 2,
            "author_name": "Alex",
            "author_email": "alex@example.com",
            "created_at": "2024-08-04T23:31:58.735-07:00",
            "updated_at": "2024-08-04T23:31:58.735-07:00"
        }
    ]
}
404 NOT FOUND

The API returns a 404 Not Found error when you provide a non-existent or mismatched value, such as an incorrect recipe ID or version ID.

json
{
    "message": "Not found"
}

Update a recipe version comment in a customer workspace ​

Updates the comment on a specific recipe version in a customer workspace. This endpoint modifies only the comment associated with the version, not the version itself.

PATCH https://YOUR_DATA_CENTER/api/v2/managed_users/:managed_user_id/recipes/:recipe_id/versions/:id
PUT https://YOUR_DATA_CENTER/api/v2/managed_users/:managed_user_id/recipes/:recipe_id/versions/:id

URL parameters ​

NameTypeDescription
managed_user_idstring
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_idstring
required		The ID of the recipe for which you plan to retrieve version details.
idstring
required		The ID of the recipe version for which you plan to update the comment.

Payload ​

NameTypeDescription
commentstring
required		The new comment for the recipe version. Must be 255 characters or fewer.

Sample request ​

shell
curl  -X PATCH 'https://YOUR_DATA_CENTER/api/v2/managed_users/:managed_user_id/recipes/:recipe_id/versions/:id' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
                "comment": ":comment"
           }'

Responses ​

200 OK

If successful, the API returns a 200 OK status and a JSON response with the updated recipe version details:

json
{
    "data": [
        {
            "id": 397103,
            "comment": "Refined the Slack channel setup for onboarding to ensure channels are created accurately based on employee roles and departments",
            "version_no": 2,
            "author_name": "Alex",
            "author_email": "alex@example.com",
            "created_at": "2024-08-04T23:31:58.735-07:00",
            "updated_at": "2024-08-07T23:31:58.735-07:00"
        }
    ]
}
404 NOT FOUND

The API returns a 404 Not Found error when you provide a non-existent or mismatched value, such as an incorrect recipe ID or version ID:

json
{
    "message": "Not found"
}
422 UNPROCESSABLE ENTITY

The API returns a 422 Unprocessable Entity error in the following scenarios:

Comment exceeds 255 characters ​

This error occurs when the recipe version comment exceeds 255 characters:

json
{
  "errors": [
        {
            "code": "validation_error",
            "title": "Comment is too long (maximum is 255 characters)",
            "detail": null
        }
    ]
}

Missing comment ​

This error occurs when the recipe version comment is missing from the request payload:

json
{
  "errors": [
        {
            "code": "validation_error",
            "title": "Missing parameter comment",
            "detail": null
        }
    ]
}

Last updated: