Introduction

Layer supports migration through a Turbopuffer-compatible wire subset and adds gateway features across its backends, including agentic search. Compatibility is the entry point; the full Layer API is available through the Layer clients for Community Edition and Pro. The gateway selects the backend. Each API page describes the current integration’s supported features and gaps.

Install

There are four ways to call Layer: the Python client, the Go client, the TypeScript client, and the REST API itself. The clients are generated from apps/layer-gateway/openapi.yaml, so all four expose the same operations — every endpoint page on this site shows them side by side. Anything the clients can do, plain HTTP can do.

pip install hevlayer                      # Python 3.11+
go get github.com/hev/layer-go            # Go 1.22+
npm install hevlayer                      # Node 18+

Point a client at the gateway:

import os

from hevlayer import AsyncHevlayer

client = AsyncHevlayer(
    base_url=os.environ["LAYER_GATEWAY_URL"],
    api_key=os.environ.get("LAYER_GATEWAY_API_KEY", ""),
)

import (
    "os"

    hevlayer "github.com/hev/layer-go"
)

client := hevlayer.NewClient(
    hevlayer.WithBaseURL(os.Getenv("LAYER_GATEWAY_URL")),
    hevlayer.WithAPIKey(os.Getenv("LAYER_GATEWAY_API_KEY")),
)

import { Hevlayer } from "hevlayer";

const client = new Hevlayer({
  baseUrl: process.env.LAYER_GATEWAY_URL,
  apiKey: process.env.LAYER_GATEWAY_API_KEY,
});

curl "$LAYER_GATEWAY_URL/health" \
  -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY"

Code examples across these pages assume this client — and in Go, a ctx context.Context. The cURL tab on each page is the bare REST contract; any HTTP stack works the same way.

Authentication

Set LAYER_GATEWAY_URL to the gateway origin, without /v2. Set LAYER_GATEWAY_API_KEY to the inbound bearer token when the gateway requires one. An isolated local gateway configured with inboundAuth.mode: open needs no token. Engine credentials belong on the gateway, not in application code.

The local Postgres quickstart is open by default. See configuration before exposing the gateway.

Routes enforce read, write or admin authorization and namespace grants. A request outside a key’s scope returns 403. Configure the gateway’s inbound authentication separately from its engine connection.

Gateway failures

Clients return connection errors when the gateway is unreachable. They do not retry directly against a backing store. Unsupported store features return 422 UnsupportedByStore; malformed input and gateway validation errors are reported separately. A client method’s existence does not establish support for every backend.

Gateway operations

Start with write and query. Other routes include scans, embedding, federation and metadata. The same clients call the entire Layer API, including operations outside the compatible subset. Backend-specific notes remain beside the affected examples.

Response metadata

Layer returns retrieval metadata in response headers. Use the generated clients’ performance response options where needed. Stable-watermark and pagination headers depend on the backend and query mode; they are not guarantees made by every store.