> ## 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. # Create workflow > Create a workflow in a project you can edit. The workflow is created as a draft and runs nothing until you activate it. You become its owner, and its runs execute as you. ## OpenAPI ````yaml https://api.summation.com/openapi.json post /v1/workflows 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: post: tags: - Workflows summary: Create workflow description: >- Create a workflow in a project you can edit. The workflow is created as a draft and runs nothing until you activate it. You become its owner, and its runs execute as you. operationId: create_workflow requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkflowCreateRequest' responses: '201': 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: WorkflowCreateRequest: 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: type: string enum: - draft - paused - archived title: Status description: >- Workflow state. A workflow becomes active only through the activate operation, which freezes the version that runs. default: draft 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: >- The workflow's graph document: the nodes it runs and how they connect, as {"nodes": [...], "edges": [...]}. This is the FULL desired document on every create and update, not a patch — what you send replaces the stored graph. It must contain a trigger node, summation.trigger.schedule/v1 or summation.trigger.manual/v1, wired to the first work node by an edge {"from_node": "", "from_port": "inputs", "to_node": "", "to_port": "inputs"}. Each node is {"key", "type", "config"}; the node type ids you may use and the config each one takes come from GET /v1/workflows/node-types. A config carries ONLY the keys its node type declares there — any other key is refused, so a field the node type does not name cannot be smuggled through it. Use the summation.trigger.schedule/v1 node exactly when this request also carries schedule triggers; see the triggers field. Omit to create an empty draft. Serializes to at most 200000 characters. The web editor adopts API-authored graphs and normalizes them to its canonical form on its next save. 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. additionalProperties: false type: object required: - project_id - title title: WorkflowCreateRequest description: >- A new workflow. Created as a draft; use the activate operation to make it run. 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 ````