v1.0Last updated October 14, 2025

API Documentation

Base URL: https://api.corpusiq.io/v1 · Contact: dev@corpusiq.io

CorpusIQ Apps SDK Documentation

Build custom integrations and extend CorpusIQ functionality with the Apps SDK.

Overview Authentication Endpoints Schemas Code Examples Errors Rate Limits Webhooks OpenAPI Spec Reviewer Notes Changelog

Overview

The API supports two read paths and one control path. POST /query searches your connected data. POST /deep_search searches the encrypted archive. DELETE /delete_my_data deletes embeddings, metadata, and tokens.

Authentication

Include the following header on every request:

http

Authorization: Bearer <access_token>

Token expiry

60 minutes with server-side refresh

Authentication

ChatGPT Actions or dashboard login

Revocation

Account settings or via deletion endpoint

Security note

Never embed tokens in client apps — use server or ChatGPT Action runtime

Endpoints

POST/querySearch connected data

Request Body

json

{
  "q": "string",
  "top_k": 8,
  "filters": {}
}

Response

json

{
  "results": [Chunk],
  "latency_ms": number,
  "usage": { "tokens": number }
}

Optional Idempotency-Key header coalesces retries for 24 hours.

POST/deep_searchSearch full encrypted archive

Request Body

json

{
  "q": "string",
  "top_k": 12,
  "time_range": "2024-10-01..2025-09-30",
  "filters": {}
}

Response

json

{
  "results": [Chunk],
  "latency_ms": number,
  "usage": {
    "tokens": number,
    "archive_units": number
  }
}

Archive units billed per 1,000 tokens retrieved.

DELETE/delete_my_dataDelete all user data

No request body required. Immediately deletes user embeddings, metadata, and refresh tokens.

json

{
  "status": "deleted",
  "deleted_resources": ["embeddings", "metadata", "tokens"],
  "audit_id": "del_01J9Z3R4A2",
  "timestamp": "2025-10-14T15:32:10Z"
}

Schemas

Chunk object

json

{
  "id": "chk_01H...",
  "source": {
    "type": "email | file",
    "path": "iCloud/Drive/...",
    "message_id": "<id@icloud.com>"
  },
  "snippet": "string",
  "score": 0.0
}

Code Examples

cURL — Query

bash

curl -s -X POST https://api.corpusiq.io/v1/query \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"q":"Find the renewal date for the ACME contract","top_k":8}'

cURL — Deep Search

bash

curl -s -X POST https://api.corpusiq.io/v1/deep_search \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"q":"Q3 revenue by client","top_k":12,"time_range":"2024-10-01..2025-09-30"}'

cURL — Delete

bash

curl -s -X DELETE https://api.corpusiq.io/v1/delete_my_data \
 -H "Authorization: Bearer $TOKEN"

JavaScript

javascript

async function query(q) {
  const r = await fetch('https://api.corpusiq.io/v1/query', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ q, top_k: 8 })
  });
  if (!r.ok) throw new Error(`HTTP ${r.status}`);
  return r.json();
}

Python

python

import requests

def deep_search(q, token):
    r = requests.post(
        'https://api.corpusiq.io/v1/deep_search',
        headers={'Authorization': f'Bearer {token}'},
        json={'q': q, 'top_k': 12}
    )
    r.raise_for_status()
    return r.json()

Errors

Status	Code	Meaning	Fix
400	bad_request	Invalid body	Send required fields
401	unauthorized	Missing or invalid token	Send Bearer token, renew if expired
403	forbidden	Scope mismatch	Reauthenticate and approve scopes
404	not_found	Route or resource missing	Check path
409	conflict	Duplicate idempotency key	Use new key for new operation
413	payload_too_large	Body too large	Reduce payload
429	rate_limited	Too many requests	Respect rate limits, backoff
500	server_error	Internal error	Retry with backoff

Rate Limits

Endpoint	Burst limit	Daily limit
/query	60 req/min	6,000/day
/deep_search	30 req/min	3,000/day
/delete_my_data	10 req/min	100/day

Webhooks

Optional webhook for deletion receipts. Verify signatures using HMAC secret via the CorpusIQ-Signature header.

Event: user.deleted

json

{
  "type": "user.deleted",
  "data": {
    "user_id": "usr_01H...",
    "audit_id": "del_01J9...",
    "timestamp": "2025-10-14T15:32:10Z"
  },
  "signature": "t=...,v1=..."
}

OpenAPI Spec

Machine-readable OpenAPI 3.0.3 specification for all public endpoints. Import into Postman, Insomnia, or any OpenAPI-compatible toolchain.

json

{
  "openapi": "3.0.3",
  "info": {
    "title": "CorpusIQ API",
    "version": "1.0.0",
    "description": "Private AI retrieval layer for business data",
    "contact": { "email": "dev@corpusiq.io" }
  },
  "servers": [{ "url": "https://api.corpusiq.io" }],
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
    }
  },
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/v1/query": {
      "post": {
        "summary": "Query connected data sources",
        "operationId": "queryData",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["query"],
                "properties": {
                  "query": { "type": "string", "description": "Natural-language question" },
                  "connectors": {
                    "type": "array",
                    "items": { "type": "string" },
                    "description": "Connector IDs to search (omit for all)"
                  },
                  "conversation_id": { "type": "string", "description": "Pass back for follow-up turns" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Answer with source citations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "answer": { "type": "string" },
                    "sources": { "type": "array", "items": { "type": "object" } },
                    "conversation_id": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/deep_search": {
      "post": {
        "summary": "Query deep archive (files, embeddings)",
        "operationId": "deepSearch",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["query"],
                "properties": {
                  "query": { "type": "string" },
                  "top_k": { "type": "integer", "default": 5 }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Ranked results with relevance scores" }
        }
      }
    },
    "/v1/delete_my_data": {
      "delete": {
        "summary": "Delete all user data and revoke connectors",
        "operationId": "deleteMyData",
        "responses": {
          "200": {
            "description": "Deletion confirmed with audit receipt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "audit_id": { "type": "string" },
                    "deleted_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Notes for Reviewers

Apple Reviewer Notes

→Sign in with Apple is implemented and required for iOS/macOS auth flows.
→No background data collection. Users explicitly connect Mail or Drive via OAuth consent screens.
→Only derived embeddings and minimal metadata are retained — raw files are never stored.
→User-initiated deletion is immediate and returns an audit receipt with timestamp.

OpenAI Reviewer Notes

→This ChatGPT Action uses the OpenAPI spec above. A reviewer account with synthetic data is available on request.
→No raw content is logged. Only derived embeddings and minimal metadata are stored.
→All external service calls are documented in the spec. There are no hidden or undisclosed endpoints.
→Users can delete all data at any time via DELETE /v1/delete_my_data.

Changelog

v1.02026-03-18 — Updated connector list, SDK section, and API examples.

Need help with the API?

Reach our engineering team or get started with a free account.

dev@corpusiq.io Get API Access — Free