> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudcoding.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates & Advanced Usage

> Using prebuilt templates and creating custom message workflows

<Info>
  **Prerequisite**: Ensure you've completed the [Quickstart](/quickstart) and have your API keys configured.
</Info>

## 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.

```bash theme={null}
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     |

<Info>
  Browse all available templates in the [Templates Library](/templates) or use our **Plan and Execute** template for most complex tasks.
</Info>

## 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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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)

<Warning>
  **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.
</Warning>

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

```bash theme={null}
# ❌ 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:

```json theme={null}
{
  "workingDir": "./src/components",
  "content": "Refactor all React components to use TypeScript"
}
```

<Warning>
  **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.
</Warning>

**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:**

```bash theme={null}
# ❌ 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](/templates) 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](/templates/overview) 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](/templates) for prebuilt workflows
* 🛠️ **Custom Messages**: Read the [Custom Templates Guide](/templates/overview) for advanced control
* 💬 **Support**: Contact our team for help with complex use cases

<Card title="Pro Tip" icon="lightbulb">
  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.
</Card>