Reference for the graph.manifest.json file that describes your graph.

Overview

The graph.manifest.json file describes your graph:

Identity - Graph name and company
Metadata - Title, description, discovery
Versions - Which versions are available
Visibility - Who can see and use the graph

This file is used during flutch graph deploy to register your graph.

The manifest describes the graph itself, not agent configurations.

Basic Structure

{
  "companySlug": "acme-corp",
  "name": "support-workflow",
  "title": "Support Workflow",
  "description": "Customer support workflow with docs search",
  "versioning": {
    "strategy": "semver",
    "defaultVersion": "1.0.0",
    "supportedVersions": ["1.0.0"]
  },
  "versions": {
    "1.0.0": {
      "status": "stable",
      "visibility": "public"
    }
  }
}

Required Fields

companySlug

Your company identifier on Flutch.

"companySlug": "acme-corp"

Rules:

Lowercase letters, hyphens only
Must match your Flutch account
Assigned during onboarding

Forms graph type: acme-corp.support::1.0.0

name

Unique graph identifier within your company.

"name": "support-workflow"

Rules:

Lowercase letters, numbers, hyphens
Unique within company
Stable (rarely change)

Forms graph type: acme-corp.support-workflow::1.0.0

title

Human-readable name for console UI.

"title": "Support Workflow"

Keep under 50 characters.

description

Short description of what the graph does.

"description": "Customer support workflow with knowledge base search"

1-3 sentences, under 200 characters.

Optional Fields

icon

Emoji or URL for graph avatar.

"icon": "🤖"

Versioning

Configuration

{
  "versioning": {
    "strategy": "semver",
    "defaultVersion": "1.0.0",
    "supportedVersions": ["1.0.0", "1.1.0"]
  }
}

strategy: Always "semver"

defaultVersion: Version used when not specified by agent

supportedVersions: List of active versions

Example: Multiple Versions

{
  "versioning": {
    "defaultVersion": "2.0.0",
    "supportedVersions": ["1.5.0", "2.0.0", "2.1.0-beta"]
  },
  "versions": {
    "1.5.0": {
      "status": "deprecated",
      "visibility": "public",
      "changelog": "Migrate to 2.0.0 by June 1st"
    },
    "2.0.0": {
      "status": "stable",
      "visibility": "public",
      "changelog": "Complete redesign, 40% faster"
    },
    "2.1.0-beta": {
      "status": "beta",
      "visibility": "private",
      "changelog": "Testing new features"
    }
  }
}

Version Metadata

Each version needs metadata in versions object:

"versions": {
  "1.0.0": {
    "status": "stable",
    "visibility": "public",
    "changelog": "Initial release"
  }
}

status

Values: "stable", "beta", "deprecated"

stable - Production ready
beta - Testing, may change
deprecated - Scheduled for removal

visibility

Values: "private", "corporate", "public"

private - Visible only to creator (for testing)
corporate - Visible to all company admins
public - Visible to all Flutch users

changelog (optional)

What changed in this version:

"changelog": "Added French support, improved response time by 20%"

Complete Examples

Simple Single Version

{
  "companySlug": "acme",
  "name": "support-workflow",
  "title": "Support Workflow",
  "description": "Customer support with docs search",
  "versioning": {
    "strategy": "semver",
    "defaultVersion": "1.0.0",
    "supportedVersions": ["1.0.0"]
  },
  "versions": {
    "1.0.0": {
      "status": "stable",
      "visibility": "public"
    }
  }
}

Multiple Versions

{
  "companySlug": "techcorp",
  "name": "support-workflow",
  "title": "Support Workflow",
  "description": "Customer support with knowledge base",
  "icon": "🎧",
  "versioning": {
    "strategy": "semver",
    "defaultVersion": "2.0.0",
    "supportedVersions": ["1.5.0", "2.0.0", "2.1.0-beta"]
  },
  "versions": {
    "1.5.0": {
      "status": "deprecated",
      "visibility": "public",
      "changelog": "Legacy version. Migrate to 2.0.0 by May 1st"
    },
    "2.0.0": {
      "status": "stable",
      "visibility": "public",
      "changelog": "Complete redesign, 40% faster, multilingual"
    },
    "2.1.0-beta": {
      "status": "beta",
      "visibility": "private",
      "changelog": "Testing new knowledge base integration"
    }
  }
}

Validation

Validate before deploying:

flutch graph validate

Common Errors

Missing required fields:

Error: Missing required field 'companySlug'

Fix: Add all required fields

Invalid version format:

Error: Version '1.0' does not follow semver

Fix: Use MAJOR.MINOR.PATCH: 1.0.0

Version mismatch:

Error: defaultVersion '1.1.0' not in supportedVersions

Fix: Ensure defaultVersion is in supportedVersions

Missing metadata:

Error: Version '1.0.0' missing from versions object

Fix: Add entry in versions for each supportedVersions