API Shipped · contrato em movimento
A mesma superfície que o console usa
Não existe uma segunda implementação atrás do console ou da CLI: os dois falam com esta. O que também significa que ela se move quando o produto se move, e esta página é cuidadosa com o que promete.
$ curl -s https://dash.commitcycle.com/v1/acme/web/tasks -H "authorization: Bearer $CC_TOKEN" -H "content-type: application/json" -d '{"title":"Export times out on large boards","requested_by":"support@acme.dev"}'
HTTP 201
{ "task": { "id": "CC-58", "state": "Triage",
"title": "Export times out on large boards", … } }
# one line, in Triage — scoping it is the next step, not this one
O intake é um POST com um título e uma credencial do board, então uma pequena ponte que você mesmo escreva pode registrar trabalho a partir do que você usa hoje.
O que é estável
POST /v1/<tenant>/<repo>/tasks
{ "title": "uma linha", "requested_by": "voce@exemplo.com" }- Um board é um par. Cada rota é delimitada por path —
/v1/<tenant>/<repo>/…— e um board é esse par, nada mais. - O intake é uma linha. Um título cai em Triage. Um pedido que não foi delimitado não é trabalho em andamento, aqui como em todo lugar.
- O estado quem muda é o gate. A rota de scoping descarta em silêncio um campo
state, então nada consegue iniciar trabalho escrevendo nele por fora.
O que ainda se move
A referência completa de payloads está registrada e não escrita, e essa ordem é deliberada, não um descuido de backlog: as formas ainda estão se movendo, e documentar um contrato em movimento produz documentação que mente. O que existe está marcado como pendente; o que está acima é o que se sustentou.
Se você vai construir em cima disso agora, o handshake de versão é a primeira parte a ligar: um cliente desatualizado é avisado em uma linha, em vez de descobrir depois como um desacordo de regras.
Onde ela para
- Ela não é o caminho do enforcement. O hook nunca chama a rede para decidir, então uma queda da API não abre uma zone — ela nunca esteve no caminho da negação.
- Ela não lê o seu branch. Um close exige um change manifest:
cycle verify --closeo constrói na máquina onde está o branch, e a API o recebe. O único diff que o board lê por conta própria é a lista de arquivos de um pull request mergeado, vinda do GitHub, onde a App dele está instalada (CC-1346, CC-1352).
As rotas como estão hoje ficam na referência da API (em inglês). Para quase tudo, a CLI e o servidor MCP são o caminho mais curto.
Perguntas que esta página responde
A API do CommitCycle é estável o suficiente para construir em cima?
O endereçamento e o intake são: um board é um par tenant/repo, e POST /tasks com um título cai em Triage. Os payloads mais ricos ainda se movem com as fases, então tudo além disso está documentado como pendente em vez de publicado e depois quebrado.