Skip to content

Developers

Build on the state layer

Telha exposes one engine through three surfaces (REST, gRPC, and MCP) plus two client SDKs. This section is the practical reference for building applications, integrations, and agents against it.

  • Query language

    The JSON query DSL: find, where operators, expand, vector, temporal coordinates, cursors, and the living fixture corpus.

    Query DSL

  • REST API

    Every /v1 endpoint: records, query, snapshot, compare, schema, ingest, generate, trace, and the OpenAPI document.

    REST reference

  • gRPC API

    The app-layer and worker services, tenant/worker token auth, deadlines, and the protobuf contracts.

    gRPC reference

  • MCP tools

    The Model Context Protocol server for agents: findRecords, getHistory, semanticSearch, generate, getTrace, and shaping.

    MCP tools

  • TypeScript SDK

    @telha/sdk: REST and gRPC transports, the typed error taxonomy, retries, and token helpers.

    TypeScript SDK

  • Python SDK

    telha: an httpx + pydantic REST client with ingest wrappers and the same error taxonomy.

    Python SDK

  • Ingestion

    Formats, the sync-vs-async split, dedup, provenance spans, and streaming multi-submit for large files.

    Ingestion

  • Generation & traces

    /v1/generate, the SSE contract, claim verification verdicts, and the immutable generation trace.

    Generation & traces

  • Error reference

    The uniform error envelope and every code the API can return, by HTTP status and gRPC mapping.

    Errors

Conventions used across every surface

Convention Rule
Auth x-api-key header (REST) or a signed tenant token (gRPC/MCP). Scope is never taken from request bodies.
Scope Every operation is bound to a (tenant, organization) pair by the key or token, not by user input.
Errors Uniform envelope {"code", "message", "request_id"}; x-request-id on every response.
Time Microseconds since epoch, or RFC3339 strings where a time coordinate is accepted.
Predicates where values are operator objects ({"$eq": …}); bare scalars are rejected.
Grammar of record core-engine/tests/fixtures/query_corpus.json (every valid and invalid shape, pinned by tests).

The fastest way in

Run the Quickstart end to end with curl, then pick the SDK for your language. The query corpus is the authoritative grammar; the SDKs and MCP tools all speak the same DSL.