Workato Recipes API

openapi: 3.1.0
info:
  title: Workato Agent Studio Data Tables Recipes API
  description: The Workato Agent Studio API provides programmatic access to manage AI agents (genies), skills, and knowledge bases within the Workato Agentic Automation platform. Use this API to create and configure AI agents, assign skills and knowledge bases, and control agent lifecycle. Rate limits are 1,000 requests per minute for list/get operations and 60 requests per minute for all other operations.
  version: '1.0'
  contact:
    name: Workato Support
    url: https://support.workato.com/
  termsOfService: https://www.workato.com/legal
servers:
- url: https://www.workato.com
  description: US Production
- url: https://app.eu.workato.com
  description: EU Production
- url: https://app.jp.workato.com
  description: JP Production
- url: https://app.sg.workato.com
  description: SG Production
- url: https://app.au.workato.com
  description: AU Production
security:
- bearerAuth: []
tags:
- name: Recipes
  description: Recipes are automated workflows that connect applications and services. Manage recipe lifecycle including creation, activation, and versioning.
paths:
  /api/recipes:
    get:
      operationId: listRecipes
      summary: Workato List Recipes
      description: Returns a paginated list of recipes in the workspace. Supports filtering by folder, running state, adapter names, and update time.
      tags:
      - Recipes
      parameters:
      - $ref: '#/components/parameters/FolderId'
      - name: with_subfolders
        in: query
        description: Include recipes in subfolders of the specified folder.
        schema:
          type: boolean
      - name: order
        in: query
        description: Sort order for results.
        schema:
          type: string
          enum:
          - asc
          - desc
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - name: running
        in: query
        description: Filter by running state.
        schema:
          type: boolean
      - name: adapter_names_all
        in: query
        description: Comma-separated list of connector names. Returns only recipes that use all of the specified connectors.
        schema:
          type: string
      - name: adapter_names_any
        in: query
        description: Comma-separated list of connector names. Returns recipes that use at least one of the specified connectors.
        schema:
          type: string
      - name: updated_after
        in: query
        description: Filter recipes updated after this ISO 8601 timestamp.
        schema:
          type: string
          format: date-time
      - name: stopped_after
        in: query
        description: Filter recipes stopped after this ISO 8601 timestamp.
        schema:
          type: string
          format: date-time
      - name: stop_cause
        in: query
        description: Filter by stop cause.
        schema:
          type: string
      responses:
        '200':
          description: A list of recipes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Recipe'
                  next_page:
                    type: boolean
                    description: Whether there are more pages available.
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createRecipe
      summary: Workato Create a Recipe
      description: Creates a new recipe in the workspace. Rate limited to 1 request per second. The recipe code must be provided in JSON format.
      tags:
      - Recipes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipeInput'
      responses:
        '200':
          description: The created recipe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipe'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/recipes/{id}:
    get:
      operationId: getRecipe
      summary: Workato Get a Recipe
      description: Returns the details of a specific recipe by its ID.
      tags:
      - Recipes
      parameters:
      - $ref: '#/components/parameters/RecipeId'
      responses:
        '200':
          description: The recipe details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipe'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateRecipe
      summary: Workato Update a Recipe
      description: Updates an existing recipe's name, code, config, or description.
      tags:
      - Recipes
      parameters:
      - $ref: '#/components/parameters/RecipeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipeInput'
      responses:
        '200':
          description: The updated recipe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipe'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteRecipe
      summary: Workato Delete a Recipe
      description: Permanently deletes a recipe from the workspace. The recipe must be stopped first.
      tags:
      - Recipes
      parameters:
      - $ref: '#/components/parameters/RecipeId'
      responses:
        '200':
          description: Deletion confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/recipes/{id}/start:
    put:
      operationId: startRecipe
      summary: Workato Start a Recipe
      description: Activates a recipe, enabling it to process trigger events.
      tags:
      - Recipes
      parameters:
      - $ref: '#/components/parameters/RecipeId'
      responses:
        '200':
          description: Start confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/recipes/{id}/stop:
    put:
      operationId: stopRecipe
      summary: Workato Stop a Recipe
      description: Deactivates a recipe, preventing it from processing new trigger events.
      tags:
      - Recipes
      parameters:
      - $ref: '#/components/parameters/RecipeId'
      responses:
        '200':
          description: Stop confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/recipes/{id}/copy:
    post:
      operationId: copyRecipe
      summary: Workato Copy a Recipe
      description: Creates a duplicate of an existing recipe.
      tags:
      - Recipes
      parameters:
      - $ref: '#/components/parameters/RecipeId'
      responses:
        '200':
          description: The copied recipe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipe'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/recipes/{recipe_id}/versions:
    get:
      operationId: listRecipeVersions
      summary: Workato List Recipe Versions
      description: Returns the version history of a recipe.
      tags:
      - Recipes
      parameters:
      - $ref: '#/components/parameters/RecipeIdPath'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: A list of recipe versions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecipeVersion'
                  next_page:
                    type: boolean
                    description: Whether there are more pages available.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/recipes/{recipe_id}/versions/{id}:
    get:
      operationId: getRecipeVersion
      summary: Workato Get a Recipe Version
      description: Returns the details of a specific version of a recipe.
      tags:
      - Recipes
      parameters:
      - $ref: '#/components/parameters/RecipeIdPath'
      - name: id
        in: path
        required: true
        description: Version number or ID.
        schema:
          type: integer
      responses:
        '200':
          description: The recipe version details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipeVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/recipes/{recipe_id}/health:
    get:
      operationId: getRecipeHealth
      summary: Workato Get Recipe Health Report
      description: Retrieves the most recent performance analysis report for a recipe. Rate limited to 20 requests per minute.
      tags:
      - Recipes
      parameters:
      - $ref: '#/components/parameters/RecipeIdPath'
      responses:
        '200':
          description: The recipe health report.
          content:
            application/json:
              schema:
                type: object
                description: Recipe performance and health analysis report.
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: queueRecipeHealthAnalysis
      summary: Workato Queue Recipe Health Analysis
      description: Queues a new performance analysis for a recipe. Analysis runs asynchronously and results are retrievable via GET. Rate limited to 20 requests per minute.
      tags:
      - Recipes
      parameters:
      - $ref: '#/components/parameters/RecipeIdPath'
      responses:
        '200':
          description: Health analysis queued confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    RecipeVersion:
      type: object
      description: A specific version snapshot of a recipe.
      properties:
        id:
          type: integer
          description: Unique identifier of this version.
        version_no:
          type: integer
          description: Sequential version number.
        comment:
          type: string
          description: Optional comment describing changes in this version.
        created_at:
          type: string
          format: date-time
          description: Timestamp when this version was created.
    SuccessResponse:
      type: object
      description: Standard success response.
      properties:
        success:
          type: boolean
          description: Whether the operation was successful.
          example: true
    Recipe:
      type: object
      description: A Workato recipe representing an automated workflow.
      properties:
        id:
          type: integer
          description: Unique identifier of the recipe.
        name:
          type: string
          description: Display name of the recipe.
        description:
          type: string
          description: Human-readable description of what the recipe does.
        folder_id:
          type: integer
          description: ID of the folder containing this recipe.
        running:
          type: boolean
          description: Whether the recipe is currently active and processing events.
        trigger_application:
          type: string
          description: The connector used for the recipe's trigger.
        action_applications:
          type: array
          items:
            type: string
          description: List of connectors used in the recipe's actions.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the recipe was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the recipe was last updated.
        stopped_at:
          type: string
          format: date-time
          description: Timestamp when the recipe was last stopped.
        stop_cause:
          type: string
          description: Reason the recipe was stopped, if applicable.
    RecipeInput:
      type: object
      description: Input schema for creating or updating a recipe.
      properties:
        recipe:
          type: object
          properties:
            name:
              type: string
              description: Display name for the recipe.
            code:
              type: string
              description: JSON-encoded recipe definition code.
            config:
              type: string
              description: JSON-encoded recipe configuration.
            folder_id:
              type: integer
              description: ID of the folder to place the recipe in.
            description:
              type: string
              description: Human-readable description of what the recipe does.
    ErrorResponse:
      type: object
      description: Standard error response.
      properties:
        message:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: Machine-readable error code.
  parameters:
    RecipeId:
      name: id
      in: path
      required: true
      description: Unique identifier of the recipe.
      schema:
        type: integer
    Page:
      name: page
      in: query
      description: Page number for pagination (1-based).
      schema:
        type: integer
        minimum: 1
        default: 1
    PerPage:
      name: per_page
      in: query
      description: Number of results per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 100
    RecipeIdPath:
      name: recipe_id
      in: path
      required: true
      description: Unique identifier of the recipe.
      schema:
        type: integer
    FolderId:
      name: folder_id
      in: query
      description: Filter results by folder ID.
      schema:
        type: integer
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication token is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request body is invalid or missing required fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API client token obtained from the Workato platform. Include as Authorization: Bearer {token}.'
externalDocs:
  description: Workato Agent Studio API Documentation
  url: https://docs.workato.com/workato-api/agent-studio.html