API Reference

Everything you need to store and retrieve key-value pairs and ordered lists via a simple REST API.

Base URL: https://lightkv.com
All endpoints use JSON request/response bodies and require a Bearer token.

Authentication

All data endpoints require an app token passed in the Authorization header.

Header
Authorization: Bearer YOUR_APP_TOKEN

Each app has two tokens:

TokenPermissionEndpoints
read_tokenRead-onlyAll GET endpoints
readwrite_tokenFull accessAll endpoints
⚠ Tokens are only shown once — at app creation or after rotation. Store them securely.

Response Format

All responses follow a consistent envelope:

Success
{ "ok": true, "data": <result> }
Error
{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Key 'foo' not found"
  }
}

Item Endpoints

Store and retrieve individual key-value pairs. Values can be any JSON primitive: string, number, boolean, or null.

POST /item/write

Create or overwrite a key-value pair. Requires the readwrite_token.

Request
curl -X POST https://lightkv.com/item/write \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "user:42:score", "value": 9001}'
Response
{ "ok": true, "data": { "key": "user:42:score", "value": 9001 } }

GET /item/read?key=KEY

Read a value by key. Works with either token.

Request
curl https://lightkv.com/item/read?key=user:42:score \
  -H "Authorization: Bearer TOKEN"
Response
{ "ok": true, "data": { "key": "user:42:score", "value": 9001 } }

DELETE /item/delete?key=KEY

Delete a key. Requires the readwrite_token.

Request
curl -X DELETE https://lightkv.com/item/delete?key=user:42:score \
  -H "Authorization: Bearer TOKEN"

GET /item/exists?key=KEY

Check if a key exists. Returns true or false.

Response
{ "ok": true, "data": true }

GET /item/keys?prefix=PREFIX

List all keys, optionally filtered by prefix.

Response
{ "ok": true, "data": ["user:42:score", "user:42:rank"] }

List Endpoints

Manage ordered collections of values. Lists support set semantics — duplicates are automatically removed on write/add.

POST /list/write

Create or overwrite a list. Requires the readwrite_token.

Request
curl -X POST https://lightkv.com/list/write \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "online-users", "values": ["alice", "bob", "carol"]}'

GET /list/read?key=KEY

Read all values in a list.

Response
{ "ok": true, "data": ["alice", "bob", "carol"] }

POST /list/add

Append values to a list. Existing values are not duplicated.

Request
curl -X POST https://lightkv.com/list/add \
  -H "Authorization: Bearer TOKEN" \
  -d '{"key": "online-users", "values": ["dave"]}'

POST /list/remove

Remove specific values from a list.

Request
curl -X POST https://lightkv.com/list/remove \
  -H "Authorization: Bearer TOKEN" \
  -d '{"key": "online-users", "values": ["bob"]}'

POST /list/purge

Delete an entire list.

Request
curl -X POST https://lightkv.com/list/purge \
  -H "Authorization: Bearer TOKEN" \
  -d '{"key": "online-users"}'

GET /list/exists?key=KEY&value=VAL

Check if a list exists (key only), or if a specific value exists in the list (key + value).

Check list exists
GET /list/exists?key=online-users
→ { "ok": true, "data": true }
Check value in list
GET /list/exists?key=online-users&value=alice
→ { "ok": true, "data": true }

GET /list/index?key=KEY&value=VAL

Get the index of a value in a list. Returns -1 if not found.

Response
{ "ok": true, "data": 2 }

GET /list/count?key=KEY

Get the number of items in a list.

Response
{ "ok": true, "data": 3 }

GET /list/slice?key=KEY&start=N&end=N

Get a subset of the list. end is inclusive.

Request & Response
GET /list/slice?key=online-users&start=0&end=1
→ { "ok": true, "data": ["alice", "bob"] }

GET /list/keys?prefix=PREFIX

List all list keys, optionally filtered by prefix.

Response
{ "ok": true, "data": ["online-users", "online-mods"] }