Org-context queries — natural-language Q&A over your Turtini org

The Public API has a single-turn natural-language endpoint at POST /v1/org-context/query that answers questions about the connected org in plain English. It's grounded in your real state (modules enabled, top-line counts, recent integration activity) — not freeform model output.

This is the "Layer D" bridge in Turtini's developer-platform stack. It pairs naturally with @turtini/mcp: AI agents in Cursor / Claude Code / Windsurf call it when they need org-level context the typed list/read endpoints can't easily express.

When to use it (vs. typed endpoints):
• Use this for fuzzy, summary-style questions: "what shipped this week?", "what modules does this org have?", "are there any pending hosted-site deploys?"
• Use the typed endpoints (GET /v1/contacts, etc.) for specific record lookups, exact counts, or anything you'll act on programmatically. The model is told NOT to invent specific numbers — for those it directs the caller to the typed API.

Auth:
• Required scope: context:read
• Covered by *:read wildcard (so a "read everything" key works without an extra grant)

Request:
POST https://api.turtini.com/v1/org-context/query
Authorization: Bearer turtini_<your-key>
Content-Type: application/json

{ "query": "summarize the last week of activity" }

Response:
{
"answer": "Over the last week, your org…",
"org": { "orgId": "...", "orgName": "...", "orgSlug": "..." },
"usage": { "inputTokens": 421, "outputTokens": 187, "cacheReadTokens": 380, "cacheCreateTokens": 0 }
}

Cost & caching: the system prompt is identical for every query against the same org and is sent with prompt caching turned on. Repeat queries from the same org get an ~80% input-token discount on cache hits, so the bridge is cheap to use at scale.

What the model sees:
• Your org name + slug
• Active Turtini modules (Builder, Accounting, Email Campaigns, etc.)
• Top-line counts: contacts, accounts, opportunities, articles, events
• The last 5 integration events (GitHub exports, hosted deploys, key creations) with timestamps
• The query

What the model does NOT see:
• Specific record contents (no contact emails, no opportunity amounts, no article bodies)
• Other orgs' data
• Anything the API key's scopes don't cover

From the SDK:
import { Turtini } from '@turtini/sdk/api'

const t = new Turtini({ apiKey: process.env.TURTINI_API_KEY! })
const { answer } = await t.context.query('what shipped this week?')

From an AI IDE: configure @turtini/mcp once (see "@turtini/mcp" article) and the agent picks this up automatically as the org_context_query tool whenever you ask org-level questions.

Limits:
• 4_000-character query body
• 1_024-token answer
• Single-turn (no conversation history)

If you need multi-turn org-grounded conversation, the in-app Wally interface is the right surface — it has tool-calling, image attachments, streaming, and tracks conversation history. The Public API bridge is for one-shot calls from external code.