Carregando Labs API Reference & Playground…
Carregando Labs API Reference & Playground…
A API RESTful do Labs fornece uma interface de alta performance e isolamento seguro por Workspace para gerenciar Projetos, Tarefas, Materiais, OKRs Estratégicos, Sprints, Decisões de Arquitetura (ADRs) e Webhooks em tempo real.
Criação, listagem com filtros por categoria e status, atualização de metadados, links externos e estatísticas agregadas.
Gestão completa de tarefas com transição rápida de status (backlog, in_progress, review, done), prioridades e responsáveis.
Alinhamento de objetivos e Key Results, cálculo dinâmico de progresso, metas vinculadas a KPIs e ciclos trimestrais.
Armazenamento de repositórios, documentações, links de Figma, credenciais e arquivos de referência dos projetos.
Ciclos de sprint padronizados de 14 dias, cálculo de velocity, métricas de throughput e acompanhamento de WIP.
Notificações HTTP push de eventos em tempo real com assinaturas criptográficas para automações em n8n, Make e Zapier.
Convenção de branches, Conventional Commits + Task Key, hook local e sincronização automática com GitHub/Bitbucket.
URL Base: https://labs.amarassist.com.br/api/v1
Formato: application/json
Charset: UTF-8| Status | Significado | Descrição |
|---|---|---|
| 200 OK | Sucesso | A requisição foi processada com êxito e os dados solicitados foram retornados no corpo da resposta. |
| 201 Created | Recurso Criado | Um novo registro (projeto, tarefa, material, OKR ou webhook) foi gerado e persistido. |
| 400 Bad Request | Requisição Inválida | O corpo da requisição está mal formatado ou viola as validações dos parâmetros. |
| 401 Unauthorized | Não Autorizado | Chave de API ausente, inválida ou revogada (Header X-API-Key). |
| 404 Not Found | Não Encontrado | O identificador ou slug do projeto/tarefa/OKR não existe no workspace do usuário. |
| 422 Unprocessable | Erro de Validação | Parâmetros obrigatórios ausentes ou em formato incompatível. |
| 500 Server Error | Erro Interno | Ocorreu uma falha inesperada durante a execução no servidor. |
A API do Labs impõe um limite de 60 requisições por minuto por chave/token para endpoints convencionais e 120 requisições por minuto para leituras em cache. Headers informativos de controle são retornados em cada chamada:
X-RateLimit-Limit: Limite total permitido na janela atualX-RateLimit-Remaining: Requisições restantes disponíveisRetry-After: Segundos para reestabelecimento em caso de código 429
Todas as chamadas à API RESTful do Labs são autenticadas via cabeçalho HTTP X-API-Key. Você pode utilizar a sua chave de API mestra do Labs ou um Personal Access Token (Sanctum) diretamente no header X-API-Key.
No painel administrativo do Labs, navegue até Configurações > Chaves de API para visualizar ou gerar sua chave mestra de integração.
Armazene a chave de forma segura no seu arquivo .env como LABS_API_KEY=sua_chave_aqui ou nas variáveis secretas do seu CI/CD.
Inclua o cabeçalho X-API-Key em todas as requisições HTTP enviadas para qualquer endpoint da API do Labs.
curl -X GET "https://labs.amarassist.com.br/api/v1/projects" \
-H "X-API-Key: YOUR_LABS_API_KEY" \
-H "Accept: application/json"
Clique no botão Autorizar no topo ou no painel direito de qualquer endpoint, cole sua chave X-API-Key e clique em Salvar. Todas as requisições enviadas no playground incluirão o header automaticamente!
O módulo de OKRs (Objectives and Key Results) do Labs conecta a visão macro do seu produto à execução diária dos times de desenvolvimento, garantindo foco em impacto de negócio e outcomes reais em vez de mero output de tarefas.
Declarações qualitativas, memoráveis e inspiradoras que definem para onde o produto ou workspace quer ir em um ciclo trimestral.
Métricas quantificáveis e mensuráveis que indicam de forma inequívoca se o objetivo está sendo alcançado com sucesso.
Projetos e entregas práticas no Kanban executados pelos desenvolvedores para mover os ponteiros dos Key Results.
| Modo | Comportamento | Endpoint / Atualização |
|---|---|---|
manual |
O percentual de 0 a 100% é definido e atualizado diretamente pelos líderes ou via API. | PATCH /api/v1/okrs/{id}/progress com payload {"progress": 75} |
tasks_linked |
Calculado automaticamente pela proporção de tarefas com status done associadas ao projeto. |
Sincronizado automaticamente a cada mudança de status no Kanban. |
kpis |
Calculado com base em valor inicial, valor atual e valor meta configurados no Key Result. | Progresso = (atual - inicial) / (meta - inicial) * 100%. |
Progresso dentro da expectativa do ciclo atual com alta probabilidade de atingimento.
Ritmo de entrega abaixo da velocidade esperada, demandando atenção do squad.
Meta crítica atrasada ou com impedimentos severos que exigem replanejamento.
Meta de 100% atingida ou superada com sucesso no ciclo.
curl -X PATCH "https://labs.amarassist.com.br/api/v1/okrs/1/progress" \
-H "X-API-Key: YOUR_LABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"progress": 85,
"status": "on_track",
"notes": "Lançamento da v1.2 concluído com 99.4% de testes passando."
}'O Labs MCP Server conecta assistentes de inteligência artificial diretamente à sua base de projetos e tarefas do Labs. Ferramentas como Antigravity, Claude Desktop e Cursor podem inspecionar repositórios, gerenciar tarefas e registrar atividades de forma autônoma.
Retorna a lista de todos os projetos cadastrados no workspace com status e estatísticas.
Recupera informações detalhadas, URLs externas (GitHub, Figma), tags e resumo de um projeto por slug.
Lista as tarefas do projeto com suporte a filtro por status (backlog, in_progress, review, done).
Cria uma nova tarefa técnica ou user story com título, descrição markdown e prioridade.
Move o card no Kanban atualizando seu status e disparando eventos em tempo real.
Acessa links de design, documentações de referência e credenciais associadas ao projeto.
Consulta as datas de início e término dos ciclos de sprint de 14 dias e suas metas.
Lê os Architectural Decision Records (ADRs) documentando decisões técnicas históricas.
{
"mcpServers": {
"labs": {
"command": "php",
"args": ["artisan", "mcp:serve"],
"env": {
"LABS_API_KEY": "YOUR_LABS_API_KEY",
"APP_URL": "https://labs.amarassist.com.br"
}
}
}
}Diretrizes técnicas, padrões de código limpo, convenções de testes e boas práticas de arquitetura adotadas no ecossistema do Labs.
Formatação rigorosa com regras Laravel opinativas. Execute vendor/bin/pint antes de qualquer pull request.
Todo endpoint deve ter testes de feature cobrindo casos de sucesso (200/201), autenticação (401) e validação (422).
Mudanças estruturais devem ser registradas em registros de decisão com contexto, opções avaliadas e consequências.
# 1. Executar bateria de testes com Pest
php artisan test
# 2. Corrigir formatação de código automaticamente
vendor/bin/pint
# 3. Gerar especificação OpenAPI estática para produção
php artisan documentator:generate
# 4. Validar segurança de dependências
composer auditMétricas ágeis e indicadores de entrega contínua baseados nos princípios do Kanban e Engenharia de Alta Performance.
Quantidade de itens concluídos (status done) por intervalo de tempo, mensurando a capacidade real do squad.
Tempo decorrido desde o momento em que o trabalho foi iniciado (in_progress) até sua conclusão e merge.
Restrição intencional da quantidade de tarefas em andamento simultâneo para combater context switching e destravar gargalos.
Convenção obrigatória de versionamento de código para toda a equipe de engenharia. Garante integração contínua, automação de ciclo de vida e cruzamento de dados em tempo real com as tarefas do Spark / Labs.
Cada tarefa no Spark possui uma Chave Canônica única composta pelo prefixo do projeto e os dígitos finais da UUID da tarefa:
Prefixo LABS para tarefas do ecossistema central.
Prefixo CORT para inteligência e agentes.
Prefixo CHEC para pagamentos e funis.
Prefixo MOBI para aplicativos Flutter / Native.
Toda branch deve ser criada a partir da main atualizada, seguindo estritamente a fórmula:
{tipo}/{TASK_KEY}-{descricao-curta-em-kebab-case}| Prefixo | Finalidade | Exemplo de Branch |
|---|---|---|
feat/ |
Nova funcionalidade de produto ou melhoria de tela | feat/LABS-3e2b9f78c78b-clickup-task-modal |
fix/ |
Correção de bug em desenvolvimento ou homologação | fix/LABS-3e2b9f78c78b-avatar-timeline-display |
hotfix/ |
Correção emergencial diretamente contra produção | hotfix/CHEC-12ab34cd56ef-pix-callback-timeout |
refactor/ |
Mudança interna no código sem alteração funcional | refactor/CORT-9a8b7c6d5e4f-extract-webhook-service |
test/ |
Criação ou refatoração de suítes de testes | test/LABS-3e2b9f78c78b-webhook-integration-tests |
chore/ |
Atualização de dependências, scripts de CI/CD ou docs | chore/LABS-3e2b9f78c78b-upgrade-vite-tailwind |
Os commits devem utilizar a convenção oficial com a chave da tarefa entre colchetes logo após o escopo:
# Formato Obrigatório:
tipo(escopo): [{TASK_KEY}] descrição clara em minúsculas
# Exemplos Práticos:
git commit -m "feat(kanban): [LABS-3e2b9f78c78b] implementar alternador de visualizacao clickup"
git commit -m "fix(activities): [LABS-3e2b9f78c78b] exibir avatar e autor correto nos eventos de tarefa"
git commit -m "refactor(projects): [LABS-3e2b9f78c78b] desacoplar webhook controller de providers externos"
git commit -m "test(projects): [LABS-3e2b9f78c78b] adicionar testes de ciclo de vida do webhook github"prepare-commit-msgInstale o hook abaixo no terminal do seu projeto. Ele extrai automaticamente a chave da tarefa da branch ativa e a injeta no seu commit, eliminando erros manuais:
cat << 'EOF' > .git/hooks/prepare-commit-msg
#!/bin/sh
BRANCH_NAME=$(git symbolic-ref --short HEAD 2>/dev/null)
TASK_KEY=$(echo "$BRANCH_NAME" | grep -o -E '[A-Z]{2,10}-([0-9a-fA-F]{6,12}|[0-9]+)' | head -n 1)
if [ -n "$TASK_KEY" ]; then
COMMIT_MSG_FILE=$1
COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
# Injeta a chave da tarefa automaticamente após o tipo(escopo):
if ! echo "$COMMIT_MSG" | grep -q "$TASK_KEY"; then
sed -i.bak -E "s/^([a-z]+(\([^)]+\))?):/\1: [$TASK_KEY]/" "$COMMIT_MSG_FILE" 2>/dev/null || true
rm -f "${COMMIT_MSG_FILE}.bak" 2>/dev/null || true
fi
fi
EOF
chmod +x .git/hooks/prepare-commit-msgAo configurar os webhooks nos repositórios, a sincronização é 100% automatizada e reflete instantaneamente no Kanban do Spark:
LABS-3e2b9f78c78b é identificada na branch ou título.# 1. Webhook GitHub (Eventos: Pushes & Pull requests)
Payload URL: https://labs.amarassist.com.br/api/webhooks/git/github
Content type: application/json
# Produção Oficial: https://labs.amarassist.com.br/api/webhooks/git/github
# 2. Webhook Bitbucket (Triggers: Repository Push, Pull Request Created/Merged)
URL: https://labs.amarassist.com.br/api/webhooks/git/bitbucket
# Produção Oficial: https://labs.amarassist.com.br/api/webhooks/git/bitbucket
# 3. Webhook Escopado por Projeto Específico (Opcional):
URL: https://labs.amarassist.com.br/api/webhooks/projects/{slug}/git/{provider}