Inspector

Execute SQL

Run a SQL statement against the actor's SQLite database.

The inspector API is subject to change without notice. Do not build production integrations on it.

SQL executes directly against actor storage. Use bind parameters for values.

POST https://rivet.example.com/gateway/{actor}/inspector/database/execute

Examples

curl -X POST "https://rivet.example.com/gateway/$ACTOR_ID/inspector/database/execute" \
  -H "Authorization: Bearer $INSPECTOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT * FROM users WHERE id = ?",
    "args": [
      "user-123"
    ]
  }'

const endpoint = "https://api.rivet.dev";
const response = await fetch(
	`${endpoint}/gateway/${process.env.ACTOR_ID}/inspector/database/execute`,
	{
		method: "POST",
		headers: {
			Authorization: `Bearer ${process.env.INSPECTOR_TOKEN}`,
			"Content-Type": "application/json",
		},
		body: JSON.stringify({
			sql: "SELECT * FROM users WHERE id = ?",
			args: ["user-123"],
		}),
	},
);
console.log(await response.json());
export {};

Authentication

Inspector endpoints do not accept namespace tokens. Send the actor’s inspector token as a bearer token in the Authorization header.

Path Parameters

Name	Type	Required	Description
`actor`	`string`	Yes	Actor ID, actor ID with an inline token (`{actor_id}@{token}`), or actor name combined with the `rvt-*` query parameters.

Headers

Name	Type	Required	Description
`Authorization`	`string`	No	Bearer token for inspector authentication. Required in production, optional in development.

Request Body

Content type: application/json.

Field	Type	Required	Description
`sql`	`string`	Yes	SQL statement to run against the actor’s SQLite database.
`args`	`any[]`	No	Positional arguments passed to the action, in order.
`properties`	`object`	No	Driver-specific execution options.

Responses

200

Rows returned by the statement.

Field	Type	Description
`rows`	`object[]`

{
  "rows": [
    {}
  ]
}

401

The inspector token is missing or invalid.