Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.larksh.com/llms.txt

Use this file to discover all available pages before exploring further.

Write data by sending PUT, POST, PATCH, or DELETE requests. The request body is JSON.

​
Set (PUT)

Replace the data at a path completely. Any existing data at that path is overwritten. 
curl -X PUT \
  'https://chess-app.larkdb.net/my-game/players/alice.json?auth=YOUR_TOKEN' \
  -d '{"name": "Alice", "score": 250, "online": true}'
Response (echoes the written data): 
{
  "name": "Alice",
  "score": 250,
  "online": true
}
PUT to a path that doesn’t exist creates it. PUT to a path that does exist replaces it entirely. Missing fields are deleted, not preserved.

​
Push (POST)

Add a new child with an auto-generated key. This is the REST equivalent of push() in the SDKs. 
curl -X POST \
  'https://chess-app.larkdb.net/my-game/messages.json?auth=YOUR_TOKEN' \
  -d '{"text": "Hello!", "sender": "alice", "timestamp": {".sv": "timestamp"}}'
Response: 
{
  "name": "-Kabc123def"
}
The name field contains the generated key. Push IDs are chronologically sortable, so later posts sort after earlier ones.
Use POST for append-only data like chat messages, event logs, or queue items where each entry needs a unique key.

​
Update (PATCH)

Merge data into an existing path. Only the specified keys are modified; everything else is preserved. 
curl -X PATCH \
  'https://chess-app.larkdb.net/my-game/players/alice.json?auth=YOUR_TOKEN' \
  -d '{"score": 300, "lastSeen": {".sv": "timestamp"}}'
This updates Alice’s score and lastSeen without touching name or online.

​
Multi-path updates

Update multiple locations atomically by using paths as keys in your PATCH body at a higher level: 
curl -X PATCH \
  'https://chess-app.larkdb.net/my-game/.json?auth=YOUR_TOKEN' \
  -d '{
    "players/alice/score": 300,
    "players/bob/score": 275,
    "leaderboard/first": "alice",
    "leaderboard/second": "bob"
  }'
All four updates happen atomically. Either they all succeed or none do. Multi-path updates are the way to keep denormalized data consistent.

​
Remove (DELETE)

Delete data at a path. 
curl -X DELETE \
  'https://chess-app.larkdb.net/my-game/players/alice.json?auth=YOUR_TOKEN'
Returns null on success. Deleting a non-existent path succeeds silently.

​
Server values

Use {".sv": "timestamp"} to write the server’s current timestamp: 
curl -X PUT \
  'https://chess-app.larkdb.net/my-game/players/alice/lastSeen.json?auth=YOUR_TOKEN' \
  -d '{".sv": "timestamp"}'
The server replaces {".sv": "timestamp"} with the actual Unix timestamp in milliseconds.

​
Silent writes

If you don’t need the response body (saving bandwidth), add print=silent: 
curl -X PUT \
  'https://chess-app.larkdb.net/my-game/players/alice/score.json?auth=YOUR_TOKEN&print=silent' \
  -d '500'
Returns 204 No Content instead of echoing the written data.

​
Error responses

When a write fails, you get an error object: 
{
  "error": "permission_denied",
  "message": "You do not have permission to write to this path"
}
Status codeMeaning
200Write succeeded
204Write succeeded (with print=silent)
400Invalid JSON or bad request
403Security rules denied the write
401Authentication required