Templates & Advanced Usage

Using prebuilt templates and creating custom message workflows

Prerequisite: Ensure you’ve completed the Quickstart and have your API keys configured.

Two Ways to Use Cloud Coding API

The Cloud Coding API offers two powerful approaches to automate your development workflow:

1. Prebuilt Templates (Recommended for Getting Started)

Ready-to-use templates for common development tasks. Perfect for quick automation without configuration.

2. Custom Messages (Advanced Control)

Script your AI agent’s exact behavior with custom conversation flows, tool selection, and workflow control.

Using Prebuilt Templates

The fastest way to get started is with our prebuilt templates. These are battle-tested workflows for common development tasks.

Our Favorite: Plan and Execute Template

Template ID: a2ef2e64-40e2-4c6a-99fc-767e3a30a963

This template breaks down complex tasks into manageable steps by first creating a detailed plan, then executing it systematically.

curl -X POST "https://api.cloudcoding.ai/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CLOUDCODING_API_KEY" \
  -d '{
    "template_id": "a2ef2e64-40e2-4c6a-99fc-767e3a30a963",
    "variables": {
      "task": "Add user authentication with JWT tokens to this React application"
    },
    "repo_url": "https://github.com/username/my-app",
    "github_token": "'$GITHUB_TOKEN'",
    "branch": "feature/auth",
    "haiku": false
  }'

Why Use Prebuilt Templates?

• ⚡ Fast Setup: No configuration needed - just provide variables
• 🧪 Battle-Tested: Proven workflows used by thousands of developers
• 📝 Smart Planning: Templates like Plan & Execute break complex tasks into steps
• 🔄 Consistent Results: Standardized approaches to common problems
• 🎯 Best Practices: Built-in industry standards and conventions

Available Template Categories

Category	Use Cases	Examples
Planning & Analysis	Code review, architecture planning	Plan & Execute, Code Audit
Feature Development	Adding new functionality	Component Creation, API Development
Code Quality	Testing, documentation, refactoring	Test Generation, Doc Writing
DevOps & Deployment	CI/CD, containerization	Docker Setup, Pipeline Creation

Browse all available templates in the Templates Library or use our Plan and Execute template for most complex tasks.

Custom Messages: Advanced Control

When you need complete control over the AI agent’s behavior, custom messages let you script exact workflows.

Quick Custom Message Example

curl -X POST "https://api.cloudcoding.ai/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CLOUDCODING_API_KEY" \
  -d '{
    "messages": [
      {
        "tools": "all",
        "content": "Add comprehensive error handling to all API endpoints"
      }
    ],
    "repo_url": "https://github.com/username/repo",
    "github_token": "'$GITHUB_TOKEN'",
    "branch": "main",
    "haiku": true
  }'

Message Structure

Each message in the messages array supports these fields:

Field	Type	Required	Description
content	string	✅ Yes	The instruction/prompt for the AI agent
tools	string/array	❌ No	Available tools: "all" or specific tool names
continueConversation	boolean	❌ No	Continue previous conversation context
workingDir	string	❌ No	Custom working directory for this message

Why Use Custom Messages?

• 🎯 Complete Control: Script exact conversation flows and agent behavior
• 🔧 Tool Selection: Choose specific tools for each step of your workflow
• 📁 Directory Focus: Limit the agent’s scope to specific repository parts
• 🔄 Conversation Flow: Continue previous contexts or start fresh sessions

Common Custom Message Patterns

1. Simple Single Task

Perfect for focused development tasks:

curl -X POST "https://api.cloudcoding.ai/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CLOUDCODING_API_KEY" \
  -d '{
    "messages": [
      {
        "tools": "all",
        "content": "Add a dark mode toggle to this React application"
      }
    ],
    "repo_url": "https://github.com/username/my-app",
    "github_token": "'$GITHUB_TOKEN'",
    "branch": "feature/dark-mode",
    "haiku": true
  }'

2. Multi-Step Workflow

Chain related tasks with conversation continuity:

curl -X POST "https://api.cloudcoding.ai/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CLOUDCODING_API_KEY" \
  -d '{
    "messages": [
      {
        "tools": "all",
        "content": "Analyze the authentication system and identify improvements"
      },
      {
        "tools": "all",
        "content": "Implement the improvements you identified",
        "continueConversation": true
      },
      {
        "tools": "all",
        "content": "Add tests for the updated system",
        "continueConversation": true
      }
    ],
    "repo_url": "https://github.com/username/secure-app",
    "github_token": "'$GITHUB_TOKEN'",
    "branch": "security/auth-improvements",
    "haiku": false
  }'

3. Tool-Controlled Workflow

Control exactly which tools are used:

curl -X POST "https://api.cloudcoding.ai/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CLOUDCODING_API_KEY" \
  -d '{
    "messages": [
      {
        "tools": ["Read", "LS", "Grep"],
        "content": "Explore and understand the project structure"
      },
      {
        "tools": ["Edit", "Write"],
        "content": "Refactor based on your analysis",
        "continueConversation": true
      },
      {
        "tools": ["Bash"],
        "content": "Run tests to verify changes",
        "continueConversation": true
      }
    ],
    "repo_url": "https://github.com/username/react-app",
    "github_token": "'$GITHUB_TOKEN'",
    "branch": "refactor/components",
    "haiku": true
  }'

5. Multi-Directory Workflow (Separate API Calls)

Critical Limitation: You cannot change workingDir and use continueConversation: true in the same request. Each directory change requires a separate API call with a fresh conversation.

Work across different parts of your repository using separate API calls:

# ❌ INCORRECT - This example will NOT work as expected
# The continueConversation with different workingDir will fail
curl -X POST "https://api.cloudcoding.ai/invoke" \
  -d '{
    "messages": [
      {
        "tools": "all",
        "content": "Migrate components to TypeScript",
        "workingDir": "./src/components"
      },
      {
        "tools": "all",
        "content": "Now update hooks",
        "workingDir": "./src/hooks",
        "continueConversation": true  // ❌ This will not work!
      }
    ]
  }'

# ✅ CORRECT - Use separate API calls for each directory
# First call - Components
curl -X POST "https://api.cloudcoding.ai/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CLOUDCODING_API_KEY" \
  -d '{
    "messages": [
      {
        "tools": "all",
        "content": "Migrate all components to TypeScript with proper type definitions",
        "workingDir": "./src/components"
      }
    ],
    "repo_url": "https://github.com/username/typescript-migration",
    "github_token": "'$GITHUB_TOKEN'",
    "branch": "migration/typescript",
    "haiku": false
  }'

# Second call - Hooks
curl -X POST "https://api.cloudcoding.ai/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CLOUDCODING_API_KEY" \
  -d '{
    "messages": [
      {
        "tools": "all",
        "content": "Update the hooks to use TypeScript interfaces",
        "workingDir": "./src/hooks"
      }
    ],
    "repo_url": "https://github.com/username/typescript-migration",
    "github_token": "'$GITHUB_TOKEN'",
    "branch": "migration/typescript",
    "haiku": false
  }'

# Third call - API Layer
curl -X POST "https://api.cloudcoding.ai/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CLOUDCODING_API_KEY" \
  -d '{
    "messages": [
      {
        "tools": "all",
        "content": "Update the API layer with TypeScript types",
        "workingDir": "./src/api"
      }
    ],
    "repo_url": "https://github.com/username/typescript-migration",
    "github_token": "'$GITHUB_TOKEN'",
    "branch": "migration/typescript",
    "haiku": false
  }'

Key Features

Available Tools

You can control which tools the AI agent uses:

Tool Category	Examples	Use Cases
File Operations	Read, Edit, Write, MultiEdit	Code modification and creation
Navigation	LS, Glob, Grep	Project exploration and search
Execution	Bash	Running tests, builds, commands
Planning	Task	Breaking down complex work
External	WebFetch, WebSearch	Research and documentation
All Tools	"all"	Full capabilities (recommended)

Working Directory Control

The workingDir field allows you to focus the AI agent on specific parts of your repository:

{
  "workingDir": "./src/components",
  "content": "Refactor all React components to use TypeScript"
}

Important Limitation: When changing the workingDir, you cannot use continueConversation: true. Each directory change requires starting a fresh conversation. The AI agent gets mounted to the specified directory and cannot maintain context across different working directories.

Common Use Cases:

• Focus on specific modules or directories
• Large codebase organization
• Component-by-component refactoring
• Gradual migration workflows
• Targeted testing and validation

Correct Usage Pattern:

# ❌ INCORRECT - This will not work as expected
{
  "messages": [
    {
      "workingDir": "./src/components",
      "content": "Analyze React components"
    },
    {
      "workingDir": "./src/utils",
      "content": "Now analyze utils",
      "continueConversation": true  // ❌ Will not work with directory change
    }
  ]
}

# ✅ CORRECT - Each directory gets its own conversation
{
  "messages": [
    {
      "workingDir": "./src/components",
      "content": "Analyze and refactor React components"
    }
  ]
}

Response Format

The API returns Server-Sent Events (SSE) with these event types:

1. Authentication: {"auth": "Authenticated Successfully!"}
2. Setup: Configuration and repository information
3. Executor: Agent conversation and tool usage
4. Push: Final commit and push status

When to Use Which Approach

Use Prebuilt Templates When:

• ✅ You want to get started quickly
• ✅ Your task fits a common pattern (planning, testing, deployment)
• ✅ You prefer battle-tested workflows
• ✅ You’re new to the Cloud Coding API

Recommended: Start with the Plan and Execute template (a2ef2e64-40e2-4c6a-99fc-767e3a30a963) for complex tasks.

Use Custom Messages When:

• ✅ You need precise control over AI behavior
• ✅ Your workflow doesn’t match existing templates
• ✅ You want to specify exact tools for each step
• ✅ You need conversation continuity across steps

Next Steps

For Beginners

1. Browse Templates: Check the Templates Library for ready-to-use workflows
2. Try Plan & Execute: Use template a2ef2e64-40e2-4c6a-99fc-767e3a30a963 for your first complex task
3. Learn Variables: Understand how to customize templates with variables

For Advanced Users

1. Custom Messages: Read the Custom Templates Guide for complete control
2. Workflow Patterns: Learn advanced patterns like tool selection and conversation flow
3. Integration: Build custom integrations using the API

Common Parameters

Parameter	Description	Example
repo_url	GitHub repository URL	"https://github.com/user/repo"
github_token	GitHub access token	"ghp_xxxxxxxxxxxx"
branch	Target branch	"main" or "feature/new-component"
haiku	Model selection	true (fast) or false (powerful)

Model Selection Guide

• Haiku ("haiku": true): Fast, cost-effective for simple tasks
• Sonnet ("haiku": false): More powerful for complex reasoning and large codebases

Getting Help

• 📚 Templates: Browse the Templates Library for prebuilt workflows
• 🛠️ Custom Messages: Read the Custom Templates Guide for advanced control
• 💬 Support: Contact our team for help with complex use cases

Pro Tip

Start with the Plan and Execute template (a2ef2e64-40e2-4c6a-99fc-767e3a30a963) for your first complex task. It breaks down work into manageable steps automatically.

Assistant

Responses are generated using AI and may contain mistakes.