Documentation

Update Agent

Update an agent's name, workflow definition, or configuration

Update an agent's name, workflow definition, or configuration

All fields are optional — only include the fields you want to change. Updating workflow_definition creates a new versioned definition while preserving the history of previous versions.

Quick reference#

Update an agent's name, workflow definition, or configuration. Send the request to PUT /api/v1/workflow/{workflowid} on the Paladin API base URL.

Method	`PUT`
Path	`/api/v1/workflow/{workflowid}`
Path parameters	workflowid
Authentication	Use the authentication method shown in the OpenAPI block and the Authentication docs. Keep API keys server-side.

Before you call#

Confirm you are using the production base URL shown in the API reference.
Make sure any path IDs belong to the same Paladin organization as the credential you are using.
Validate request bodies and required fields before sending production traffic.

Common error checks#

Use 401 or 403 responses to check credentials, organization scope, and permissions.
Use 404 responses to check whether the referenced resource exists in the current organization.
Use 422 responses to inspect missing or invalid request fields.

OpenAPI#

PUT /api/v1/workflow/{workflowid}

openapi: 3.1.0
info:
  title: Paladin API
  description: API for the Paladin app
  version: 1.0.0
servers:
  - url: https://app.paladin.northmanngrp.com
    description: Production

security: []
paths:
  /api/v1/workflow/{workflow_id}:
    put:
      tags:
        - main
      summary: Update Workflow
      description: |-
        Update an existing workflow.

        Args:
            workflow_id: The ID of the workflow to update
            request: The update request containing the new name and workflow definition

        Returns:
            The updated workflow

        Raises:
            HTTPException: If the workflow is not found or if there's a database error
      operationId: update_workflow_api_v1_workflow__workflow_id__put
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: integer
            title: Workflow Id
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
        - name: X-API-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkflowRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    UpdateWorkflowRequest:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        workflow_definition:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Workflow Definition
        template_context_variables:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Template Context Variables
        workflow_configurations:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Workflow Configurations
      type: object
      title: UpdateWorkflowRequest
    WorkflowResponse:
      properties:
        id:
          type: integer
          title: Id
        name:
          type: string
          title: Name
        status:
          type: string
          title: Status
        created_at:
          type: string
          format: date-time
          title: Created At
        workflow_definition:
          additionalProperties: true
          type: object
          title: Workflow Definition
        current_definition_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Current Definition Id
        template_context_variables:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Template Context Variables
        call_disposition_codes:
          anyOf:
            - $ref: '#/components/schemas/CallDispositionCodes'
            - type: 'null'
        total_runs:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Runs
        workflow_configurations:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Workflow Configurations
        version_number:
          anyOf:
            - type: integer
            - type: 'null'
          title: Version Number
        version_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Version Status
        workflow_uuid:
          anyOf:
            - type: string
            - type: 'null'
          title: Workflow Uuid
      type: object
      required:
        - id
        - name
        - status
        - created_at
        - workflow_definition
        - current_definition_id
      title: WorkflowResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CallDispositionCodes:
      properties:
        disposition_codes:
          items:
            type: string
          type: array
          title: Disposition Codes
          default: []
      type: object
      title: CallDispositionCodes
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError