Vai al contenuto principale

Search

La Search API esegue full-text search globale sul workspace in una sola chiamata. Invece di cercare ogni dominio separatamente, fai query una volta e ottieni una lista mista e classificata di hit — documenti, channels, messaggi, todos, file del drive, trascrizioni vocali e chat IA — ciascuno taggato con il tipo di entità da cui proviene.

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"

Disponibile in​

Public APICLIMCPCopera AI
✅ Full✅ Full✅ Full—

La CLI e l'MCP server hostato espongono la stessa search globale. Non è esposta all'assistente Copera AI in-app.

Come funziona​

Invia un GET a /search con una query string. L'endpoint cerca ogni tipo di entità per cui hai permesso, classifica i risultati e li restituisce come una lista unica di hit tipizzati.

Parametri​

  • q — obbligatorio. La query di search (almeno un carattere).
  • types — opzionale. Restringe la search a tipi di entità specifici. Accetta un valore separato da virgole (?types=document,channel) o parametri ripetuti (?types=document&types=channel). Quando omesso, vengono cercati tutti i tipi consentiti. Valori validi:
    • document
    • channel
    • channelMessage
    • todo
    • todoItem
    • driveContent
    • voiceTranscription
    • aiChat
    • aiChatMessage
  • sortBy — createdAt o updatedAt (default updatedAt).
  • sortOrder — asc o desc (default desc).
  • limit — numero di risultati, 1–100 (default 50).

Response​

La response wrappa gli hit con alcuni metadati:

{
  "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": "…" }
  ]
}

Ogni hit porta un campo entityType che ti dice quale forma aspettarti. I campi per tipo rispecchiano l'entità (ad esempio, gli hit document hanno un title e mdBody; gli hit channelMessage hanno content, author e channel; gli hit driveContent hanno name, mimeType e size). Tutti i timestamp sono epoch milliseconds.

Permessi e filtri​

La search rispetta gli scope del token. Ogni tipo di entità si mappa a uno scope di dominio — ad esempio, i risultati document richiedono access_docs, i risultati channel e trascrizione richiedono access_channels e i risultati drive richiedono access_drive. Se al token manca lo scope per un tipo, quel tipo viene scartato in silenzio dai risultati.

Se richiedi esplicitamente un set di types e il token ha permesso per nessuno di essi, la richiesta restituisce un 403.

Autenticazione e scope​

La search richiede un Personal Access Token (cp_pat_) — le integration API key (cp_key_) non sono accettate su questo endpoint. I risultati sono poi filtrati dagli scope di dominio che il token detiene (vedi sopra). Gli utenti external non possono usare questo endpoint. Vedi Autenticazione.

Riferimento​