Query your KopyKat data from anywhere
Send a question from any app, script, or AI agent and get back matching emails, or an AI answer with sources. Every key only sees the data of the account that created it.
1. Get a key
Create keys from Profile, then API Keys. Any account with an active trial or subscription can create up to 10 keys. Each key is shown only once and is sent as a Bearer token.
2. Endpoint
POST https://otkjutqmmxfdcqaavwoi.supabase.co/functions/v1/query
Authorization: Bearer kk_live_...
Content-Type: application/jsonBody fields:
mode: one of"search"(default),"ask","emails","count", or"senders". See below.query: your question, up to 2,000 characters. Required forsearchandask.limit: number of results. 1 to 20 forsearchandask, 1 to 50 foremails(default 10).filters: optional structured filters, used byemails,count, andask.sort:"newest"(default),"oldest", or"amount". Used byemails.group_by:"none"(default),"sender","domain","category","day","week", or"month". Used bycount.
Two data sources
Your KopyKat data can be queried two ways, and you choose which one per request:
- Content search (
search,ask): finds emails whose full text is closest in meaning to your question. - Email records (
emails,count): exact filtering and counting over each email's sender, domain, subject, received date, category, short summary, attachments, and extracted amounts, reference numbers, dates, and action items.
The ask mode uses both: matching content plus the newest email records that fit your filters. Category, summary, and extracted fields are AI-generated and may be imperfect.
Available filters:
sender: part of the sender email or name.domain: sender domain, for examplestripe.com.category: the email's category label.start_date,end_date: ISO dates, inclusive.has_attachments:trueorfalse.keyword: words to match in subject, summary, or sender.min_amount: only emails mentioning an amount at least this large.
3. Search example
curl -X POST https://otkjutqmmxfdcqaavwoi.supabase.co/functions/v1/query \
-H "Authorization: Bearer $KOPYKAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "flight confirmation for Denver", "limit": 5}'Response:
{
"mode": "search",
"query": "flight confirmation for Denver",
"results": [
{
"id": "8f1c...",
"subject": "Your flight to Denver",
"sender": "noreply@airline.com",
"sender_name": "Airline",
"type": "email",
"received_at": "2026-09-28T14:02:11Z",
"snippet": "Confirmation code ABC123...",
"score": 0.712
}
]
}4. Ask example (JavaScript)
const res = await fetch("https://otkjutqmmxfdcqaavwoi.supabase.co/functions/v1/query", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KOPYKAT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ query: "What did my agent sign up for this week?", mode: "ask" }),
});
const { answer, sources, records } = await res.json();sources are the content matches, records are the email records the answer could draw on.
Email records example
curl -X POST https://otkjutqmmxfdcqaavwoi.supabase.co/functions/v1/query \
-H "Authorization: Bearer $KOPYKAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "emails",
"filters": { "domain": "stripe.com", "start_date": "2026-09-01", "min_amount": 100 },
"sort": "amount",
"limit": 5
}'Response:
{
"mode": "emails",
"count": 1,
"emails": [
{
"email_id": "3b7e...",
"document_id": "8f1c...",
"sender": "receipts@stripe.com",
"sender_name": "Stripe",
"sender_domain": "stripe.com",
"subject": "Your receipt from Acme",
"received_at": "2026-09-14T09:31:00Z",
"category": "receipt",
"summary": "Payment receipt for an annual plan.",
"has_attachments": true,
"attachment_names": ["receipt.pdf"],
"max_amount": 240,
"extracted": { "amounts": ["$240.00"], "reference_numbers": ["INV-1042"] }
}
]
}Count example
curl -X POST https://otkjutqmmxfdcqaavwoi.supabase.co/functions/v1/query \
-H "Authorization: Bearer $KOPYKAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"mode": "count", "group_by": "sender", "filters": {"start_date": "2026-09-01"}}'Response:
{
"mode": "count",
"group_by": "sender",
"total": 42,
"groups": [
{ "group": "alerts@github.com", "count": 17 },
{ "group": "noreply@airline.com", "count": 6 }
]
}Up to 50 groups are returned, largest first. Week groups are labeled by the Monday that starts the week.
Top senders example
The senders mode returns your top senders and how many emails each one sent, the same report as the dashboard. It accepts the same filters, for example a date range. limit sets how many senders to return, up to 25.
curl -X POST https://otkjutqmmxfdcqaavwoi.supabase.co/functions/v1/query \
-H "Authorization: Bearer $KOPYKAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"mode": "senders", "limit": 25, "filters": {"start_date": "2026-09-01", "end_date": "2026-09-30"}}'Response:
{
"mode": "senders",
"total": 42,
"senders": [
{ "sender": "alerts@github.com", "sender_name": "GitHub", "count": 17 },
{ "sender": "noreply@airline.com", "sender_name": "Airline", "count": 6 }
]
}5. Use it as a tool in your agent
Describe the endpoint as a tool so your agent can look things up in your KopyKat data while it works:
{
"name": "search_kopykat",
"description": "Search the user's KopyKat email data. Returns matching emails with subject, sender, date and snippet.",
"parameters": {
"type": "object",
"properties": { "query": { "type": "string" } },
"required": ["query"]
}
}When the agent calls the tool, POST its query to the endpoint and return the results.
Limits
- 60 requests per minute and 1,000 per day, per key. AI answers (
ask) are limited to 100 per day. - Up to 20 results per request for
searchandask, up to 50 foremails. Up to 10 active keys per account. - Requires an active trial or subscription.
Errors
Errors return JSON like {"error": "..."} with these status codes:
400: Invalid request body (for example, an empty or too long query).401: Missing, invalid, or revoked API key.402: Your trial or subscription has ended.429: Rate limit reached. Wait and retry after the Retry-After header.500 / 502: Something went wrong on our side. Retry later.