Flow Definition

Root Structure

Every CAFF flow is a JSON object with this shape:

{
  "$schema": "https://cavos.org/schemas/flow/v1.json",
  "version": "1.0.0",
  "metadata": { ... },
  "variables": { ... },
  "nodes": [ ... ],
  "edges": [ ... ],
  "viewport": { ... },
  "credentials": { ... },
  "runtime": { ... },
  "settings": { ... }
}

Metadata

{
  "metadata": {
    "id": "unique-flow-id",
    "name": "My Agent Flow",
    "description": "What this flow does",
    "author": "user-id",
    "tags": ["support", "chatbot"],
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Field	Type	Required	Description
id	string	Yes	Unique identifier
name	string	Yes	Display name
description	string	No	What the flow does
author	string	No	Creator user ID
tags	string[]	No	Categorization tags
createdAt	ISO 8601	No	Creation timestamp
updatedAt	ISO 8601	No	Last update timestamp

Viewport

Canvas state for the flow builder:

{
  "viewport": {
    "x": 0,
    "y": 0,
    "zoom": 1
  }
}

Credentials

Define credential requirements for portability:

{
  "credentials": {
    "required": [
      {
        "key": "openai_api_key",
        "description": "OpenAI API key for GPT models",
        "type": "api_key"
      }
    ],
    "optional": [
      {
        "key": "slack_token",
        "description": "Slack bot token for notifications"
      }
    ]
  }
}

Runtime Configuration

{
  "runtime": {
    "supportedRuntimes": ["node", "edge"],
    "timeoutMs": 300000,
    "memoryMB": 256,
    "maxConcurrency": 5,
    "retry": {
      "maxAttempts": 3,
      "backoffMs": 1000,
      "backoffMultiplier": 2
    }
  }
}