Projetos

Projetos organizam o trabalho de um time e podem ser vinculados a um squad e a um cliente. A etapa do projeto determina o status retornado pela API.

GET /projects

Lista os projetos do time autenticado. Projetos com archived_at preenchido não são retornados.

Parâmetros de consulta

Parâmetro	Tipo	Padrão	Descrição
`page`	number	`1`	Página atual.
`limit`	number	`20`	Itens por página, até `100`.
`squad_id`	uuid	—	Filtra pelo squad vinculado.
`client_id`	uuid	—	Filtra pelo cliente vinculado.
`status`	string	—	`backlog`, `active`, `paused`, `completed` ou `cancelled`. O filtro é resolvido pelas etapas do time.
`priority`	string	—	`low`, `medium`, `high` ou `urgent`.
`search`	string	—	Busca em `name` e `description`.
`sort`	string	`-created_at`	Campo de ordenação; use `-` para ordem decrescente.

Os campos aceitos em sort são name, stage_id, priority, start_date, due_date, created_at e updated_at.

curl -X GET "https://app.usecolmeia.com/api/v1/projects?status=active&priority=high" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Resposta

{
  "success": true,
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440002",
      "name": "Implantação do portal do cliente",
      "slug": "implantacao-portal-cliente-a1b2c",
      "description": "Configuração do portal e do fluxo de atendimento.",
      "status": "active",
      "stage_id": "770e8400-e29b-41d4-a716-446655440006",
      "stage": {
        "id": "770e8400-e29b-41d4-a716-446655440006",
        "name": "Em andamento",
        "slug": "ongoing",
        "color": "#2563eb",
        "position": 2,
        "is_initial": false,
        "is_done": false,
        "is_archived": false
      },
      "priority": "high",
      "color": "#2563eb",
      "briefing": "Configuração do portal e do fluxo de atendimento.",
      "squad_id": "440e8400-e29b-41d4-a716-446655440006",
      "squad": {
        "id": "440e8400-e29b-41d4-a716-446655440006",
        "name": "Operações"
      },
      "client_id": "550e8400-e29b-41d4-a716-446655440000",
      "client": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Empresa Exemplo Ltda."
      },
      "start_date": "2026-08-01",
      "due_date": "2026-09-30",
      "completed_at": null,
      "created_by": "880e8400-e29b-41d4-a716-446655440004",
      "created_at": "2026-08-01T09:00:00Z",
      "updated_at": "2026-08-08T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

POST /projects

Cria um projeto. name é obrigatório. Se slug for omitido, a API gera um valor a partir do nome; se stage_id e status forem omitidos, a etapa inicial do time é usada.

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do projeto.
`slug`	string	Não	Identificador único no time.
`description`	string	Não	Descrição do projeto.
`status`	string	Não	`backlog`, `active`, `paused`, `completed` ou `cancelled`; seleciona uma etapa correspondente.
`stage_id`	uuid	Não	Seleciona diretamente uma etapa que pertence ao time. Tem precedência sobre `status`.
`priority`	string	Não	`low`, `medium`, `high` ou `urgent`. O padrão é `medium`.
`color`	string	Não	Cor associada ao projeto.
`start_date`	date	Não	Data no formato `YYYY-MM-DD`.
`due_date`	date	Não	Data no formato `YYYY-MM-DD`.
`briefing`	string	Não	Briefing do trabalho.
`squad_id`	uuid	Não	Squad vinculado.
`client_id`	uuid	Não	Cliente vinculado.

curl -X POST https://app.usecolmeia.com/api/v1/projects \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Implantação do portal do cliente",
    "status": "active",
    "priority": "high",
    "client_id": "550e8400-e29b-41d4-a716-446655440000",
    "due_date": "2026-09-30"
  }'

A criação retorna 201. Um slug já usado no mesmo time retorna 422 DUPLICATE_ENTRY.

GET /projects/:id

Retorna um projeto do time autenticado, com etapa, squad e cliente quando vinculados.

curl -X GET https://app.usecolmeia.com/api/v1/projects/660e8400-e29b-41d4-a716-446655440002 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

PUT /projects/:id

Atualiza campos do projeto. Envie ao menos um campo. stage_id precisa pertencer ao time; alternativamente, envie um status válido para resolver uma etapa correspondente.

Campo atualizável	Tipo
`name`, `slug`	string
`description`, `color`, `briefing`	string ou `null`
`start_date`, `due_date`, `completed_at`	data ou data/hora ISO 8601, conforme o campo
`squad_id`, `client_id`	uuid ou `null`
`stage_id`	uuid da etapa do time
`status`	`backlog`, `active`, `paused`, `completed` ou `cancelled`
`priority`	`low`, `medium`, `high` ou `urgent`

curl -X PUT https://app.usecolmeia.com/api/v1/projects/660e8400-e29b-41d4-a716-446655440002 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "completed_at": "2026-09-30T17:00:00Z"
  }'

Projetos arquivados não podem ser alterados pela API. O PUT retorna 409 PROJECT_ARCHIVED; restaure o projeto pelo painel antes de editá-lo.

DELETE /projects/:id

Não suportado. Este endpoint retorna 405 METHOD_NOT_ALLOWED; o arquivamento de projetos exige uma sessão autenticada de administrador no painel.

{
  "success": false,
  "error": {
    "code": "METHOD_NOT_ALLOWED",
    "message": "O arquivamento de projetos exige uma sessão autenticada de administrador"
  }
}

Erros comuns

Status	Código	Causa
`400`	`VALIDATION_ERROR`	Corpo inválido, `name` ausente, enum inválido ou nenhum campo para atualizar.
`404`	`NOT_FOUND`	Projeto ou etapa não encontrado no time.
`409`	`PROJECT_ARCHIVED`	Tentativa de alterar um projeto arquivado.
`422`	`DUPLICATE_ENTRY`	`slug` já está em uso no time.
`405`	`METHOD_NOT_ALLOWED`	Tentativa de excluir ou arquivar um projeto pela API.

Projetos

On this page