> ## Documentation Index > Fetch the complete documentation index at: https://docs.summation.com/llms.txt > Use this file to discover all available pages before exploring further. # Update workflow > Replace a workflow's editable state. The request is the complete desired state: triggers it omits are deleted, and a graph it omits is left untouched. Editing changes what the next activation would run, never what an active schedule is running now. ## OpenAPI ````yaml https://api.summation.com/openapi.json put /v1/workflows/{workflow_id} openapi: 3.1.0 info: title: summation-api public API version: 0.1.0 servers: [] security: [] tags: - name: Auth description: Machine authentication for API clients. - name: Tenant description: Organization and tenant context resolved by summation-api. - name: Projects description: Project resources. - name: Conversations description: Conversation and message resources. - name: Reports description: Report resources and report operations. - name: Runs description: Project run history and execution status. - name: Playbooks description: Playbook resources. - name: Files description: Project file resources. - name: Catalog Entries description: Project-scoped data asset attachments. - name: Data Connectors description: Reusable external data source connections. - name: App Connectors description: External app connectors whose tools the agent can use during chat. - name: Tables description: Canonical table metadata and catalog. - name: Views description: Canonical Summation view metadata and catalog. - name: Query Executions description: Read-only SQL query execution. - name: Grid description: Materialized grid status, sync, and lineage. - name: Schedules description: Schedule and schedule run inspection. - name: Workflows description: >- Workflows: what they run, when they run, and where their output is delivered. - name: Verification Tests description: >- Administrative custom verification-test definitions, overlays, and effective-set previews. paths: /v1/workflows/{workflow_id}: put: tags: - Workflows summary: Update workflow description: >- Replace a workflow's editable state. The request is the complete desired state: triggers it omits are deleted, and a graph it omits is left untouched. Editing changes what the next activation would run, never what an active schedule is running now. operationId: update_workflow parameters: - name: workflow_id in: path required: true schema: type: string title: Workflow Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkflowUpdateRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/WorkflowResponse' '400': description: Invalid request or unsupported option. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemError' '401': description: Missing, invalid, or expired credentials. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemError' '403': description: Authenticated but missing the required scope. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemError' '404': description: Resource not found or not accessible. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemError' '409': description: >- The workflow changed since the revision you read, the update asked to make it active (which only the activate operation can do), or the request_id was already used. Nothing was applied. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemError' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemError' '500': description: Internal server error. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemError' '503': description: >- The workflows service is temporarily unavailable. Retry this request shortly. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemError' security: - SummationMachineAuth: - agent:write components: schemas: WorkflowUpdateRequest: properties: project_id: type: string minLength: 1 title: Project Id description: Project the workflow belongs to. You must have editor access to it. title: type: string maxLength: 255 minLength: 1 title: Title description: Workflow name, shown wherever it is listed. description: type: string maxLength: 2000 title: Description description: Optional longer description. default: '' status: anyOf: - type: string enum: - draft - active - paused - archived - type: 'null' title: Status description: >- New workflow state. Omit to leave it unchanged. active is accepted only as an echo: an already active workflow can be handed back exactly as it reads, and the update leaves it active. It cannot be used to ACTIVATE a workflow — that is the activate operation, which freezes the version that runs — so asking for active on a workflow that is not already active is refused. output_folder: type: string maxLength: 512 title: Output Folder description: >- Project folder the workflow writes its outputs to, for example /Reports. default: '' graph: anyOf: - additionalProperties: true type: object - type: 'null' title: Graph description: >- Replacement graph document, in the same shape and with the same trigger and edge rules as on create: send the full desired document, since what you send replaces the stored graph rather than merging into it. Omit to leave the stored graph untouched. Serializes to at most 200000 characters. triggers: items: $ref: '#/components/schemas/WorkflowTriggerRequest' type: array maxItems: 20 title: Triggers description: >- Schedules that start this workflow. Omit for a workflow that only runs on demand. These rows and the graph's trigger nodes must agree: a schedule here requires a summation.trigger.schedule/v1 node in the graph — it is the node the schedule's parameter values are bound to — and that node requires a schedule here, or nothing would fire it. A request where the two disagree is refused. expected_revision: type: integer minimum: 0 title: Expected Revision description: >- The revision you last read. The update is applied only if the workflow is still at that revision; otherwise nothing changes and the request conflicts. This is what stops a stale client deleting another client's triggers. additionalProperties: false type: object required: - project_id - title - expected_revision title: WorkflowUpdateRequest description: >- A full replacement of a workflow's editable state. Editing a workflow changes what the NEXT activation would run, never what an already active schedule is running. This is the read-modify-write half of the surface, so it takes a workflow exactly as a GET renders it, plus ``expected_revision``: the fields a workflow reports but does not let you set — its id, owner, execution format, revision, active version, run steps and timestamps — are dropped rather than refused. Anything else it does not recognise is still a 422, so a misspelled field cannot silently skip part of the change. ``status`` is the one field that is writable AND readable with a value the write half cannot mint, so it is accepted as an echo rather than dropped: see its description and ``update_workflow``. WorkflowResponse: properties: data: $ref: '#/components/schemas/Workflow' type: object required: - data title: WorkflowResponse ProblemError: description: >- Public error envelope (RFC 7807 ``application/problem+json``). Mirrors the body produced by :func:`api_error`. Declaring it in the contract lets generated clients type error handling instead of guessing. properties: type: description: URI reference identifying the problem type. title: Type type: string title: description: Short, human-readable summary of the problem type. title: Title type: string status: description: HTTP status code. title: Status type: integer detail: description: Human-readable explanation specific to this occurrence. title: Detail type: string code: description: Stable, machine-readable error code. title: Code type: string request_id: description: Correlation id, echoed in the x-request-id header. title: Request Id type: string required: - type - title - status - detail - code - request_id title: ProblemError type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError WorkflowTriggerRequest: properties: id: type: string title: Id description: Existing trigger id to update. Omit to create a new trigger. default: '' type: type: string const: schedule title: Type description: >- Trigger kind. Only schedule triggers can be created through this API. default: schedule label: type: string maxLength: 255 title: Label description: Human-readable name for this schedule. default: '' enabled: type: boolean title: Enabled description: Set false to keep the schedule but stop it firing. default: true params: additionalProperties: true type: object title: Params description: >- Parameter values this schedule passes to the workflow, merged over the workflow's own values. schedule: $ref: '#/components/schemas/WorkflowTriggerSchedule' description: Cadence and timezone for this schedule. additionalProperties: false type: object required: - schedule title: WorkflowTriggerRequest description: >- One schedule trigger on a workflow. Triggers are a full replace-set on every write: a workflow's triggers are exactly the ones the request carries, and any it omits are deleted along with their backing schedule. Echo the ``id`` of a trigger you are keeping so its stored settings survive the write. An editor-supported trigger read back from a GET is field for field a trigger this model takes, in either spelling, so a caller can hand it straight back on a write. Broader legacy scheduler shapes remain readable but must be replaced before this API will write the workflow. Workflow: properties: id: type: string title: Id projectId: type: string title: Projectid title: type: string title: Title description: type: string title: Description ownerUserId: type: string title: Owneruserid description: >- The user the workflow runs as. Assigned at creation and never reassigned. status: type: string title: Status description: One of draft, active, paused, archived, unknown. executionFormat: type: string title: Executionformat description: >- typed_graph for workflows built from a graph document. Fixed when the workflow is created. outputFolder: type: string title: Outputfolder revision: type: integer title: Revision description: Advances on every change. Pass it back as expected_revision. activeVersionId: type: string title: Activeversionid description: >- The activated version this workflow currently runs, or empty if it has never been activated. graph: anyOf: - additionalProperties: true type: object - type: 'null' title: Graph description: The editable graph document, for graph workflows. triggers: items: $ref: '#/components/schemas/WorkflowTrigger' type: array title: Triggers steps: items: $ref: '#/components/schemas/WorkflowStep' type: array title: Steps createdAt: anyOf: - type: string - type: 'null' title: Createdat updatedAt: anyOf: - type: string - type: 'null' title: Updatedat type: object required: - id - projectId - title - description - ownerUserId - status - executionFormat - outputFolder - revision - activeVersionId - triggers - steps title: Workflow ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError WorkflowTriggerSchedule: properties: type: type: string enum: - one_time - daily - weekly - monthly title: Type description: 'Editor-supported cadence kind: one_time, daily, weekly, or monthly.' zone_id: type: string title: Zone Id description: >- IANA timezone the schedule's local times are read in, for example America/Los_Angeles. time_of_day: anyOf: - type: string - type: 'null' title: Time Of Day description: >- Local minute-precision time for the cadence; use HH:mm. HH:mm:00 is accepted and normalized, but nonzero seconds are refused because the workflow editor cannot preserve them. default: '09:00' run_date: anyOf: - type: string format: date - type: 'null' title: Run Date description: >- Required for type one_time, ignored otherwise. The single local date the schedule runs on, as YYYY-MM-DD, read in zone_id at time_of_day. days_of_week: items: type: string enum: - MONDAY - TUESDAY - WEDNESDAY - THURSDAY - FRIDAY - SATURDAY - SUNDAY type: array title: Days Of Week description: >- Required for type weekly, ignored otherwise. UPPERCASE day names — MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY — one entry per day the schedule runs. day_of_month: anyOf: - type: integer maximum: 31 minimum: 1 - type: 'null' title: Day Of Month description: >- Required for type monthly, ignored otherwise. Day of the month, 1 to 31. interval: type: integer const: 1 title: Interval description: >- Must be 1; the workflow editor does not support skipping recurrence periods. default: 1 additionalProperties: false type: object required: - type - zone_id title: WorkflowTriggerSchedule description: >- A trigger's cadence and the timezone its local times are read in. ``type`` is one of one_time, daily, weekly, monthly — exactly the cadences the workflow editor can read and write without changing their meaning. It decides which other fields are required: one_time needs ``run_date``, weekly needs ``days_of_week``, and monthly needs ``day_of_month``. Every type reads ``time_of_day``, a local minute-precision ``HH:mm`` time defaulting to 09:00. ``days_of_week`` holds UPPERCASE day names (MONDAY … SUNDAY). Recurrences are every one period; skipped-period, cron, interval, biweekly, month-end, and yearly schedules are refused until the editor can represent them. ``zone_id`` is REQUIRED on every type here. The shared scheduler expression defaults to UTC, but a schedule's timezone decides when it fires and which calendar day its relative date parameters resolve against, so silently defaulting it would re-time a caller's schedule rather than refuse an incomplete one. The web-app BFF requires zoneId on the same write for the same reason. Field names are documented in snake_case, and every one is ALSO accepted in its camelCase spelling (``zoneId``, ``timeOfDay``, ``daysOfWeek``, …), which is how a supported cadence read back from a GET is spelled. WorkflowTrigger: properties: id: type: string title: Id type: type: string title: Type description: schedule, webhook, api, data_event, or unknown. label: type: string title: Label enabled: type: boolean title: Enabled params: additionalProperties: true type: object title: Params description: Parameter values this trigger passes to the workflow. schedule: anyOf: - $ref: '#/components/schemas/WorkflowSchedule' - type: 'null' description: Cadence, for schedule triggers. type: object required: - id - type - label - enabled - params title: WorkflowTrigger WorkflowStep: properties: id: type: string title: Id position: type: integer title: Position type: type: string title: Type description: playbook, email_delivery, slack_delivery, or unknown. targetFileId: type: string title: Targetfileid description: Playbook or attachment file this step acts on. config: additionalProperties: true type: object title: Config targets: items: $ref: '#/components/schemas/WorkflowStepTarget' type: array title: Targets type: object required: - id - position - type - targetFileId - config - targets title: WorkflowStep description: >- One step of a legacy step-shaped workflow. Graph workflows carry a graph instead. WorkflowSchedule: properties: type: type: string title: Type description: >- Stored cadence kind. Writes accept one_time, daily, weekly, and monthly; existing workflows may read as cron, interval, biweekly, or month_end until their cadence is replaced. zoneId: type: string title: Zoneid description: IANA timezone the schedule's local times are read in. cronExpression: anyOf: - type: string - type: 'null' title: Cronexpression everyMinutes: anyOf: - type: integer - type: 'null' title: Everyminutes timeOfDay: anyOf: - type: string - type: 'null' title: Timeofday description: Local time of day, in this schedule's timezone. runDate: anyOf: - type: string - type: 'null' title: Rundate anchorDate: anyOf: - type: string - type: 'null' title: Anchordate daysOfWeek: anyOf: - items: type: string type: array - type: 'null' title: Daysofweek description: Uppercase weekday names, for example MONDAY. dayOfMonth: anyOf: - type: integer - type: 'null' title: Dayofmonth interval: anyOf: - type: integer - type: 'null' title: Interval description: >- How many periods apart the cadence repeats, for cadences that can skip periods. type: object required: - type - zoneId title: WorkflowSchedule description: >- A trigger's stored cadence, including legacy shapes that are now read-only. Editor-supported cadences are field-for-field invertible into ``WorkflowTriggerSchedule``. Broader scheduler cadences remain visible so existing workflows can be diagnosed, but a write must replace them with an editor-supported shape. ``zoneId`` lives HERE rather than on the trigger because the write model carries the timezone inside the schedule; putting it one level up would drop the timezone on every supported round trip that copied the schedule across. WorkflowStepTarget: properties: kind: type: string enum: - email_to - email_cc - email_bcc - slack_channel - slack_user - unknown title: Kind description: >- email_to, email_cc, email_bcc, slack_channel, slack_user, or unknown. value: type: string title: Value description: Email address, or Slack channel or user id. displayName: type: string title: Displayname type: object required: - kind - value - displayName title: WorkflowStepTarget securitySchemes: SummationMachineAuth: type: oauth2 flows: clientCredentials: scopes: agent:read: agent:read agent:write: agent:write tokenUrl: /v1/auth/m2m/token ````