Execute a Hrana JSON v3 cursor

POST

/v1/disks/{disk}/sqlite/{database}/hrana/v3/cursor

curl --request POST \
  --url https://api.wabe.sh/v1/disks/demo/sqlite/mydb/hrana/v3/cursor \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "batch": { "steps": [ { "stmt": { "sql": "SELECT 1 AS n" } } ] } }'

SDK base /v1/disks/{disk}/sqlite/{database}/hrana/. Named databases are independent within a disk. Bearer authentication is required on every continuation. Transaction TTL defaults to 60 seconds, idle sessions outside a transaction to 30 seconds. The previous custom SQL and libsql URI routes are disabled. Protobuf, WebSocket and replication are outside this profile.

Authorizations

• bearerAuth
• runtimeAccess

Parameters

Path Parameters

disk

required

string

/^[A-Za-z0-9_-]{1,128}$/

Example

demo

Project disk name, or the disk ID in the actor runtime disk URL.

database

required

string

/^[A-Za-z0-9_-]{1,128}$/

Example

mydb

Request Body^required

Media typeapplication/json

object

baton

Omit or use null for a new session. Pass the latest baton to continue; the SDK rotates tokens. A cursor header baton becomes usable only after body EOF.

string | null

batch

required

object

steps

required

Array<object>

object

stmt

required

One sql or sql_id, typed args or named_args, and optional want_rows (default true).

object

condition

Hrana ok/error/not/and/or/is_autocommit condition; step references point to earlier steps.

object | null

Example

{
  "batch": {
    "steps": [
      {
        "stmt": {
          "sql": "SELECT 1 AS n"
        }
      }
    ]
  }
}

Responses

200

Protocol results; statement errors can occur inside HTTP 200. SQL COMMIT acknowledges buffered state without an object-store flush. Cursor EOF alone does not commit an open transaction.

Media typeapplication/x-ndjson

string

Example

{"base_url":null,"baton":"YOUR_CURSOR_BATON"}
{"type":"step_begin","step":0,"cols":[{"name":"n","decltype":null}]}
{"type":"row","row":[{"type":"integer","value":"1"}]}
{"type":"step_end","affected_row_count":0,"last_insert_rowid":null}
{"type":"replication_index","replication_index":null}

400

Invalid names or protocol request.

401

Missing, invalid or revoked project API key, or an invalid runtime access token.

Media typeapplication/json

object

error

required

string

message

required

string

403

Actor runtime token does not authorize this disk or instance generation.

Media typeapplication/json

object

error

required

string

message

required

string

404

Invalid, expired, wrong-scope or retired-session baton.

408

SQL execution/admission/backpressure deadline expired.

413

Request or configured resource limit exceeded.

503

SQL execution unavailable or storage failure.