Skip to main content

Search

The Search API runs global, full-text search across your workspace in a single call. Instead of searching each domain separately, you query once and get back a ranked, mixed list of hits — documents, channels, messages, todos, drive files, voice transcriptions, and AI chats — each tagged with the entity type it came from.

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"

Available in​

Public APICLIMCPCopera AI
✅ Full✅ Full✅ Full—

The CLI and the hosted MCP server expose the same global search. It is not exposed to the in-app Copera AI assistant.

How it works​

Send a GET to /search with a query string. The endpoint searches every entity type you have permission for, ranks the results, and returns them as a single list of typed hits.

Parameters​

  • q — required. The search query (at least one character).
  • types — optional. Restrict the search to specific entity types. Accepts a comma-separated value (?types=document,channel) or repeated parameters (?types=document&types=channel). When omitted, all permitted types are searched. Valid values:
    • document
    • channel
    • channelMessage
    • todo
    • todoItem
    • driveContent
    • voiceTranscription
    • aiChat
    • aiChatMessage
  • sortBy — createdAt or updatedAt (default updatedAt).
  • sortOrder — asc or desc (default desc).
  • limit — number of results, 1–100 (default 50).

Response​

The response wraps the hits with some metadata:

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

Each hit carries an entityType field that tells you which shape to expect. The fields per type mirror the entity (for example, document hits have a title and mdBody; channelMessage hits have content, author, and channel; driveContent hits have name, mimeType, and size). All timestamps are epoch milliseconds.

Permissions and filtering​

Search respects your token's scopes. Each entity type maps to a domain scope — for example, document results need access_docs, channel and transcription results need access_channels, and drive results need access_drive. If your token lacks the scope for a type, that type is silently dropped from the results.

If you explicitly request a set of types and your token has permission for none of them, the request returns a 403.

Authentication & scope​

Search requires a Personal Access Token (cp_pat_) — integration API keys (cp_key_) are not accepted on this endpoint. The results are then filtered by the domain scopes your token holds (see above). External users cannot use this endpoint. See Authentication.

Reference​