API endpoints

Every operation of the HTTP API, grouped by area, as declared in api/openapi.yaml. "Access" is the minimum role of a signed-in user and the minimum scope of an API key; "session only" operations do not accept API keys. Load the OpenAPI file into any OpenAPI viewer or client generator for request and response schemas.

config

Configuration as code (YAML export, import and the GitOps directory).

Endpoint	What it does	Access
POST /api/v1/export	Export reports, queries, connections and channels as YAML	role editor, scope read
POST /api/v1/import	Plan or apply YAML documents	role admin, scope admin
POST /api/v1/gitops/detach	Let the UI change a resource the configuration directory manages	role admin, scope admin
POST /api/v1/gitops/attach	Give a detached resource back to the configuration directory	role admin, scope admin

ai

The AI assistant (proposals only; nothing runs by itself).

Endpoint	What it does	Access
GET /api/v1/ai/status	Whether the AI assistant is available	role viewer, scope read
POST /api/v1/ai/generate	Ask the AI assistant for a query or a schedule	role editor, scope run

health

Liveness and readiness probes. Public, never contain secrets.

Endpoint	What it does	Access
GET /health/live	Liveness probe	public
GET /health/ready	Readiness probe	public

setup

First-run wizard. Available until the first user exists.

Endpoint	What it does	Access
GET /api/v1/setup/status	Whether the setup wizard must run	public
POST /api/v1/setup	Create the first admin and sign in	public

auth

Sign in and sign out.

Endpoint	What it does	Access
POST /api/v1/auth/login	Sign in with email and password	public
POST /api/v1/auth/login/second-factor	Finish signing in with a TOTP code or a recovery code	public
POST /api/v1/auth/login/second-factor/passkey	Start the passkey step of a sign-in	public
POST /api/v1/auth/passkey/options	Start signing in with a passkey, without a password	public
POST /api/v1/auth/passkey	Finish signing in with a passkey	public
GET /api/v1/auth/oidc/login	Leave for the identity provider (OIDC)	public
GET /api/v1/auth/oidc/callback	Come back from the identity provider	public
POST /api/v1/auth/password-reset	Email a link to choose a new password	public
POST /api/v1/auth/password-reset/confirm	Choose a new password with an emailed link	public
POST /api/v1/auth/logout	Sign out of the current session	role viewer, scope read, session only

me

The signed-in user's profile, password, sessions and two-factor authentication.

Endpoint	What it does	Access
GET /api/v1/me	The signed-in user	role viewer, scope read
PATCH /api/v1/me	Update name and preferences	role viewer, scope write, session only
POST /api/v1/me/password	Change the password	role viewer, scope write, session only
GET /api/v1/me/sessions	Active sessions of the caller	role viewer, scope read, session only
POST /api/v1/me/sessions/{sessionId}/revoke	Sign out one session	role viewer, scope write, session only
POST /api/v1/me/sessions/revoke-all	Sign out everywhere, including this session	role viewer, scope write, session only
POST /api/v1/me/2fa/totp/setup	Start enrolling an authenticator app	role viewer, scope write, session only
POST /api/v1/me/2fa/totp/confirm	Activate the authenticator app with a first code	role viewer, scope write, session only
POST /api/v1/me/2fa/totp/disable	Turn off two-factor authentication	role viewer, scope write, session only
POST /api/v1/me/2fa/recovery-codes	Replace the recovery codes	role viewer, scope write, session only
GET /api/v1/me/passkeys	The caller's passkeys	role viewer, scope read, session only
POST /api/v1/me/passkeys	Finish adding a passkey	role viewer, scope write, session only
POST /api/v1/me/passkeys/options	Start adding a passkey	role viewer, scope write, session only
PATCH /api/v1/me/passkeys/{passkeyId}	Rename a passkey	role viewer, scope write, session only
POST /api/v1/me/passkeys/{passkeyId}/remove	Remove a passkey	role viewer, scope write, session only

users

Workspace members and their roles.

Endpoint	What it does	Access
GET /api/v1/users	Members of the workspace	role viewer, scope read
POST /api/v1/users	Add a user with a temporary password	role admin, scope admin
GET /api/v1/users/{userId}	One member of the workspace	role viewer, scope read
PATCH /api/v1/users/{userId}	Change name, role or enabled state	role admin, scope admin
POST /api/v1/users/{userId}/reset-password	Give the user a new temporary password	role admin, scope admin
POST /api/v1/users/{userId}/2fa/disable	Turn off another user's two-factor authentication	role admin, scope admin

api-keys

Keys for automation. Managed by admins.

Endpoint	What it does	Access
GET /api/v1/api-keys	API keys of the workspace	role admin, scope admin
POST /api/v1/api-keys	Create an API key	role admin, scope admin
POST /api/v1/api-keys/{apiKeyId}/revoke	Revoke an API key	role admin, scope admin

settings

Workspace settings.

Endpoint	What it does	Access
GET /api/v1/settings	Workspace settings	role viewer, scope read
PATCH /api/v1/settings	Change workspace settings	role admin, scope admin
GET /api/v1/settings/oidc	Single sign-on (OIDC) settings	role admin, scope admin
PUT /api/v1/settings/oidc	Change the single sign-on (OIDC) settings	role admin, scope admin
POST /api/v1/settings/oidc/test	Read the provider's discovery document	role admin, scope admin
GET /api/v1/settings/alerts	System alert channels and the outbound heartbeat	role admin, scope admin
PUT /api/v1/settings/alerts	Replace the system alert and heartbeat settings	role admin, scope admin
GET /api/v1/settings/ai	The AI assistant's provider and its settings	role admin, scope admin
PUT /api/v1/settings/ai	Choose the AI provider, or turn the assistant off	role admin, scope admin
POST /api/v1/settings/ai/test	Check AI settings before saving them	role admin, scope admin

security-events

Audit trail of security-relevant actions, for admins.

Endpoint	What it does	Access
GET /api/v1/security-events	Security events, newest first	role admin, scope admin

system

The instance itself (storage, backups, version), for admins.

Endpoint	What it does	Access
GET /api/v1/system/about	Version of this instance and the latest release	role viewer, scope read
GET /api/v1/system/storage	Artifact storage, retention and scheduled backups	role admin, scope admin

plugins

Installed plugins with their configuration schemas, capabilities and translations.

Endpoint	What it does	Access
GET /api/v1/plugins	Installed plugins	role viewer, scope read

connections

User databases. Rowbird only reads from them.

Endpoint	What it does	Access
GET /api/v1/connections	Connections of the workspace, by name	role viewer, scope read
POST /api/v1/connections	Add a connection	role admin, scope admin
POST /api/v1/connections/test	Test configuration that is not saved	role admin, scope admin
GET /api/v1/connections/{connectionId}	One connection	role viewer, scope read
PATCH /api/v1/connections/{connectionId}	Change a connection	role admin, scope admin
DELETE /api/v1/connections/{connectionId}	Delete a connection that nothing uses	role admin, scope admin
POST /api/v1/connections/{connectionId}/test	Test a saved connection	role admin, scope admin
GET /api/v1/connections/{connectionId}/schema	Cached schema of the database	role viewer, scope read
POST /api/v1/connections/{connectionId}/schema/refresh	Introspect the schema again	role editor, scope write

queries

Named, versioned SQL bound to a connection, and its preview.

Endpoint	What it does	Access
GET /api/v1/queries	Queries of the workspace, most recently changed first	role viewer, scope read
POST /api/v1/queries	Create a query and its first version	role editor, scope write
POST /api/v1/queries/preview	Run SQL read-only with a row cap and a short timeout	role editor, scope run
GET /api/v1/queries/{queryId}	One query with its current version	role viewer, scope read
PATCH /api/v1/queries/{queryId}	Change a query	role editor, scope write
DELETE /api/v1/queries/{queryId}	Delete a query that no report uses	role editor, scope write
GET /api/v1/queries/{queryId}/versions	Versions of a query, newest first	role viewer, scope read
GET /api/v1/queries/{queryId}/versions/{number}	One version with its SQL	role viewer, scope read
POST /api/v1/queries/{queryId}/restore	Make a copy of an old version the current one	role editor, scope write

channels

Destinations with their settings (email, chats, webhooks, buckets) and health.

Endpoint	What it does	Access
GET /api/v1/channels	Channels of the workspace, by name, with their health	role viewer, scope read
POST /api/v1/channels	Create a channel	role admin, scope admin
POST /api/v1/channels/test	Test unsaved channel settings	role admin, scope admin
GET /api/v1/channels/{channelId}	One channel	role viewer, scope read
PATCH /api/v1/channels/{channelId}	Change a channel	role admin, scope admin
DELETE /api/v1/channels/{channelId}	Delete a channel that no delivery uses	role admin, scope admin
POST /api/v1/channels/{channelId}/test	Send a test message through a saved channel	role editor, scope run
POST /api/v1/channels/{channelId}/retry-failed	Send a channel's failed delivery attempts again	role editor, scope run

links

Shared links to run files, with expiry, revocation and a download log.

Endpoint	What it does	Access
GET /api/v1/links	Shared links, newest first	role viewer, scope read
GET /api/v1/links/{linkId}	One link with its latest downloads	role viewer, scope read
POST /api/v1/links/{linkId}/revoke	Revoke a link at once	role editor, scope write

reports

Queries on a schedule, with a condition, and their schedules.

Endpoint	What it does	Access
GET /api/v1/reports	Reports of the workspace, by title, with their last run	role viewer, scope read
POST /api/v1/reports	Create a report and schedule its first run	role editor, scope write
GET /api/v1/reports/{reportId}	One report	role viewer, scope read
PATCH /api/v1/reports/{reportId}	Change a report	role editor, scope write
DELETE /api/v1/reports/{reportId}	Delete a report and its runs	role editor, scope write
POST /api/v1/reports/{reportId}/pause	Stop scheduling a report	role editor, scope write
POST /api/v1/reports/{reportId}/resume	Schedule a paused report again from now	role editor, scope write
POST /api/v1/reports/{reportId}/run	Queue a manual run	role editor, scope run
POST /api/v1/schedules/preview	Next occurrences and description of a schedule	role viewer, scope read
GET /api/v1/reports/{reportId}/deliveries	A report's deliveries, in order	role viewer, scope read
POST /api/v1/reports/{reportId}/deliveries	Add a delivery to a report	role editor, scope write
PUT /api/v1/reports/{reportId}/deliveries/{deliveryId}	Replace a delivery's settings	role editor, scope write
DELETE /api/v1/reports/{reportId}/deliveries/{deliveryId}	Remove a delivery	role editor, scope write
POST /api/v1/deliveries/preview	Render a delivery's message without sending it	role editor, scope run
POST /api/v1/reports/{reportId}/test-delivery	Run the report now and deliver it only to the caller	role editor, scope run

runs

Executions of reports, scheduled or manual.

Endpoint	What it does	Access
GET /api/v1/runs	Runs, newest first	role viewer, scope read
GET /api/v1/runs/{runId}	One run with its steps, parameters, condition and result sample	role viewer, scope read
POST /api/v1/runs/{runId}/cancel	Cancel a pending or running run	role editor, scope run
POST /api/v1/runs/{runId}/attempts/{attemptId}/retry	Send a failed delivery attempt again	role editor, scope run
GET /api/v1/runs/{runId}/result	The run's result as a file	role viewer, scope read

notifications

In-app notifications of the signed-in user, and the real-time event stream.

Endpoint	What it does	Access
GET /api/v1/notifications	The signed-in user's notifications, newest first	role viewer, scope read
POST /api/v1/notifications/read-all	Mark every notification of the signed-in user as read	role viewer, scope read
POST /api/v1/notifications/{notificationId}/read	Mark one notification as read	role viewer, scope read
GET /api/v1/dashboard	Home page summary and what the health banner shows	role viewer, scope read
GET /api/v1/events	Real-time events as Server-Sent Events	role viewer, scope read