CorpusIQ Logo

CorpusIQ API

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

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