Branches

Uma branch é um ponteiro nomeado para um commit. Cada branch mantém seu próprio draft (rascunho) e HEAD (último commit publicado).

Objeto Branch

{
  "id": "b2c3d4e5f6a1",
  "assistant_id": "a1b2c3d4e5f6",
  "name": "main",
  "head_commit_id": "c3d4e5f6a1b2",
  "created_at": "2026-03-24T10:00:00Z",
  "updated_at": "2026-03-24T10:05:00Z"
}

Campo	Descrição
`id`	Identificador único da branch
`name`	Nome da branch (ex: `main`, `feature/nova-saudacao`)
`head_commit_id`	Último commit publicado. `null` se nunca foi publicado.

Branch main

Todo assistente começa com uma branch main. Esta é a branch de produção — o endpoint GET /assistants/{id}/runtime sempre lê o HEAD da main.

A branch main não pode ser deletada.

Ciclo de vida

Criar branch → Editar draft → Publicar → (Merge na main)
                    ↑              │
                    └── continuar ─┘

1. Criar

Ao criar uma branch, o draft é inicializado com o conteúdo do HEAD da main. Você pode criar a partir de um nome:

POST /assistants/{id}/branches
{ "name": "feature/nova-saudacao" }

2. Fork

Se quiser copiar o draft de uma branch existente (incluindo mudanças não publicadas):

POST /assistants/{id}/branches/{branch_name}/fork
{ "name": "experiment/variacao-a" }

3. Publicar

Transforma o draft atual em um commit imutável e avança o HEAD:

POST /assistants/{id}/branches/{branch_name}/publish
{
  "message": "Melhorou a saudação inicial",
  "author_type": "human"
}

4. Merge

Para levar as mudanças de uma branch para outra (tipicamente para a main):

POST /assistants/{id}/branches/{target_branch_name}/merge
{
  "source_branch_name": "feature_branch_name",
  "commit": true
}

O merge faz uma comparação 3-way (ancestor, source, target) e aplica as mudanças no draft da branch de destino. Se commit for true, publica automaticamente após o merge.

Se ambas as branches modificaram o mesmo path, o merge retorna um erro 409 Conflict com a lista de paths em conflito. Resolva os conflitos manualmente editando o draft antes de tentar novamente.

5. Rollback

Para reverter o HEAD para um commit anterior:

POST /assistants/{id}/branches/{branch_name}/rollback
{ "commit_id": "commit_anterior_id" }

O rollback atualiza o HEAD e reseta o draft para o estado daquele commit.

Verificando mudanças

Antes de publicar, verifique se há mudanças pendentes no draft:

GET /assistants/{id}/branches/{branch_name}/changes
→ { "has_changes": true }

Para ver o diff detalhado entre o draft e o HEAD:

GET /assistants/{id}/branches/{branch_name}/diff
→ { "diffs": [...] }

Relacionados

Drafts — como editar o conteúdo de uma branch
API de Branches — referência completa dos endpoints

Branches

On this page