Pular para o conteúdo principal

Search

A Search API executa uma busca global full-text em todo o seu workspace em uma única chamada. Em vez de buscar cada domínio separadamente, você consulta uma única vez e recebe de volta uma lista mista e ranqueada de resultados — documentos, channels, mensagens, todos, arquivos do drive, transcrições de voz e chats de IA — cada um marcado com o tipo de entidade de onde veio.

Quick Start​

# Search across every entity type you can access
curl -X GET "https://api.copera.ai/public/v1/search?q=quarterly%20plan" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Restrict to specific entity types
curl -X GET "https://api.copera.ai/public/v1/search?q=contract&types=document,driveContent" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Sort and limit the results
curl -X GET "https://api.copera.ai/public/v1/search?q=plan&sortBy=updatedAt&sortOrder=desc&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Disponível em​

Public APICLIMCPCopera AI
✅ Completo✅ Completo✅ Completo—

A CLI e o servidor MCP hospedado expõem a mesma busca global. Ela não é exposta ao assistente Copera AI dentro do app.

Como funciona​

Envie um GET para /search com uma query string. O endpoint busca em todos os tipos de entidade para os quais você tem permissão, ranqueia os resultados e os retorna como uma única lista de resultados tipados.

Parâmetros​

  • q — obrigatório. A query de busca (pelo menos um caractere).
  • types — opcional. Restringe a busca a tipos de entidade específicos. Aceita um valor separado por vírgulas (?types=document,channel) ou parâmetros repetidos (?types=document&types=channel). Quando omitido, todos os tipos permitidos são buscados. Valores válidos:
    • document
    • channel
    • channelMessage
    • todo
    • todoItem
    • driveContent
    • voiceTranscription
    • aiChat
    • aiChatMessage
  • sortBy — createdAt ou updatedAt (padrão updatedAt).
  • sortOrder — asc ou desc (padrão desc).
  • limit — número de resultados, 1–100 (padrão 50).

Resposta​

A resposta envolve os resultados com alguns metadados:

{
  "query": "quarterly plan",
  "totalHits": 12,
  "processingTimeMs": 8,
  "hits": [
    { "entityType": "document", "_id": "…", "title": "Q3 Plan", "updatedAt": 1719400000000 },
    { "entityType": "channelMessage", "_id": "…", "content": "let's finalize the plan", "channel": "…" }
  ]
}

Cada resultado carrega um campo entityType que indica qual formato esperar. Os campos por tipo espelham a entidade (por exemplo, resultados document têm um title e mdBody; resultados channelMessage têm content, author e channel; resultados driveContent têm name, mimeType e size). Todos os timestamps são em milissegundos epoch.

Permissões e filtragem​

A busca respeita os escopos do seu token. Cada tipo de entidade mapeia para um escopo de domínio — por exemplo, resultados document precisam de access_docs, resultados de channel e transcrição precisam de access_channels, e resultados de drive precisam de access_drive. Se o seu token não tiver o escopo de um tipo, esse tipo é silenciosamente removido dos resultados.

Se você solicitar explicitamente um conjunto de types e o seu token não tiver permissão para nenhum deles, a requisição retorna um 403.

Autenticação e escopo​

A busca requer um Personal Access Token (cp_pat_) — integration API keys (cp_key_) não são aceitas neste endpoint. Os resultados são então filtrados pelos escopos de domínio que o seu token possui (veja acima). Usuários externos não podem usar este endpoint. Veja Autenticação.

Referência​