Skip to main content
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: 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

CategoryUse CasesExamples
Planning & AnalysisCode review, architecture planningPlan & Execute, Code Audit
Feature DevelopmentAdding new functionalityComponent Creation, API Development
Code QualityTesting, documentation, refactoringTest Generation, Doc Writing
DevOps & DeploymentCI/CD, containerizationDocker 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:
FieldTypeRequiredDescription
contentstring✅ YesThe instruction/prompt for the AI agent
toolsstring/array❌ NoAvailable tools: "all" or specific tool names
continueConversationboolean❌ NoContinue previous conversation context
workingDirstring❌ NoCustom 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 CategoryExamplesUse Cases
File OperationsRead, Edit, Write, MultiEditCode modification and creation
NavigationLS, Glob, GrepProject exploration and search
ExecutionBashRunning tests, builds, commands
PlanningTaskBreaking down complex work
ExternalWebFetch, WebSearchResearch 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

ParameterDescriptionExample
repo_urlGitHub repository URL"https://github.com/user/repo"
github_tokenGitHub access token"ghp_xxxxxxxxxxxx"
branchTarget branch"main" or "feature/new-component"
haikuModel selectiontrue (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.