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 | |
|---|---|
question | Required, 1 to 2,000 characters. |
database | Scope to one database. |
conversation_id | Continue a conversation (keeps its database). |
deep | Use the stronger model. |
about | The 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:
| Type | Data |
|---|---|
start | conversation_id, message_id |
tool | tool: {id, name, label, status}, a step like "Checking health findings of app-prod": running, then done or error |
text | text: the next piece of the answer (Markdown) |
source | source: {label, href}, data the answer uses, with its dashboard path |
action | action: a button: {kind: "fix", database, finding_id, fix_id, label, …} (apply it with POST /v1/databases/{ref}/fixes) or {kind: "link", href, label} |
done | done: {model, remaining}, built-in questions left this month (-1 with your own key) |
error | error: {code, message}; no more events follow |
A refusal before the stream starts is a JSON error with a code:
| Status | Code | Meaning |
|---|---|---|
| 403 | not_enabled | An admin hasn't turned Ask Rowsafe on |
| 402 | no_model | No built-in questions on this plan and no own key |
| 402 | limit_reached | This month's built-in questions are used |
| 429 | rate_limited | More than 10 questions a minute, or 3 at once, per organization |
| 409 | key_invalid | The stored key can't be used anymore; add it again |
Settings and keys
| Method and path | |
|---|---|
GET /v1/ask/settings | On 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/key | Removes 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/conversations | The 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/conversations | Deletes every conversation (audited) |
POST /v1/ask/messages/{id}/feedback | {"rating": "up" | "down" | ""} |
Conversations are deleted 30 days after their last message.