> ## 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.

# REST API

> Read and write data over HTTP, no SDK required

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](/platform/authentication) (HS256 JWTs signed with your secret key) or [Firebase Auth tokens](/firebase/auth).

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](/platform/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](/lark-sdk/overview) or [Firebase SDKs](/firebase/overview) instead.

## Quick example

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Reading data" icon="book-open" href="/rest-api/reading">
    GET requests, shallow reads, queries, and formatting options.
  </Card>

  <Card title="Writing data" icon="pen" href="/rest-api/writing">
    PUT, POST, PATCH, DELETE, multi-path updates, and server values.
  </Card>

  <Card title="Streaming" icon="signal-stream" href="/rest-api/streaming">
    Server-Sent Events for real-time updates over HTTP.
  </Card>

  <Card title="Conditional requests" icon="code-compare" href="/rest-api/conditional">
    ETags and compare-and-swap for safe concurrent writes.
  </Card>
</CardGroup>