All edit operations initiated from Apidog CLI are treated as initiated by AI / AI Agents by default.AI Branch is designed to provide AI Agents with an isolated editing branch in Apidog projects. With AI Branch, AI can create and update project resources without directly changing the main branch or a standard sprint branch. After the changes are complete, users can review the differences in the client or CLI, then merge the results into the target branch directly or through a merge request.Why AI Branch Is Needed#
AI-initiated edits can be unpredictable, while Apidog CLI provides a wide range of editing capabilities. AI Branch is designed for these higher-risk AI-initiated editing operations, allowing AI Agents to edit project resources within a controlled scope.You can also upgrade to Apidog 2.8.31 or later and enable direct edit permissions for the main branch, standard sprint branches, and general branches as needed under Project Settings -> Feature Settings -> External AI Edit Permissions. Once enabled, these permissions bypass the direct-edit restrictions that normally require AI Branch.What Is AI Branch?#
AI Branch is a special sprint branch. Like a standard sprint branch, it stores changes to project resources. However, it is intended by default for external AI operations, such as CLI-based edits, and keeps a human confirmation step before changes are merged.Key characteristics of AI Branch include:1.
Isolated editing: Changes made from the CLI to resources such as APIs, documentation, data models, and test scenarios are stored in the AI Branch and do not directly affect the main branch or the source branch.
2.
Clear source: AI Branches cannot be created directly in the Apidog client. They must be created from a CLI or MCP source. An AI Branch records its source branch and is usually merged back into that source branch, making it easier to understand the context of AI-generated changes.
3.
Human confirmation: Changes in an AI Branch must be confirmed by a user before they are merged. Users can review differences, select the resource scope, and choose whether to merge directly or create a merge request.
4.
No quantity limit: There is currently no active limit on the number of AI Branches that can be created. AI Agents can use them to process data by business domain, iteration, or feature.
5.
Automatic archiving: To prevent uncontrolled growth of AI Branches during project collaboration, each AI Branch is compared with its source branch every 24 hours. If no differences are found, it is automatically archived. You can restore archived AI Branches in Apidog at any time, or recreate new AI Branches from Apidog CLI, without any limit.
AI Branch is used to store write results from external AI or CLI operations. Normal in-client editing, merging, and review by users still follow project member permissions and branch protection rules.
Use Cases#
AI Branch is suitable when AI needs to participate in project resource maintenance while branch isolation and human confirmation must still be preserved.| Scenario | Description |
|---|
| Generate API drafts from code | After reading the code, AI creates or updates HTTP API endpoints in an AI Branch. Users confirm the changes before merging. |
| Organize API resources in bulk | AI can adjust API directories, add descriptions, and update data models or response components without directly affecting the current collaboration branch. |
| Generate automated test drafts | AI can create test scenarios, test cases, or test data in an AI Branch for later confirmation by testers. |
| Fill gaps in API documentation | AI can supplement missing fields based on bug reports, API implementations, or OpenAPI files. |
| Batch write in CI/CD | Automated workflows can write generated results into an AI Branch and wait for user review before merging. |
Basic Workflow#
A typical AI Branch workflow is as follows:1
Create an AI Branch and specify the source branch it is based on.
2
Import the resources that need to be edited into the AI Branch, or create new resources in the AI Branch.
3
An AI Agent, CLI, or automation script modifies resources in the AI Branch.
4
The user reviews the differences between the AI Branch and the source branch, then confirms the resource scope to be merged.
5
Depending on the target branch protection rules, merge directly or create a merge request.
Create an AI Branch#
Use branch create --type ai to create an AI Branch. The legacy sprint-branch and sb entry points remain compatible, but the unified branch entry point is recommended.| Command | Description | Example |
|---|
branch create --type ai | Create an AI Branch. | apidog branch create --project <projectId> --type ai --name "ai/20260312-from-main-userRegister" --from main |
branch list --type ai | View AI Branches in a project. | apidog branch list --project <projectId> --type ai |
branch list --type all | View all branch types in a project. | apidog branch list --project <projectId> --type all |
branch get --type ai | View details of a specified AI Branch, including its branch type and source information. | apidog branch get <branchName> --project <projectId> --type ai |
Example: Create an AI Branch for the user registration APIWe recommend naming AI Branches in the format ai/YYYYMMDD-from-sourceBranch-featureOrModule, for example, ai/20260312-from-main-userRegister. A clear name helps the team understand the branch source, purpose, and creation time.
Edit Resources in an AI Branch#
When the CLI writes project resources, you can use branch parameters to write those resources into an AI Branch. Parameters vary slightly across resource commands. Before use, check the corresponding command help and JSON Schema.| Resource Type | Common Commands | Example |
|---|
| HTTP API endpoint | endpoint create, endpoint update | apidog endpoint create --project <projectId> --branch <aiBranchName> --file ./endpoint.json |
| Data model | schema create, schema update | apidog schema update <schemaId> --project <projectId> --branch <aiBranchName> --file ./schema.json |
| Markdown document | doc create, doc update | apidog doc create --project <projectId> --branch <aiBranchName> --file ./doc.json |
| Test scenario | test-scenario create, test-scenario update | apidog test-scenario update <scenarioId> --project <projectId> --branch <aiBranchName> --file ./scenario.json |
| Test suite | test-suite create, test-suite update | apidog test-suite create --project <projectId> --branch <aiBranchName> --file ./suite.json |
| Test data | test-data create, test-data update | apidog test-data create --project <projectId> --branch <aiBranchName> --file ./test-data.json |
When creating or updating complex resources, we recommend using cli-schema first to view and validate the data structure.Import Resources from the Source Branch#
If an AI Branch needs to modify existing resources, use branch pick-to first to import resources from the source branch into the AI Branch. After import, AI can continue editing those resources in the AI Branch.| Command | Description | Example |
|---|
branch pick-to | Import resources from a source branch into a target AI Branch. | apidog branch pick-to --project <projectId> --from <sourceBranchName> --to <aiBranchName> --endpoint-ids <ids> |
Example: Import endpoints and let AI modify thempick-to imports only the resources explicitly specified in the command. If directories, data models, response components, or other related resources are required, confirm the resource scope before importing.
View AI Branch Changes#
Before merging, we recommend previewing the candidate changes between the AI Branch and the target branch. The CLI can use merge-request preview to scan currently supported resource types. You can also view more complete branch differences in the client.| Command | Description | Example |
|---|
merge-request preview | Scan candidate changes to confirm the resource scope before merging. | apidog merge-request preview --project <projectId> --from <aiBranchName> --to <targetBranchName> |
branch get --type ai | View basic AI Branch information. | apidog branch get <aiBranchName> --project <projectId> --type ai |
Example: Preview candidate changes before mergingmerge-request preview scans candidate differences for resource types currently supported by the CLI. It is not a complete resource diff. Before the final merge, we still recommend confirming important resource content in the client.
Merge an AI Branch#
After the AI Branch changes are complete, you can merge them back into the source branch or another target branch. For unprotected target branches, use branch merge to merge directly. For protected main branches, use merge-request create to create a merge request and go through the review process.| Command | Description | Example |
|---|
branch merge | Directly merge specified resources from an AI Branch. | apidog branch merge --project <projectId> --from <aiBranchName> --to <targetBranchName> --endpoint-ids <ids> |
merge-request create | Create a merge request. | apidog merge-request create --project <projectId> --from <aiBranchName> --to <targetBranchName> --reviewer-ids <userIds> --endpoint-ids <ids> |
merge-request approve | Approve a merge request. | apidog merge-request approve <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./approve.json |
merge-request reject | Reject a merge request. | apidog merge-request reject <mergeRequestId> --project <projectId> --to <targetBranchName> |
Example: Directly merge endpoint changesExample: Create a merge requestBoth direct merge and merge requests merge only the explicitly provided resource list. They do not automatically include referenced resources or directory resources. When defining the merge scope, confirm dependencies among endpoints, directories, data models, response components, and test resources.
Archive and Delete an AI Branch#
After an AI Branch is merged or no longer needed, you can archive it first and then delete it. Before deletion, confirm that the changes in the branch have been merged or are no longer required.| Command | Description | Example |
|---|
branch archive --type ai | Archive an AI Branch. | apidog branch archive <aiBranchName> --project <projectId> --type ai |
branch delete --type ai | Delete an archived AI Branch. | apidog branch delete <aiBranchName> --project <projectId> --type ai |
External AI Edit Permissions#
By default, the CLI recommends writing project resources through AI Branch. This allows AI-generated changes to enter an isolated branch first and be merged only after user confirmation.If you want external AI or CLI operations to directly edit the main branch, standard sprint branches, or general branches, enable the corresponding permissions in the client:Project Settings - Feature Settings - AI Feature Settings - External AI Edit Permissions
| Permission | Description |
|---|
| Main branch direct edit permission | Allows external AI or CLI operations to directly write to the main branch. |
| Standard sprint branch direct edit permission | Allows external AI or CLI operations to directly write to standard sprint branches. |
| General branch direct edit permission | Allows external AI or CLI operations to directly write to general branches. |
| AI Branch direct edit permission | Allows external AI or CLI operations to write to AI Branches created and maintained by AI. This is usually kept enabled. |
To protect project resources, we recommend having external AI or CLI operations write to an AI Branch first and merge only after user confirmation. Enable direct edit permissions only when an automation workflow clearly needs to modify the target branch directly.
Best Practices#
1.
Create one AI Branch per task: Each AI Branch should correspond to a clear task, such as completing the user registration API, organizing order module documentation, or generating payment test scenarios.
2.
Import before editing: When modifying existing resources, use pick-to to import them first, then update them in the AI Branch to avoid confusion about the source.
3.
Preview differences before merging: Use merge-request preview or the client diff view to confirm resource content and dependencies.
4.
Explicitly select the merge scope: Merge commands process only the provided resource list. For related resources such as API directories, data models, response components, and test cases, confirm them together.
5.
Keep human review: AI-generated API definitions, test scripts, and data models should be reviewed by project members before merging.
6.
Archive branches promptly: AI Branches that have been merged or abandoned should be archived promptly to keep the branch list clear.
FAQ#
AI Branch is a special sprint branch mainly used to store write results from external AI, CLI operations, or automation scripts. It records the source branch and encourages users to confirm differences before merging. Standard sprint branches are usually used for day-to-day collaboration among team members.
No. Changes in an AI Branch are saved in that AI Branch first. Related resources enter the target branch only after a user performs a direct merge or creates and approves a merge request.
In an Apidog project, go to Project Settings - Feature Settings - AI Feature Settings - External AI Edit Permissions, then enable direct edit permissions for the main branch, standard sprint branches, or general branches as needed. After these permissions are enabled, external AI or CLI operations can directly write within the corresponding branch scope.
No. Both branch merge and merge-request create are executed according to the explicitly provided resource list. If endpoints reference data models, response components, directories, or test resources, confirm and add the corresponding resource scope before merging.
No. Deletion is not mandatory. We recommend archiving the branch after confirming that its changes have been merged or are no longer needed, and then deciding whether to delete it according to your team's conventions to avoid long-term accumulation of historical branches.
