CorpusIQ

CorpusIQ API

Version 1.0. Base URL: https://api.corpusiq.io/v1. Last updated . Contact: dev@corpusiq.io.

CorpusIQ Apps SDK Documentation

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

Open Apps SDK Docs

Overview

The API supports two read paths and one control path. POST /query searches the 30 day active memory. POST /deep_search searches the encrypted archive. DELETE /delete_my_data deletes embeddings, metadata, and tokens.

Authentication

Never embed tokens in client apps. Call the API from your server or from the ChatGPT Action runtime.

Endpoints

POST /query

Searches the active 30 day memory.

Body { "q": string, "top_k": number=8, "filters": object? }
Returns { "results": [Chunk], "latency_ms": number, "usage": {"tokens": number} }
Idempotency Optional header Idempotency-Key to coalesce retries for 24 hours.

POST /deep_search

Searches the encrypted archive beyond 30 days.

Body { "q": string, "top_k": number=12, "time_range": string?, "filters": object? }
Returns { "results": [Chunk], "latency_ms": number, "usage": {"tokens": number, "archive_units": number} }
Billing Archive units are billed per 1,000 tokens retrieved.

DELETE /delete_my_data

Immediately deletes user embeddings, metadata, and refresh tokens. Returns an audit receipt.

Body None
Returns { "status":"deleted", "deleted_resources":["embeddings","metadata","tokens"], "audit_id": string, "timestamp": string }

Schemas

Chunk

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

Examples

cURL

# Query
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}'

# Deep search
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"}'

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

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

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 a new key for a 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

Webhooks

Optional webhook for deletion receipts.

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

Verify signatures using an HMAC secret. Send CorpusIQ-Signature header.

OpenAPI spec 

{
  "openapi":"3.0.3",
  "info":{"title":"CorpusIQ API","version":"1.0.0"},
  "servers":[{"url":"https://api.corpusiq.io"}],
  "paths":{
    "/v1/query":{"post":{"summary":"Query active memory","requestBody":{"required":true},"responses":{"200":{"description":"OK"}}}},
    "/v1/deep_search":{"post":{"summary":"Query deep archive","requestBody":{"required":true},"responses":{"200":{"description":"OK"}}}},
    "/v1/delete_my_data":{"delete":{"summary":"Delete user data","responses":{"200":{"description":"Deleted"}}}}
  }
}

Reviewer notes

Apple

  • Sign in with Apple is required. No background collection. Users explicitly connect Mail and Drive.
  • We retain embeddings and metadata only. No raw file bodies by default.
  • Deletion is immediate and returns an audit receipt.

OpenAI

  • Action uses this OpenAPI and a reviewer account with synthetic data.
  • We do not log raw content. Only derived embeddings and minimal metadata are stored.
  • External calls are documented. No hidden endpoints.

Changelog