AI Branch: Safer Project Changes with AI Agents

This is a 10-part series sharing how Apidog developed Apidog CLI, a command-line tool for API testing and API lifecycle management. Read in order or jump to any post that interests you:

When an Agent modifies project resources, safety and reviewability matter. AI Branch provides an isolated editing environment—changes enter the target branch only after human confirmation.

The Security Challenge

When AI Agents participate in API development and testing, they can create, update, and delete project resources through CLI commands.

This power comes with risk.

How do you let Agents work on real projects without risking the main branch?

AI Branch: The Safety Layer

AI Branch is a special type of Sprint Branch designed specifically for external AI and CLI operations.

Key concept:

All edit operations initiated from Apidog CLI are treated as initiated by AI / AI Agents by default.

AI Branch provides AI Agents with an isolated editing branch. Changes stay in the AI Branch until a human reviews and merges them.

Agent makes changes via CLI
        ↓
Changes stored in AI Branch (isolated)
        ↓
User reviews differences
        ↓
User confirms resource scope
        ↓
Merge to target branch (direct or merge request)

The main branch stays untouched until you approve.

Why AI Branch Is Needed

AI-initiated edits can be unpredictable. Apidog CLI provides a wide range of editing capabilities—endpoints, schemas, test scenarios, test suites, and more.

AI Branch is designed for these higher-risk AI-initiated editing operations.

It allows AI Agents to edit project resources within a controlled scope:

What Is AI Branch?

AI Branch is a special sprint branch with specific characteristics:

Key Characteristics

How It Works

Normal in-client editing by users still follows project member permissions and branch protection rules.

Use Cases

AI Branch is suitable when AI needs to participate in project maintenance while preserving branch isolation and human confirmation.

Basic Workflow

A typical AI Branch workflow:

┌─────────────────────────────────────────────────────────────────┐
│                     AI BRANCH WORKFLOW                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Step 1: Create AI Branch                                        │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog branch create --type ai             │                  │
│  │ --name "ai/20260312-from-main-feature"     │                  │
│  │ --from main                                │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Step 2: Import or Create Resources                              │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog branch pick-to (import existing)    │                  │
│  │ OR                                         │                  │
│  │ apidog endpoint create (create new)        │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Step 3: AI Modifies Resources                                   │
│  ┌───────────────────────────────────────────┐                  │
│  │ Agent uses CLI to update endpoints,       │                  │
│  │ schemas, test scenarios, etc.             │                  │
│  │ (--branch parameter specifies AI Branch)  │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Step 4: User Reviews Differences                                │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog merge-request preview              │                  │
│  │ OR                                         │                  │
│  │ View in Apidog client                     │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Step 5: Merge to Target Branch                                  │
│  ┌───────────────────────────────────────────┐                  │
│  │ Direct merge (unprotected branch)         │                  │
│  │ OR                                         │                  │
│  │ Merge request (protected branch)          │                  │
│  └───────────────────────────────────────────┘                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Create an AI Branch

Use branch create --type ai:

apidog branch create \
  --project 123456 \
  --type ai \
  --name "ai/20260312-from-main-userRegister" \
  --from main

Naming recommendation: ai/YYYYMMDD-from-sourceBranch-featureOrModule

Edit Resources in an AI Branch

When CLI writes project resources, use --branch parameter to write into AI Branch:

Recommended workflow:

# 1. Get schema
apidog cli-schema get endpoint-create

# 2. Validate before writing
apidog cli-schema validate endpoint-create --file ./endpoint.json

# 3. Write to AI Branch (not main)
apidog endpoint create \
  --project 123456 \
  --branch "ai/20260312-from-main-userRegister" \
  --file ./endpoint.json

Import Existing Resources

To modify existing resources, import them from source branch first:

apidog branch pick-to \
  --project 123456 \
  --from main \
  --to "ai/20260312-from-main-userRegister" \
  --endpoint-ids 1001,1002

This ensures AI works with the correct base version.

Review Changes Before Merge

Before merging, preview differences:

apidog merge-request preview \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main

Or view complete diff in Apidog client.

Merge an AI Branch

After review, merge changes:

Direct Merge (Unprotected Branch)

apidog branch merge \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --endpoint-ids 1001,1002

Merge Request (Protected Branch)

apidog merge-request create \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --reviewer-ids 20001,20002 \
  --endpoint-ids 1001,1002

Important: Merge commands process only explicitly provided resource list. Confirm dependencies (directories, models, response components, tests) before merging.

Archive and Delete

After changes are merged or no longer needed:

# Archive
apidog branch archive "ai/20260312-from-main-userRegister" \
  --project 123456 --type ai

# Delete (after archiving)
apidog branch delete "ai/20260312-from-main-userRegister" \
  --project 123456 --type ai

External AI Edit Permissions

By default, CLI writes to AI Branch. This keeps AI-generated changes isolated until user confirmation.

To enable direct editing of main branch:

Project Settings → Feature Settings → AI Feature Settings → External AI Edit Permissions

Recommendation: Keep AI Branch isolation enabled. Enable direct edit only when automation workflows clearly need it.

Best Practices

AI Branch in the CLI + SKILL Workflow

AI Branch integrates naturally with CLI + SKILL:

Every write goes through AI Branch → human review → merge.

Security Summary

Together, these layers create a safer loop for Agent-driven project changes.

What's Next

With AI Branch providing the safety layer, all the pieces are in place:

• MCP for tool connection (Part 1)
• CLI + SKILL for workflow execution (Parts 2-5)
• Validation results (Part 6)
• Practical workflows (Part 7)
• CI/CD foundation (Part 8)
• AI Branch for safety (Part 9)

Now it's time for the vision.

In Part 10, Spec-First Was Yesterday. Welcome to Skill-First., we'll outline how API development evolves with AI Agents—and what teams should do next.

Key Takeaways

• AI Branch provides isolated editing for AI/CLI operations
• Changes don't affect main branch until human confirmation
• Create with branch create --type ai, write with --branch parameter
• Import existing resources with branch pick-to before editing
• Preview with merge-request preview, then merge or create merge request
• Direct edit permissions can bypass AI Branch—use carefully
• Best practice: one AI Branch per task, validate before write, review before merge

Download Apidog to design, mock, test, and document APIs in one workspace. Learn more about Apidog CLI for command-line API testing, CI automation, and AI Agent workflows.