{"openapi":"3.1.0","info":{"title":"DEV3 Cogvane API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"n3k_…"}}},"paths":{"/me":{"get":{"summary":"The workspace this key belongs to","tags":["Workspace"],"security":[{"bearer":[]}],"x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"plan":{"type":"string"},"members":{"type":"number"}},"required":["id","name","plan","members"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/usage":{"get":{"summary":"Runs and operations used in the current billing period","tags":["Workspace"],"security":[{"bearer":[]}],"x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"plan":{"type":"string"},"rows":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string"},"used":{"type":"number"},"limit":{"type":"number"}},"required":["metric","used","limit"],"additionalProperties":false}}},"required":["plan","rows"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/nodes":{"get":{"summary":"Node catalogue","tags":["Flows"],"security":[{"bearer":[]}],"x-scope":"flows:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"category":{"type":"string"},"ports":{"type":"array","items":{"type":"string"}}},"required":["type","label","category","ports"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/flows":{"get":{"summary":"List flows","tags":["Flows"],"security":[{"bearer":[]}],"x-scope":"flows:read","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"type":"number"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"publishedNo":{"type":"number"},"tags":{"type":"array","items":{"type":"string"}}},"required":["id","name","status","publishedNo","tags"],"additionalProperties":{}}}},"required":["total","data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"post":{"summary":"Create a flow by importing JSON (credentials by name only)","tags":["Flows"],"security":[{"bearer":[]}],"x-scope":"flows:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"flow":{},"credentialMap":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"name":{"type":"string"}},"required":["flow"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"flowId":{"type":"string"},"dropped":{"type":"array","items":{"type":"string"}},"missingCredentials":{"type":"array","items":{"type":"string"}},"issues":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"nodeId":{"type":"string"}},"required":["level","code","message"],"additionalProperties":false}}},"required":["flowId","dropped","missingCredentials","issues"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/flows/{id}":{"get":{"summary":"Get a flow with its draft graph","tags":["Flows"],"security":[{"bearer":[]}],"x-scope":"flows:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"publishedNo":{"type":"number"},"tags":{"type":"array","items":{"type":"string"}},"draft":{"type":"object","properties":{"cogvaneFlow":{"type":"number","const":1},"nodes":{"type":"array","items":{}},"edges":{"type":"array","items":{}}},"required":["nodes","edges"],"additionalProperties":false},"draftRev":{"type":"number"}},"required":["id","name","status","publishedNo","tags","draft","draftRev"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"patch":{"summary":"Update the draft (needs the current draftRev)","tags":["Flows"],"security":[{"bearer":[]}],"x-scope":"flows:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"draftRev":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"graph":{"type":"object","properties":{"cogvaneFlow":{"type":"number","const":1},"nodes":{"type":"array","items":{}},"edges":{"type":"array","items":{}}},"required":["nodes","edges"],"additionalProperties":false},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"timezone":{"type":"string"}},"required":["draftRev"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"draftRev":{"type":"number"},"issues":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"nodeId":{"type":"string"}},"required":["level","code","message"],"additionalProperties":false}}},"required":["draftRev","issues"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/flows/{id}/publish":{"post":{"summary":"Publish the draft as a new immutable version","tags":["Flows"],"security":[{"bearer":[]}],"x-scope":"flows:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"note":{"type":"string","maxLength":300},"expectedVersionNo":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"versionId":{"type":"string"},"no":{"type":"number"},"live":{"type":"boolean"},"hookKey":{"type":"string"},"secret":{"type":"string"}},"required":["versionId","no","live"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/flows/{id}/activate":{"post":{"summary":"Activate the published version (triggers go live)","tags":["Flows"],"security":[{"bearer":[]}],"x-scope":"flows:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"status":{"type":"string"}},"required":["status"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/flows/{id}/pause":{"post":{"summary":"Pause a flow","tags":["Flows"],"security":[{"bearer":[]}],"x-scope":"flows:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"status":{"type":"string"}},"required":["status"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/flows/{id}/versions":{"get":{"summary":"List published versions","tags":["Flows"],"security":[{"bearer":[]}],"x-scope":"flows:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"no":{"type":"number"},"note":{"type":"string"},"graphHash":{"type":"string"}},"required":["id","no","note","graphHash"],"additionalProperties":{}}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/flows/{id}/export":{"get":{"summary":"Export a flow as JSON (credential names only)","tags":["Flows"],"security":[{"bearer":[]}],"x-scope":"flows:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"cogvaneFlow":{"type":"number","const":1},"name":{"type":"string"},"graph":{"type":"object","properties":{"cogvaneFlow":{"type":"number","const":1},"nodes":{"type":"array","items":{}},"edges":{"type":"array","items":{}}},"required":["nodes","edges"],"additionalProperties":false}},"required":["cogvaneFlow","name","graph"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/runs":{"get":{"summary":"List runs","tags":["Runs"],"security":[{"bearer":[]}],"x-scope":"runs:read","parameters":[{"name":"flow","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"type":"number"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"flowId":{"type":"string"},"status":{"type":"string"}},"required":["id","flowId","status"],"additionalProperties":{}}}},"required":["total","data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/runs/{id}":{"get":{"summary":"Run with steps (redacted previews)","tags":["Runs"],"security":[{"bearer":[]}],"x-scope":"runs:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"run":{"type":"object","properties":{"id":{"type":"string"},"flowId":{"type":"string"},"status":{"type":"string"}},"required":["id","flowId","status"],"additionalProperties":{}},"steps":{"type":"array","items":{"type":"object","properties":{"seq":{"type":"number"},"nodeId":{"type":"string"},"status":{"type":"string"}},"required":["seq","nodeId","status"],"additionalProperties":{}}}},"required":["run","steps"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/flows/{id}/runs":{"post":{"summary":"Start a run of the published version (manual trigger)","tags":["Runs"],"security":[{"bearer":[]}],"x-scope":"runs:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"input":{},"idempotencyKey":{"type":"string","maxLength":200}},"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"duplicate":{"type":"boolean"}},"required":["id","status","duplicate"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/runs/{id}/retry":{"post":{"summary":"Retry a failed, timed-out or cancelled run","tags":["Runs"],"security":[{"bearer":[]}],"x-scope":"runs:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"fromStep":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"duplicate":{"type":"boolean"}},"required":["id","status","duplicate"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/runs/{id}/cancel":{"post":{"summary":"Cancel a run","tags":["Runs"],"security":[{"bearer":[]}],"x-scope":"runs:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"status":{"type":"string"}},"required":["status"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/credentials":{"get":{"summary":"List credential names (values are never returned)","tags":["Vault"],"security":[{"bearer":[]}],"x-scope":"vault:list","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"hint":{"type":"string"}},"required":["id","name","kind","hint"],"additionalProperties":{}}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}}}}