Introduction

Use the Layer clients or plain HTTP against your gateway URL. The local quickstart writes and queries rows through the gateway.

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/v2/namespaces" \
  -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

When fronting Turbopuffer with deriveFromStore, use the upstream API key as the gateway bearer token. Standalone configuration controls the connection and inbound authentication mode.

curl --fail-with-body http://localhost:8080/v2/namespaces \
  -H "Authorization: Bearer $TURBOPUFFER_API_KEY"

Client examples using LAYER_GATEWAY_URL refer to the gateway base URL. LAYER_GATEWAY_API_KEY is the bearer token for a keyed connection.

Gateway failures

SDKs return connection errors when the gateway is unreachable. They do not retry directly against a backing store. Store failures and unsupported request shapes remain visible to callers.

Gateway operations

Write rows, query, scan, embed, and federate.

Response metadata

Layer returns retrieval metadata in response headers. Generated clients expose those headers in their typed responses where supported.