Visão geral das APIs do Cherri Code

O Cherri Code oferece várias APIs para acesso programático aos dados da sua equipe, agentes de codificação com IA e análises.

APIs disponíveis

A Cloud Agents API e os SDKs executam fluxos de trabalho de agentes do Cherri Code (contexto do workspace, ferramentas, comandos e edições). Eles não são uma API independente de inferência de modelo nem de chat-completions. O Cherri Code Router seleciona modelos para essas execuções de agentes quando você usa Auto / auto-smart; consulte Router no TypeScript SDK ou Python SDK.

Autenticação

As APIs Admin, Analytics, Rastreamento de Código com IA e Bugbot aceitam autenticação básica. A Cloud Agents API aceita autenticação básica ou Bearer. A API Origin usa credenciais Bearer por meio do CLI do Origin ou de um Origin App.

Autenticação básica

Use sua chave de API como nome de usuário na autenticação básica (deixe a senha em branco):

curl https://api.cursor.com/teams/members \  -u SUA_CHAVE_DE_API:

Ou defina diretamente o cabeçalho Authorization:

Authorization: Basic {base64_encode('SUA_CHAVE_DE_API:')}

Autenticação Bearer (Cloud Agents API)

A Cloud Agents API também aceita cabeçalhos Authorization: Bearer <key>. Os dois esquemas funcionam da mesma forma — use o que for mais fácil no seu cliente HTTP:

curl https://api.cursor.com/v1/me \  -H "Authorization: Bearer YOUR_API_KEY"

Criando chaves de API

Administradores da equipe podem criar e gerenciar chaves de API na página Chaves de API do dashboard.

API de administração e API de Rastreamento de Código com IA

1. Acesse cursor.com/dashboard → Chaves de API
2. Clique em New API Key
3. Dê à chave um nome descritivo (por exemplo, "Integração do dashboard de uso")
4. Copie a chave gerada imediatamente. Você não poderá visualizá-la novamente.

Formato da chave: crsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Escopo obrigatório: admin:*

Analytics API

Gere uma chave de API no dashboard do Cherri Code → Chaves de API.

Cloud Agents API

Crie uma chave de API de usuário em Cherri Code Dashboard → Chaves de API, ou use uma chave de API de conta de serviço nas configurações da equipe.

API Origin

Para solicitações autenticadas por usuário, faça login com a CLI do Origin ou forneça a ela uma chave de API de usuário pessoal. A CLI troca a chave por um access token de curta duração antes de chamar o Origin. Chaves da Team API de administração com o scope admin:* não autenticam no Origin. Apps usam app JWTs e installation access tokens. Veja autenticação da API Origin.

Limites de taxa

Todas as APIs implementam limitação de taxa para garantir uso justo e estabilidade do sistema. Os limites são aplicados por usuário autenticado, equipe ou organização, e a maioria vale para um único endpoint. A menos que um endpoint documente um limite diferente, o padrão é de 20 solicitações por minuto.

Limites de taxa por API

Resposta de Limite de Taxa

Quando você ultrapassar o limite de taxa, receberá uma resposta 429 Too Many Requests. As respostas da API de administração e da API da organização incluem Retry-After: 60 e este corpo:

{  "code": "error",  "message": "Rate limit exceeded"}

Cache

Várias APIs oferecem suporte a cache HTTP com ETags para reduzir o consumo de banda e melhorar o desempenho.

APIs compatíveis

• Analytics API: Todos os endpoints (tanto no nível da equipe quanto por usuário) oferecem suporte a cache HTTP
• AI Code Tracking API: Os endpoints oferecem suporte a cache HTTP

Como o cache funciona

1. Solicitação inicial: Faça uma solicitação a qualquer endpoint compatível
2. Resposta inclui ETag: A API retorna um cabeçalho ETag na resposta
3. Solicitações subsequentes: Inclua o valor de ETag em um cabeçalho If-None-Match
4. 304 Not Modified: Se os dados não tiverem mudado, você receberá uma resposta 304 Not Modified sem corpo

Exemplo

# Requisição inicialcurl -X GET "https://api.cursor.com/analytics/team/dau" \  -H "Authorization: Bearer YOUR_API_KEY" \  -D headers.txt# Resposta inclui: ETag: "abc123xyz"# Requisição subsequente com ETagcurl -X GET "https://api.cursor.com/analytics/team/dau" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "If-None-Match: \"abc123xyz\""# Retorna 304 Not Modified se os dados não foram alterados

Duração do cache

• Duração do cache: 15 minutos (Cache-Control: public, max-age=900)
• As respostas incluem o cabeçalho ETag
• Inclua o cabeçalho If-None-Match em solicitações subsequentes para receber 304 Not Modified quando os dados não tiverem sido alterados

Benefícios

• Reduz o consumo de banda: respostas 304 não têm corpo
• Respostas mais rápidas: evita processar dados que não mudaram
• Compatível com rate limits: respostas 304 não contam para os limites de taxa
• Melhor desempenho: especialmente útil para endpoints consultados com frequência

Boas práticas

1. Implementar recuo exponencial

Ao receber uma resposta 429, aguarde antes de tentar novamente com atrasos crescentes:

import timeimport requestsdef make_request_with_backoff(url, headers, max_retries=5):    for attempt in range(max_retries):        response = requests.get(url, headers=headers)                if response.status_code == 429:            # Exponential backoff: 1s, 2s, 4s, 8s, 16s            wait_time = 2 ** attempt            print(f"Rate limited. Waiting {wait_time}s before retry...")            time.sleep(wait_time)            continue                    return response        raise Exception("Max retries exceeded")

2. Distribua solicitações ao longo do tempo

Distribua suas chamadas de API ao invés de fazê-las em rajadas:

• Agende tarefas em lote para serem executadas em intervalos diferentes
• Adicione intervalos entre as solicitações ao processar grandes volumes de dados
• Use sistemas de filas para suavizar picos de tráfego

3. Aproveite o cache

Para Analytics API e AI Code Tracking API:

Essas APIs oferecem suporte a cache HTTP com ETags. Consulte a seção Caching acima para saber como usar ETags para reduzir o consumo de banda e evitar solicitações desnecessárias.

Principais benefícios:

• Reduz o consumo de banda
• Respostas mais rápidas quando os dados não mudaram
• Não conta para os limites de taxa (no caso de respostas 304)

Use atalhos de data (7d, 30d) em vez de timestamps para melhor suporte de cache na Analytics API.

4. Monitore seu uso

Acompanhe os padrões de solicitações para ficar dentro dos limites:

• Registre os horários das chamadas de API e os códigos de resposta
• Configure alertas para respostas 429
• Monitore as tendências de uso diárias/semanais
• Ajuste os intervalos de sondagem conforme as necessidades reais

5. Agrupe com inteligência

Para endpoints com paginação:

• Defina tamanhos de página adequados para obter mais dados por requisição
• Para endpoints da Analytics API por usuário: use o parâmetro users para filtrar usuários específicos
• Para grandes extrações de dados: use endpoints CSV quando disponíveis (eles fazem streaming dos dados de forma eficiente)

6. Faça polling em intervalos adequados

Evite fazer polling excessivo em endpoints que atualizam raramente:

• Admin API /teams/daily-usage-data: Faça polling no máximo uma vez por hora (dados agregados a cada hora)
• Admin API /teams/filtered-usage-events: Faça polling no máximo uma vez por hora (dados agregados a cada hora)
• Admin API /organizations/pooled-usage: Faça polling no máximo uma vez por hora (dados agregados a cada hora)
• Admin API /organizations/filtered-usage-events: Faça polling no máximo uma vez por hora (dados agregados a cada hora)
• Analytics API: Use atalhos de data (7d, 30d) para melhor suporte a cache
• AI Code Tracking API: Os dados são ingeridos quase em tempo real, mas fazer polling a cada poucos minutos é suficiente

7. Lide com erros de forma adequada

Implemente o tratamento adequado de erros para todas as chamadas de API:

async function fetchAnalytics(endpoint) {  try {    const response = await fetch(`https://api.cursor.com${endpoint}`, {      headers: {        'Authorization': `Basic ${btoa(API_KEY + ':')}`      }    });        if (response.status === 429) {      // Rate limited - implement backoff      throw new Error('Rate limit exceeded');    }        if (response.status === 401) {      // Invalid API key      throw new Error('Authentication failed');    }        if (response.status === 403) {      // Permissões insuficientes      throw new Error('Enterprise access required');    }        if (!response.ok) {      throw new Error(`API error: ${response.status}`);    }        return await response.json();  } catch (error) {    console.error('API request failed:', error);    throw error;  }}

Respostas de erro comuns

Todas as APIs usam códigos de status HTTP padrão:

400 Solicitação inválida

Os parâmetros da solicitação são inválidos ou há campos obrigatórios ausentes.

{  "error": "Requisição Inválida",  "message": "Alguns usuários não estão no time"}

401 Não autorizado

Chave de API inválida ou ausente.

{  "error": "Não autorizado",  "message": "Chave de API inválida"}

403 Proibido

Chave de API válida, mas com permissões insuficientes (por exemplo, funcionalidades Enterprise em um plano que não é Enterprise).

{  "error": "Forbidden",  "message": "Enterprise access required"}

404 Não encontrado

O recurso solicitado não existe.

{  "error": "Não encontrado",  "message": "Recurso não encontrado"}

429 Muitas solicitações

Limite de taxa excedido. Implemente recuo exponencial.

{  "error": "Muitas Requisições",  "message": "Limite de requisições excedido. Tente novamente mais tarde."}

500 Erro Interno do Servidor

Erro no servidor. Entre em contato com o suporte se o problema persistir.

{  "error": "Erro Interno do Servidor",  "message": "Ocorreu um erro inesperado"}