REST API - Lark

Lark exposes a REST API for reading and writing data over plain HTTP. If you’re working from a server, a script, a CLI tool, or any environment where you don’t want to maintain a persistent connection, the REST API is the way to go.

URL format

Every REST request targets a path in a database, with .json appended. The database goes in the subdomain, separated from your project ID by --:

https://{database}--{projectId}.larkdb.net/{path}.json

For example, to access /players/alice in the my-game database of project chess-app:

https://my-game--chess-app.larkdb.net/players/alice.json

The root of the database:

https://my-game--chess-app.larkdb.net/.json

The default database

If you leave the database out of the subdomain, Lark routes to a database named default:

https://chess-app.larkdb.net/players/alice.json

That request is identical to:

https://default--chess-app.larkdb.net/players/alice.json

Authentication

Pass an auth token as a query parameter:

GET https://my-game--chess-app.larkdb.net/players.json?auth=YOUR_TOKEN

The auth parameter accepts any token that Lark supports: Lark tokens (HS256 JWTs signed with your secret key) or Firebase Auth tokens. You can also use access_token as an alias:

GET https://my-game--chess-app.larkdb.net/players.json?access_token=YOUR_TOKEN

If you omit the token, the request is treated as anonymous. Your security rules determine what anonymous clients can access.

Operations at a glance

HTTP method	Operation	Description
`GET`	Read	Fetch data at a path
`PUT`	Set	Replace data at a path
`POST`	Push	Add a child with an auto-generated key
`PATCH`	Update	Merge data at a path
`DELETE`	Remove	Delete data at a path

When to use the REST API

Reading or writing data from your backend without maintaining a WebSocket connection.
One-off scripts to import data, seed a database, or run migrations.
Receiving a webhook and writing to Lark with a single HTTP call.
Edge functions, serverless workers, or other runtimes without WebSocket support.
Quick reads with curl to inspect your data.

For real-time subscriptions and persistent connections, use the Lark SDK or Firebase SDKs instead.

Quick example

# Write data
curl -X PUT \
  'https://my-game--chess-app.larkdb.net/players/alice.json?auth=YOUR_TOKEN' \
  -d '{"name": "Alice", "score": 0}'

# Read it back
curl 'https://my-game--chess-app.larkdb.net/players/alice.json?auth=YOUR_TOKEN'
# {"name":"Alice","score":0}

# Update a single field
curl -X PATCH \
  'https://my-game--chess-app.larkdb.net/players/alice.json?auth=YOUR_TOKEN' \
  -d '{"score": 42}'

# Push a new child with auto-generated key
curl -X POST \
  'https://my-game--chess-app.larkdb.net/messages.json?auth=YOUR_TOKEN' \
  -d '{"text": "Hello!", "sender": "alice"}'
# {"name":"-Kabc123xyz"}

# Delete data
curl -X DELETE \
  'https://my-game--chess-app.larkdb.net/players/alice.json?auth=YOUR_TOKEN'

What’s next

Reading data

GET requests, shallow reads, queries, and formatting options.

Writing data

PUT, POST, PATCH, DELETE, multi-path updates, and server values.

Streaming

Server-Sent Events for real-time updates over HTTP.

Conditional requests

ETags and compare-and-swap for safe concurrent writes.

​URL format

​The default database

​Authentication

​Operations at a glance

​When to use the REST API

​Quick example

​What’s next