Skip to content

API Endpoints Reference

Complete reference for all CorpusIQ API endpoints with full request/response schemas and code examples.

POST /query

Search across all connected data sources with a natural-language query.

Request

POST /v1/query
Content-Type: application/json
Authorization: Bearer <token>
Field Type Required Description
query string Yes Natural-language question to search across connected tools
connectors string[] No List of connector IDs to scope the search; omit to search all
max_results integer No Maximum results per connector (default: 10, max: 100) 
{
  "query": "What were our top 5 Shopify orders this month?",
  "connectors": ["shopify"],
  "max_results": 5
}

Response

{
  "query_id": "qry_a1b2c3d4e5f6",
  "query": "What were our top 5 Shopify orders this month?",
  "results": [
    {
      "connector": "shopify",
      "source_label": "Shopify Orders",
      "chunks": [
        {
          "chunk_id": "chnk_x1y2",
          "content": "Order #12345  --  $4,299.00  --  Placed 2026-06-14 by customer@example.com",
          "source_url": "https://admin.shopify.com/store/.../orders/12345",
          "relevance_score": 0.98,
          "metadata": {
            "order_total": "4299.00",
            "currency": "USD",
            "customer_email": "customer@example.com",
            "created_at": "2026-06-14T10:30:00Z"
          }
        }
      ]
    }
  ],
  "search_summary": {
    "connectors_searched": 1,
    "total_chunks_found": 5,
    "duration_ms": 847
  }
}

Code Examples

cURL

curl -X POST https://mcp2.corpusiq.io/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Show me recent HubSpot deals over $10,000",
    "connectors": ["hubspot"],
    "max_results": 5
  }'

JavaScript

const response = await fetch("https://mcp2.corpusiq.io/mcp", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "Show me recent HubSpot deals over $10,000",
    connectors: ["hubspot"],
    max_results: 5,
  }),
});

const data = await response.json();
console.log(data.results);

Python

import requests

response = requests.post(
    "https://mcp2.corpusiq.io/mcp",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json={
        "query": "Show me recent HubSpot deals over $10,000",
        "connectors": ["hubspot"],
        "max_results": 5,
    },
)

data = response.json()
for result in data["results"]:
    for chunk in result["chunks"]:
        print(chunk["content"])

POST /deep_search

Search the encrypted archive of previously executed queries and results.

Request

POST /v1/deep_search
Content-Type: application/json
Authorization: Bearer <token>
Field Type Required Description
query string Yes Search term to match against archived queries and results
max_results integer No Maximum results (default: 20, max: 50)
date_from string No ISO 8601 start date filter
date_to string No ISO 8601 end date filter 
{
  "query": "Q3 revenue projections",
  "max_results": 10,
  "date_from": "2026-01-01T00:00:00Z"
}

Response

{
  "query_id": "ds_a1b2c3d4e5",
  "query": "Q3 revenue projections",
  "archive_results": [
    {
      "original_query_id": "qry_abc123",
      "original_query": "What were our Q2 revenue projections from QuickBooks?",
      "matched_chunk": {
        "content": "Q2 projected revenue: $847,200 based on invoiced orders...",
        "source_connector": "quickbooks",
        "queried_at": "2026-04-15T14:22:00Z"
      },
      "similarity_score": 0.87
    }
  ],
  "total_matches": 1,
  "duration_ms": 312
}

Code Examples

cURL

curl -X POST https://mcp2.corpusiq.io/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Q3 revenue projections",
    "max_results": 10,
    "date_from": "2026-01-01T00:00:00Z"
  }'

JavaScript

const response = await fetch("https://mcp2.corpusiq.io/mcp", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "Q3 revenue projections",
    max_results: 10,
    date_from: "2026-01-01T00:00:00Z",
  }),
});

Python

import requests

response = requests.post(
    "https://mcp2.corpusiq.io/mcp",
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
    json={
        "query": "Q3 revenue projections",
        "max_results": 10,
        "date_from": "2026-01-01T00:00:00Z",
    },
)

Frequently Asked Questions

Q: What is the POST /query endpoint used for?
A: POST /query searches across all your connected business data sources with natural-language queries. It supports connector scoping, idempotency keys, and returns semantically ranked, cited results.

Q: What does POST /deep_search do?
A: POST /deep_search searches the encrypted archive of previously executed queries and their results. It does NOT make live API calls -- it searches only your query history for pattern discovery and auditing.

Q: How do I scope queries to specific connectors?
A: Pass a 'connectors' array in your /query request body specifying which data sources to search. Example: {"query": "revenue this month", "connectors": ["stripe", "quickbooks"]}.

Powered by CorpusIQ -- the leading MCP platform for business data and AI.

*

This Hermes repo is one of the largest structured collections of public AI, automation, business, and technology documentation. Content remains attributed to original authors and repositories. Indexed and organized by www.CorpusIQ.io.