> ## Documentation Index
> Fetch the complete documentation index at: https://strattumai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickUp

> Configure o conector ClickUp para sincronizar tasks, spaces, lists e membros com a plataforma strattum.ai.

O conector ClickUp sincroniza tasks e a estrutura do workspace do ClickUp com a infraestrutura strattum.ai. Os dados aparecem no Data Catalog e alimentam o contexto de trabalho e projetos no Memory e no Knowledge.

## Capacidades

* Sincroniza tasks, spaces, lists e membros do workspace.
* Carga incremental de tasks pela data de atualização (`date_updated`).
* Autenticação via API key pessoal do ClickUp.

## Objetos suportados

| Objeto    | O que vem                                                                                                                           |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `tasks`   | Tasks com `id`, `name`, `description`, `status`, criador, assignees e timestamps de criação, atualização e fechamento (incremental) |
| `spaces`  | Spaces do workspace                                                                                                                 |
| `lists`   | Lists dentro dos spaces                                                                                                             |
| `members` | Membros do workspace                                                                                                                |

## Pré-requisitos

<CardGroup cols={2}>
  <Card title="Conta ClickUp" icon="list-check">
    Acesso a um workspace ClickUp com as tasks que você quer sincronizar.
  </Card>

  <Card title="API key e Team ID" icon="key">
    A API key pessoal e o ID do workspace (team). O passo a passo está abaixo.
  </Card>
</CardGroup>

## Configuração

<Steps>
  <Step title="Gere a API key">
    No ClickUp, acesse **Settings → Apps** e copie a **API Token** pessoal, que começa com `pk_`.

    <Warning>
      A API key concede o mesmo acesso do seu usuário. Guarde-a em local seguro e nunca a comite em repositórios.
    </Warning>
  </Step>

  <Step title="Descubra o Team ID">
    O Team ID (ID do workspace) aparece na URL do ClickUp: `app.clickup.com/{team_id}/...`. Copie o número.
  </Step>

  <Step title="Adicione o conector no Console">
    No menu lateral do Console, clique em **Conectores → + Nova Conexão** e selecione **ClickUp**. Preencha os campos:

    * **Nome do Conector** — identificador na lista de conectores (Obrigatório)
    * **API Key** — token `pk_...` gerado na etapa anterior (Obrigatório)
    * **Team ID** — ID numérico do workspace (Obrigatório)
  </Step>

  <Step title="Teste e salve">
    Clique em **Testar Conexão** para validar as credenciais e, em seguida, em **Salvar Conector**.
  </Step>
</Steps>

## Autenticação e escopos

A autenticação é por API key pessoal enviada no header `Authorization` contra a API v2 do ClickUp. A API key não tem escopos granulares — o acesso é o mesmo do usuário dono da chave.

| Acesso do usuário               | Para que serve                        |
| ------------------------------- | ------------------------------------- |
| Membro do workspace (team)      | Listar spaces, lists, tasks e membros |
| Acesso às tasks dos spaces-alvo | Ler as tasks que serão sincronizadas  |

## Frequência de sync

O conector sincroniza **a cada 15 minutos**. A primeira execução após a ativação roda como sample sync (amostra) e, ao concluir, o ciclo completo passa a rodar no schedule padrão.

## Limitações conhecidas

* `spaces`, `lists` e `members` são carregados em full refresh a cada ciclo; apenas `tasks` é incremental.
* A API key herda o acesso do usuário dono; tasks em spaces sem acesso não são sincronizadas.
* Tasks deletadas na origem não são removidas automaticamente em modo incremental.
* Campos customizados são lidos como retornados pela API, sem normalização adicional.

## Troubleshooting

| Sintoma                          | Causa provável               | O que fazer                                                    |
| -------------------------------- | ---------------------------- | -------------------------------------------------------------- |
| `401 Unauthorized`               | API key inválida ou revogada | Gere uma nova API key em Settings → Apps e atualize o conector |
| `Team not found` ou tasks vazias | Team ID incorreto            | Confirme o ID na URL `app.clickup.com/{team_id}/...`           |
| Tasks de um space não aparecem   | Usuário sem acesso ao space  | Conceda acesso ao usuário dono da API key                      |
| `api_key must not be empty`      | Campo API Key vazio          | Preencha a API key no formulário de conexão                    |

## Próximos passos

<CardGroup cols={2}>
  <Card title="Guia de desenvolvimento local" icon="terminal" href="/data-pipelines/local-development">
    Configure o ambiente local completo com Prefect, worker e Docker Compose.
  </Card>

  <Card title="Quickstart — Data Pipelines" icon="rocket" href="/data-pipelines/quickstart">
    Ative conectores via Console strattum.ai sem precisar de ambiente local.
  </Card>
</CardGroup>