### Clone Hatchify Repository and Install Dependencies (Bash)

Source: https://github.com/sider-ai/hatchify/blob/master/README.md

This snippet demonstrates how to clone the Hatchify project from GitHub and install its Python dependencies using uv. It's a prerequisite for setting up the development environment.

```bash
git clone https://github.com/Sider-ai/hatchify.git
cd hatchify

# Install dependencies (recommended using uv)
uv sync
```

--------------------------------

### Environment Variable Override Examples (Bash)

Source: https://github.com/sider-ai/hatchify/blob/master/README.md

Demonstrates how to override YAML configurations using environment variables with the `HATCHIFY__` prefix. This allows for dynamic configuration changes, especially in production environments.

```bash
# Override server port
export HATCHIFY__SERVER__PORT=8080

# Override base_url (use in production deployment)
export HATCHIFY__SERVER__BASE_URL=https://your-domain.com

# Override database platform
export HATCHIFY__DB__PLATFORM=postgresql
```

--------------------------------

### Manage Hatchify Docker Container (Bash)

Source: https://github.com/sider-ai/hatchify/blob/master/README.md

Common Docker commands for managing the Hatchify container, including viewing logs, stopping, starting, restarting, and removing the container.

```bash
# View Logs
# Real-time log viewing
docker logs -f hatchify

# View last 100 lines
docker logs --tail 100 hatchify

# Container Management
# Stop container
docker stop hatchify

# Start container
docker start hatchify

# Restart container
docker restart hatchify

# Remove container
docker rm -f hatchify
```

--------------------------------

### Get Webhook Information and Schema

Source: https://context7.com/sider-ai/hatchify/llms.txt

Retrieves the input/output schema and configuration details for a graph's webhook.

```APIDOC
## GET /api/web-hooks/webhook-info/{graph_id}

### Description
Retrieves webhook input/output schema and configuration for a specified graph.

### Method
GET

### Endpoint
`/api/web-hooks/webhook-info/{graph_id}`

### Parameters
#### Path Parameters
- **graph_id** (string) - Required - The ID of the graph to get webhook information for.

### Response
#### Success Response (200)
- **data** (object) - Webhook information and schema details.
  - **graph_id** (string) - The ID of the graph.
  - **input_type** (string) - The expected content type for webhook input (e.g., "application/json").
  - **data_fields** (array of strings) - List of expected data field names in the input.
  - **file_fields** (array of strings) - List of expected file field names in the input.
  - **input_schema** (object) - JSON schema describing the expected input.
  - **output_schema** (object) - JSON schema describing the expected output.
- **message** (string) - Confirmation message, e.g., "ok".

### Response Example
```json
{
  "code": 200,
  "data": {
    "graph_id": "graph456",
    "input_type": "application/json",
    "data_fields": ["text", "language"],
    "file_fields": [],
    "input_schema": {
      "type": "object",
      "properties": {
        "text": {"type": "string", "description": "Text to analyze"},
        "language": {"type": "string", "enum": ["en", "es", "fr"]}
      },
      "required": ["text"]
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "sentiment": {"type": "string"},
        "confidence": {"type": "number"}
      }
    }
  },
  "message": "ok"
}
```
```

--------------------------------

### Configure MCP Tool Servers - SSE Transport (TOML)

Source: https://github.com/sider-ai/hatchify/blob/master/README.md

Configures an MCP tool server using the 'sse' (Server-Sent Events) transport protocol. This setup requires a URL for the SSE endpoint and includes options for authentication headers and read timeouts.

```toml
[[servers]]
name = "calculator-sse"
transport = "sse"
enabled = true
url = "http://localhost:8000/sse"
prefix = "calc"
timeout = 5
sse_read_timeout = 300

[servers.headers]
Authorization = "Bearer your-token"
```

--------------------------------

### Get Webhook Information and Schema

Source: https://context7.com/sider-ai/hatchify/llms.txt

Retrieves the input and output schema for a graph's webhook, including expected data fields, file fields, and JSON schema definitions. This is essential for correctly interacting with the webhook.

```bash
# Retrieve webhook input/output schema for a graph
curl -X GET "http://localhost:8000/api/web-hooks/webhook-info/graph456" \
  -H "Content-Type: application/json"
```

--------------------------------

### Get Graph Details by ID (Bash)

Source: https://context7.com/sider-ai/hatchify/llms.txt

This endpoint retrieves the full configuration details for a specific graph workflow, identified by its unique ID. It returns information such as the graph's name, description, current specification, version ID, and timestamps.

```bash
# Retrieve a specific graph configuration
curl -X GET "http://localhost:8000/api/graphs/get_by_id/graph456" \
  -H "Content-Type: application/json"

# Response:
{
  "code": 200,
  "data": {
    "id": "graph456",
    "name": "Sentiment Analysis Workflow",
    "description": "Analyzes sentiment and generates reports",
    "current_spec": {
      "name": "Sentiment Analysis Workflow",
      "agents": [
        {
          "name": "sentiment_analyzer",
          "category": "general",
          "model": "gpt-4o",
          "instruction": "Analyze the sentiment of the provided text",
          "tools": ["text_analysis"],
          "structured_output_schema": {
            "type": "object",
            "properties": {
              "sentiment": {"type": "string"},
              "confidence": {"type": "number"}
            }
          }
        }
      ],
      "entry_point": "sentiment_analyzer",
      "nodes": ["sentiment_analyzer", "report_generator"],
      "edges": [{"from_node": "sentiment_analyzer", "to_node": "report_generator"}]
    },
    "current_version_id": 1,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  },
  "message": "ok"
```

--------------------------------

### Build and Run Hatchify Docker Image (Bash)

Source: https://github.com/sider-ai/hatchify/blob/master/README.md

Instructions for building a Docker image for Hatchify and running it as a container. This includes port mapping, volume mounting for persistent data and configuration, and explanations of the parameters.

```bash
# 1. Build Image
docker build -t hatchify .

# 2. Start Container
# Run in background with port mapping and volume mounting
docker run -itd \
  --name=hatchify \
  -p 8000:8000 \
  -v ./data:/app/data \
  -v ./resources:/app/resources \
  hatchify
```

--------------------------------

### Get Web Builder Chat History

Source: https://context7.com/sider-ai/hatchify/llms.txt

Retrieves the conversation history for a specific web builder session associated with a graph ID. This GET request allows users to review past interactions and generated content. The response includes messages from both the user and the assistant.

```bash
curl -X GET "http://localhost:8000/api/web-builder/history/graph456" \
  -H "Content-Type: application/json"
```

--------------------------------

### Get Execution Details by ID

Source: https://context7.com/sider-ai/hatchify/llms.txt

Retrieves the details of a specific execution record using its unique identifier.

```APIDOC
## GET /api/executions/get_by_id/{executionId}

### Description
Retrieves the detailed information for a specific execution record identified by its unique ID.

### Method
GET

### Endpoint
/api/executions/get_by_id/{executionId}

### Path Parameters
- **executionId** (string) - Required - The unique identifier of the execution record to retrieve.

### Response
#### Success Response (200)
- **code** (integer) - The HTTP status code (200).
- **data** (object) - Contains the details of the execution record.
  - **id** (string) - The unique identifier for the execution.
  - **graph_id** (string) - The ID of the graph associated with the execution.
  - **session_id** (string) - The ID of the session associated with the execution.
  - **execution_type** (string) - The type of execution (e.g., "WEBHOOK", "GRAPH_BUILDER").
  - **status** (string) - The current status of the execution (e.g., "completed").
  - **error_message** (string | null) - Any error message associated with the execution.
  - **created_at** (string) - The timestamp when the execution was created (ISO 8601 format).
  - **started_at** (string) - The timestamp when the execution started (ISO 8601 format).
  - **completed_at** (string) - The timestamp when the execution was completed (ISO 8601 format).
- **message** (string) - A confirmation message (e.g., "ok").

#### Response Example
```json
{
  "code": 200,
  "data": {
    "id": "exec_webhook_999",
    "graph_id": "graph456",
    "session_id": "graph456",
    "execution_type": "WEBHOOK",
    "status": "completed",
    "error_message": null,
    "created_at": "2025-01-15T13:00:00Z",
    "started_at": "2025-01-15T13:00:01Z",
    "completed_at": "2025-01-15T13:00:15Z"
  },
  "message": "ok"
}
```
```

--------------------------------

### Launch Hatchify Development Server (Bash)

Source: https://github.com/sider-ai/hatchify/blob/master/README.md

Commands to launch the Hatchify application in development mode using uvicorn or by running the main Python script. Access the API documentation at http://localhost:8000/docs.

```bash
# Development mode
uvicorn hatchify.launch.launch:app --reload --host 0.0.0.0 --port 8000

# Or use main.py
python main.py
```

--------------------------------

### Configure MCP Servers Programmatically (Python)

Source: https://context7.com/sider-ai/hatchify/llms.txt

Demonstrates programmatic configuration of Model Context Protocol (MCP) servers using various transport methods: stdio, SSE, and StreamableHTTP. This allows for flexible integration with different server implementations.

```python
from hatchify.common.domain.entity.mcp_card import MCPCard, MCPTransportConfig

# Stdio transport (local process)
mcp_filesystem = MCPCard(
    name="filesystem",
    transport="stdio",
    enabled=True,
    config=MCPTransportConfig(
        command="npx",
        args=["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
        cwd="/tmp",
        env={"NODE_ENV": "production"}
    ),
    prefix="fs",
    tool_filters={
        "allowed": ["read_file", "write_file", "list_directory"]
    }
)

# SSE transport (server-sent events)
mcp_calculator = MCPCard(
    name="calculator",
    transport="sse",
    enabled=True,
    config=MCPTransportConfig(
        url="http://localhost:8000/sse",
        timeout=5,
        sse_read_timeout=300,
        headers={"Authorization": "Bearer token123"}
    ),
    prefix="calc"
)

# StreamableHTTP transport
mcp_weather = MCPCard(
    name="weather",
    transport="streamablehttp",
    enabled=True,
    config=MCPTransportConfig(
        url="http://localhost:8001/mcp/",
        timeout=30,
        terminate_on_close=True
    ),
    prefix="weather"
)
```

--------------------------------

### Get Paginated Execution Records

Source: https://context7.com/sider-ai/hatchify/llms.txt

Retrieves a paginated list of execution records, allowing for sorting by creation date.

```APIDOC
## GET /api/executions/page

### Description
Retrieves a paginated list of execution records. Supports filtering by page number, size, and sorting by creation date in ascending or descending order.

### Method
GET

### Endpoint
/api/executions/page

### Query Parameters
- **page** (integer) - Required - The page number to retrieve.
- **size** (integer) - Required - The number of records per page.
- **sort** (string) - Optional - The field to sort by. Use a hyphen prefix for descending order (e.g., `-created_at`).

### Response
#### Success Response (200)
- **code** (integer) - The HTTP status code (200).
- **data** (object) - Contains the pagination details and items.
  - **items** (array) - An array of execution record objects.
    - **id** (string) - The unique identifier for the execution.
    - **graph_id** (string) - The ID of the graph associated with the execution.
    - **session_id** (string) - The ID of the session associated with the execution.
    - **execution_type** (string) - The type of execution (e.g., "WEBHOOK", "GRAPH_BUILDER").
    - **status** (string) - The current status of the execution (e.g., "completed").
    - **created_at** (string) - The timestamp when the execution was created (ISO 8601 format).
    - **completed_at** (string, optional) - The timestamp when the execution was completed (ISO 8601 format).
  - **total** (integer) - The total number of records available.
  - **page** (integer) - The current page number.
  - **size** (integer) - The number of records per page.
- **message** (string) - A confirmation message (e.g., "ok").

#### Response Example
```json
{
  "code": 200,
  "data": {
    "items": [
      {
        "id": "exec_webhook_999",
        "graph_id": "graph456",
        "session_id": "graph456",
        "execution_type": "WEBHOOK",
        "status": "completed",
        "created_at": "2025-01-15T13:00:00Z",
        "completed_at": "2025-01-15T13:00:15Z"
      },
      {
        "id": "exec789",
        "graph_id": "graph456",
        "session_id": "abc123def456",
        "execution_type": "GRAPH_BUILDER",
        "status": "completed",
        "created_at": "2025-01-15T10:30:00Z"
      }
    ],
    "total": 150,
    "page": 1,
    "size": 20
  },
  "message": "ok"
}
```
```

--------------------------------

### Web Builder - Get Chat History

Source: https://context7.com/sider-ai/hatchify/llms.txt

Retrieves the conversation history for a specific Web Builder session associated with a graph.

```APIDOC
## GET /api/web-builder/history/{graphId}

### Description
Fetches the complete conversation history for a Web Builder session linked to a specific graph ID. This allows users to review past interactions and the generated responses.

### Method
GET

### Endpoint
/api/web-builder/history/{graphId}

### Path Parameters
- **graphId** (string) - Required - The unique identifier of the graph whose Web Builder session history is to be retrieved.

### Response
#### Success Response (200)
- **code** (integer) - The HTTP status code (200).
- **data** (array) - An array of message objects representing the conversation history.
  - **id** (string) - The unique identifier for the message.
  - **session_id** (string) - The ID of the session the message belongs to.
  - **role** (string) - The role of the speaker ('user' or 'assistant').
  - **content** (array) - The content of the message, typically containing text.
    - **type** (string) - The type of content (e.g., "text").
    - **text** (string) - The actual text content of the message.
  - **created_at** (string) - The timestamp when the message was created (ISO 8601 format).
- **message** (string) - A confirmation message (e.g., "ok").

#### Response Example
```json
{
  "code": 200,
  "data": [
    {
      "id": "msg_001",
      "session_id": "graph456",
      "role": "user",
      "content": [{"type": "text", "text": "Create a modern landing page with dark theme"}],
      "created_at": "2025-01-15T14:00:00Z"
    },
    {
      "id": "msg_002",
      "session_id": "graph456",
      "role": "assistant",
      "content": [{"type": "text", "text": "I'll create a modern landing page..."}],
      "created_at": "2025-01-15T14:00:05Z"
    }
  ],
  "message": "ok"
}
```
```

--------------------------------

### Storage Configuration in YAML

Source: https://github.com/sider-ai/hatchify/blob/master/README.md

Sets up storage using OpenDAL, specifying the schema, bucket, folder, and root directory. Supports various schemas like 'fs', 's3', and 'oss'.

```yaml
storage:
  platform: opendal
  opendal:
    schema: fs
    bucket: hatchify
    folder: dev
    root: ./data/storage
```

--------------------------------

### Configure Model and MCP Server (TOML)

Source: https://github.com/sider-ai/hatchify/blob/master/README.md

These TOML snippets show how to configure model providers (e.g., OpenAI) and Model Context Protocol (MCP) servers. This is crucial for enabling Hatchify to interact with different LLMs and external services.

```toml
# Copy configuration files
cp resources/example.mcp.toml resources/mcp.toml
cp resources/example.models.toml resources/models.toml

# Edit model configuration (resources/models.toml)
[[models]]
name = "gpt-4o"
provider = "openai"
api_key = "your-api-key-here"
api_base = "https://api.openai.com/v1"

# Edit MCP server configuration (resources/mcp.toml) (optional)
[[servers]]
name = "filesystem"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"]
```

--------------------------------

### Get Graph Details

Source: https://context7.com/sider-ai/hatchify/llms.txt

Retrieves detailed information about a specific graph, including its ID, name, description, and update timestamp. This is useful for verifying graph existence and current state.

```json
{
  "code": 200,
  "data": {
    "id": "graph456",
    "name": "Advanced Sentiment Analysis",
    "description": "Enhanced sentiment analysis with multi-language support",
    "current_version_id": null,
    "updated_at": "2025-01-15T11:45:00Z"
  },
  "message": "ok"
}
```

--------------------------------

### Deploy Web Application

Source: https://context7.com/sider-ai/hatchify/llms.txt

Deploys the web application generated by the Web Builder. This POST request accepts a JSON payload with 'graph_id' and a 'rebuild' flag. It initiates the deployment process and returns execution details.

```bash
curl -X POST "http://localhost:8000/api/web-builder/deploy" \
  -H "Content-Type: application/json" \
  -d '{ "graph_id": "graph456", "rebuild": true }'
```

--------------------------------

### Server Configuration in YAML

Source: https://github.com/sider-ai/hatchify/blob/master/README.md

Defines the server's host, port, and base URL. The `base_url` is critical for production deployments and webhook callbacks.

```yaml
hatchify:
  server:
    host: 0.0.0.0
    port: 8000
    base_url: http://localhost:8000  # ⚠️ Must change to public URL in production
```

--------------------------------

### Get Graph Details by ID

Source: https://context7.com/sider-ai/hatchify/llms.txt

Retrieve the detailed configuration of a specific graph using its unique ID. This endpoint provides information about the graph's specification, including agents, nodes, and edges.

```APIDOC
## GET /api/graphs/get_by_id/{graph_id}

### Description
Retrieve a specific graph configuration by its ID. This endpoint returns the full details of a graph, including its specification, version, and timestamps.

### Method
GET

### Endpoint
`/api/graphs/get_by_id/{graph_id}`

### Parameters
#### Path Parameters
- **graph_id** (string) - Required - The unique identifier of the graph to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The graph's unique identifier.
- **name** (string) - The name of the graph.
- **description** (string) - A description of the graph.
- **current_spec** (object) - The current specification of the graph, including agents, entry point, nodes, and edges.
- **current_version_id** (integer) - The ID of the current version of the graph specification.
- **created_at** (string) - Timestamp when the graph was created (ISO 8601 format).
- **updated_at** (string) - Timestamp when the graph was last updated (ISO 8601 format).

#### Response Example
```json
{
  "code": 200,
  "data": {
    "id": "graph456",
    "name": "Sentiment Analysis Workflow",
    "description": "Analyzes sentiment and generates reports",
    "current_spec": {
      "name": "Sentiment Analysis Workflow",
      "agents": [
        {
          "name": "sentiment_analyzer",
          "category": "general",
          "model": "gpt-4o",
          "instruction": "Analyze the sentiment of the provided text",
          "tools": ["text_analysis"],
          "structured_output_schema": {
            "type": "object",
            "properties": {
              "sentiment": {"type": "string"},
              "confidence": {"type": "number"}
            }
          }
        }
      ],
      "entry_point": "sentiment_analyzer",
      "nodes": ["sentiment_analyzer", "report_generator"],
      "edges": [{"from_node": "sentiment_analyzer", "to_node": "report_generator"}]
    },
    "current_version_id": 1,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  },
  "message": "ok"
}
```
```

--------------------------------

### Web Builder Configuration in YAML

Source: https://github.com/sider-ai/hatchify/blob/master/README.md

Defines settings for the web application builder, including the repository URL, branch, workspace, initialization steps (with environment variable injection), and security configurations (allowed and sensitive paths).

```yaml
web_app_builder:
  repo_url: https://github.com/Sider-ai/hatchify-web-app-template.git
  branch: master
  workspace: ./data/workspace

  init_steps:
    - type: env
      file: .env
      vars:
        VITE_API_BASE_URL: "{{base_url}}"
        VITE_GRAPH_ID: "{{graph_id}}"
        VITE_BASE_PATH: "/preview/{{graph_id}}"

  security:
    allowed_directories:
      - ./data/workspace
      - /tmp
    sensitive_paths:
      - ~/.ssh
      - ~/.aws
      - /etc/passwd
      - /root
```

--------------------------------

### Get Specific Execution Record by ID

Source: https://context7.com/sider-ai/hatchify/llms.txt

Fetches the details of a single execution record using its unique ID. This is helpful for inspecting the complete state and results of a specific past operation. The execution ID is part of the URL path.

```bash
curl -X GET "http://localhost:8000/api/executions/get_by_id/exec_webhook_999" \
  -H "Content-Type: application/json"
```

--------------------------------

### List All Graphs with Pagination (Bash)

Source: https://context7.com/sider-ai/hatchify/llms.txt

This endpoint provides a paginated list of all available graph workflows. Users can specify the page number, the number of items per page, and sorting parameters (e.g., by creation date in descending order). The response includes the items, total count, current page, page size, and total number of pages.

```bash
# Get paginated list of all graphs
curl -X GET "http://localhost:8000/api/graphs/page?page=1&size=10&sort=-created_at" \
  -H "Content-Type: application/json"

# Response:
{
  "code": 200,
  "data": {
    "items": [
      {
        "id": "graph456",
        "name": "Sentiment Analysis Workflow",
        "description": "Analyzes sentiment and generates reports",
        "created_at": "2025-01-15T10:30:00Z"
      },
      {
        "id": "graph789",
        "name": "Content Generation Pipeline",
        "description": "Multi-step content creation workflow",
        "created_at": "2025-01-14T15:20:00Z"
      }
    ],
    "total": 25,
    "page": 1,
    "size": 10,
    "pages": 3
  },
  "message": "ok"
```

--------------------------------

### Configure MCP Tool Servers - Stdio Transport (TOML)

Source: https://github.com/sider-ai/hatchify/blob/master/README.md

Configures an MCP (Model Context Protocol) tool server using the 'stdio' transport protocol, suitable for local processes. It specifies the command to run the server, arguments, working directory, environment variables, and tool filters.

```toml
[[servers]]
name = "filesystem"
transport = "stdio"
enabled = true
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
prefix = "fs"  # Tool name prefix

# Optional configuration
cwd = "/tmp"
encoding = "utf-8"

[servers.env]
NODE_ENV = "production"

[servers.tool_filters]
allowed = ["read_file", "write_file"]  # Whitelist
```

--------------------------------

### Database Configuration in YAML (SQLite)

Source: https://github.com/sider-ai/hatchify/blob/master/README.md

Configures the database connection, currently supporting only SQLite. Includes driver, file path, and echo settings. Future releases will support PostgreSQL and MySQL.

```yaml
db:
  platform: sqlite
  sqlite:
    driver: sqlite+aiosqlite
    file: ./data/dev.db
    echo: False
    pool_pre_ping: True
```

--------------------------------

### Web Builder - Deploy Web Application

Source: https://context7.com/sider-ai/hatchify/llms.txt

Deploys the web application generated by the Web Builder and streams deployment logs.

```APIDOC
## POST /api/web-builder/deploy

### Description
Deploys the web application associated with a specific graph ID. This endpoint can trigger a rebuild of the application before deployment.

### Method
POST

### Endpoint
/api/web-builder/deploy

### Request Body
- **graph_id** (string) - Required - The unique identifier of the graph whose application should be deployed.
- **rebuild** (boolean) - Required - A flag indicating whether to rebuild the application before deployment.

### Request Example
```json
{
  "graph_id": "graph456",
  "rebuild": true
}
```

### Response
#### Success Response (200)
- **code** (integer) - The HTTP status code (200).
- **data** (object) - Contains identifiers related to the deployment process.
  - **graph_id** (string) - The ID of the graph for which the application was deployed.
  - **session_id** (string) - The ID of the session associated with the deployment.
  - **execution_id** (string) - The unique identifier for the deployment execution.
- **message** (string) - A confirmation message (e.g., "ok").

#### Response Example
```json
{
  "code": 200,
  "data": {
    "graph_id": "graph456",
    "session_id": "graph456",
    "execution_id": "exec_deploy_001"
  },
  "message": "ok"
}
```

## GET /api/web-builder/deploy/{executionId}

### Description
Streams the logs and status updates of a Web Builder deployment process using Server-Sent Events (SSE). Clients can monitor the build and deployment progress in real-time.

### Method
GET

### Endpoint
/api/web-builder/deploy/{executionId}

### Path Parameters
- **executionId** (string) - Required - The ID of the deployment execution to stream logs for.

### Response
#### Success Response (200)
- The response is a stream of Server-Sent Events (SSE).
  - **event: build_log** - Contains log messages during the build process.
    - **data**: `{"message": "<log_message_text>"}`
  - **event: deployed** - Indicates that the application has been deployed.
    - **data**: `{"url": "<deployment_url>", "status": "<deployment_status>"}` (e.g., "success", "failed")

#### Response Example (SSE Stream)
```
event: build_log
data: {"message": "Installing dependencies..."}

event: build_log
data: {"message": "Building React application..."}

event: deployed
data: {"url": "http://localhost:8000/preview/graph456", "status": "success"}
```

### Accessing the Deployed App
- The deployed application can typically be accessed at `http://localhost:8000/preview/{graph_id}/`.
```

--------------------------------

### Get Paginated Execution Records

Source: https://context7.com/sider-ai/hatchify/llms.txt

Retrieves a paginated list of execution records, sorted by creation date in descending order. This endpoint is useful for tracking past operations and their statuses. It requires 'page' and 'size' query parameters for pagination and an optional 'sort' parameter.

```bash
curl -X GET "http://localhost:8000/api/executions/page?page=1&size=20&sort=-created_at" \
  -H "Content-Type: application/json"
```

--------------------------------

### Python: Build Graph Programmatically

Source: https://context7.com/sider-ai/hatchify/llms.txt

Demonstrates how to programmatically build and execute a graph using Hatchify's Python SDK.

```APIDOC
## Python SDK: Graph Building

### Description
This example shows how to define a `GraphSpec` with agents and edges, build it using `DynamicGraphBuilder`, and then execute it asynchronously.

### Method
N/A (SDK Usage)

### Endpoint
N/A (SDK Usage)

### Parameters
N/A (SDK Usage)

### Request Example
```python
from hatchify.common.domain.entity.graph_spec import GraphSpec, Edge
from hatchify.common.domain.entity.agent_node_spec import AgentNode
from hatchify.core.graph.dynamic_graph_builder import DynamicGraphBuilder
from hatchify.core.manager.tool_manager import tool_factory
from hatchify.core.manager.function_manager import function_router
from hatchify.core.factory.session_manager_factory import create_session_manager
from hatchify.common.domain.entity.graph_execute_data import GraphExecuteData

# Define graph specification
graph_spec = GraphSpec(
    name="Content Pipeline",
    description="Multi-step content generation workflow",
    agents=[
        AgentNode(
            name="researcher",
            category="general",
            model="gpt-4o",
            instruction="Research the given topic and provide key points",
            tools=["web_search", "wikipedia"],
            structured_output_schema={
                "type": "object",
                "properties": {
                    "key_points": {"type": "array", "items": {"type": "string"}},
                    "sources": {"type": "array", "items": {"type": "string"}}
                }
            }
        ),
        AgentNode(
            name="writer",
            category="general",
            model="claude-sonnet-4-5-20250929",
            instruction="Write engaging content based on research",
            tools=[],
            structured_output_schema={
                "type": "object",
                "properties": {
                    "content": {"type": "string"},
                    "word_count": {"type": "integer"}
                }
            }
        )
    ],
    nodes=["researcher", "writer"],
    edges=[
        Edge(from_node="researcher", to_node="writer")
    ],
    entry_point="researcher",
    input_schema={
        "type": "object",
        "properties": {
            "topic": {"type": "string", "description": "Topic to research"}
        },
        "required": ["topic"]
    },
    output_schema={
        "type": "object",
        "required": ["writer"],
        "properties": {
            "writer": {"type": "object"}
        }
    }
)

# Build executable graph
builder = DynamicGraphBuilder(
    tool_router=tool_factory,
    function_router=function_router,
    session_manager=create_session_manager(graph_id="content_pipeline", session_id="session_123")
)

graph = builder.build_graph(graph_spec)

# Execute graph
execute_data = GraphExecuteData(
    jsons={"topic": "Quantum Computing Applications"},
    files={}
)

result = await graph.invoke_async(execute_data)

# Access results
researcher_output = result.results["researcher"].result.structured_output
writer_output = result.results["writer"].result.structured_output

print(f"Research: {researcher_output.key_points}")
print(f"Content: {writer_output.content}")
```

### Response
N/A (SDK Usage)

#### Response Example
N/A (SDK Usage)
```

--------------------------------

### Create Graph Version Snapshot

Source: https://context7.com/sider-ai/hatchify/llms.txt

Creates a snapshot of the current graph version, enabling rollback capabilities. A comment can be added to describe the snapshot. This is crucial for version control and recovery.

```bash
# Create a version snapshot for rollback capability
curl -X POST "http://localhost:8000/api/graphs/graph456/snapshot?comment=Stable%20version%20before%20major%20changes" \
  -H "Content-Type: application/json"
```

--------------------------------

### List Available Tools

Source: https://context7.com/sider-ai/hatchify/llms.txt

Retrieves a list of all registered tools, including both built-in (MCP) and custom tools. This endpoint is essential for understanding the available functionalities that can be integrated into workflows or called by the AI.

```bash
curl -X GET "http://localhost:8000/api/tools/all" \
  -H "Content-Type: application/json"
```

--------------------------------

### API: Query Sessions

Source: https://context7.com/sider-ai/hatchify/llms.txt

Demonstrates how to query paginated session lists with filters using a `curl` command. It specifies the HTTP method, URL with parameters for pagination and filtering, and sets the content type.

```bash
# Get paginated session list with filters
curl -X GET "http://localhost:8000/api/sessions/page?page=1&size=10&graph_id=graph456&scene=GRAPH_BUILDER" \
  -H "Content-Type: application/json"
```

--------------------------------

### List Available Tools

Source: https://context7.com/sider-ai/hatchify/llms.txt

Retrieves a list of all registered tools, including both Model-Centric Platform (MCP) tools and custom-developed tools.

```APIDOC
## GET /api/tools/all

### Description
Fetches a list of all tools that are registered within the system. This includes tools provided by the Model-Centric Platform (MCP) as well as any custom tools that have been integrated.

### Method
GET

### Endpoint
/api/tools/all

### Response
#### Success Response (200)
- **code** (integer) - The HTTP status code (200).
- **data** (array) - An array of tool objects. The exact structure of tool objects might vary, but typically includes identifiers and descriptions.
- **message** (string) - A confirmation message (e.g., "ok").

#### Response Example
```json
{
  "code": 200,
  "data": [
    {
      "id": "tool_calculator_basic",
      "name": "Basic Calculator",
      "description": "Performs basic arithmetic operations."
    },
    {
      "id": "tool_custom_api_fetcher",
      "name": "Custom API Fetcher",
      "description": "Fetches data from an external custom API."
    }
  ],
  "message": "ok"
}
```
```

--------------------------------

### Configure LLM Providers (TOML)

Source: https://github.com/sider-ai/hatchify/blob/master/README.md

Defines configurations for various Large Language Model (LLM) providers such as OpenAI and Anthropic. Supports multiple providers, priority-based fallback, and individual model enabling/disabling. This TOML file is crucial for setting up unified model management.

```toml
default_provider = "openai-like"

[providers.openai]
id = "openai"
name = "OpenAI"
family = "openai"
base_url = "https://api.openai.com/v1"
api_key = "sk-xxx"
enabled = true
priority = 3  # Priority, lower number = higher priority

[[providers.openai.models]]
id = "gpt-4o"
name = "gpt-4o"
max_tokens = 16384
context_window = 128000
description = "..."

[providers.anthropic]
id = "anthropic"
family = "anthropic"
base_url = "https://api.anthropic.com"
api_key = "sk-ant-xxx"
enabled = true
priority = 4

[[providers.anthropic.models]]
id = "claude-sonnet-4-5-20250929"
max_tokens = 64000
context_window = 200000
```

--------------------------------

### Configure Hatchify with Environment Variables in Docker (Bash)

Source: https://github.com/sider-ai/hatchify/blob/master/README.md

Demonstrates how to override Hatchify's configuration using environment variables when running the Docker container. This is useful for dynamic configuration in different deployment environments.

```bash
docker run -itd \
  --name=hatchify \
  -p 8000:8000 \
  -e HATCHIFY__SERVER__BASE_URL=https://your-domain.com \
  -e HATCHIFY__SERVER__PORT=8000 \
  -v ./data:/app/data \
  -v ./resources:/app/resources \
  hatchify
```

--------------------------------

### Create Web Builder Conversational Session

Source: https://context7.com/sider-ai/hatchify/llms.txt

Initiates a new conversational session for the Web Builder, allowing users to describe the desired web application. This POST request takes a JSON payload with 'graph_id', 'message', and 'redeploy' options. It returns session and execution IDs for subsequent interactions.

```bash
curl -X POST "http://localhost:8000/api/web-builder/stream" \
  -H "Content-Type: application/json" \
  -d '{ "graph_id": "graph456", "message": "Create a modern landing page with a dark theme and gradient background", "redeploy": false }'
```

--------------------------------

### Create Graph Version Snapshot

Source: https://context7.com/sider-ai/hatchify/llms.txt

Creates a snapshot of the current graph version for rollback purposes.

```APIDOC
## POST /api/graphs/{graph_id}/snapshot

### Description
Creates a version snapshot for rollback capability.

### Method
POST

### Endpoint
`/api/graphs/{graph_id}/snapshot`

### Parameters
#### Path Parameters
- **graph_id** (string) - Required - The ID of the graph for which to create a snapshot.

#### Query Parameters
- **comment** (string) - Optional - A comment describing the snapshot.

### Response
#### Success Response (200)
- **data** (object) - Snapshot details including ID, version number, comment, and creation timestamp.
  - **id** (integer) - The unique identifier for the snapshot.
  - **graph_id** (string) - The ID of the graph the snapshot belongs to.
  - **version_number** (integer) - The version number of the snapshot.
  - **spec** (object) - The graph specification at the time of the snapshot.
  - **comment** (string) - The comment provided for the snapshot.
  - **branch_session_id** (string) - The session ID for the branch.
  - **created_at** (string) - ISO 8601 timestamp of when the snapshot was created.
- **message** (string) - Confirmation message, e.g., "ok".

### Response Example
```json
{
  "code": 200,
  "data": {
    "id": 5,
    "graph_id": "graph456",
    "version_number": 5,
    "spec": {
      "name": "Advanced Sentiment Analysis",
      "agents": [...],
      "entry_point": "sentiment_analyzer"
    },
    "comment": "Stable version before major changes",
    "branch_session_id": "session_branch_123",
    "created_at": "2025-01-15T12:00:00Z"
  },
  "message": "ok"
}
```
```

--------------------------------

### System Information API

Source: https://github.com/sider-ai/hatchify/blob/master/README.md

Endpoints to retrieve information about available tools and models.

```APIDOC
## System

### GET /api/tools

#### Description
List available tools.

### GET /api/models

#### Description
List available models.
```

--------------------------------

### Web Builder API

Source: https://github.com/sider-ai/hatchify/blob/master/README.md

Endpoints for the Web Builder feature, including session creation, conversational building, and deployment.

```APIDOC
## Web Builder

### POST /api/web_builder/create

#### Description
Create Web Builder session.

### POST /api/web_builder/chat

#### Description
Conversational building.

### POST /api/web_builder/deploy

#### Description
Deploy generated web application.
```

--------------------------------

### Web Builder - Create Conversational Session

Source: https://context7.com/sider-ai/hatchify/llms.txt

Initiates a conversational session for the Web Builder to generate or modify web application components.

```APIDOC
## POST /api/web-builder/stream

### Description
Starts a new conversational session for the Web Builder. This endpoint is used to provide initial instructions for generating or modifying a web application based on a given graph ID.

### Method
POST

### Endpoint
/api/web-builder/stream

### Request Body
- **graph_id** (string) - Required - The unique identifier of the graph to associate with this session.
- **message** (string) - Required - The user's instruction or prompt for the web builder.
- **redeploy** (boolean) - Optional - A flag indicating whether to redeploy the application immediately after generation (defaults to false).

### Request Example
```json
{
  "graph_id": "graph456",
  "message": "Create a modern landing page with a dark theme and gradient background",
  "redeploy": false
}
```

### Response
#### Success Response (200)
- **code** (integer) - The HTTP status code (200).
- **data** (object) - Contains identifiers for the newly created session and execution.
  - **graph_id** (string) - The ID of the graph associated with the session.
  - **session_id** (string) - The unique identifier for the conversational session.
  - **execution_id** (string) - The unique identifier for the execution initiated by this request.
- **message** (string) - A confirmation message (e.g., "ok").

#### Response Example
```json
{
  "code": 200,
  "data": {
    "graph_id": "graph456",
    "session_id": "graph456",
    "execution_id": "exec_web_builder_001"
  },
  "message": "ok"
}
```

## GET /api/web-builder/stream/{executionId}

### Description
Streams the progress and output of a Web Builder conversational session using Server-Sent Events (SSE). This endpoint allows clients to receive real-time updates as the AI works on generating or modifying the web application.

### Method
GET

### Endpoint
/api/web-builder/stream/{executionId}

### Path Parameters
- **executionId** (string) - Required - The ID of the execution for which to stream updates.

### Response
#### Success Response (200)
- The response is a stream of Server-Sent Events (SSE).
  - **event: agent_message** - Contains messages from the AI agent.
    - **data**: `{"content": "<message_text>"}`
  - **event: file_modified** - Notifies about file modifications.
    - **data**: `{"file": "<file_path>", "operation": "<operation_type>"}` (e.g., "edit", "create", "delete")
  - **event: completed** - Indicates the completion of the session.
    - **data**: `{"status": "<status>", "files_changed": <count>}` (e.g., "success", "failed")

#### Response Example (SSE Stream)
```
event: agent_message
data: {"content": "I'll create a modern landing page with dark theme. Let me modify the components..."}

event: file_modified
data: {"file": "src/App.tsx", "operation": "edit"}

event: completed
data: {"status": "success", "files_changed": 3}
```
```

--------------------------------

### Python: Register Custom Tool

Source: https://context7.com/sider-ai/hatchify/llms.txt

Shows how to register a custom tool within the Hatchify ecosystem using Python.

```APIDOC
## Python SDK: Custom Tool Registration

### Description
This example demonstrates how to define a custom tool using Pydantic models for input and registering it with the `ToolRouter`.

### Method
N/A (SDK Usage)

### Endpoint
N/A (SDK Usage)

### Parameters
N/A (SDK Usage)

### Request Example
```python
from strands import tool, ToolContext
from hatchify.core.factory.tool_factory import ToolRouter
from pydantic import BaseModel

tool_router = ToolRouter()

class MyCustomToolInput(BaseModel):
    argument1: str
    argument2: int

@tool(input_schema=MyCustomToolInput)
def my_custom_tool(context: ToolContext, input_data: MyCustomToolInput):
    """A sample custom tool."""
    # Tool logic here
    print(f"Received: {input_data.argument1}, {input_data.argument2}")
    return {"status": "success"}

# Register the tool
tool_router.register(my_custom_tool)
```

### Response
N/A (SDK Usage)

#### Response Example
N/A (SDK Usage)
```

--------------------------------

### List Available Language Models

Source: https://context7.com/sider-ai/hatchify/llms.txt

Fetches a list of all configured Large Language Models (LLMs) available for use within the system. This endpoint provides model IDs, names, and descriptions, enabling users to select appropriate models for their tasks.

```bash
curl -X GET "http://localhost:8000/api/models/all" \
  -H "Content-Type: application/json"
```

--------------------------------

### Stream Deployment Logs (SSE)

Source: https://context7.com/sider-ai/hatchify/llms.txt

Streams Server-Sent Events (SSE) for the deployment process, providing real-time build logs and the final deployment URL upon success. This endpoint is crucial for monitoring the deployment status and accessing the deployed application.

```bash
curl -N "http://localhost:8000/api/web-builder/deploy/exec_deploy_001" \
  -H "Accept: text/event-stream"
```