Templates & Advanced Usage - Cloud Coding API

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:

Authentication: {"auth": "Authenticated Successfully!"}
Setup: Configuration and repository information
Executor: Agent conversation and tool usage
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

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

For Advanced Users

Custom Messages: Read the Custom Templates Guide for complete control
Workflow Patterns: Learn advanced patterns like tool selection and conversation flow
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.

Overview

Advanced

​Two Ways to Use Cloud Coding API

​1. Prebuilt Templates (Recommended for Getting Started)

​2. Custom Messages (Advanced Control)

​Using Prebuilt Templates

​Our Favorite: Plan and Execute Template

​Why Use Prebuilt Templates?

​Available Template Categories

​Custom Messages: Advanced Control

​Quick Custom Message Example

​Message Structure

​Why Use Custom Messages?

​Common Custom Message Patterns

​1. Simple Single Task

​2. Multi-Step Workflow

​3. Tool-Controlled Workflow

​5. Multi-Directory Workflow (Separate API Calls)

​Key Features

​Available Tools

​Working Directory Control

​Response Format

​When to Use Which Approach

​Use Prebuilt Templates When:

​Use Custom Messages When:

​Next Steps

​For Beginners

​For Advanced Users

​Common Parameters

​Model Selection Guide

​Getting Help

Pro Tip

Two Ways to Use Cloud Coding API

1. Prebuilt Templates (Recommended for Getting Started)

2. Custom Messages (Advanced Control)

Using Prebuilt Templates

Our Favorite: Plan and Execute Template

Why Use Prebuilt Templates?

Available Template Categories

Custom Messages: Advanced Control

Quick Custom Message Example

Message Structure

Why Use Custom Messages?

Common Custom Message Patterns

1. Simple Single Task

2. Multi-Step Workflow

3. Tool-Controlled Workflow

5. Multi-Directory Workflow (Separate API Calls)

Key Features

Available Tools

Working Directory Control

Response Format

When to Use Which Approach

Use Prebuilt Templates When:

Use Custom Messages When:

Next Steps

For Beginners

For Advanced Users

Common Parameters

Model Selection Guide

Getting Help