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>
Idempotency-Key: <unique-key>  (optional)

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
  }
}

Idempotency

Pass an Idempotency-Key header to safely retry /query requests without creating duplicate query records. The key must be unique per request. Subsequent requests with the same key within 24 hours return the cached response.

Idempotency-Key: req_2026-06-16_sales_report

Code Examples

cURL

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

JavaScript

const response = await fetch("https://api.corpusiq.io/v1/query", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  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
import uuid

response = requests.post(
    "https://api.corpusiq.io/v1/query",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    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://api.corpusiq.io/v1/deep_search \
  -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://api.corpusiq.io/v1/deep_search", {
  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://api.corpusiq.io/v1/deep_search",
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
    json={
        "query": "Q3 revenue projections",
        "max_results": 10,
        "date_from": "2026-01-01T00:00:00Z",
    },
)

---

DELETE /delete_my_data

Permanently delete all data associated with the authenticated user. This action is irreversible.

Request

DELETE /v1/delete_my_data
Authorization: Bearer <token>

No request body is required. The API returns a confirmation payload before executing deletion.

Response

{
  "status": "deletion_confirmed",
  "details": {
    "oauth_tokens_revoked": 12,
    "query_history_deleted": true,
    "archive_entries_removed": 847,
    "webhooks_unregistered": 2,
    "profile_deleted": true
  },
  "message": "All user data has been permanently deleted. This action cannot be undone."
}

Code Examples

cURL

curl -X DELETE https://api.corpusiq.io/v1/delete_my_data \
  -H "Authorization: Bearer <token>"

JavaScript

const response = await fetch("https://api.corpusiq.io/v1/delete_my_data", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${token}` },
});
const result = await response.json();
console.log(result.message);

Python

import requests

response = requests.delete(
    "https://api.corpusiq.io/v1/delete_my_data",
    headers={"Authorization": f"Bearer {token}"},
)
print(response.json()["message"])

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: What happens when I call DELETE /delete_my_data?
A: This endpoint permanently deletes all user data: OAuth tokens, query history, archive entries, webhook registrations, and user profile. The action is irreversible and triggers a user.deleted webhook event.

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"]}.

Internal Links

• CorpusIQ API Overview — Full REST API documentation and base URL reference
• API Authentication Guide — Bearer tokens, OAuth 2.0, and security best practices
• API Endpoints Reference — Complete request/response schemas and code examples
• API Rate Limits — Per-endpoint quotas and retry strategies
• CorpusIQ Webhooks — Event notifications and HMAC signature verification
• Enterprise AI Data Access Guide — SSO, SAML, SOC 2, and data residency
• Secure AI Data Connectivity — Encryption, network security, and compliance

---

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