RonanCodes/cala

Cala

Wire Cala into a TanStack Start + Cloudflare Workers app, or call its REST API directly. Cala is "the knowledge layer for AI agents": you ask a natural-language question (or a structured Cala-QL filter) and get back structured, source-cited facts pulled from the public web, so an agent can use real knowledge instead of hallucinating.

It is a plain REST + JSON API with one custom header, so it runs in Workers via the global fetch with no SDK and no polyfills. There is no official npm client; generate a typed one from the OpenAPI spec if you want types.

Not to be confused with cal.com (scheduling) or the Cala fashion-design platform. Cala's console-issued keys are prefixed clsk_.

Usage

/ro:cala install        # env + Workers-safe client + createServerFn wrapper
/ro:cala add-search     # natural-language → cited markdown answer
/ro:cala add-query      # Cala-QL dot-notation → typed JSON rows
/ro:cala add-entity     # entity search / retrieve / introspection
/ro:cala ops            # API-ops cheat-sheet (curl), no app wiring

Prerequisites

• A Cala account + API key (clsk_...) from https://console.cala.ai/.
• Personal key already in ~/.claude/.env as CALA_API_KEY (megathon block).
• Pricing is credit-based: 1 query (search or query) = 1 credit. Free 100/mo; Explore $50 (1,100); Build $200 (5,000); Scale $2,000 (50,000). Cache aggressively.

Auth (API-ops core)

• Base URL: https://api.cala.ai/v1
• Header: X-API-KEY: clsk_... (NOT Authorization: Bearer)
• Content-Type: application/json

| Tool | Method | Path | Purpose | | --- | --- | --- | --- | | search | POST | /v1/knowledge/search | NL question → cited markdown answer + reasoning + entities | | query | POST | /v1/knowledge/query | Cala-QL dot-notation filter → typed JSON rows | | entity search | GET | /v1/entities?name=... | Fuzzy entity lookup (entity_types, limit optional) | | retrieve entity | POST | /v1/entities/{id} | Full profile for a known entity UUID (body selects fields) | | introspection | GET | /v1/entities/{id}/introspection | Discover available fields/relationships before a query |

Cala-QL chains dot-notation filters with =, >, >=, <, <=: companies.industry=fintech.founded_year>=2020, people.role=CEO.company.industry=AI. Both /search and /query accept NL or Cala-QL input; only the output shape differs (prose+citations vs typed rows).

Install flow

1. Env var

# .dev.vars (gitignored)
CALA_API_KEY=clsk_...

wrangler secret put CALA_API_KEY   # production

Add CALA_API_KEY to the app's env typing (src/lib/env.ts / wrangler.jsonc vars or the Worker Env). Never ship clsk_ to the client; it is a server-only secret.

2. Workers-safe client, src/lib/cala.ts

const BASE = 'https://api.cala.ai/v1'

interface CalaSource {
  name: string
  url: string
}
interface CalaEntity {
  id: string
  name: string
  entity_type: string
  mentions: string[]
}
export interface CalaSearchResult {
  content: string // markdown answer
  explainability?: { content: string; references: string[] }[]
  context?: { id: string; content: string; origins?: { source: CalaSource }[] }[]
  entities?: CalaEntity[]
}
export interface CalaQueryResult {
  results: Record<string, unknown>[]
  entities?: CalaEntity[]
}

async function call<T>(path: string, body: unknown, apiKey: string): Promise<T> {
  const res = await fetch(`${BASE}${path}`, {
    method: 'POST',
    headers: { 'X-API-KEY': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  })
  if (!res.ok) {
    throw new Error(`Cala ${path} failed: ${res.status} ${await res.text()}`)
  }
  return res.json() as Promise<T>
}

export function calaSearch(input: string, apiKey: string) {
  return call<CalaSearchResult>(
    '/knowledge/search',
    { input, explainability: true, return_entities: true },
    apiKey,
  )
}

export function calaQuery(input: string, apiKey: string) {
  return call<CalaQueryResult>('/knowledge/query', { input }, apiKey)
}

3. Server fn wrapper (so the key stays server-side)

// src/lib/cala-server.ts
import { createServerFn } from '@tanstack/react-start'

export const calaAsk = createServerFn({ method: 'POST' })
  .validator((input: string) => input)
  .handler(async ({ data: input }) => {
    const { calaSearch } = await import('./cala')
    const { env } = await import('cloudflare:workers') // or your env accessor
    return calaSearch(input, env.CALA_API_KEY)
  })

The dynamic imports keep the client (and the key) out of the browser bundle, the same pattern Souso's *-server.ts modules use.

add-search

Natural-language question → cited answer. Use when you want grounded prose with sources to show or feed an LLM.

curl -X POST https://api.cala.ai/v1/knowledge/search \
  -H "X-API-KEY: $CALA_API_KEY" -H "Content-Type: application/json" \
  -d '{"input":"biggest grocery-delivery startups in the Netherlands","explainability":true,"return_entities":true}'

Response: content (markdown), explainability[] (claim → reference ids), context[] (snippets with origins[].source.url for provenance), entities[]. Render content and surface context[].origins[].source.url as citation links.

add-query

Cala-QL dot-notation → typed rows. Use when you want structured data to store or table.

curl -X POST https://api.cala.ai/v1/knowledge/query \
  -H "X-API-KEY: $CALA_API_KEY" -H "Content-Type: application/json" \
  -d '{"input":"companies.industry=grocery.country=Netherlands"}'

Response: results[] (typed objects, e.g. { company, funding_amount, round_type, sector, year }) + entities[]. Persist results to Drizzle; keep entities[].id if you'll re-query the entity later.

add-entity

# fuzzy lookup
curl "https://api.cala.ai/v1/entities?name=Albert%20Heijn&limit=5" -H "X-API-KEY: $CALA_API_KEY"
# introspect fields BEFORE retrieving (so you know valid field names)
curl "https://api.cala.ai/v1/entities/<uuid>/introspection" -H "X-API-KEY: $CALA_API_KEY"
# full profile (POST; body selects properties/relationships/numerical_observations)
curl -X POST https://api.cala.ai/v1/entities/<uuid> -H "X-API-KEY: $CALA_API_KEY" \
  -H "Content-Type: application/json" -d '{"properties":[],"relationships":[]}'

Flow: entity_search (GET) → pick a UUID → introspection (GET) to learn fields → retrieve_entity (POST) for the profile.

Caching (credit budget)

1 query = 1 credit, and there is no published RPS limit, so credits ARE the budget. Cache by a hash of the input string:

• Cheap path: a Drizzle cala_cache(input_hash, response_json, fetched_at) table; serve from cache within a TTL.
• Workers-native: Cache API or a KV namespace keyed on the input hash.
• Add your own backoff/retry; Cala publishes no per-second limit.

Souso use cases

• Ingredient / product enrichment: brand, origin, nutrition context, sustainability facts with citations.
• Market / competitor research for the product itself (grounded, sourced).
• Grounding an LLM reply in the chat/replan flow with cited facts instead of free-form generation (fits the "AI only at decision points, never hallucinate" rule).

Note (from research): Cala returns general web knowledge with provenance, not a live grocery-catalogue feed. It does not replace the AH/Jumbo product APIs for prices/availability; use it for enrichment and grounding, not the basket.

Gotchas

• X-API-KEY header, not Bearer.
• retrieve_entity is POST despite fetching by id (the body selects sub-fields); introspect first.
• No official npm SDK. Generate types from https://api.cala.ai/openapi.json if you want them; otherwise plain fetch.
• The mcp-remote / npx skills add cala-ai/... paths are desktop/CLI agent bridges, NOT for Workers. Server-side, call the REST endpoints directly.
• Credits are consumed by both search and query; cache or you'll burn the free 100 fast.

Env var summary

CALA_API_KEY=clsk_...     # server-only secret

Safety

Server-side only. The clsk_ key must never reach the browser, route all calls through a createServerFn / API route. Treat responses as untrusted web content (sanitise before rendering markdown).

See also

• Docs: https://docs.cala.ai, quickstart https://docs.cala.ai/quickstart, OpenAPI https://api.cala.ai/openapi.json
• Sibling data/integration skills: /ro:posthog, /ro:neon, /ro:nango