@glidecms/gaia-sdk

TypeScript SDK for the Glide Gaia AI API. Semantic search, taxonomy/image/article suggestions, RAG-powered answers with SSE streaming, and content ingestion.

Zero runtime dependencies. Native fetch. Typed errors. Automatic retries with exponential backoff.

Install

npm install @glidecms/gaia-sdk

Requires Node.js >= 22.

Quick start

import { Client } from '@glidecms/gaia-sdk';

const gaia = new Client({
  baseUrl: 'https://gaia.your-tenant.gcpp.io',
  apiKey: 'your-api-key',
  tenantId: 'your-tenant-id',
});

const results = await gaia.searchArticles('inflation rate cut', { maxResults: 5 });
const suggestions = await gaia.suggestTaxonomies(
  { headline: 'Markets rally on Fed decision', body_plain: 'Stock markets surged today...' },
  { maxSuggestions: 5 },
);

API methods

All methods are on the Client instance directly (no sub-clients):

| Category | Methods | |---|---| | Health & config | health(), getConfig(), listTaxonomies(), listSuggestionExamples(), listSampleArticles() | | Search | searchArticles(query, options?, opts?), searchImages(query, options?, opts?) | | Suggestions | suggestTaxonomies(input, options?, opts?), suggestImages(input, options?, opts?), suggestArticles(input, options?, opts?), findSimilarArticlesByIds(ids, options?, opts?) | | RAG answers | answer(query, options?, opts?) — SSE streaming via AsyncGenerator<AnswerEvent> | | Generate | generateTaxonomyDescription(input) | | Ingest | ingestTaxonomies(items), ingestArticles(items), ingestImages(items) | | Agent metadata | capabilities.describe(), capabilities.listOperations() |

AI-assisted usage

For SDK selection, safe defaults, task-oriented method guidance, and mutation guardrails, see Agent guide.

Documentation

| | | |---|---| | How-to guides | Configuration, search, suggestions, streaming answers, ingestion, error handling, request options | | API reference | Full method signatures, option types, return types, errors | | Migration notes | Clearer method names and deprecated aliases | | Agent guide | Agent/MCP usage guidance and capabilities metadata |

Guarantees

• Timeouts. Default 30s for API calls, 5s for health(). Per-request override via opts.timeout.
• Cancellation. All methods accept AbortSignal. Aborted requests throw immediately without retry.
• Retry. 5xx and network errors retried with exponential backoff. 4xx, aborts, and timeouts are never retried.
• Rate limiting. 429 responses throw GaiaRateLimitError with retryAfter populated.
• health(). Validates response status. Non-2xx throws typed GaiaError.
• answer() streaming. Early exit from the async generator cancels the upstream HTTP connection and stops server-side generation. Timeout and abort are distinguished from network failures.
• Config validation. Constructor throws immediately if baseUrl, apiKey, or tenantId is missing or empty.
• Agent capabilities. client.capabilities.describe() returns JSON-safe metadata for tool planning.
• Deduplication. Concurrent identical GETs without per-request opts share one fetch. GETs with opts always make independent requests.