Introduction

Layer speaks the upstream store’s native wire protocol, adding the fields it needs through x-layer-* headers, so pointing a client at the gateway just works — and gains stable reads, the document cache, and Layer’s enhanced search features without changing the requests you already send.

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["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

Every request carries Authorization: Bearer <key>. The gateway accepts two kinds of bearer:

• The store key. The default VectorStore credential (the turbopuffer key you already own) is accepted as an admin bearer. This is the drop-in default for a turbopuffer-backed store: point an existing client at the gateway and keep your key. No setup, full access.
• A minted key. Admin can mint keys scoped to a set of namespaces crossed with read/write — hand one to a team or a service without exposing the rest of the store. Minted keys are gateway-only and never work against the upstream directly. See API keys.

Routes are classified read, write, or admin; each endpoint page notes anything beyond the obvious (GET/query-shaped routes are read, namespace writes are write, Pipeline/Function/key management is admin). A request past a key’s scope or namespace grant answers 403 with the reason named.

Connection environment variables:

Additional language targets are added through the SDK harness rather than maintained by hand.

Gateway failures

The Python, Go, and TypeScript SDKs talk to the Layer gateway. If the gateway is unreachable, the original connection error is returned. SDKs do not retry directly against a backing store, because the server chooses that store from the namespace’s VectorStore and the client surface stays backend-neutral.

Enhancements to upstream routes

Cross-cutting conventions

These apply to every endpoint Layer proxies, whether the route is upstream-compatible or Layer-only.

• _hevlayer_* reserved. Document attributes prefixed with _hevlayer_ are reserved for the proxy layer. Writing to them is a validation error; reading them is fine when explicitly requested. The gateway stamps _hevlayer_upserted_at itself on every upsert and patch — a caller-supplied value is ignored and overwritten with the server’s epoch-ms watermark.
• Hard vs soft failures. The backing engine’s write and query failures are hard failures and return 5xx. Aerospike document-cache failures are soft and never block the response.
• x-layer-cache header. Fetch responses include hit, miss, or miss-on-error so callers can distinguish a cold cache from an outage.
• Response headers. Query pagination uses x-layer-next-cursor. See Response headers.

Compatibility posture