Skip to content
Rowsafe
Docs

Ask Rowsafe API

Ask Rowsafe endpoints, streamed events, errors and limits.

The dashboard's Ask panel uses these endpoints. Call them with a read-write API key (Authorization: Bearer rsk_...); read-only keys can read settings and conversations but not ask. What the model sees: Ask Rowsafe.

Ask a question

POST /v1/ask

{
  "question": "Why is app-prod slow today?",
  "database": "app-prod",
  "conversation_id": "conv_…",
  "deep": false,
  "about": { "kind": "finding", "id": "query_regression" }
}
Field
questionRequired, 1 to 2,000 characters.
databaseScope to one database.
conversation_idContinue a conversation (keeps its database).
deepUse the stronger model.
aboutThe item an Explain button was pressed on: finding (finding id and database), alert (alert id), or query (query id and database).

The answer streams as server-sent events. Event name = type; data = one JSON object:

TypeData
startconversation_id, message_id
tooltool: {id, name, label, status}, a step like "Checking health findings of app-prod": running, then done or error
texttext: the next piece of the answer (Markdown)
sourcesource: {label, href}, data the answer uses, with its dashboard path
actionaction: a button: {kind: "fix", database, finding_id, fix_id, label, …} (apply it with POST /v1/databases/{ref}/fixes) or {kind: "link", href, label}
donedone: {model, remaining}, built-in questions left this month (-1 with your own key)
errorerror: {code, message}; no more events follow

A refusal before the stream starts is a JSON error with a code:

StatusCodeMeaning
403not_enabledAn admin hasn't turned Ask Rowsafe on
402no_modelNo built-in questions on this plan and no own key
402limit_reachedThis month's built-in questions are used
429rate_limitedMore than 10 questions a minute, or 3 at once, per organization
409key_invalidThe stored key can't be used anymore; add it again

Settings and keys

Method and path
GET /v1/ask/settingsOn or off, answer source (builtin, own_key or none), models, this month's usage, who handles a question
PUT /v1/ask/settings{"enabled": true} turns it on (audited as ask.enabled / ask.disabled)
PUT /v1/ask/key{"provider": "openrouter" | "anthropic" | "openai", "api_key": "…", "fast_model": "", "deep_model": ""}: checks the key with the provider, stores it encrypted (audited as ask.key_set, without the key)
DELETE /v1/ask/keyRemoves the key (audited as ask.key_removed)
GET /v1/ask/suggestions?database=Up to four questions worth asking now, from current findings and alerts

Conversations

Method and path
GET /v1/ask/conversationsThe organization's conversations, newest first
GET /v1/ask/conversations/{id}One conversation with its messages, sources and actions
DELETE /v1/ask/conversations/{id}Deletes one conversation
DELETE /v1/ask/conversationsDeletes every conversation (audited)
POST /v1/ask/messages/{id}/feedback{"rating": "up" | "down" | ""}

Conversations are deleted 30 days after their last message.

Edit on GitHub