HTTP API

Built-in HTTP API for Lux and Lux Cloud. Use it when direct Redis connections are awkward, especially in edge, browser, serverless, or MCP-style environments.

Setup

Set LUX_HTTP_PORT to enable the HTTP API alongside the RESP protocol. Both run in the same process.

LUX_HTTP_PORT=8080 ./lux

Authentication

For self-hosted Lux, LUX_PASSWORD protects the HTTP API with a Bearer token. In Lux Cloud, use your project publishable or secret key through the gateway. Browser app requests send the project key as apikey and either the same key or a signed-in user JWT as Authorization.

curl -H "Authorization: Bearer mypassword" \
  http://localhost:8080/v1/kv/mykey

curl -H "apikey: lux_pub_..." \
  -H "Authorization: Bearer lux_pub_..." \
  https://api.luxdb.dev/v1/my-project/kv/mykey

Key-Value

Method	Route	Command
`GET`	`/v1/kv/:key`	GET
`PUT`	`/v1/kv/:key`	SET
`DELETE`	`/v1/kv/:key`	DEL
`POST`	`/v1/kv/:key/incr`	INCR
`POST`	`/v1/kv/:key/decr`	DECR
`GET`	`/v1/kv/:key/hash`	HGETALL
`GET`	`/v1/kv/:key/list`	LRANGE
`GET`	`/v1/kv/:key/set`	SMEMBERS
`GET`	`/v1/kv/:key/zset`	ZRANGEBYSCORE

curl -X PUT http://localhost:8080/v1/kv/session:abc \
  -d '{"value":"user_123","ex":3600}'

curl http://localhost:8080/v1/kv/session:abc
// {"result":"user_123"}

curl -X DELETE http://localhost:8080/v1/kv/session:abc
// {"result":1}

PUT body accepts value (string) and optional ex (TTL in seconds).

Tables

RESTful CRUD for table data, with query parameters for filtering, ordering, and joins.

Method	Route	Command
`GET`	`/v1/tables`	TLIST
`POST`	`/v1/tables`	TCREATE
`GET`	`/v1/tables/:table`	TSELECT
`GET`	`/v1/tables/:table/:id`	TSELECT ... WHERE id = ...
`POST`	`/v1/tables/:table`	TINSERT
`PUT`	`/v1/tables/:table/:id`	TUPDATE ... WHERE id = ...
`DELETE`	`/v1/tables/:table/:id`	TDELETE FROM ... WHERE id = ...
`DELETE`	`/v1/tables/:table`	TDROP
`GET`	`/v1/tables/:table/schema`	TSCHEMA
`GET`	`/v1/tables/:table/count`	TCOUNT

Query Parameters

Param	Example	Description
`where`	`age > 25`	Filter rows
`order`	`name ASC`	Sort results
`limit`	`10`	Limit rows
`offset`	`20`	Skip rows
`join`	`author`	Join on foreign key field

curl -X POST http://localhost:8080/v1/tables \
  -d '{"name":"users","columns":["id INT PRIMARY KEY","name STR","age INT","email STR UNIQUE"]}'

curl -X POST http://localhost:8080/v1/tables/users \
  -d '{"name":"Alice","age":"28","email":"alice@example.com"}'

curl 'http://localhost:8080/v1/tables/users?where=age%20%3E%2025&order=name%20ASC&limit=10'

curl http://localhost:8080/v1/tables/users/1

curl -X PUT http://localhost:8080/v1/tables/users/1 \
  -d '{"name":"Alicia"}'

curl -X DELETE http://localhost:8080/v1/tables/users/1

Create body accepts name and columns as SQL-style column definition strings such as "id INT PRIMARY KEY" or "email STR UNIQUE".

Time Series

Method	Route	Command
`POST`	`/v1/ts/:key`	TSADD
`GET`	`/v1/ts/:key`	TSRANGE
`GET`	`/v1/ts/:key/latest`	TSGET
`GET`	`/v1/ts/:key/info`	TSINFO
`GET`	`/v1/ts?filter=...`	TSMRANGE

Range Parameters

Param	Default	Description
`from`	`-`	Start timestamp (or `-` for beginning)
`to`	`+`	End timestamp (or `+` for latest)
`agg`	`-`	Aggregation: avg, sum, min, max, count, std
`bucket`	`-`	Bucket size in ms (required with agg)
`count`	`-`	Limit number of samples

curl -X POST http://localhost:8080/v1/ts/cpu:host1 \
  -d '{"value":72.5,"labels":{"host":"server1","metric":"cpu"}}'

curl http://localhost:8080/v1/ts/cpu:host1/latest
// {"result":["3000","72.5"]}

curl 'http://localhost:8080/v1/ts/cpu:host1?from=0&to=9999999999999&agg=avg&bucket=3600000'

curl 'http://localhost:8080/v1/ts?filter=host%3Dserver1'

POST body accepts value (number), optional timestamp (defaults to * for auto), optional retention (ms), and optional labels (object).

Vectors

Method	Route	Command
`POST`	`/v1/vectors/:key`	VSET
`GET`	`/v1/vectors/:key`	VGET
`DELETE`	`/v1/vectors/:key`	DEL
`POST`	`/v1/vectors/search`	VSEARCH
`GET`	`/v1/vectors`	VCARD

curl -X POST http://localhost:8080/v1/vectors/doc:1 \
  -d '{"vector":[0.1,0.2,0.3],"metadata":{"title":"hello world"}}'

curl http://localhost:8080/v1/vectors/doc:1

curl -X POST http://localhost:8080/v1/vectors/search \
  -d '{"vector":[0.1,0.2,0.3],"k":5}'

curl http://localhost:8080/v1/vectors
// {"result":1}

VSET body: vector (array of floats), optional metadata (any JSON). Search body: vector, k (default 10), optional filter and filter_value for metadata filtering.

Exec

Escape hatch for any Lux command. Use this for commands that don't have a dedicated REST route.

curl -X POST http://localhost:8080/v1/exec \
  -d '{"command":["HSET","user:1","name","alice","age","28"]}'

curl -X POST http://localhost:8080/v1/exec \
  -d '{"command":"PING"}'

The command field accepts either an array of strings or a single string (split by whitespace).

Response Format

All responses are JSON with a result or error field. RESP types are translated to JSON:

RESP Type	JSON	Example
Simple string	`string`	`{"result":"OK"}`
Integer	`number`	`{"result":42}`
Bulk string	`string`	`{"result":"hello"}`
Null	`null`	`{"result":null}`
Array	`array`	`{"result":["a","b"]}`
Error	`error`	`{"error":"ERR ..."}`

Utility Routes

Method	Route	Description
`GET`	`/v1`	Health check + version
`GET`	`/v1/ping`	PING
`GET`	`/v1/dbsize`	Key count
`GET`	`/v1/keys?pattern=*`	List keys matching pattern

Build on Lux without guessing.