Saltar al contenido principal

Search

La API de Search ejecuta una búsqueda global de texto completo en tu workspace con una sola llamada. En lugar de buscar en cada dominio por separado, consultas una vez y obtienes una lista mixta y ordenada de coincidencias (documentos, channels, mensajes, todos, archivos de drive, transcripciones de voz y chats de IA), cada una etiquetada con el tipo de entidad del que proviene.

Inicio rápido​

# 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"

Disponible en​

Public APICLIMCPCopera AI
✅ Completo✅ Completo✅ Completo—

El CLI y el servidor MCP alojado exponen la misma búsqueda global. No está expuesta al asistente Copera AI dentro de la app.

Cómo funciona​

Envía un GET a /search con una cadena de consulta. El endpoint busca en cada tipo de entidad para el que tienes permiso, ordena los resultados y los devuelve como una sola lista de coincidencias tipadas.

Parámetros​

  • q: obligatorio. La consulta de búsqueda (al menos un carácter).
  • types: opcional. Restringe la búsqueda a tipos de entidad específicos. Acepta un valor separado por comas (?types=document,channel) o parámetros repetidos (?types=document&types=channel). Cuando se omite, se buscan todos los tipos permitidos. Valores válidos:
    • document
    • channel
    • channelMessage
    • todo
    • todoItem
    • driveContent
    • voiceTranscription
    • aiChat
    • aiChatMessage
  • sortBy: createdAt o updatedAt (predeterminado updatedAt).
  • sortOrder: asc o desc (predeterminado desc).
  • limit: número de resultados, 1–100 (predeterminado 50).

Respuesta​

La respuesta envuelve las coincidencias con algunos metadatos:

{
  "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 coincidencia lleva un campo entityType que te indica qué forma esperar. Los campos por tipo reflejan la entidad (por ejemplo, las coincidencias document tienen un title y mdBody; las coincidencias channelMessage tienen content, author y channel; las coincidencias driveContent tienen name, mimeType y size). Todas las marcas de tiempo son milisegundos epoch.

Permisos y filtrado​

Search respeta los alcances de tu token. Cada tipo de entidad se asigna a un alcance de dominio: por ejemplo, los resultados document necesitan access_docs, los resultados de channel y transcripción necesitan access_channels, y los resultados de drive necesitan access_drive. Si tu token carece del alcance para un tipo, ese tipo se descarta silenciosamente de los resultados.

Si solicitas explícitamente un conjunto de types y tu token no tiene permiso para ninguno de ellos, la solicitud devuelve un 403.

Autenticación y alcance​

Search requiere un Personal Access Token (cp_pat_): las claves de API de integración (cp_key_) no se aceptan en este endpoint. Los resultados se filtran luego según los alcances de dominio que tenga tu token (ver arriba). Los usuarios externos no pueden usar este endpoint. Consulta Autenticación.

Referencia​