> For the complete documentation index, see [llms.txt](https://academy.shade.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.shade.inc/developers/automate/automations.md).

# Automations

Automations run actions when something happens in a drive, for example tagging files on upload or emailing a share link when a folder changes.

An automation is a graph of trigger, condition, and action nodes. Create it with `POST /automations`, save the graph with `PUT /automations/{automation_id}`, then activate a version with `PATCH /automations/{automation_id}/versions/{version}/status`. `GET /automations/integrations` lists every available trigger and action.

## GET /automations/integrations

> List available integrations with their triggers and actions

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"automations","description":"Automations run actions when something happens in a drive, for example\ntagging files on upload or emailing a share link when a folder changes.\n\nAn automation is a graph of trigger, condition, and action nodes. Create it\nwith `POST /automations`, save the graph with `PUT /automations/{automation_id}`,\nthen activate a version with `PATCH /automations/{automation_id}/versions/{version}/status`.\n`GET /automations/integrations` lists every available trigger and action."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"IntegrationDTO":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"triggers":{"items":{"$ref":"#/components/schemas/TriggerDTO"},"type":"array","title":"Triggers"},"actions":{"items":{"$ref":"#/components/schemas/ActionDTO"},"type":"array","title":"Actions"}},"type":"object","required":["id","name","description","triggers","actions"],"title":"IntegrationDTO"},"TriggerDTO":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"output_schema":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object","title":"Output Schema"},"config_schema":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object"},{"type":"null"}],"title":"Config Schema"}},"type":"object","required":["id","name","description","output_schema"],"title":"TriggerDTO"},"JsonValue-Output":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object"},{"type":"null"}]},"ActionDTO":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"config_schema":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object","title":"Config Schema"},"output_schema":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object","title":"Output Schema"},"suggested_follow_up":{"anyOf":[{"$ref":"#/components/schemas/SuggestedFollowUp"},{"type":"null"}]},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"}},"type":"object","required":["id","name","description","config_schema","output_schema"],"title":"ActionDTO"},"SuggestedFollowUp":{"properties":{"integration_id":{"$ref":"#/components/schemas/IntegrationId"},"operation":{"type":"string","title":"Operation"},"config_from_output":{"additionalProperties":{"type":"string"},"type":"object","title":"Config From Output"}},"type":"object","required":["integration_id","operation","config_from_output"],"title":"SuggestedFollowUp","description":"A node the editor seeds downstream when this action is added, with its\nconfig wired to this action's output."},"IntegrationId":{"type":"string","enum":["SHADE","CONDITIONS","NOTIFICATIONS","EXTERNAL","TOPAZ","OPUS_CLIP","YOUTUBE","VIMEO","CANVA","ORDINAL"],"title":"IntegrationId"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/automations/integrations":{"get":{"tags":["automations"],"summary":"List available integrations with their triggers and actions","operationId":"listIntegrations","parameters":[{"name":"workspace_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"},"description":"ID of the workspace. List yours with `GET /workspaces`."},{"name":"drive_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Drive Id"},"description":"ID of the drive. List a workspace's drives with `GET /workspaces/{workspace_id}/drives`."}],"responses":{"200":{"description":"A list of all registered integrations.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /automations

> List automations for a drive

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"automations","description":"Automations run actions when something happens in a drive, for example\ntagging files on upload or emailing a share link when a folder changes.\n\nAn automation is a graph of trigger, condition, and action nodes. Create it\nwith `POST /automations`, save the graph with `PUT /automations/{automation_id}`,\nthen activate a version with `PATCH /automations/{automation_id}/versions/{version}/status`.\n`GET /automations/integrations` lists every available trigger and action."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"AutomationListItemDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"status":{"$ref":"#/components/schemas/AutomationStatus"},"created":{"type":"string","format":"date-time","title":"Created"},"created_by_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By Id"},"created_by_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By Name"},"created_by_avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By Avatar Url"},"trigger":{"anyOf":[{"$ref":"#/components/schemas/AutomationListItemTriggerDTO"},{"type":"null"}]},"total_runs":{"type":"integer","title":"Total Runs"},"last_published":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Published"},"last_failed_run":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Failed Run"}},"type":"object","required":["id","name","description","status","created","created_by_id","created_by_name","created_by_avatar_url","trigger","total_runs","last_published","last_failed_run"],"title":"AutomationListItemDTO"},"AutomationStatus":{"type":"string","enum":["DRAFT","ACTIVE","BROKEN"],"title":"AutomationStatus"},"AutomationListItemTriggerDTO":{"properties":{"integration_id":{"type":"string","title":"Integration Id"},"operation":{"type":"string","title":"Operation"},"label":{"type":"string","title":"Label"},"manual_target":{"anyOf":[{"$ref":"#/components/schemas/ManualTarget"},{"type":"null"}]},"has_input_fields":{"type":"boolean","title":"Has Input Fields","default":false}},"type":"object","required":["integration_id","operation","label"],"title":"AutomationListItemTriggerDTO"},"ManualTarget":{"oneOf":[{"$ref":"#/components/schemas/ManualAssetTarget"},{"$ref":"#/components/schemas/DirectoryTarget"}],"discriminator":{"propertyName":"type","mapping":{"asset":"#/components/schemas/ManualAssetTarget","directory":"#/components/schemas/DirectoryTarget"}}},"ManualAssetTarget":{"properties":{"type":{"type":"string","const":"asset","title":"Type","default":"asset"}},"type":"object","title":"ManualAssetTarget"},"DirectoryTarget":{"properties":{"type":{"type":"string","const":"directory","title":"Type","default":"directory"}},"type":"object","title":"DirectoryTarget"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/automations":{"get":{"tags":["automations"],"summary":"List automations for a drive","operationId":"listAutomations","parameters":[{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to list automations for."},"description":"The id of the drive to list automations for."}],"responses":{"200":{"description":"A list of automations in the specified drive.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AutomationListItemDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create a new automation

> Create an automation with an initial v1 DRAFT version.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"automations","description":"Automations run actions when something happens in a drive, for example\ntagging files on upload or emailing a share link when a folder changes.\n\nAn automation is a graph of trigger, condition, and action nodes. Create it\nwith `POST /automations`, save the graph with `PUT /automations/{automation_id}`,\nthen activate a version with `PATCH /automations/{automation_id}/versions/{version}/status`.\n`GET /automations/integrations` lists every available trigger and action."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"CreateAutomationRequest":{"properties":{"name":{"type":"string","title":"Name"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","required":["name","drive_id"],"title":"CreateAutomationRequest"},"AutomationDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"created_by_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By Id"},"created":{"type":"string","format":"date-time","title":"Created"},"loaded_version":{"$ref":"#/components/schemas/AutomationVersionDTO"},"active_version":{"anyOf":[{"$ref":"#/components/schemas/AutomationVersionDTO"},{"type":"null"}]},"active_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Active Version Number"},"versions":{"items":{"$ref":"#/components/schemas/AutomationVersionSummaryDTO"},"type":"array","title":"Versions"}},"type":"object","required":["id","name","description","drive_id","created_by_id","created","loaded_version","active_version","active_version_number","versions"],"title":"AutomationDTO"},"AutomationVersionDTO":{"properties":{"version":{"type":"integer","title":"Version"},"status":{"$ref":"#/components/schemas/AutomationStatus"},"viewport":{"$ref":"#/components/schemas/Viewport"},"nodes":{"items":{"$ref":"#/components/schemas/AutomationNodeDTO"},"type":"array","title":"Nodes"},"edges":{"items":{"$ref":"#/components/schemas/AutomationEdgeDTO"},"type":"array","title":"Edges"}},"type":"object","required":["version","status","viewport","nodes","edges"],"title":"AutomationVersionDTO"},"AutomationStatus":{"type":"string","enum":["DRAFT","ACTIVE","BROKEN"],"title":"AutomationStatus"},"Viewport":{"properties":{"x":{"type":"number","title":"X"},"y":{"type":"number","title":"Y"},"zoom":{"type":"number","title":"Zoom"}},"type":"object","required":["x","y","zoom"],"title":"Viewport"},"AutomationNodeDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"node_type":{"$ref":"#/components/schemas/NodeType"},"integration_id":{"type":"string","title":"Integration Id"},"operation":{"type":"string","title":"Operation"},"label":{"type":"string","title":"Label"},"config":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object","title":"Config"},"position_x":{"type":"number","title":"Position X"},"position_y":{"type":"number","title":"Position Y"}},"type":"object","required":["id","node_type","integration_id","operation","label","config","position_x","position_y"],"title":"AutomationNodeDTO"},"NodeType":{"type":"string","enum":["TRIGGER","ACTION","CONDITION"],"title":"NodeType"},"JsonValue-Output":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object"},{"type":"null"}]},"AutomationEdgeDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"source_node_id":{"type":"string","format":"uuid","title":"Source Node Id"},"target_node_id":{"type":"string","format":"uuid","title":"Target Node Id"},"output_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Key"}},"type":"object","required":["id","source_node_id","target_node_id"],"title":"AutomationEdgeDTO"},"AutomationVersionSummaryDTO":{"properties":{"version":{"type":"integer","title":"Version"},"status":{"$ref":"#/components/schemas/AutomationStatus"}},"type":"object","required":["version","status"],"title":"AutomationVersionSummaryDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/automations":{"post":{"tags":["automations"],"summary":"Create a new automation","description":"Create an automation with an initial v1 DRAFT version.","operationId":"createAutomation","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAutomationRequest"}}}},"responses":{"200":{"description":"The newly created automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /automations/{automation\_id}

> Get an automation by ID

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"automations","description":"Automations run actions when something happens in a drive, for example\ntagging files on upload or emailing a share link when a folder changes.\n\nAn automation is a graph of trigger, condition, and action nodes. Create it\nwith `POST /automations`, save the graph with `PUT /automations/{automation_id}`,\nthen activate a version with `PATCH /automations/{automation_id}/versions/{version}/status`.\n`GET /automations/integrations` lists every available trigger and action."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"AutomationDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"created_by_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By Id"},"created":{"type":"string","format":"date-time","title":"Created"},"loaded_version":{"$ref":"#/components/schemas/AutomationVersionDTO"},"active_version":{"anyOf":[{"$ref":"#/components/schemas/AutomationVersionDTO"},{"type":"null"}]},"active_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Active Version Number"},"versions":{"items":{"$ref":"#/components/schemas/AutomationVersionSummaryDTO"},"type":"array","title":"Versions"}},"type":"object","required":["id","name","description","drive_id","created_by_id","created","loaded_version","active_version","active_version_number","versions"],"title":"AutomationDTO"},"AutomationVersionDTO":{"properties":{"version":{"type":"integer","title":"Version"},"status":{"$ref":"#/components/schemas/AutomationStatus"},"viewport":{"$ref":"#/components/schemas/Viewport"},"nodes":{"items":{"$ref":"#/components/schemas/AutomationNodeDTO"},"type":"array","title":"Nodes"},"edges":{"items":{"$ref":"#/components/schemas/AutomationEdgeDTO"},"type":"array","title":"Edges"}},"type":"object","required":["version","status","viewport","nodes","edges"],"title":"AutomationVersionDTO"},"AutomationStatus":{"type":"string","enum":["DRAFT","ACTIVE","BROKEN"],"title":"AutomationStatus"},"Viewport":{"properties":{"x":{"type":"number","title":"X"},"y":{"type":"number","title":"Y"},"zoom":{"type":"number","title":"Zoom"}},"type":"object","required":["x","y","zoom"],"title":"Viewport"},"AutomationNodeDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"node_type":{"$ref":"#/components/schemas/NodeType"},"integration_id":{"type":"string","title":"Integration Id"},"operation":{"type":"string","title":"Operation"},"label":{"type":"string","title":"Label"},"config":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object","title":"Config"},"position_x":{"type":"number","title":"Position X"},"position_y":{"type":"number","title":"Position Y"}},"type":"object","required":["id","node_type","integration_id","operation","label","config","position_x","position_y"],"title":"AutomationNodeDTO"},"NodeType":{"type":"string","enum":["TRIGGER","ACTION","CONDITION"],"title":"NodeType"},"JsonValue-Output":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object"},{"type":"null"}]},"AutomationEdgeDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"source_node_id":{"type":"string","format":"uuid","title":"Source Node Id"},"target_node_id":{"type":"string","format":"uuid","title":"Target Node Id"},"output_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Key"}},"type":"object","required":["id","source_node_id","target_node_id"],"title":"AutomationEdgeDTO"},"AutomationVersionSummaryDTO":{"properties":{"version":{"type":"integer","title":"Version"},"status":{"$ref":"#/components/schemas/AutomationStatus"}},"type":"object","required":["version","status"],"title":"AutomationVersionSummaryDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/automations/{automation_id}":{"get":{"tags":["automations"],"summary":"Get an automation by ID","operationId":"getAutomation","parameters":[{"name":"automation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The automation id","description":"The UUID of the automation to retrieve."},"description":"The UUID of the automation to retrieve."}],"responses":{"200":{"description":"The automation with its active (or latest) version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Save automation graph (whole-graph replace)

> Replace all nodes and edges for an automation.\
> \
> If the current version is DRAFT, overwrites it in place.\
> If the current version is ACTIVE, creates a new DRAFT version\
> to preserve the active version's graph for execution history.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"automations","description":"Automations run actions when something happens in a drive, for example\ntagging files on upload or emailing a share link when a folder changes.\n\nAn automation is a graph of trigger, condition, and action nodes. Create it\nwith `POST /automations`, save the graph with `PUT /automations/{automation_id}`,\nthen activate a version with `PATCH /automations/{automation_id}/versions/{version}/status`.\n`GET /automations/integrations` lists every available trigger and action."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"SaveAutomationRequest":{"properties":{"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"viewport":{"$ref":"#/components/schemas/Viewport"},"nodes":{"items":{"$ref":"#/components/schemas/SaveNodeData"},"type":"array","title":"Nodes"},"edges":{"items":{"$ref":"#/components/schemas/SaveEdgeData"},"type":"array","title":"Edges"}},"type":"object","required":["name","viewport","nodes","edges"],"title":"SaveAutomationRequest"},"Viewport":{"properties":{"x":{"type":"number","title":"X"},"y":{"type":"number","title":"Y"},"zoom":{"type":"number","title":"Zoom"}},"type":"object","required":["x","y","zoom"],"title":"Viewport"},"SaveNodeData":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"node_type":{"$ref":"#/components/schemas/NodeType"},"integration_id":{"type":"string","title":"Integration Id"},"operation":{"type":"string","title":"Operation"},"label":{"type":"string","title":"Label","default":""},"config":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Input"},"type":"object","title":"Config"},"position_x":{"type":"number","title":"Position X","default":0},"position_y":{"type":"number","title":"Position Y","default":0}},"type":"object","required":["id","node_type","integration_id","operation"],"title":"SaveNodeData"},"NodeType":{"type":"string","enum":["TRIGGER","ACTION","CONDITION"],"title":"NodeType"},"JsonValue-Input":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue-Input"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Input"},"type":"object"},{"type":"null"}]},"SaveEdgeData":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"source_node_id":{"type":"string","format":"uuid","title":"Source Node Id"},"target_node_id":{"type":"string","format":"uuid","title":"Target Node Id"},"output_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Key"}},"type":"object","required":["id","source_node_id","target_node_id"],"title":"SaveEdgeData"},"AutomationDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"created_by_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By Id"},"created":{"type":"string","format":"date-time","title":"Created"},"loaded_version":{"$ref":"#/components/schemas/AutomationVersionDTO"},"active_version":{"anyOf":[{"$ref":"#/components/schemas/AutomationVersionDTO"},{"type":"null"}]},"active_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Active Version Number"},"versions":{"items":{"$ref":"#/components/schemas/AutomationVersionSummaryDTO"},"type":"array","title":"Versions"}},"type":"object","required":["id","name","description","drive_id","created_by_id","created","loaded_version","active_version","active_version_number","versions"],"title":"AutomationDTO"},"AutomationVersionDTO":{"properties":{"version":{"type":"integer","title":"Version"},"status":{"$ref":"#/components/schemas/AutomationStatus"},"viewport":{"$ref":"#/components/schemas/Viewport"},"nodes":{"items":{"$ref":"#/components/schemas/AutomationNodeDTO"},"type":"array","title":"Nodes"},"edges":{"items":{"$ref":"#/components/schemas/AutomationEdgeDTO"},"type":"array","title":"Edges"}},"type":"object","required":["version","status","viewport","nodes","edges"],"title":"AutomationVersionDTO"},"AutomationStatus":{"type":"string","enum":["DRAFT","ACTIVE","BROKEN"],"title":"AutomationStatus"},"AutomationNodeDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"node_type":{"$ref":"#/components/schemas/NodeType"},"integration_id":{"type":"string","title":"Integration Id"},"operation":{"type":"string","title":"Operation"},"label":{"type":"string","title":"Label"},"config":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object","title":"Config"},"position_x":{"type":"number","title":"Position X"},"position_y":{"type":"number","title":"Position Y"}},"type":"object","required":["id","node_type","integration_id","operation","label","config","position_x","position_y"],"title":"AutomationNodeDTO"},"JsonValue-Output":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object"},{"type":"null"}]},"AutomationEdgeDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"source_node_id":{"type":"string","format":"uuid","title":"Source Node Id"},"target_node_id":{"type":"string","format":"uuid","title":"Target Node Id"},"output_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Key"}},"type":"object","required":["id","source_node_id","target_node_id"],"title":"AutomationEdgeDTO"},"AutomationVersionSummaryDTO":{"properties":{"version":{"type":"integer","title":"Version"},"status":{"$ref":"#/components/schemas/AutomationStatus"}},"type":"object","required":["version","status"],"title":"AutomationVersionSummaryDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/automations/{automation_id}":{"put":{"tags":["automations"],"summary":"Save automation graph (whole-graph replace)","description":"Replace all nodes and edges for an automation.\n\nIf the current version is DRAFT, overwrites it in place.\nIf the current version is ACTIVE, creates a new DRAFT version\nto preserve the active version's graph for execution history.","operationId":"saveAutomation","parameters":[{"name":"automation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The automation id","description":"The UUID of the automation to save."},"description":"The UUID of the automation to save."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveAutomationRequest"}}}},"responses":{"200":{"description":"The saved automation with updated version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## DELETE /automations/{automation\_id}

> Delete an automation

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"automations","description":"Automations run actions when something happens in a drive, for example\ntagging files on upload or emailing a share link when a folder changes.\n\nAn automation is a graph of trigger, condition, and action nodes. Create it\nwith `POST /automations`, save the graph with `PUT /automations/{automation_id}`,\nthen activate a version with `PATCH /automations/{automation_id}/versions/{version}/status`.\n`GET /automations/integrations` lists every available trigger and action."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/automations/{automation_id}":{"delete":{"tags":["automations"],"summary":"Delete an automation","operationId":"deleteAutomation","parameters":[{"name":"automation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The automation id","description":"The UUID of the automation to delete."},"description":"The UUID of the automation to delete."}],"responses":{"204":{"description":"Successful Response"},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /automations/{automation\_id}/executions

> Get execution history for an automation

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"automations","description":"Automations run actions when something happens in a drive, for example\ntagging files on upload or emailing a share link when a folder changes.\n\nAn automation is a graph of trigger, condition, and action nodes. Create it\nwith `POST /automations`, save the graph with `PUT /automations/{automation_id}`,\nthen activate a version with `PATCH /automations/{automation_id}/versions/{version}/status`.\n`GET /automations/integrations` lists every available trigger and action."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"PaginatedExecutionsDTO":{"properties":{"executions":{"items":{"$ref":"#/components/schemas/AutomationExecutionDTO"},"type":"array","title":"Executions"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"},"has_next":{"type":"boolean","title":"Has Next"}},"type":"object","required":["executions","page","page_size","has_next"],"title":"PaginatedExecutionsDTO"},"AutomationExecutionDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"automation_id":{"type":"string","format":"uuid","title":"Automation Id"},"version":{"type":"integer","title":"Version"},"status":{"$ref":"#/components/schemas/ExecutionStatus"},"trigger_data":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object","title":"Trigger Data"},"node_outputs":{"additionalProperties":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object"},"type":"object","title":"Node Outputs"},"current_node_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Current Node Id"},"execution_type":{"$ref":"#/components/schemas/ExecutionType"},"node_state":{"anyOf":[{"$ref":"#/components/schemas/NodeState"},{"type":"null"}]},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"},"duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Ms"},"created":{"type":"string","format":"date-time","title":"Created"}},"type":"object","required":["id","automation_id","version","status","trigger_data","node_outputs","current_node_id","execution_type","node_state","started_at","completed_at","duration_ms","created"],"title":"AutomationExecutionDTO"},"ExecutionStatus":{"type":"string","enum":["QUEUED","PROCESSING","DEFERRED_PROCESSING","COMPLETED","FAILED","CANCELLED"],"title":"ExecutionStatus"},"JsonValue-Output":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object"},{"type":"null"}]},"ExecutionType":{"type":"string","enum":["DEFAULT","POLLING"],"title":"ExecutionType","description":"Which path a claimed execution takes: a fresh node run, or a poll tick\nresuming the in-flight node from ``node_state``."},"NodeState":{"properties":{"poll":{"anyOf":[{"$ref":"#/components/schemas/PollState"},{"type":"null"}]}},"type":"object","title":"NodeState","description":"State the harness keeps for the in-flight node across worker ticks.\nPolling today; anything else that must survive between ticks later."},"PollState":{"properties":{"status":{"type":"string","enum":["started","processing","completed","failed"],"title":"Status","default":"started"},"poll_params":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object","title":"Poll Params"},"ratio":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Ratio"},"status_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Text"},"started_at":{"type":"string","format":"date-time","title":"Started At"},"polling_since":{"type":"string","format":"date-time","title":"Polling Since"},"erroring_since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Erroring Since"},"poll_attempts":{"type":"integer","title":"Poll Attempts","default":0}},"type":"object","title":"PollState","description":"A polling node's whereabouts and progress, persisted between ticks so\nany worker can resume it; kept apart from the queue status so a\nstale-worker reset can't lose it. ``status`` is what the action last\nreported; \"completed\" and \"failed\" never persist -- they make the harness\nfinalize or fail the node."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/automations/{automation_id}/executions":{"get":{"tags":["automations"],"summary":"Get execution history for an automation","operationId":"listAutomationExecutions","parameters":[{"name":"automation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The automation id","description":"The UUID of the automation to get executions for."},"description":"The UUID of the automation to get executions for."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"title":"Page number","description":"1-indexed page number.","default":1},"description":"1-indexed page number."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"title":"Page size","description":"Number of executions per page.","default":20},"description":"Number of executions per page."}],"responses":{"200":{"description":"Paginated list of executions for the automation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedExecutionsDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## POST /automations/{automation\_id}/executions

> Run a manually-triggered automation on a selection

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"automations","description":"Automations run actions when something happens in a drive, for example\ntagging files on upload or emailing a share link when a folder changes.\n\nAn automation is a graph of trigger, condition, and action nodes. Create it\nwith `POST /automations`, save the graph with `PUT /automations/{automation_id}`,\nthen activate a version with `PATCH /automations/{automation_id}/versions/{version}/status`.\n`GET /automations/integrations` lists every available trigger and action."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"ManualRunRequest":{"properties":{"selection":{"$ref":"#/components/schemas/ManualRunSelection"},"inputs":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Input"},"type":"object","title":"Inputs"}},"type":"object","required":["selection"],"title":"ManualRunRequest"},"ManualRunSelection":{"oneOf":[{"$ref":"#/components/schemas/AssetSelection"},{"$ref":"#/components/schemas/DirectorySelection"}],"discriminator":{"propertyName":"type","mapping":{"asset":"#/components/schemas/AssetSelection","directory":"#/components/schemas/DirectorySelection"}}},"AssetSelection":{"properties":{"type":{"type":"string","const":"asset","title":"Type","default":"asset"},"asset_ids":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":1000,"minItems":1,"title":"Asset Ids"}},"type":"object","required":["asset_ids"],"title":"AssetSelection"},"DirectorySelection":{"properties":{"type":{"type":"string","const":"directory","title":"Type","default":"directory"},"paths":{"items":{"type":"string"},"type":"array","maxItems":1000,"minItems":1,"title":"Paths"}},"type":"object","required":["paths"],"title":"DirectorySelection"},"JsonValue-Input":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue-Input"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Input"},"type":"object"},{"type":"null"}]},"ManualRunResponse":{"properties":{"execution_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Execution Ids"}},"type":"object","required":["execution_ids"],"title":"ManualRunResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/automations/{automation_id}/executions":{"post":{"tags":["automations"],"summary":"Run a manually-triggered automation on a selection","operationId":"runAutomation","parameters":[{"name":"automation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The automation id","description":"The UUID of the automation."},"description":"The UUID of the automation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManualRunRequest"}}}},"responses":{"201":{"description":"The ids of the queued executions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManualRunResponse"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /automations/{automation\_id}/executions/form

> The input form for manually running an automation

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"automations","description":"Automations run actions when something happens in a drive, for example\ntagging files on upload or emailing a share link when a folder changes.\n\nAn automation is a graph of trigger, condition, and action nodes. Create it\nwith `POST /automations`, save the graph with `PUT /automations/{automation_id}`,\nthen activate a version with `PATCH /automations/{automation_id}/versions/{version}/status`.\n`GET /automations/integrations` lists every available trigger and action."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"ExecutionFormDTO":{"properties":{"inputs_schema":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object"},{"type":"null"}],"title":"Inputs Schema"}},"type":"object","required":["inputs_schema"],"title":"ExecutionFormDTO"},"JsonValue-Output":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object"},{"type":"null"}]},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/automations/{automation_id}/executions/form":{"get":{"tags":["automations"],"summary":"The input form for manually running an automation","operationId":"getAutomationRunForm","parameters":[{"name":"automation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The automation id","description":"The UUID of the automation."},"description":"The UUID of the automation."}],"responses":{"200":{"description":"JSON schema for run inputs; null when there is no form.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionFormDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /automations/{automation\_id}/versions/{version}

> Get a specific version of an automation

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"automations","description":"Automations run actions when something happens in a drive, for example\ntagging files on upload or emailing a share link when a folder changes.\n\nAn automation is a graph of trigger, condition, and action nodes. Create it\nwith `POST /automations`, save the graph with `PUT /automations/{automation_id}`,\nthen activate a version with `PATCH /automations/{automation_id}/versions/{version}/status`.\n`GET /automations/integrations` lists every available trigger and action."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"AutomationVersionDTO":{"properties":{"version":{"type":"integer","title":"Version"},"status":{"$ref":"#/components/schemas/AutomationStatus"},"viewport":{"$ref":"#/components/schemas/Viewport"},"nodes":{"items":{"$ref":"#/components/schemas/AutomationNodeDTO"},"type":"array","title":"Nodes"},"edges":{"items":{"$ref":"#/components/schemas/AutomationEdgeDTO"},"type":"array","title":"Edges"}},"type":"object","required":["version","status","viewport","nodes","edges"],"title":"AutomationVersionDTO"},"AutomationStatus":{"type":"string","enum":["DRAFT","ACTIVE","BROKEN"],"title":"AutomationStatus"},"Viewport":{"properties":{"x":{"type":"number","title":"X"},"y":{"type":"number","title":"Y"},"zoom":{"type":"number","title":"Zoom"}},"type":"object","required":["x","y","zoom"],"title":"Viewport"},"AutomationNodeDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"node_type":{"$ref":"#/components/schemas/NodeType"},"integration_id":{"type":"string","title":"Integration Id"},"operation":{"type":"string","title":"Operation"},"label":{"type":"string","title":"Label"},"config":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object","title":"Config"},"position_x":{"type":"number","title":"Position X"},"position_y":{"type":"number","title":"Position Y"}},"type":"object","required":["id","node_type","integration_id","operation","label","config","position_x","position_y"],"title":"AutomationNodeDTO"},"NodeType":{"type":"string","enum":["TRIGGER","ACTION","CONDITION"],"title":"NodeType"},"JsonValue-Output":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object"},{"type":"null"}]},"AutomationEdgeDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"source_node_id":{"type":"string","format":"uuid","title":"Source Node Id"},"target_node_id":{"type":"string","format":"uuid","title":"Target Node Id"},"output_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Key"}},"type":"object","required":["id","source_node_id","target_node_id"],"title":"AutomationEdgeDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/automations/{automation_id}/versions/{version}":{"get":{"tags":["automations"],"summary":"Get a specific version of an automation","operationId":"getAutomationVersion","parameters":[{"name":"automation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The automation id","description":"The UUID of the automation."},"description":"The UUID of the automation."},{"name":"version","in":"path","required":true,"schema":{"type":"integer","title":"The version number","description":"The version number to retrieve."},"description":"The version number to retrieve."}],"responses":{"200":{"description":"The requested automation version with its nodes and edges.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationVersionDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Set the status of an automation version

> Set a version's status. When activating, any previously active version is deactivated.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"automations","description":"Automations run actions when something happens in a drive, for example\ntagging files on upload or emailing a share link when a folder changes.\n\nAn automation is a graph of trigger, condition, and action nodes. Create it\nwith `POST /automations`, save the graph with `PUT /automations/{automation_id}`,\nthen activate a version with `PATCH /automations/{automation_id}/versions/{version}/status`.\n`GET /automations/integrations` lists every available trigger and action."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"SetVersionStatusRequest":{"properties":{"status":{"$ref":"#/components/schemas/AutomationStatus"}},"type":"object","required":["status"],"title":"SetVersionStatusRequest"},"AutomationStatus":{"type":"string","enum":["DRAFT","ACTIVE","BROKEN"],"title":"AutomationStatus"},"AutomationDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"created_by_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By Id"},"created":{"type":"string","format":"date-time","title":"Created"},"loaded_version":{"$ref":"#/components/schemas/AutomationVersionDTO"},"active_version":{"anyOf":[{"$ref":"#/components/schemas/AutomationVersionDTO"},{"type":"null"}]},"active_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Active Version Number"},"versions":{"items":{"$ref":"#/components/schemas/AutomationVersionSummaryDTO"},"type":"array","title":"Versions"}},"type":"object","required":["id","name","description","drive_id","created_by_id","created","loaded_version","active_version","active_version_number","versions"],"title":"AutomationDTO"},"AutomationVersionDTO":{"properties":{"version":{"type":"integer","title":"Version"},"status":{"$ref":"#/components/schemas/AutomationStatus"},"viewport":{"$ref":"#/components/schemas/Viewport"},"nodes":{"items":{"$ref":"#/components/schemas/AutomationNodeDTO"},"type":"array","title":"Nodes"},"edges":{"items":{"$ref":"#/components/schemas/AutomationEdgeDTO"},"type":"array","title":"Edges"}},"type":"object","required":["version","status","viewport","nodes","edges"],"title":"AutomationVersionDTO"},"Viewport":{"properties":{"x":{"type":"number","title":"X"},"y":{"type":"number","title":"Y"},"zoom":{"type":"number","title":"Zoom"}},"type":"object","required":["x","y","zoom"],"title":"Viewport"},"AutomationNodeDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"node_type":{"$ref":"#/components/schemas/NodeType"},"integration_id":{"type":"string","title":"Integration Id"},"operation":{"type":"string","title":"Operation"},"label":{"type":"string","title":"Label"},"config":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object","title":"Config"},"position_x":{"type":"number","title":"Position X"},"position_y":{"type":"number","title":"Position Y"}},"type":"object","required":["id","node_type","integration_id","operation","label","config","position_x","position_y"],"title":"AutomationNodeDTO"},"NodeType":{"type":"string","enum":["TRIGGER","ACTION","CONDITION"],"title":"NodeType"},"JsonValue-Output":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue-Output"},"type":"object"},{"type":"null"}]},"AutomationEdgeDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"source_node_id":{"type":"string","format":"uuid","title":"Source Node Id"},"target_node_id":{"type":"string","format":"uuid","title":"Target Node Id"},"output_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Key"}},"type":"object","required":["id","source_node_id","target_node_id"],"title":"AutomationEdgeDTO"},"AutomationVersionSummaryDTO":{"properties":{"version":{"type":"integer","title":"Version"},"status":{"$ref":"#/components/schemas/AutomationStatus"}},"type":"object","required":["version","status"],"title":"AutomationVersionSummaryDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/automations/{automation_id}/versions/{version}/status":{"patch":{"tags":["automations"],"summary":"Set the status of an automation version","description":"Set a version's status. When activating, any previously active version is deactivated.","operationId":"setAutomationVersionStatus","parameters":[{"name":"automation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The automation id","description":"The UUID of the automation."},"description":"The UUID of the automation."},{"name":"version","in":"path","required":true,"schema":{"type":"integer","title":"The version number","description":"The version number to update."},"description":"The version number to update."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetVersionStatusRequest"}}}},"responses":{"200":{"description":"The automation with the updated version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Receive an inbound webhook for a webhook trigger node

> Public endpoint: callers authenticate with the trigger node's bearer\
> token (enforced by the dispatcher when require\_auth is enabled), not a\
> Shade session.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"automations","description":"Automations run actions when something happens in a drive, for example\ntagging files on upload or emailing a share link when a folder changes.\n\nAn automation is a graph of trigger, condition, and action nodes. Create it\nwith `POST /automations`, save the graph with `PUT /automations/{automation_id}`,\nthen activate a version with `PATCH /automations/{automation_id}/versions/{version}/status`.\n`GET /automations/integrations` lists every available trigger and action."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/automations/webhooks/{trigger_node_id}":{"post":{"tags":["automations"],"summary":"Receive an inbound webhook for a webhook trigger node","description":"Public endpoint: callers authenticate with the trigger node's bearer\ntoken (enforced by the dispatcher when require_auth is enabled), not a\nShade session.","operationId":"receiveAutomationWebhook","parameters":[{"name":"trigger_node_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The webhook trigger node id","description":"The trigger node id embedded in the webhook URL."},"description":"The trigger node id embedded in the webhook URL."}],"responses":{"200":{"description":"Acknowledgement that an execution was queued.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://academy.shade.inc/developers/automate/automations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
