# Workflows

## List workflows

`GET https://app.italic.com/api/v2/workflows`

Required permission: workflows:read.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Italic API",
    "version": "2.0.0",
    "description": "Recordings, devices, chat, tasks, workflows, connectors and notifications. Text syncs to Italic; audio stays on the client."
  },
  "servers": [
    {
      "url": "https://app.italic.com/api/v2"
    }
  ],
  "paths": {
    "/workflows": {
      "get": {
        "operationId": "listWorkflows",
        "summary": "List workflows",
        "tags": [
          "Workflows"
        ],
        "parameters": [],
        "description": "Required permission: workflows:read.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success. Writes without read permission return an ID and revision only.",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Request identifier for troubleshooting."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkflowList"
                }
              }
            }
          },
          "default": {
            "description": "Request failed. Errors include a stable code and a readable message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key from Settings → Developers → API keys."
      },
      "accountSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "A signed-in Italic account session. An API key cannot create or revoke keys."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "minLength": 0,
                "maxLength": 100
              },
              "message": {
                "type": "string",
                "minLength": 0,
                "maxLength": 1000
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ]
      },
      "Workflow": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
          },
          "name": {
            "type": "string",
            "minLength": 0,
            "maxLength": 60
          },
          "enabled": {
            "type": "boolean"
          },
          "trigger": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "recording"
                ]
              },
              "phrases": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "match": {
                "type": "string",
                "enum": [
                  "anywhere",
                  "start"
                ]
              },
              "input": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "hold",
                      "doubleTap",
                      "tripleTap",
                      "recordButton",
                      "pushToTalk",
                      "appRecord"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "kind": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "clip",
                      "memo"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "type",
              "phrases",
              "match",
              "input",
              "kind"
            ]
          },
          "actions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "pattern": "^[a-z][a-z0-9]{0,15}$",
                  "description": "Unique within the workflow; later actions use it in `{{<id>.<output>}}` variables."
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "ai",
                    "agent",
                    "send_email",
                    "create_event",
                    "create_reminder",
                    "send_slack_message",
                    "send_webhook",
                    "create_notion_page",
                    "append_to_notion_page",
                    "save_to_drive",
                    "create_linear_issue",
                    "comment_on_linear_issue",
                    "update_linear_issue",
                    "run_connector_tool"
                  ]
                },
                "approval": {
                  "type": "string",
                  "enum": [
                    "ask",
                    "auto"
                  ],
                  "description": "`ask`: the action waits in Tasks. `auto`: it runs. Write with AI (`ai`) has none."
                }
              },
              "required": [
                "id",
                "type"
              ],
              "description": "One step, with the fields of its type, exactly as the workflow builders in the apps save it: `ai` (instructions, format), `agent` (instructions, apps), `send_email` (to, cc, subject, body, from), `create_event` (title, start, end, location, notes), `create_reminder` (title, notes, due, list), `send_webhook` (url for a new webhook, or webhookId for one the account's workflows already send to; message), `send_slack_message`, `create_notion_page`, `append_to_notion_page`, `save_to_drive`, the Linear actions and `run_connector_tool`. Text fields are templates with `{{recording.transcript}}`-style variables. GET /workflows returns saved actions in this shape; the server checks every field as the builders do."
            }
          },
          "createdAt": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "updatedAt": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "id",
          "name",
          "enabled",
          "trigger",
          "actions",
          "createdAt",
          "updatedAt"
        ]
      },
      "WorkflowList": {
        "type": "object",
        "properties": {
          "workflows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Workflow"
            }
          },
          "webhooks": {
            "type": "array",
            "description": "Where the workflows' Send webhook actions send, by webhookId.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 256,
                  "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "url"
              ]
            }
          }
        },
        "required": [
          "workflows",
          "webhooks"
        ]
      }
    }
  }
}
```

## Create a workflow

`POST https://app.italic.com/api/v2/workflows`

Required permission: workflows:manage. A Send webhook action with a new `url` also needs webhooks:manage; its signing secret is returned once, in `secrets`. An account can have 20 workflows.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Italic API",
    "version": "2.0.0",
    "description": "Recordings, devices, chat, tasks, workflows, connectors and notifications. Text syncs to Italic; audio stays on the client."
  },
  "servers": [
    {
      "url": "https://app.italic.com/api/v2"
    }
  ],
  "paths": {
    "/workflows": {
      "post": {
        "operationId": "createWorkflow",
        "summary": "Create a workflow",
        "tags": [
          "Workflows"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Reuse the same key and body when retrying; the retry returns the first result with `replayed: true`. Keys are kept for 24 hours."
          }
        ],
        "description": "Required permission: workflows:manage. A Send webhook action with a new `url` also needs webhooks:manage; its signing secret is returned once, in `secrets`. An account can have 20 workflows.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkflowInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success. Writes without read permission return an ID and revision only.",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Request identifier for troubleshooting."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkflowResult"
                }
              }
            }
          },
          "default": {
            "description": "Request failed. Errors include a stable code and a readable message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key from Settings → Developers → API keys."
      },
      "accountSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "A signed-in Italic account session. An API key cannot create or revoke keys."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "minLength": 0,
                "maxLength": 100
              },
              "message": {
                "type": "string",
                "minLength": 0,
                "maxLength": 1000
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ]
      },
      "Workflow": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
          },
          "name": {
            "type": "string",
            "minLength": 0,
            "maxLength": 60
          },
          "enabled": {
            "type": "boolean"
          },
          "trigger": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "recording"
                ]
              },
              "phrases": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "match": {
                "type": "string",
                "enum": [
                  "anywhere",
                  "start"
                ]
              },
              "input": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "hold",
                      "doubleTap",
                      "tripleTap",
                      "recordButton",
                      "pushToTalk",
                      "appRecord"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "kind": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "clip",
                      "memo"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "type",
              "phrases",
              "match",
              "input",
              "kind"
            ]
          },
          "actions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "pattern": "^[a-z][a-z0-9]{0,15}$",
                  "description": "Unique within the workflow; later actions use it in `{{<id>.<output>}}` variables."
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "ai",
                    "agent",
                    "send_email",
                    "create_event",
                    "create_reminder",
                    "send_slack_message",
                    "send_webhook",
                    "create_notion_page",
                    "append_to_notion_page",
                    "save_to_drive",
                    "create_linear_issue",
                    "comment_on_linear_issue",
                    "update_linear_issue",
                    "run_connector_tool"
                  ]
                },
                "approval": {
                  "type": "string",
                  "enum": [
                    "ask",
                    "auto"
                  ],
                  "description": "`ask`: the action waits in Tasks. `auto`: it runs. Write with AI (`ai`) has none."
                }
              },
              "required": [
                "id",
                "type"
              ],
              "description": "One step, with the fields of its type, exactly as the workflow builders in the apps save it: `ai` (instructions, format), `agent` (instructions, apps), `send_email` (to, cc, subject, body, from), `create_event` (title, start, end, location, notes), `create_reminder` (title, notes, due, list), `send_webhook` (url for a new webhook, or webhookId for one the account's workflows already send to; message), `send_slack_message`, `create_notion_page`, `append_to_notion_page`, `save_to_drive`, the Linear actions and `run_connector_tool`. Text fields are templates with `{{recording.transcript}}`-style variables. GET /workflows returns saved actions in this shape; the server checks every field as the builders do."
            }
          },
          "createdAt": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "updatedAt": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "id",
          "name",
          "enabled",
          "trigger",
          "actions",
          "createdAt",
          "updatedAt"
        ]
      },
      "WorkflowInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60
          },
          "enabled": {
            "type": "boolean",
            "description": "Defaults to true."
          },
          "trigger": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "recording"
                ]
              },
              "phrases": {
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 100
                },
                "maxItems": 12,
                "description": "Words that start the workflow. Empty: any words, so input or kind must narrow it."
              },
              "match": {
                "type": "string",
                "enum": [
                  "anywhere",
                  "start"
                ],
                "description": "`start`: the transcript must begin with a phrase. `anywhere`: a phrase anywhere in it."
              },
              "input": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "hold",
                      "doubleTap",
                      "tripleTap",
                      "recordButton",
                      "pushToTalk",
                      "appRecord"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Only recordings from this device input. Null or omitted: any input."
              },
              "kind": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "clip",
                      "memo"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Only Clips or only Memos. Null or omitted: both."
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false,
            "description": "Which new recordings start the workflow. Every condition given must match."
          },
          "actions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "pattern": "^[a-z][a-z0-9]{0,15}$",
                  "description": "Unique within the workflow; later actions use it in `{{<id>.<output>}}` variables."
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "ai",
                    "agent",
                    "send_email",
                    "create_event",
                    "create_reminder",
                    "send_slack_message",
                    "send_webhook",
                    "create_notion_page",
                    "append_to_notion_page",
                    "save_to_drive",
                    "create_linear_issue",
                    "comment_on_linear_issue",
                    "update_linear_issue",
                    "run_connector_tool"
                  ]
                },
                "approval": {
                  "type": "string",
                  "enum": [
                    "ask",
                    "auto"
                  ],
                  "description": "`ask`: the action waits in Tasks. `auto`: it runs. Write with AI (`ai`) has none."
                }
              },
              "required": [
                "id",
                "type"
              ],
              "description": "One step, with the fields of its type, exactly as the workflow builders in the apps save it: `ai` (instructions, format), `agent` (instructions, apps), `send_email` (to, cc, subject, body, from), `create_event` (title, start, end, location, notes), `create_reminder` (title, notes, due, list), `send_webhook` (url for a new webhook, or webhookId for one the account's workflows already send to; message), `send_slack_message`, `create_notion_page`, `append_to_notion_page`, `save_to_drive`, the Linear actions and `run_connector_tool`. Text fields are templates with `{{recording.transcript}}`-style variables. GET /workflows returns saved actions in this shape; the server checks every field as the builders do."
            },
            "minItems": 1,
            "maxItems": 8
          }
        },
        "required": [
          "name",
          "trigger",
          "actions"
        ],
        "additionalProperties": false
      },
      "WorkflowResult": {
        "type": "object",
        "properties": {
          "workflow": {
            "$ref": "#/components/schemas/Workflow"
          },
          "secrets": {
            "type": "array",
            "description": "Signing secrets of webhooks this request added, shown once.",
            "items": {
              "type": "object",
              "properties": {
                "actionIndex": {
                  "type": "integer"
                },
                "url": {
                  "type": "string"
                },
                "secret": {
                  "type": "string"
                }
              },
              "required": [
                "actionIndex",
                "url",
                "secret"
              ]
            }
          },
          "replayed": {
            "type": "boolean"
          }
        },
        "required": [
          "workflow"
        ]
      }
    }
  }
}
```

## Get a workflow

`GET https://app.italic.com/api/v2/workflows/{id}`

Required permission: workflows:read.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Italic API",
    "version": "2.0.0",
    "description": "Recordings, devices, chat, tasks, workflows, connectors and notifications. Text syncs to Italic; audio stays on the client."
  },
  "servers": [
    {
      "url": "https://app.italic.com/api/v2"
    }
  ],
  "paths": {
    "/workflows/{id}": {
      "get": {
        "operationId": "getWorkflow",
        "summary": "Get a workflow",
        "tags": [
          "Workflows"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 256,
              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
            }
          }
        ],
        "description": "Required permission: workflows:read.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success. Writes without read permission return an ID and revision only.",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Request identifier for troubleshooting."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkflowResult"
                }
              }
            }
          },
          "default": {
            "description": "Request failed. Errors include a stable code and a readable message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key from Settings → Developers → API keys."
      },
      "accountSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "A signed-in Italic account session. An API key cannot create or revoke keys."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "minLength": 0,
                "maxLength": 100
              },
              "message": {
                "type": "string",
                "minLength": 0,
                "maxLength": 1000
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ]
      },
      "Workflow": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
          },
          "name": {
            "type": "string",
            "minLength": 0,
            "maxLength": 60
          },
          "enabled": {
            "type": "boolean"
          },
          "trigger": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "recording"
                ]
              },
              "phrases": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "match": {
                "type": "string",
                "enum": [
                  "anywhere",
                  "start"
                ]
              },
              "input": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "hold",
                      "doubleTap",
                      "tripleTap",
                      "recordButton",
                      "pushToTalk",
                      "appRecord"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "kind": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "clip",
                      "memo"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "type",
              "phrases",
              "match",
              "input",
              "kind"
            ]
          },
          "actions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "pattern": "^[a-z][a-z0-9]{0,15}$",
                  "description": "Unique within the workflow; later actions use it in `{{<id>.<output>}}` variables."
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "ai",
                    "agent",
                    "send_email",
                    "create_event",
                    "create_reminder",
                    "send_slack_message",
                    "send_webhook",
                    "create_notion_page",
                    "append_to_notion_page",
                    "save_to_drive",
                    "create_linear_issue",
                    "comment_on_linear_issue",
                    "update_linear_issue",
                    "run_connector_tool"
                  ]
                },
                "approval": {
                  "type": "string",
                  "enum": [
                    "ask",
                    "auto"
                  ],
                  "description": "`ask`: the action waits in Tasks. `auto`: it runs. Write with AI (`ai`) has none."
                }
              },
              "required": [
                "id",
                "type"
              ],
              "description": "One step, with the fields of its type, exactly as the workflow builders in the apps save it: `ai` (instructions, format), `agent` (instructions, apps), `send_email` (to, cc, subject, body, from), `create_event` (title, start, end, location, notes), `create_reminder` (title, notes, due, list), `send_webhook` (url for a new webhook, or webhookId for one the account's workflows already send to; message), `send_slack_message`, `create_notion_page`, `append_to_notion_page`, `save_to_drive`, the Linear actions and `run_connector_tool`. Text fields are templates with `{{recording.transcript}}`-style variables. GET /workflows returns saved actions in this shape; the server checks every field as the builders do."
            }
          },
          "createdAt": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "updatedAt": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "id",
          "name",
          "enabled",
          "trigger",
          "actions",
          "createdAt",
          "updatedAt"
        ]
      },
      "WorkflowResult": {
        "type": "object",
        "properties": {
          "workflow": {
            "$ref": "#/components/schemas/Workflow"
          },
          "secrets": {
            "type": "array",
            "description": "Signing secrets of webhooks this request added, shown once.",
            "items": {
              "type": "object",
              "properties": {
                "actionIndex": {
                  "type": "integer"
                },
                "url": {
                  "type": "string"
                },
                "secret": {
                  "type": "string"
                }
              },
              "required": [
                "actionIndex",
                "url",
                "secret"
              ]
            }
          },
          "replayed": {
            "type": "boolean"
          }
        },
        "required": [
          "workflow"
        ]
      }
    }
  }
}
```

## Turn a workflow on or off

`PATCH https://app.italic.com/api/v2/workflows/{id}`

Required permission: workflows:write.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Italic API",
    "version": "2.0.0",
    "description": "Recordings, devices, chat, tasks, workflows, connectors and notifications. Text syncs to Italic; audio stays on the client."
  },
  "servers": [
    {
      "url": "https://app.italic.com/api/v2"
    }
  ],
  "paths": {
    "/workflows/{id}": {
      "patch": {
        "operationId": "setWorkflowEnabled",
        "summary": "Turn a workflow on or off",
        "tags": [
          "Workflows"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 256,
              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
            }
          }
        ],
        "description": "Required permission: workflows:write.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkflowEnabled"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success. Writes without read permission return an ID and revision only.",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Request identifier for troubleshooting."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkflowResult"
                }
              }
            }
          },
          "default": {
            "description": "Request failed. Errors include a stable code and a readable message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key from Settings → Developers → API keys."
      },
      "accountSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "A signed-in Italic account session. An API key cannot create or revoke keys."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "minLength": 0,
                "maxLength": 100
              },
              "message": {
                "type": "string",
                "minLength": 0,
                "maxLength": 1000
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ]
      },
      "Workflow": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
          },
          "name": {
            "type": "string",
            "minLength": 0,
            "maxLength": 60
          },
          "enabled": {
            "type": "boolean"
          },
          "trigger": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "recording"
                ]
              },
              "phrases": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "match": {
                "type": "string",
                "enum": [
                  "anywhere",
                  "start"
                ]
              },
              "input": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "hold",
                      "doubleTap",
                      "tripleTap",
                      "recordButton",
                      "pushToTalk",
                      "appRecord"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "kind": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "clip",
                      "memo"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "type",
              "phrases",
              "match",
              "input",
              "kind"
            ]
          },
          "actions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "pattern": "^[a-z][a-z0-9]{0,15}$",
                  "description": "Unique within the workflow; later actions use it in `{{<id>.<output>}}` variables."
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "ai",
                    "agent",
                    "send_email",
                    "create_event",
                    "create_reminder",
                    "send_slack_message",
                    "send_webhook",
                    "create_notion_page",
                    "append_to_notion_page",
                    "save_to_drive",
                    "create_linear_issue",
                    "comment_on_linear_issue",
                    "update_linear_issue",
                    "run_connector_tool"
                  ]
                },
                "approval": {
                  "type": "string",
                  "enum": [
                    "ask",
                    "auto"
                  ],
                  "description": "`ask`: the action waits in Tasks. `auto`: it runs. Write with AI (`ai`) has none."
                }
              },
              "required": [
                "id",
                "type"
              ],
              "description": "One step, with the fields of its type, exactly as the workflow builders in the apps save it: `ai` (instructions, format), `agent` (instructions, apps), `send_email` (to, cc, subject, body, from), `create_event` (title, start, end, location, notes), `create_reminder` (title, notes, due, list), `send_webhook` (url for a new webhook, or webhookId for one the account's workflows already send to; message), `send_slack_message`, `create_notion_page`, `append_to_notion_page`, `save_to_drive`, the Linear actions and `run_connector_tool`. Text fields are templates with `{{recording.transcript}}`-style variables. GET /workflows returns saved actions in this shape; the server checks every field as the builders do."
            }
          },
          "createdAt": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "updatedAt": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "id",
          "name",
          "enabled",
          "trigger",
          "actions",
          "createdAt",
          "updatedAt"
        ]
      },
      "WorkflowEnabled": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean"
          }
        },
        "required": [
          "enabled"
        ],
        "additionalProperties": false
      },
      "WorkflowResult": {
        "type": "object",
        "properties": {
          "workflow": {
            "$ref": "#/components/schemas/Workflow"
          },
          "secrets": {
            "type": "array",
            "description": "Signing secrets of webhooks this request added, shown once.",
            "items": {
              "type": "object",
              "properties": {
                "actionIndex": {
                  "type": "integer"
                },
                "url": {
                  "type": "string"
                },
                "secret": {
                  "type": "string"
                }
              },
              "required": [
                "actionIndex",
                "url",
                "secret"
              ]
            }
          },
          "replayed": {
            "type": "boolean"
          }
        },
        "required": [
          "workflow"
        ]
      }
    }
  }
}
```

## Delete a workflow

`DELETE https://app.italic.com/api/v2/workflows/{id}`

Required permission: workflows:manage. Webhooks no other workflow sends to stop.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Italic API",
    "version": "2.0.0",
    "description": "Recordings, devices, chat, tasks, workflows, connectors and notifications. Text syncs to Italic; audio stays on the client."
  },
  "servers": [
    {
      "url": "https://app.italic.com/api/v2"
    }
  ],
  "paths": {
    "/workflows/{id}": {
      "delete": {
        "operationId": "deleteWorkflow",
        "summary": "Delete a workflow",
        "tags": [
          "Workflows"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 256,
              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
            }
          }
        ],
        "description": "Required permission: workflows:manage. Webhooks no other workflow sends to stop.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success. Writes without read permission return an ID and revision only.",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Request identifier for troubleshooting."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Deleted"
                }
              }
            }
          },
          "default": {
            "description": "Request failed. Errors include a stable code and a readable message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key from Settings → Developers → API keys."
      },
      "accountSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "A signed-in Italic account session. An API key cannot create or revoke keys."
      }
    },
    "schemas": {
      "Deleted": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
          },
          "deleted": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "deleted"
        ],
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "minLength": 0,
                "maxLength": 100
              },
              "message": {
                "type": "string",
                "minLength": 0,
                "maxLength": 1000
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}
```

## Replace a workflow

`PUT https://app.italic.com/api/v2/workflows/{id}`

Required permission: workflows:manage. Saves the whole workflow, as the builders do. An action sent without `condition`, or a Send email action without `from`, keeps its saved one. A new webhook `url` needs webhooks:manage.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Italic API",
    "version": "2.0.0",
    "description": "Recordings, devices, chat, tasks, workflows, connectors and notifications. Text syncs to Italic; audio stays on the client."
  },
  "servers": [
    {
      "url": "https://app.italic.com/api/v2"
    }
  ],
  "paths": {
    "/workflows/{id}": {
      "put": {
        "operationId": "replaceWorkflow",
        "summary": "Replace a workflow",
        "tags": [
          "Workflows"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 256,
              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
            }
          }
        ],
        "description": "Required permission: workflows:manage. Saves the whole workflow, as the builders do. An action sent without `condition`, or a Send email action without `from`, keeps its saved one. A new webhook `url` needs webhooks:manage.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkflowInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success. Writes without read permission return an ID and revision only.",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Request identifier for troubleshooting."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkflowResult"
                }
              }
            }
          },
          "default": {
            "description": "Request failed. Errors include a stable code and a readable message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key from Settings → Developers → API keys."
      },
      "accountSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "A signed-in Italic account session. An API key cannot create or revoke keys."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "minLength": 0,
                "maxLength": 100
              },
              "message": {
                "type": "string",
                "minLength": 0,
                "maxLength": 1000
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ]
      },
      "Workflow": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
          },
          "name": {
            "type": "string",
            "minLength": 0,
            "maxLength": 60
          },
          "enabled": {
            "type": "boolean"
          },
          "trigger": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "recording"
                ]
              },
              "phrases": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "match": {
                "type": "string",
                "enum": [
                  "anywhere",
                  "start"
                ]
              },
              "input": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "hold",
                      "doubleTap",
                      "tripleTap",
                      "recordButton",
                      "pushToTalk",
                      "appRecord"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "kind": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "clip",
                      "memo"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "type",
              "phrases",
              "match",
              "input",
              "kind"
            ]
          },
          "actions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "pattern": "^[a-z][a-z0-9]{0,15}$",
                  "description": "Unique within the workflow; later actions use it in `{{<id>.<output>}}` variables."
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "ai",
                    "agent",
                    "send_email",
                    "create_event",
                    "create_reminder",
                    "send_slack_message",
                    "send_webhook",
                    "create_notion_page",
                    "append_to_notion_page",
                    "save_to_drive",
                    "create_linear_issue",
                    "comment_on_linear_issue",
                    "update_linear_issue",
                    "run_connector_tool"
                  ]
                },
                "approval": {
                  "type": "string",
                  "enum": [
                    "ask",
                    "auto"
                  ],
                  "description": "`ask`: the action waits in Tasks. `auto`: it runs. Write with AI (`ai`) has none."
                }
              },
              "required": [
                "id",
                "type"
              ],
              "description": "One step, with the fields of its type, exactly as the workflow builders in the apps save it: `ai` (instructions, format), `agent` (instructions, apps), `send_email` (to, cc, subject, body, from), `create_event` (title, start, end, location, notes), `create_reminder` (title, notes, due, list), `send_webhook` (url for a new webhook, or webhookId for one the account's workflows already send to; message), `send_slack_message`, `create_notion_page`, `append_to_notion_page`, `save_to_drive`, the Linear actions and `run_connector_tool`. Text fields are templates with `{{recording.transcript}}`-style variables. GET /workflows returns saved actions in this shape; the server checks every field as the builders do."
            }
          },
          "createdAt": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "updatedAt": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "id",
          "name",
          "enabled",
          "trigger",
          "actions",
          "createdAt",
          "updatedAt"
        ]
      },
      "WorkflowInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60
          },
          "enabled": {
            "type": "boolean",
            "description": "Defaults to true."
          },
          "trigger": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "recording"
                ]
              },
              "phrases": {
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 100
                },
                "maxItems": 12,
                "description": "Words that start the workflow. Empty: any words, so input or kind must narrow it."
              },
              "match": {
                "type": "string",
                "enum": [
                  "anywhere",
                  "start"
                ],
                "description": "`start`: the transcript must begin with a phrase. `anywhere`: a phrase anywhere in it."
              },
              "input": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "hold",
                      "doubleTap",
                      "tripleTap",
                      "recordButton",
                      "pushToTalk",
                      "appRecord"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Only recordings from this device input. Null or omitted: any input."
              },
              "kind": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "clip",
                      "memo"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Only Clips or only Memos. Null or omitted: both."
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false,
            "description": "Which new recordings start the workflow. Every condition given must match."
          },
          "actions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "pattern": "^[a-z][a-z0-9]{0,15}$",
                  "description": "Unique within the workflow; later actions use it in `{{<id>.<output>}}` variables."
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "ai",
                    "agent",
                    "send_email",
                    "create_event",
                    "create_reminder",
                    "send_slack_message",
                    "send_webhook",
                    "create_notion_page",
                    "append_to_notion_page",
                    "save_to_drive",
                    "create_linear_issue",
                    "comment_on_linear_issue",
                    "update_linear_issue",
                    "run_connector_tool"
                  ]
                },
                "approval": {
                  "type": "string",
                  "enum": [
                    "ask",
                    "auto"
                  ],
                  "description": "`ask`: the action waits in Tasks. `auto`: it runs. Write with AI (`ai`) has none."
                }
              },
              "required": [
                "id",
                "type"
              ],
              "description": "One step, with the fields of its type, exactly as the workflow builders in the apps save it: `ai` (instructions, format), `agent` (instructions, apps), `send_email` (to, cc, subject, body, from), `create_event` (title, start, end, location, notes), `create_reminder` (title, notes, due, list), `send_webhook` (url for a new webhook, or webhookId for one the account's workflows already send to; message), `send_slack_message`, `create_notion_page`, `append_to_notion_page`, `save_to_drive`, the Linear actions and `run_connector_tool`. Text fields are templates with `{{recording.transcript}}`-style variables. GET /workflows returns saved actions in this shape; the server checks every field as the builders do."
            },
            "minItems": 1,
            "maxItems": 8
          }
        },
        "required": [
          "name",
          "trigger",
          "actions"
        ],
        "additionalProperties": false
      },
      "WorkflowResult": {
        "type": "object",
        "properties": {
          "workflow": {
            "$ref": "#/components/schemas/Workflow"
          },
          "secrets": {
            "type": "array",
            "description": "Signing secrets of webhooks this request added, shown once.",
            "items": {
              "type": "object",
              "properties": {
                "actionIndex": {
                  "type": "integer"
                },
                "url": {
                  "type": "string"
                },
                "secret": {
                  "type": "string"
                }
              },
              "required": [
                "actionIndex",
                "url",
                "secret"
              ]
            }
          },
          "replayed": {
            "type": "boolean"
          }
        },
        "required": [
          "workflow"
        ]
      }
    }
  }
}
```