GRIP OS by Caugia

Authentication

All requests use a Bearer API key. Keys are scoped to a single Caugia workspace; the workspace is implied by the key, never passed as a parameter.

Authorization: Bearer sk_caugia_<your_secret>

Create and revoke keys at /admin/integrations. Plaintext is returned once at creation and never again.

POST /api/v1/chat

Run one Sophie turn. Pass a user message and optional conversation history. The response mirrors the internal brain response: the answer plus the reasoning trace, RAG hits, and confidence verdict.

Request

{
  "message": "What's my binding constraint and what's it costing me?",
  "history": [
    { "role": "user", "content": "hi" },
    { "role": "assistant", "content": "Hi, I'm Sophie." }
  ],
  "mode": "operator",
  "source": "my-crm-integration"
}

Response

{
  "response": "Your binding constraint is D03: PMF narrative broken...",
  "reasoning_trace": [
    { "hop": 0, "tool": "get_constraint_details", "input_summary": "{}", "result_summary": "{ constraint: ... }" }
  ],
  "rag_hits": [
    { "title": "Aligned on Paper", "source": "Caugia archetype library §2.1" }
  ],
  "confidence": {
    "score": 0.88,
    "level": "high",
    "totalClaims": 8,
    "verifiedClaims": 7,
    "verdicts": [ ... ]
  }
}

Rate limit

60 requests per minute per key. Exceeding returns 429 with retry_after_seconds.

Examples

curl

curl https://os.caugia.com/api/v1/chat \
  -H "Authorization: Bearer sk_caugia_..." \
  -H "Content-Type: application/json" \
  -d '{"message":"What is my binding constraint?"}'

TypeScript (fetch)

const res = await fetch('https://os.caugia.com/api/v1/chat', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SOPHIE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: 'What is my binding constraint?',
    mode: 'operator',
  }),
});
const { response, confidence } = await res.json();
console.log(response, 'confidence:', confidence.level);

TypeScript (SDK)

// npm i @caugia/sophie (coming soon)
import { SophieClient } from '@caugia/sophie';

const sophie = new SophieClient({ apiKey: process.env.SOPHIE_API_KEY! });
const turn = await sophie.chat('What is my binding constraint?');
console.log(turn.response);

Python

import os, httpx

async def ask_sophie(message: str) -> dict:
    async with httpx.AsyncClient(timeout=60) as c:
        r = await c.post(
            "https://os.caugia.com/api/v1/chat",
            headers={"Authorization": f"Bearer {os.environ['SOPHIE_API_KEY']}"},
            json={"message": message, "mode": "operator"},
        )
        r.raise_for_status()
        return r.json()

Modes

The mode parameter switches Sophie's persona:

operator — internal constraint diagnosis (default for founders / CROs)
customer — sales + customer conversations
support — product help + troubleshooting
success — adoption + expansion

Errors

400 — missing / invalid message
401 — invalid or revoked API key
429 — rate limit exceeded; honour Retry-After
502 — upstream model unavailable; retry with backoff