> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Turso API reference

> API reference for the Turso plugin in Corsair: every `turso.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Changes

### listen

`changes.listen`

Listen to committed insert/update/delete events for a table in a Turso database

**Risk:** `read`

```ts theme={null}
await corsair.turso.api.changes.listen({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `databaseUrl` | `string` | Yes | Database-specific URL, e.g. [https://mydb-myorg.turso.io](https://mydb-myorg.turso.io) — NOT the platform API host |
| `table` | `string` | Yes | Table to watch for committed changes |
| `action` | `insert \| update \| delete` | Yes | Which committed action to stream: insert, update or delete |
| `maxEvents` | `number` | No | Stop after this many events have been received. Defaults to 10. |
| `timeoutMs` | `number` | No | Stop listening after this many milliseconds. Defaults to 15000. |

**Output:** `object`

> [accordion] Output full type
>
> ```ts theme={null}
> {
>   mode: stream,
>   table: string,
>   action: insert | update | delete,
>   events: {
>     table: string,
>     action: insert | update | delete,
>     receivedAt: string,
>     data?: Record<string, any>
>   }[],
>   stoppedBy: max_events | timeout | stream_closed
> } | {
>   mode: health_check,
>   table: string,
>   action: insert | update | delete,
>   listenAvailable: false,
>   reason: string,
>   databaseReachable: boolean
> }
> ```

***

## Regions

### closest

`regions.closest`

Get the closest Turso region based on client location, to minimize latency

**Risk:** `read`

```ts theme={null}
await corsair.turso.api.regions.closest({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `server` | `string` | Yes | Location code for the server that answered the request |
| `client` | `string` | No | Location code for the requesting client |

***

## Tokens

### validate

`tokens.validate`

Validate a Turso API token and retrieve its expiration time (-1 when it never expires)

**Risk:** `read`

```ts theme={null}
await corsair.turso.api.tokens.validate({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `exp` | `number` | Yes | Token expiry in unix epoch seconds, or -1 when the token never expires |

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.