Introduction

Auth, limits, and how to call the API (REST + tRPC)

Kontext exposes both REST and tRPC-style HTTP endpoints. Use the SDK for the best experience; otherwise call the HTTP endpoints directly with your API key.

Get the Kontext SDK

Install from npm and view release history.

Base URL

https://api.kontext.dev

Authentication

• Header: x-api-key — required for all public endpoints
• OAuth: Gmail connect flow via /oauth/gmail and /oauth/google/callback (no API key on callback; uses signed state)

Example header:

x-api-key: ktext_xxxxxxxxx

Response Codes

Kontext uses standard HTTP codes to indicate the success or failure of your requests.

Status	Description
200	Successful request
400	Invalid request parameters
401	Missing or invalid API key
403	Forbidden - check your permissions
404	Resource not found
429	Rate limit exceeded
500	Internal server error

Rate Limiting

• Default: ~30 requests/min per API key (burst up to ~5 rps)
• Standard headers returned:
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset

Error Format

All errors follow a consistent format:

{
  "error": {
    "code": "UNAUTHORIZED_USER",
    "message": "User has not authorized Gmail access"
  }
}

Common Error Codes

Code	Description
UNAUTHORIZED_USER	User hasn’t connected Gmail
INVALID_API_KEY	API key is invalid or missing
RATE_LIMITED	Too many requests
INVALID_USER_ID	User ID format is invalid
NOT_FOUND	Resource or facts not found
INVALID_REQUEST	Validation error
SERVER_ERROR	Internal server error

SDK vs HTTP

We recommend using the SDKs:

• SDK unwraps tRPC envelopes automatically, returns typed results, and sets x-api-key for you (with sensible retries).
• Plain HTTP requires sending a tRPC JSON envelope (e.g., { "input": { ... } }), parsing result.data, and handling auth/retries yourself.
• Prefer the SDK unless you need a custom transport or minimal dependency footprint.

// SDK (recommended)
import { Persona } from '@kontext.dev/kontext-sdk';
const persona = new Persona({ apiKey: process.env.KONTEXT_API_KEY! });
const context = await persona.getContext({ userId, task });

// HTTP (tRPC)
await fetch('https://api.kontext.dev/trpc/data.context', {
  method: 'POST',
  headers: { 'x-api-key': process.env.KONTEXT_API_KEY!, 'content-type': 'application/json' },
  body: JSON.stringify({ userId, task })
});

Privacy & PII

Privacy is enforced at context build time (sanitizer). The server enforces DEFAULT_PRIVACY_LEVEL (default strict); any inbound privacy level from clients is ignored. Strict mode redacts common PII classes (emails, phone numbers, cards, addresses, medical IDs, etc.). User names are not redacted by default.