Skip to main content

Best practices

1. (optional) GET /v1/history?q=<question>   → is there a saved answer already?
2. POST /v1/ask                              → only if there isn't (spends LLM)
3. run sql + params on your database          (read-only user)
4. POST /v1/feedback                         → 👍 / 👎 from the user

Checklist​

  • The call to Datafala goes out from your backend; the API key never goes to the browser or the app.
  • The SQL runs with a read-only user, with access only to the registered tables and a maximum time per query.
  • params is always passed to the driver, even when empty.
  • end_user is sent in every question, generated with HMAC and a fixed server secret.
  • If the system is multi-company, there is RLS, filtered views or restricted access (see Data scope).
  • The timeout of your HTTP client on /v1/ask is at least 60 s, and a timeout is not retried automatically.
  • Errors are handled by the code, with Retry-After respected on 429 and 503.
  • The request_id (or the X-Request-ID header) is recorded in your logs.
  • The user can give 👍 / 👎, sent to /v1/feedback.

Save tokens​

  • Reuse before generating. Repeated questions can come from /v1/history?q= or from your own cache by request_id.
  • Be careful with relative dates when reusing: the stored params are the ones from the day of the question.
  • Show the explanation to the user. It helps people notice when the query is not what they wanted, and a 👎 becomes a signal for the administrator to improve the context and examples.