AI Context API: Developer Guide to Saving and Sharing Chat Context

Building AI agents that remember conversation history requires more than a good prompt. You need a reliable API to save, retrieve, and share chat context between sessions and tools. AirClippy's AI Context API provides exactly that — a REST interface for private context storage with scoped agent access. ## Overview The AI Context API is part of AirClippy's AI Context Vault at airclippy.com/ai-context. It provides: - Full CRUD for chat context objects - API key authentication for owner operations - Scoped share tokens for third-party agent access - Automatic TTL expiry for contexts and tokens Base URL: https://airclippy.com/api/v1 Full documentation: airclippy.com/ai-context/docs ## Authentication Two token types are supported: ### API Keys (actx_sk_…) Used for full context management — create, read, update, delete, and mint share tokens. Create keys in the dashboard or via the keys endpoint. Authorization: Bearer actx_sk_YOUR_KEY ### Share Tokens (actx_sh_…) Used by third-party agents for scoped access to a specific context. Minted by the context owner with chosen permissions and expiry. Authorization: Bearer actx_sh_YOUR_TOKEN Agents pulling context via the share endpoint do not need an API key. ## Endpoints Reference ### Contexts POST /api/v1/contexts — Create a new context GET /api/v1/contexts — List all contexts GET /api/v1/contexts/:id — Get a specific context PATCH /api/v1/contexts/:id — Update or append to a context DELETE /api/v1/contexts/:id — Delete a context permanently ### Share Tokens POST /api/v1/contexts/:id/share — Mint a scoped share token ### Agent Access GET /api/v1/share/:token — Pull context (share token) PATCH /api/v1/share/:token — Append or update (share token) ### API Keys POST /api/v1/keys — Create a new API key (Firebase auth) GET /api/v1/keys — List your keys DELETE /api/v1/keys — Revoke a key ## Creating a Context curl -X POST https://airclippy.com/api/v1/contexts \ -H "Authorization: Bearer actx_sk_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Handoff to Agent B", "messages": [ { "role": "system", "content": "You are helping with airclippy." }, { "role": "user", "content": "Continue from here…" } ], "metadata": { "source": "cursor", "tags": ["mvp"] }, "ttlDays": 7 }' Response includes the context id, message count, and expiresAt timestamp. ## Updating and Appending Full update: curl -X PATCH https://airclippy.com/api/v1/contexts/CONTEXT_ID \ -H "Authorization: Bearer actx_sk_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Updated title", "messages": [...] }' Append messages without replacing the thread: curl -X PATCH https://airclippy.com/api/v1/contexts/CONTEXT_ID \ -H "Authorization: Bearer actx_sk_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "append": true, "messages": [ { "role": "assistant", "content": "Completed the API integration." } ] }' ## Minting Share Tokens curl -X POST https://airclippy.com/api/v1/contexts/CONTEXT_ID/share \ -H "Authorization: Bearer actx_sk_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "scopes": ["read", "append"], "ttlHours": 24, "label": "Agent B" }' Available scopes: read, append, write. The token is returned once in the response. ## Agent Integration Pattern The most common pattern: an agent pulls context at startup and optionally appends results. // 1. Pull context const res = await fetch(`https://airclippy.com/api/v1/share/${shareToken}`); const { context } = await res.json(); // 2. Use messages in your LLM call const completion = await openai.chat.completions.create({ model: "gpt-4o-mini", messages: context.messages, }); // 3. Append the agent's reply (if append scope granted) await fetch(`https://airclippy.com/api/v1/share/${shareToken}`, { method: "PATCH", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ append: true, messages: [{ role: "assistant", content: completion.choices[0].message.content }], }), }); This creates a self-updating context thread that grows with each agent run. ## Free Tier Limits - 50 private contexts per account - 10 API keys - Default 7-day context TTL (max 30 days) - 512 KB payload size per context - 500 messages maximum per context - 20 share grants per context These limits are generous for individual developers and small teams. See airclippy.com/ai-context/docs for the latest details. ## Error Handling The API returns standard HTTP status codes: - 401: Invalid or missing authentication token - 403: Insufficient scope for the requested operation - 404: Context or token not found (may have expired) - 413: Payload exceeds 512 KB limit - 429: Rate limit exceeded Always check for expired contexts and tokens in production agents. ## Security Best Practices - **Never commit API keys**: Use environment variables - **Use minimal scopes**: Grant read-only when agents do not need to write - **Set short token expiry**: 24 hours covers most handoff scenarios - **Revoke unused keys**: Remove keys for deprecated integrations - **Delete sensitive contexts**: Remove contexts containing confidential data when done ## Why Use AI Context API Over Alternatives Compared to saving chat logs in files, databases, or public clipboards: - **Structured format**: Standard messages array ready for LLM APIs - **Scoped access**: Share tokens limit what agents can do - **Automatic expiry**: No stale context accumulation - **No infrastructure**: No database setup or hosting required - **Agent-native**: Built specifically for AI agent handoff workflows ## Get Started 1. Sign in at airclippy.com/ai-context 2. Create an API key 3. Save your first context via curl or the dashboard 4. Mint a share token and integrate with your agent The AI Context API turns conversation history into a programmable resource. Build agents that remember, hand off, and continue — without rebuilding context every session.