Configuration API

The configuration API lets a script do anything you can do in your instance's control panel. That covers adding and testing connections, indexing databases, writing knowledge, building fassads and modules, pinning widgets, writing email templates and sending broadcasts, changing settings, and managing API keys and people. It is the same API the control panel is built on, opened to your own scripts through personal access tokens.

To let software ask questions and run fassads, use the askDBLM API with an API key instead. It is simpler, and an API key cannot change anything.

Base URL: https://<your-instance>.askdblm.com/api/admin

A self-hosted instance serves the same API at its own address, followed by /api/admin. The examples in this guide use https://acme.askdblm.com and a sample music-store database.

1. Quickstart

1. Create a token. In your instance's control panel, open Access tokens and choose Create token. Everybody who can sign in has this page. Name the token after what will use it, pick a role no higher than your own, choose when it expires, and copy it. The token is shown only once.

2. Keep it out of your code:

export ASKDBLM_ADMIN=https://acme.askdblm.com/api/admin
export ASKDBLM_TOKEN=dblm_pat_16ad2d04f287_…        # the token you copied

3. Check it:

curl -H "Authorization: Bearer $ASKDBLM_TOKEN" "$ASKDBLM_ADMIN/whoami"

{
  "mode": "sso",
  "uses_sessions": true,
  "authenticated": true,
  "user": "[email protected]",
  "role": "owner",
  "token": { "id": "16ad2d04f287", "name": "setup-script", "prefix": "dblm_pat_16ad2d04f287", "role": "owner", "expires_at": "2026-12-29T14:57:53Z" }
}

role is what the token may do right now. token.role is the most it was created to do.

4. Change something. This adds a connection:

curl -H "Authorization: Bearer $ASKDBLM_TOKEN" -H "Content-Type: application/json" \
     "$ASKDBLM_ADMIN/connections" \
     -d '{"name": "warehouse", "driver": "postgres", "host": "db.acme.internal", "username": "readonly", "password": "…"}'

2. Personal access tokens

A personal access token is you, for a script. Send it with every request:

Authorization: Bearer dblm_pat_16ad2d04f287_…

It acts as you. Everything a token does is done in your name. It carries the role you gave it, and never more than you hold at the time of each request. If an owner lowers your role, your owner tokens act at your new role from their next request. If you lose access to the instance, your tokens stop working with it (401 access_revoked). In a hosted instance that follows your membership in askDBLM, and takes effect within a few minutes.

It always expires, after 30 days, 90 days or a year. There is no "never". To keep a script running, create its next token before the current one expires, and revoke the old one once the script has switched.

It is shown once. askDBLM keeps a hash of the token, not the token. The Access tokens page lists your tokens by name and prefix (dblm_pat_16ad2d04f287_…), with when each was last used and from where. Revoke a token there and it is refused from its next request. Owners see, and may revoke, everybody's tokens.

It cannot make tokens. Tokens are only ever created by a signed-in person, on the Access tokens page. A token that leaked cannot mint itself a replacement.

Everything it changes is recorded. Each change a token makes (every POST, PUT, PATCH and DELETE, including ones that are refused) goes into the instance's audit log under your name, with the operation token. Owners see it on the Audit page.

Tokens and API keys are different credentials.

Neither works on the other's API.

3. Roles

Every request needs a role, the lesser of the token's and yours. Reading most things needs only viewer. Changing things needs the role shown here:

A request above the role you have is refused with 403 insufficient_role, and the message says which role it needed.

4. Conventions

Requests. Send JSON with Content-Type: application/json. Fields the endpoint does not use are ignored. A body that is not valid JSON is refused with 400 invalid_request.

Names in paths. URL-encode them. Names of connections, fassads and modules cannot contain /, and a path containing an encoded slash (%2F) is refused.

Lists come wrapped: {"items": [...], "total": 3}. Some also say how they are sorted ("sort": "name", "order": "asc").

Errors share one shape. Build your handling on code:

{ "error": { "code": "insufficient_role", "message": "this needs the owner role; you have editor" } }

Rate limit. A token may make 120 requests a minute, in bursts of up to 60. Beyond that the answer is 429 rate_limited with a Retry-After header.

Secrets are write-only. Connection passwords, header values, the model's API key, the Resend key and the WhatsApp access token and app secret can be set, but no endpoint ever returns them. Responses say only whether one is set: password_configured, header_names, api_key_configured, resend_api_key_configured, access_token_configured, app_secret_configured.

Background jobs. Indexing a database and generating knowledge take a while, so those requests return 202 Accepted with a job. Poll GET /jobs/{id} until its status is completed, failed or cancelled:

{
  "id": "job_960cd73e5511c368",
  "type": "index",
  "status": "running",
  "connection": "chinook",
  "database": "",
  "target": "chinook",
  "progress": 40,
  "phase": "introspecting",
  "message": "",
  "skipped": false,
  "created_at": "2026-09-30T14:58:11Z",
  "started_at": "2026-09-30T14:58:11Z"
}

A job has an error when it failed, and finished_at once it is over. Only one job at a time may work on a target. Starting another on the same target is refused with 409 jobs_running.

Identity. Each response carries an X-Request-ID header.

5. Reference

Paths below are relative to the base URL, https://<your-instance>.askdblm.com/api/admin.

Identity and health

Connections

A connection is how the instance reaches one of your databases, or a REST API described by an OpenAPI document.

A connection with "managed": "email" is the one askDBLM keeps to the instance's email database. It can be tested, indexed and given knowledge like any other, and added to a module; it cannot be changed or removed, and adding a connection under its name is refused.

Body for adding, changing and testing:

Through an SSH server. A database that is reachable only from another server, such as a bastion or the database's own machine, can be reached through an SSH server there. host and port are then the database's address as the SSH server reaches it: 127.0.0.1 for a database on the SSH server itself. Available for postgres, mysql, mongo and clickhouse.

{"name": "lab", "driver": "postgres", "host": "127.0.0.1", "port": 5432,
 "username": "readonly", "password": "…",
 "ssh": {"host": "bastion.example.com", "port": 22, "username": "tunnel", "password": "…"}}

The SSH server's host key is pinned when the connection is saved, and every connection checks the server against it, so a different server answering at that address is refused. Left out, host_key pins the key the server shows when you save: compare the fingerprint in the answer with the server's own (ssh-keygen -lf on its host key). A fingerprint you give is checked against the server's key before it is pinned. Through a tunnel, postgres cannot use ssl_mode verify-full, and mongo needs one server's address rather than a mongodb+srv one.

Changing a connection:

• An omitted driver keeps the current one.
• An omitted or empty password keeps the stored password, together with any host, port, username or SSL mode you leave out.
• If you send a new password, send host, port and username with it.
• headers set to null keeps the current headers, and {} clears them.
• An omitted ssh keeps the SSH server, and null stops connecting through one. An ssh object for the same server and user keeps the stored password and key you leave out, and the pinned host key. To pin a new key after the server's has changed, send its fingerprint as host_key.
• For sqlite and openapi, send path or spec again.

A connection as returned: name, driver, host, port, username, ssl_mode, path, spec, header_names, password_configured, dsn_redacted (the connection string with its secrets masked) and, for one through an SSH server, ssh: host, port, username, password_configured, private_key_configured and host_key, the pinned key's fingerprint.

A test answers 200 either way, with {"ok": true, "driver": "postgres", "latency_ms": 42}. A failed test has "ok": false, an error_code (invalid_connection, timeout, auth, refused or connection_test_failed) and a message. Through an SSH server, the code can also be ssh_unreachable, ssh_auth (the SSH server turned the sign-in down), ssh_host_key (its key is not the pinned one), ssh_forward (signed in, but the SSH server could not reach the database) or ssh_config. A test of unsaved settings that go through an SSH server also has ssh_host_key, the fingerprint saving them would pin.

Databases and indexing

Indexing reads a database's schema so questions can be answered from it. {conn} is a connection; {conn}/{db} is one database on it. A sqlite or openapi connection is indexed as a whole, by {conn} alone.

The body of POST /databases/{conn}/index is optional:

If a database on the connection is busy, nothing is started and the request is refused with 409 jobs_running.

Jobs

A job's type is index, refresh, generate (knowledge), module_generate (module knowledge) or broadcast (sending a broadcast, with target broadcast:<id>). Jobs that were running when the instance restarted end as failed. Cancelling a broadcast's job pauses the broadcast.

Knowledge

Knowledge is what the instance knows about a database beyond its schema: descriptions of tables and columns, relationships, business rules, example questions and a glossary. It makes answers better.

The document:

{
  "conn_name": "chinook",
  "description": "A digital music store.",
  "tables": [
    {
      "schema_name": "", "table_name": "Invoice",
      "summary": "One row per customer purchase.", "description": "",
      "pinned": true,
      "columns": [ { "column_name": "Total", "description": "Amount charged, in USD." } ]
    }
  ],
  "relationships":   [ { "description": "Invoice.CustomerId references Customer.CustomerId." } ],
  "business_rules":  [ { "text": "Revenue means the sum of Invoice.Total.", "pinned": true } ],
  "example_queries": [ { "question": "Revenue by country", "query": "SELECT BillingCountry, SUM(Total) FROM Invoice GROUP BY 1" } ],
  "glossary":        [ { "term": "Track", "definition": "One song." } ],
  "generated_by": "manual",
  "is_dirty": false,
  "updated_at": "2026-09-30T15:02:44Z"
}

A database's knowledge is Dirty once a refresh finds its schema changed since the knowledge was written: tables, columns, types, keys or comments. Generate it again so answers use what changed.

Every item can be pinned, so that generating knowledge again keeps it. PUT replaces the document entirely. Read it, change it, and send all of it back. The instance sets conn_name, generated_by (manual), is_dirty and updated_at itself. A table needs a table_name, a column a column_name, a rule its text, an example its question and a glossary entry its term. Otherwise the answer is 400 invalid_knowledge.

Fassads

A fassad is a saved query with parameters (sql), or a saved question template (nlq).

A fassad:

A saved query must only read. One that would change data is saved, but refused when it runs (403 not_read_only).

A fassad that answers for one user takes that user's id as a parameter. askDBLM has no users of its own, so the server that runs the fassad, the one holding the credentials, authenticates and authorizes the user, then supplies the id in args, where it is bound as a value and cannot change the query. Never let a browser or app choose the id.

Health says whether a fassad still fits the schema it runs against:

An sql fassad is checked by its database, which plans the query without returning any rows: when it is saved, when its database is re-indexed, and by /check. A check that passes takes the current schema as the new yardstick, so /check is also how a stale fassad is marked as reviewed. An nlq fassad writes a new query each run, so what it reads is the query its last run wrote; a re-index that changes those tables makes it stale until it next runs. Deleting its connection, its index or its module makes a fassad broken.

Running a fassad takes {"args": {"n": "5"}}. Values are strings here. It answers with name, mode, target, duration_ms, health after the run, warnings (for nlq, when the knowledge it used is missing or older than the schema) and either:

• for sql: rendered_sql and result (columns, rows);
• for nlq: question and query, an answer.

For software that runs fassads, the askDBLM API is the better fit. It needs only an API key, accepts typed arguments, and returns reports.

Modules

A module is a hand-picked group of tables that can span databases, so a question can join across them.

• Naming tables. A table is named as it is in its database. Where two schemas of one database each have a table of that name, name it as schema.table; a bare name that fits both is refused with 400 invalid_module.
• Foreign-key parents. A table added because a selected table points to it cannot be removed on its own; it goes when nothing needs it. Adding it yourself makes it a selection, so it stays when the table that pulled it in goes.
• Hidden columns go with their table when it is removed. A hidden column renamed or dropped in the database hides nothing: saving the table's list lets it go, whether or not you send it again.
• A missing database. When a connection a module reads is deleted, or one of its databases is no longer indexed, questions to the module fail with 400 invalid_module naming that database, and fassads that ask the module are marked broken. Index the database again or remove its tables. Removing other tables meanwhile keeps that database's foreign-key parents as they were, and says so in warnings.

Questions and history

POST /query takes a question and the module to ask: questions are asked of modules, never of a connection or database directly. It also takes an optional session_id for follow-up questions, and chart: true to suggest a chart. It answers with question, summary, results (one per database, each with the query that ran, its result, and any chart, visual or error), targets and duration_ms. visual is the whole suggested chart and chart its one-measure form, as in the askDBLM API. A question may take up to two minutes.

A module question over databases that one query cannot reach has a single result with steps: what ran on each database, as source, driver and query. Its query is then how dblm joined their results.

Questions here count toward your plan's monthly allowance, like any other. For product features, prefer the askDBLM API, which adds reports and long-question handling.

Widgets

A widget is a saved query pinned to a board with a chart. Each person has their own board; a token works on its owner's.

A widget:

When changing a widget, title, question and sql are always replaced by what you send. The other fields keep their current values when omitted. A widget carries the result of its last run, with last_run_at: data holds its first 500 rows, for the table, and row_count how many the run returned. A failed refresh keeps the last good data and sets last_error.

Its chart. A widget returns its chart as both visual and chart. One sent as visual is checked (400 invalid_widget says what is wrong with it) and kept as sent. One sent as chart alone is made whole and fitted to the rows at the next refresh: rows that repeat x beside a column of a few values get a split by that column, so they draw as one series each. A chart sent back as the widget returned it, as its visual or its chart, changes nothing, so a change of title or place keeps every measure. Saving a chart that draws columns the saved rows were not kept for refreshes the widget before it answers, re-running its query, so the tile draws every row.

A chart may group time: x.grain (minute to year) with aggregate (sum, avg, min or max), for lines, areas, bars and heatmaps whose x holds moments. A number with an aggregate combines every row instead, and has no x.

The chart draws every row. When a run returns more rows than data keeps, chart_data carries the columns the chart draws, for all of them: x, the split, then the measures, as {"columns": [...], "rows": [...], "total": n}. Past 50,000 rows it is reduced, and reduced says how: a chart that groups time keeps one row for each step (and each value of its split), its measures combined as aggregate says ("group": exactly what it draws, from every row; x is the step's start), and a number that combines every row keeps that one row; a line, area or bar chart without a split keeps its shape ("shape": the rows in order, cut into slices, each keeping its first and last row and every measure's lowest and highest, so no peak or dip is lost; skipped counts rows with no number to draw); and any other chart keeps the first 50,000 ("first"), since a split's Other sums every row. There is no chart_data when data holds every row.

A merged answer (one whose result has steps, from a module spanning databases one query cannot reach) is pinned with its steps. A refresh then does what the answer did, without the model: it runs each step on its database, loads the results into an in-memory database, and runs sql there. Every step and the join must be read-only, and a refresh reads each step's rows again, so a step that reads a large table makes a heavier widget. When changing a merged widget, steps left out keep their value.

Settings

Which AI model the instance uses.

Every field of the body is optional. A field you leave out keeps its value, and an empty string clears it:

The answer may carry warnings, for example a provider with no key. On hosted plans the model is provided for you, so most instances never need this endpoint.

Email settings

How the instance sends email: through your own Resend account, from a domain you have verified there.

Every field of the body is optional. A field you leave out keeps its value, and an empty string clears it:

The check answers with ok, a message to show, and, when the key may list them, the account's domains (name, status) and from_verified. A key restricted to sending works but cannot list domains, so it answers "restricted": true instead. An instance can also take its key from the DBLM_RESEND_API_KEY environment variable; then resend_api_key_configured is true while resend_api_key_in_config is false.

Email templates

An email template is a React Email component: the email's design, with variables filled in for each recipient. Most are written by the agent, the instance's AI model, in a conversation: describe the email, then ask for changes until it is right. Every change is kept as a version you can go back to. The agent follows the instance's brand guide. You can also write or edit the code yourself.

A template:

{
  "name": "welcome",
  "description": "Sent to new customers",
  "subject": "Welcome to Northwind, {{firstName}}",
  "source": "import { Html, Text, Link } from \"react-email\";\n\nexport default function Welcome({ firstName, unsubscribeUrl }: { firstName?: string; unsubscribeUrl?: string }) {\n  return (\n    <Html>\n      <Text>Hi {firstName || \"there\"}, welcome to Northwind.</Text>\n      <Link href={unsubscribeUrl}>Unsubscribe</Link>\n    </Html>\n  );\n}\n\nWelcome.PreviewProps = { firstName: \"Ana\" };\n"
}

What a template may be. The source is one module whose default export is the component. It may import only from react-email (or the older @react-email/components) and react, and the components available are Body, Button, CodeInline, Column, Container, Font, Head, Heading, Hr, Html, Img, Link, Markdown, Preview, Row, Section and Text. Style with inline style objects. A template runs in the instance with no network access, so it cannot fetch anything.

Variables are the props the template reads. Each one's value comes from a column of the recipient list, so every variable is text. Give the component PreviewProps with a sample of each: they fill the preview. The template can use a variable in logic, for example {firstName || "there"} for a recipient with no first name. askDBLM passes two props of its own to every email: email, the recipient's address, and unsubscribeUrl. Link to unsubscribeUrl from every template you will send to a list.

Saving checks the template. It is compiled, run and rendered with its samples. One that does not compile, throws, or uses a {{placeholder}} that is not one of its variables is refused with 400 invalid_template, and the message says why, with the line number for a compile error. The answer to a create or change carries warnings too, for example an email over 100 KB, which Gmail cuts short, or a template with no unsubscribe link.

A preview takes {"source", "subject", "values"} (only values for a saved template; each value replaces that variable's sample) and answers with the rendered subject, html and text, its size_bytes, the template's variables and any warnings.

A draft takes {"instruction": "A welcome email with their first name and plan"}. To change a template, send its source and subject too, with an instruction such as "Make the button green". It answers with source, subject, the model's notes and a preview. A draft that does not work is sent back to the model once with the reason. Each draft counts as one question against the instance's monthly allowance (429 quota_exhausted when it is used up).

Talking to the agent. Send {"message": "A welcome email with their first name and a button to sign in"} to POST /email-templates/chat for a new template, then {"message": "Make the button green"} to POST /email-templates/{name}/chat for each change. The agent sees the conversation so far, the template as it is now and the brand guide. A message that asks for a change saves the template as the next version; a question ("Which details does it use?") is answered and changes nothing. Either way the answer is a step:

A turn takes up to a couple of minutes and finishes even if the caller hangs up: its result is saved, and shows in the history. The agent answers one message per template at a time; a second is refused with 409 agent_busy. A change that does not produce a working template is sent back to the model once with the reason, and 422 draft_failed means nothing was changed. Each message counts as one question against the instance's monthly allowance.

The history is {"items": [...], "working": {...}}, where working (when present) is the message the agent is still answering, with by and started_at. Each item is a step:

Saving a new source or subject by hand is a step too; a new name or description is not. A template keeps its last 200 steps, and deleting it deletes them.

A test takes {"to": ["[email protected]"], "values": {"firstName": "Ana"}} and sends each address its own email, with [Test] before the subject, from the email settings' sender. It answers {"sent": [{"to", "id"}]} with Resend's id for each. An instance may send 20 test emails an hour.

Brand guide

How your email should look and sound: your colors, type, buttons, layout, imagery and voice. The agent follows it in every template it writes, unless a message asks for something else. Rather than write one from nothing, upload screenshots of your website, pages of your brand book or exports from your design tool, and the instance's AI model works it out. Check what it found, then save it.

A guide. Every field is optional, but a guide may not be empty:

A color that is not a hex code, a font stack with anything but font names and commas, or a logo not at an https:// address is refused with 400 invalid_brand.

Working one out. POST /email-brand/analyze takes {"files": [{"name", "type", "data"}], "notes": "..."}: up to 6 files, 2.5 MB in all, each with its media type and its bytes in base64. The model reads PNG, JPEG and WebP images and PDF files as they are, and SVG, CSS, HTML, Markdown and plain text as text. Notes are optional: who the business is, what to stress, the address of the logo. It answers with a proposed guide and the sources it came from, in a minute or so, and counts as one question against the instance's monthly allowance. Files it cannot use, or a model that cannot read images, are refused with 400 invalid_brand; models run through Ollama read images but not PDF files.

Broadcasts

A broadcast sends an email template to a list of recipients: a CSV file whose columns fill the template's variables. It starts as a draft, which you can change and review, and sending it runs as a job.

The recipient list is UTF-8 CSV with a header row, separated by commas, semicolons or tabs, up to 10 MB, 50,000 rows and 50 columns. One column holds the addresses: one called email (or e-mail, to, and the like) is chosen, or the first whose cells are mostly addresses; email_column changes it. Each template variable is filled from the column of the same name, matched ignoring case, spaces and punctuation, so First Name fills firstName. column_map changes that: {"firstName": "given_name"}, or "" for no column, in which case the variable is empty and the template's fallback shows. A row is skipped when it has no address (no_address), one that is not valid (invalid_address), one already on the list (duplicate), or one on the do-not-email list (suppressed).

The user ID column, when the list has one, holds each recipient's ID in your own records. It links every email sent to that person in the email database, so questions can join the emails to your users. A column called user_id, customer_id, account_id, member_id, contact_id, external_id, uid or id (ignoring case, spaces and punctuation) is chosen; user_id_column changes it, "" for none. The review warns when some recipients have none. Each recipient then has a user_id.

A broadcast:

The review of a draft says what would go out. ready is true when nothing stops it; otherwise problems say what to fix: no template, no list, no address column, nobody to send to, no Resend key or From, a template that no longer renders, or a template with no unsubscribe link. warnings are worth reading first: a variable with no column, empty cells, skipped rows. It also holds the template's variables, each with its column and how many recipients have it empty, the unused_columns, the sender (from, reply_to), and samples: the first three recipients' emails, rendered (to, subject, html, text, size_bytes).

Sending takes the number of recipients it will go to, counts.pending, as confirm_recipients; any other number is refused with 409 broadcast_not_ready, so a list that changed since you looked is not sent by mistake. The template is copied at that moment: changing it afterwards changes nothing about the broadcast. Emails go out in batches of up to 100, at the email settings' requests_per_second, each its own email to one recipient.

A send pauses with a pause_reason when Resend's daily or monthly limit is used up, when Resend refuses the key or the sender, or when Resend cannot be reached, and when the instance restarts. Resume it once the cause is fixed: it goes on where it stopped, and nobody gets an email twice. A recipient is unknown when Resend may or may not have sent their email and the instance could not tell within a day; they are not sent to again.

Unsubscribing. Every email carries the List-Unsubscribe and List-Unsubscribe-Post headers Gmail and Yahoo require from bulk senders, and the template's unsubscribeUrl is a link to a page on the instance, at /u/..., which asks before unsubscribing; a mail client's one-click unsubscribe needs no page. Unsubscribing puts the address on the do-not-email list. The links point at public_url in the email settings, or, when that is empty, at the address the broadcast was sent from, which must be one recipients can reach: an instance reached at localhost or a private address is refused with 503 email_unavailable until public_url is set.

Bounces and complaints. Resend can report what became of each email after it was sent. POST /email-settings/webhook sets that up: it creates a webhook in your Resend account that calls the instance at /webhooks/resend (at public_url, or the address you call from, which must be reachable from the internet), asking for email.delivered, email.delivery_delayed, email.bounced and email.complained, and keeps its signing secret. Every report is checked against that secret and refused when it is more than five minutes old. A key that may only send cannot create webhooks: add one in Resend yourself, with that address and those events, and send its signing secret as webhook_secret in the email settings. Sending a webhook_secret replaces a webhook askDBLM made, which is removed from Resend. webhook_endpoint says where askDBLM's webhook reports to; when it is not webhook_url, the public address changed since, and connecting again points the webhook at the new one.

Each recipient then shows a delivery: delayed, delivered, soft_bounced (a temporary bounce), bounced or complained (marked as spam), with a delivery_note saying why for a bounce, and the results CSV gains both columns. An address that bounces for good, from any email the Resend account sends, and an address that marks one of this instance's emails as spam, go on the do-not-email list, with the reason bounced or complained.

Do-not-email list

Addresses the instance never emails. Every broadcast skips them.

Email database

Everything Email keeps is in a database of its own: the templates and their history, the brand guide, the broadcasts and their recipient lists, the do-not-email list, and a record of every email sent and whom it went to. On an instance whose state is in Postgres it is a second database on the same server, named after the state database with _email added (dblm_email on a hosted instance); otherwise it is the SQLite file ~/.dblm/email.db. WhatsApp keeps a database of its own beside it.

askDBLM offers it to the query side as a connection it keeps, called email, read only: on Postgres it logs in as a role that may only read, on SQLite it opens the file read only. The connection is made the first time Email is used. Index it, generate knowledge for it and add it to a module, and questions about who was sent what go through questions, the public API and fassads like any other. A module can hold your own databases too, so one question can join the emails to your customers. It comes with knowledge already written, pinned so that generating knowledge keeps it, and indexing it replaces addresses in the sample rows with [email protected] and the like and leaves out the cells of uploaded lists, so neither reaches the model. It is in no module until you add it; an API key allowed every module can then ask about the people you email.

GET /email-settings reports it as database: backend (postgres or sqlite), location (the database or the file), connection (once made), ready, and a problem when something stops it. On a Postgres server where the state user may not create databases or roles, the problem says what an administrator runs once; or set DBLM_EMAIL_DSN to a database made by hand and DBLM_EMAIL_READER_DSN to a read-only login for it.

WhatsApp settings

How the instance sends WhatsApp messages: through your own WhatsApp Business account on Meta's Cloud API, from your own number. Meta bills the account for each message.

Every field of the body is optional. A field you leave out keeps its value, and an empty string clears it:

The IDs are in the app's dashboard under WhatsApp, API Setup; the app ID and secret under App settings, Basic. An instance can also take the token from DBLM_WHATSAPP_TOKEN and the secret from DBLM_WHATSAPP_APP_SECRET; then access_token_configured is true while access_token_in_config is false.

The check answers with ok, a message to show, problems that stop sending, notes that do not, the account_name, and the number: display_phone_number, verified_name, quality_rating (GREEN, YELLOW, RED or NA), messaging_limit (Meta's tier, such as TIER_2K), daily_limit (people the business may message in a rolling 24 hours, shared by every number in its Meta business portfolio; 0 with "unlimited": true), throughput and country. With the app's ID and secret it adds the token: valid, expires_at (null for a token that does not expire), scopes and the permissions it is missing. A token Meta refuses is "ok": false with Meta's reason, not an error.

WhatsApp templates

A WhatsApp message template is Meta's, not the instance's: a fixed shape (a header, a body, a footer, buttons) with variables Meta fills in for each message, and Meta reviews every template before it can be sent. The instance keeps a copy and follows its status. A template starts here as a draft, checked against Meta's rules as it is written; submitting sends it to Meta for review, usually decided within a day. Templates your account already has, made in WhatsApp Manager, are imported.

A template is named by its name and its language, as in Meta's account, so a template's path is /whatsapp-templates/{name}/{language}.

A template:

{
  "name": "trial_reminder",
  "language": "en_GB",
  "category": "UTILITY",
  "body": "Hi {{first_name}}, your trial of the {{plan}} plan ends on {{end_date}}. Reply if you need help.",
  "footer": "Northwind",
  "buttons": [{"type": "URL", "text": "Upgrade", "url": "https://northwind.example.com/upgrade/{{account_id}}"}],
  "variables": [{"name": "first_name", "sample": "Ana"}, {"name": "plan", "sample": "Pro"},
                {"name": "end_date", "sample": "12 October"}, {"name": "account_id", "sample": "4812"}]
}

Kinds. A template is one of four kinds, all written, checked, submitted and sent the same way:

A one-time code, a limited-time offer and a carousel have no opt-out button: people stop them by replying STOP, which the instance records.

Placeholders, for trying a template out. A picture, video or document header saved without a sample gets a public placeholder, and the answer warns until you give your own: https://placehold.co/1200x628/png?text=Sample+image (a PNG), https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4 (MDN's public-domain clip, an MP4 of H.264 and AAC) and https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf (a PDF). A place header saved without a place gets Times Square. Meta reviews the template with the sample, and a test message sends it when media_url gives none.

{
  "name": "new_in",
  "language": "en",
  "category": "MARKETING",
  "body": "Picked for you, {{first_name}}: this week's favourites.",
  "variables": [{"name": "first_name", "sample": "Ana"}],
  "cards": [
    {"header": {"format": "IMAGE", "example": "https://cdn.example.com/tote.png"}, "body": "The everyday tote, in three colours.",
     "buttons": [{"type": "URL", "text": "Shop", "url": "https://shop.example.com/tote"}, {"type": "QUICK_REPLY", "text": "More like this"}]},
    {"header": {"format": "IMAGE", "example": "https://cdn.example.com/jacket.png"}, "body": "A rain jacket that packs into its pocket.",
     "buttons": [{"type": "URL", "text": "Shop", "url": "https://shop.example.com/jacket"}, {"type": "QUICK_REPLY", "text": "More like this"}]}
  ]
}

Variables. In a named template a variable is its own name, lowercase letters and underscores. In a positional one it is where it is: header.1, body.1, body.2, and button.0 for the value at the end of the first button's address. A copy-code button's code is the variable copy_code (button.N when positional). Every variable needs a sample.

Saving checks the template against Meta's rules, so a mistake shows in a second rather than in Meta's review. It is refused with 400 invalid_whatsapp_template, every problem in the message, for: a name Meta does not take, a language it does not know, a header over 60 characters or with more than one variable, a body that is empty, over 1,024 characters, starts or ends with a variable or has two variables side by side, a variable written wrongly or used twice, a footer with a variable, too many buttons or quick replies split around other buttons, a link not at https:// or with its variable anywhere but the end, a missing sample, or a sample on more than one line, and for breaking a kind's rules above. The answer carries warnings too, such as too many variables for the text around them, which Meta also refuses, or a placeholder still in a header or a card. POST /whatsapp-templates/check takes the same body and answers with the template (its variables worked out), problems and warnings, saving nothing.

Opting out. A marketing template must let people stop: it needs a quick reply marked "opt_out": true, such as "Stop promotions", whose taps come back to the instance marked as opt-outs. A draft without one is saved with a warning and refused when submitted.

Submitting answers with the template, now PENDING with its meta_id, and warnings, for example when Meta filed it under another category. Meta's refusal is 422 whatsapp_failed with its reason, for example a template of that name and language already in the account (import it instead). The instance asks Meta about templates under review every 5 minutes, and about the others hourly, so status follows Meta's decision; an import asks at once.

Changing a template. A draft changes here only. A submitted one keeps its name and language, and a change to what Meta reviews goes to Meta at once and back to PENDING. Meta allows that once a day and ten times in 30 days for an approved template, never to another category, and not at all while it is reviewing (409 template_in_review). A new description changes nothing at Meta.

Pictures, videos and documents go to Meta with the template: submitting it, or changing one Meta has, fetches each sample from its address and uploads it through the Meta app the token belongs to, so the settings need app_id (503 whatsapp_unavailable without it). The instance fetches only a public https:// address, never one on its own network, and only a file Meta takes: a JPEG or PNG picture up to 5 MB, an MP4 or 3GPP video up to 16 MB, a PDF up to 16 MB. A sample it cannot fetch or Meta would not take is 400 invalid_whatsapp_template, naming the header or the card.

Writing with the agent. Send {"message": "A reminder three days before a trial ends, with their first name and plan", "language": "en_GB"} to POST /whatsapp-templates/chat for a new draft (language defaults to en), then {"message": "Make it shorter"} to POST /whatsapp-templates/{name}/{language}/chat for each change. The agent writes every kind of template, for whatever business and purpose the message names, and assumes no business, brand or product it does not name (it writes a variable such as {{business_name}} instead). It writes to Meta's rules, chooses the category honestly and says why, gives every variable a sample, and, when you give no picture, video, document or place, uses the placeholders above and says so. Of the brand guide it takes the tone of voice alone, for when you do not say how a template should sound. A marketing message always gets its opt-out quick reply. A template the agent writes that breaks Meta's rules goes back to it once with the problems; 422 draft_failed means nothing was changed.

A message that asks for a change saves a draft as its next version. A template Meta has is not changed by a message, since saving it sends it to Meta for review again: the change comes back as a proposal (the template's message, as content below), kept in the history, to save with PUT when you choose. Its category stays, as Meta keeps it. A question changes nothing. The agent does not work on a template Meta is reviewing (409 template_in_review). Either way the answer is:

A turn takes up to a minute or two and finishes even if the caller hangs up; the agent answers one message per template at a time (409 agent_busy), and each message counts as one question against the instance's monthly allowance.

The history is {"items": [...], "working": {...}}, as for email templates, where working is a message the agent is still answering. Each step has seq, kind (chat, edit, created or restore), message, reply, suggestions, changed (whether it changed the template), restored_from, proposal, by and at. One step asked for by its seq carries content: category, parameter_format, header, body, footer, buttons, variables, auth, offer and cards after it. A change saved by hand is a step too; a new description is not. Restoring works on a draft; for a template Meta has, save the version's content with PUT, which sends it to Meta. A template keeps its last 200 steps, and deleting it deletes them.

An import answers {"imported", "updated", "gone", "conflicts"}: templates added, templates whose content or status changed, templates submitted from here that the account no longer has (now DELETED), and drafts here with the name and language of a template in the account, which are left as they are.

A test takes {"to": ["+44 7400 123456"], "values": {"first_name": "Ana"}, "media_url": "https://..."} and sends each number the template, with its samples where values gives none. A number written without its country code is read in default_country. media_url is the header's picture, video or document, for a template with one; without it the header's sample is sent. A one-time code sends its sample code, and a limited-time offer counts down from the moment it is sent. Only an approved template can be sent (409 template_not_approved). It answers {"sent": [{"to", "message_id", "status"}]}, where status is accepted, or held_for_quality_assessment when Meta is pacing the template. An instance may send 20 test messages an hour, and Meta charges for them as for any message.

WhatsApp broadcasts

A WhatsApp broadcast sends an approved template to a list of phone numbers: a CSV file whose rows are the people, one column their number and the others filling the template's variables. Each person gets their own message from your number, and Meta charges your account for each one it delivers.

A draft takes name, mode ("api", the default, to send through Meta, or "hand" to send by hand — see Sending by hand), template and language (an approved template's, as in /whatsapp-templates/{name}/{language}, but not a one-time code's), media_url (the header's picture, video or document at https://, for a template with one; every message gets the same; a carousel's cards go with the template's own), phone_column, consent_column, user_id_column, column_map ({"first_name": "First Name"}) and fallbacks ({"first_name": "there"}, used where a cell is empty, since Meta refuses an empty value). In column_map and fallbacks, "" removes a variable's entry; a variable with no column takes its fallback in every message.

The list. A CSV file in UTF-8, with or without a byte-order mark, separated by commas, semicolons or tabs, up to 10 MB, 50,000 rows and 50 columns. Uploading it guesses the columns: the numbers (phone, mobile, whatsapp and the like, else a column of numbers), the consent (opt_in, consent, whatsapp_opt_in), the user ID, and each variable's column by its name, ignoring case and punctuation. Numbers are read as people write them; one without its country code is read in the settings' default_country, and every number is sent with + and its country code. A row is skipped, with its reason, when it has no_number, an invalid_number, a duplicate of an earlier row's number, a number on the do-not-message list (suppressed), or, with a consent column, a cell that does not say yes (no_consent; yes, true, 1, y, x and a date count as yes).

The review is the draft's review: ready, problems that stop it from being sent and warnings worth reading, will_send (the messages the send would make), skips_at_send (rows skipped as the send starts, because they depend on the template and the mapping: country_not_delivered for a US number with a marketing template, which WhatsApp does not deliver there, and empty_variable for an empty cell with no fallback), the template, each variable's column, fallback and empty cells, the unused_columns, the recipients' countries, the first three messages' samples ({"row", "to", "values"}), and the verified_name the consent names. The broadcast's limit is Meta's daily messaging limit: daily_limit people in a rolling 24 hours, shared by every number in your Meta business portfolio, how many this instance messaged in the last 24 hours, and the days the list takes at least.

Sending needs confirm_recipients to be the review's will_send and confirm_consent to be true: your word that everyone on the list agreed to receive WhatsApp messages from your business, which Meta requires. Who confirmed it, and when, is kept as consent_by and consent_at, and in the audit log. The send then sends one message a request, paced across the instance at messages_per_second, and every message carries biz_opaque_callback_data of <broadcast>:<row>. Each recipient becomes:

Meta refusing a message for coming too fast, or failing for a moment, sends it again a little later. The broadcast's status is sending, then completed; or:

• waiting, with wait_for and resume_at, when Meta's daily limit is reached (limit: it goes on once the 24-hour window has moved on) or Meta paused the template for low quality (template: it goes on when Meta lifts the pause, after 3 hours the first time and 6 the second). It goes on by itself; resume tries at once.
• paused, with pause_reason, for what needs a person: the token refused, the account restricted or without a payment method, the template gone, disabled or against policy, many messages refused in a row, or a restart. resume goes on where it stopped.

Unknown messages may be sent again with resend-unknown from a paused, waiting or completed broadcast, once they are two hours old (Meta's report on one may come late): some people may get the message twice, and Meta charges again. A 409 broadcast_not_ready says when none is old enough.

A finished broadcast's list is deleted 30 days after it ends (purged); its counts are kept, and so is a record of every message Meta took, with its reports and replies, in the WhatsApp database's whatsapp_sends.

Sending by hand

Some numbers are not on the WhatsApp Business API, or you would rather send from your own phone. A broadcast made with mode "hand" is worked through by people instead: the panel steps a sender through the list one person at a time, and each message goes out from that sender's own WhatsApp, through a link that opens it with the person's number and the template's words already filled in.

GET /whatsapp-hand lists the broadcasts being worked by hand, newest first. The sub-paths below need only an editor — a sender takes one number at a time, so no more than one person's message is ever in their hands — where the broadcasts themselves, and the list, are the owner's.

A hand broadcast is made and sent as any other is: a draft, its CSV with the list, then POST /whatsapp-broadcasts/{id}/send with confirm_recipients and confirm_consent; its status becomes sending. Nothing goes to Meta and no job runs, so its review leaves out the token, the account and the verified name it would otherwise need, and the view carries no Meta daily limit — the sender's own allowance stands in (below). cancel finishes it early.

POST /whatsapp-broadcasts/{id}/hand/next hands a sender their next person: row (their line in the list), to (their number), digits (the number as the links want it), text (the message as the template fills it), links (app, web or wa_me, to open it on this device) and, for a template with a picture, video or document, media and media_url. Calling it again hands back the person already held rather than a second; a person stays held for 15 minutes, so a restart or a long gap hands them to someone else.

POST /whatsapp-broadcasts/{id}/hand/{seq} records what became of a person's message, then hands out the next. Its body is {"outcome": ...}:

When nothing is left, the reply is done. A 409 hand_row_not_held means the person is not this sender's to settle, and a 409 broadcast_not_ready that the broadcast is not a hand broadcast that is sending.

GET /whatsapp-broadcasts/{id}/hand/media fetches that picture, video or document as the file itself, to save and attach in WhatsApp; a 400 invalid_broadcast says the template carries none.

A sender may send hand_daily_limit messages by hand in any 24 hours — 100 unless the deployment sets it, and 0 for no limit. That is the instance's configuration, not a setting the API changes. Each reply's sent is how many that sender has sent in the last 24 hours, daily_limit their allowance and unlimited when there is none; limit_at is when a full count frees up. A 429 hand_limit_reached says the allowance is spent.

WhatsApp reports

Meta reports what became of each message, what people send back, and changes to templates and the account, to /webhooks/whatsapp on the instance. Each call is signed with the Meta app's secret (X-Hub-Signature-256), and one that is not is refused (401); an instance with no app secret takes none (404). A call is answered 200 once it is recorded, otherwise Meta sends it again, for up to 7 days; a call that arrives twice changes nothing twice.

Connecting. POST /whatsapp-settings/webhook sets the address in Meta. It needs the app's secret, and the instance's public address (public_url in the email settings) at https://, which Meta requires. Meta checks the address as it connects, with the verify token the instance made.

The settings then show webhook_mode, webhook_endpoint (where Meta reports to; connect again if the public address moved) and webhook_verify_token, with webhook_url, for setting it up by hand in the app's dashboard instead. DELETE /whatsapp-settings/webhook takes the address back out of Meta.

What a report does:

• A message's status lands on its recipient: delivery becomes sent, delivered or read (with delivery_at), ranked so a late or repeated report never takes back a later one; the counts gain delivered (read included) and read. A message whose send had no answer (unknown) is found by the <broadcast>:<row> it carried and becomes sent. A failure after the send makes the recipient failed with Meta's error_code and error, such as 131049 or 131026; 131050 also puts the number on the do-not-message list. The recipient keeps Meta's pricing_category and the person's bsuid (business-scoped user ID) when Meta gives them.
• A reply to a broadcast's message sets the recipient's replied_at, and the counts gain replied. A reply that is the message's answer is matched by it; one without is matched to the latest message sent to the number in the three days before.
• A stop: a tap on a marketing template's opt-out button, a reply that is a stop word (the whole reply, ignoring case and punctuation), or the person turning off your marketing in WhatsApp's settings, puts them on the do-not-message list. Turning it back on in WhatsApp takes off an entry made that way, and no other.
• A template's status (APPROVED, REJECTED with its reason, PAUSED, DISABLED...), quality and, once Meta has changed it, category, are brought up to date; a change made in WhatsApp Manager is read again. A broadcast waiting for a paused template goes on once it is approved again.
• The account's messaging limit or number quality changing is read again at once.

Do-not-message list

Numbers no WhatsApp broadcast sends to: skipped when a list is read, and again as each message is about to go. A number is added when Meta answers a send with 131050 (the person turned off your marketing in WhatsApp), and, with reports connected, when a person taps the opt-out button, replies a stop word, or stops your marketing in WhatsApp. Owners add and remove numbers by hand. A person Meta knows only by their business-scoped user ID, with no number the instance has sent to, is kept by that ID. It is separate from the email do-not-email list: they are separate consents.

WhatsApp database

Everything WhatsApp keeps is in a database of its own, apart from the email database: the templates and their history, the broadcasts and their recipient lists, the do-not-message list, and a record of every message sent and whom it went to. On an instance whose state is in Postgres it is another database on the same server, named after the state database with _whatsapp added (dblm_whatsapp on a hosted instance); otherwise it is the SQLite file ~/.dblm/whatsapp.db. DBLM_WHATSAPP_DSN names a database made by hand instead, with DBLM_WHATSAPP_READER_DSN its read-only login, for a server where the state user may not create databases or roles.

askDBLM offers it to the query side as a connection it keeps, called whatsapp ("managed": "whatsapp"), read only, made the first time WhatsApp is used. Index it, generate knowledge for it and add it to a module, and questions about who was messaged what go through questions, the public API and fassads. Put the email database in the same module, and one question covers both channels through the people's user IDs ("people who got the trial email but never read the WhatsApp reminder"). It comes with knowledge already written, pinned so that generating knowledge keeps it, and indexing it replaces numbers in the sample rows with +15550000001 and the like and leaves out the cells of uploaded lists and Meta's IDs for people and messages, so none of them reaches the model. It is in no module until you add it.

GET /whatsapp-settings reports it as database: backend, location, connection (once made), ready, and a problem when something stops it, as GET /email-settings does for the email database.

Survey settings

The link base used when a survey link goes out, and the message a closed form shows. On a hosted instance the base is the instance's own address; set public_url when links should point somewhere else.

{ "public_url": "https://surveys.example.com", "closed_message": "This survey has closed." }

Both fields are optional; send "" to clear one.

Survey forms

A form is one whole HTML page, written by the form-builder agent, with every question it asks declared beside it as typed fields. Build one by talking to the agent, or send the page and its fields yourself. Once a form exists, send it to a list through a broadcast, or mint one person's link directly. Either way the person answers at a public page, GET /s/{token}, and the page's form submits the answers back to POST /s/{token}. The page needs no token of its own: the link carries one.

A form body names it, describes it, and holds its page and its fields. one_per_person allows one submission per link — a person who has already finished such a survey is refused a second time with 409 survey_already_answered; closed makes it take no new answers.

html is the whole page the agent wrote — markup, <style> and <script> alike; a script the page carries runs for the person answering. Leave the page's colours and fonts to the variables --bg, --surface, --text, --muted, --border, --accent, --accent-hi, --danger, --radius, --heading-font and --body-font: the instance's look fills them in. A page that is not already a whole document is wrapped in a bare one. At most 200,000 characters.

A form that a broadcast's issued links have gone out on, or that a broadcast is still draft or open on, cannot be renamed or deleted: it answers 409 survey_form_in_use. Delete the broadcast first to free the form.

{
  "name": "onboarding",
  "description": "A short onboarding check-in",
  "one_per_person": true,
  "closed": false,
  "closed_message": "This survey has closed.",
  "html": "<form><h1>About you</h1><textarea name=\"q1\" required></textarea><button type=\"submit\">Send</button></form>",
  "fields": [
    { "id": "q1", "kind": "long_text", "label": "What did you think?", "required": true }
  ]
}

A field has an id (unique within the form), a kind, a label, and optionally required, help, options (for a choice), min and max (for a rating, scale or number), max_length (for text) and min_label/max_label (for a scale). A text field may also demand more of the answer: min_length is the fewest characters it will take, and pattern a regular expression the text must match. A multi-choice field may demand min_choices. A date may be pinned between min_date and max_date. The kinds are short_text, long_text, single_choice, multi_choice, rating, scale, number, date, email and phone. A form holds at most 200 fields; a field at most 50 options. The names new, chat and check are reserved.

Every control that collects an answer must carry name="<field id>", the id of the field it answers; askDBLM reads the answers from those controls when the page's form submits. Put the questions inside a <form>, so that submitting it sends the survey.

Talking to the agent:

{ "message": "a two-screen onboarding survey: what they thought, and how likely they are to recommend us" }

The answer is {"form": {...}, "entry": {...}} — the form as it now stands, and the turn just taken.

Survey broadcasts

A broadcast sends one form to a list of people, each getting their own link. It goes: create it naming the form, upload the list as CSV, look over the review, then issue it. After issuing, every row has a token. Read the links with GET /survey-broadcasts/{id}/links or export them with /links.csv, and read the answers gathered so far with /results.csv.

{ "name": "March onboarding", "form": "onboarding", "user_id_column": "user_id", "name_column": "name" }

user_id_column and name_column say which column of the uploaded list holds the person's ID and name. While the broadcast is a draft, GET carries a review with ready, will_issue, skipped, problems and warnings, the columns the list has (and which are empty), the unused_columns, and a few samples with the link each row would get and why a row is skipped.

A broadcast is draft, open or closed. Each link is not_started, started, completed or skipped; a row with no user ID, or a repeat of one already in the list, is skipped and kept so the review can show it.

Survey responses

A response is in_progress until the person sends it, then completed.

Survey database

Everything surveys keep is in a database of its own, apart from the email database and the WhatsApp database. On an instance whose state is in Postgres it is another database on the same server, named after the state database with _survey added (dblm_survey on a hosted instance); otherwise it is the SQLite file ~/.dblm/survey.db. DBLM_SURVEY_DSN names a database made by hand instead, with DBLM_SURVEY_READER_DSN its read-only login.

askDBLM offers it to the query side as a connection it keeps, called survey ("managed": "survey"), read only, made at startup, like the email and WhatsApp connections. Index it, generate knowledge for it and add it to a module, and questions about who answered what go through questions, the public API and fassads. Put it in the same module as the email and WhatsApp databases, and one question covers all three through the people's user IDs. It comes with knowledge already written, pinned so that generating knowledge keeps it, and indexing it leaves the cells that identify a person out, so none of them reaches the model. It is in no module until you add it.

GET /survey-settings reports it as database: backend, location, connection (once made), ready, and a problem when something stops it, as GET /email-settings does for the email database.

API keys

API keys are what software uses to call the askDBLM API.

The body when issuing one:

{
  "name": "website",
  "scope": { "fassads": ["top_genres"], "query": true, "targets": ["module:chinook"] },
  "expires_in_days": 90
}

scope.fassads lists fassad names, or ["*"] for every fassad. scope.targets says which modules the key's questions may go to: module:<name>, or ["*"] for any module, and it applies when query is true. A connection or connection/database target is refused with 400 invalid_api_key: questions are asked of modules only. expires_in_days is 1 to 3650, or 0 for never. A key as returned has id, prefix, name, scope, created_by, created_at, expires_at, last_used_at and last_used_ip.

People

Who may use a self-hosted instance's control panel, and in which role. In a hosted instance people are managed in askDBLM, and these endpoints answer 409 managed_by_portal.

The last owner cannot be removed or demoted.

Audit log

Query parameters: user, connection, operation (for example token, nlq or fassad), date_from and date_to (YYYY-MM-DD), errors_only=1, limit (up to 1000; 100 by default) and offset. It answers with items (each with ts, user, op, connection, sql, row_count, error, duration_ms and remote_addr), has_more, and a summary of the page.

A token's change is filed under its owner, with op set to token and connection naming the call and the token: POST /api/admin/connections (token setup-script).

Access tokens

Tokens are created on the Access tokens page. A token cannot create one (403 tokens_cannot_create_tokens).

6. Recipes

Each recipe assumes ASKDBLM_ADMIN and ASKDBLM_TOKEN are set, as in the quickstart.

Set up an instance from a script

This adds a connection, checks it, indexes it, waits for the index, and has knowledge written. It needs an owner token.

#!/bin/sh
# setup.sh: connect, index and document one database.
set -eu
auth="Authorization: Bearer $ASKDBLM_TOKEN"
json="Content-Type: application/json"

# 1. The connection. The password comes from your secret store, not the script.
curl -sS --fail-with-body -H "$auth" -H "$json" "$ASKDBLM_ADMIN/connections" \
  -d "$(jq -n --arg pw "$WAREHOUSE_PASSWORD" \
        '{name: "warehouse", driver: "postgres", host: "db.acme.internal", username: "readonly", password: $pw}')" >/dev/null

# 2. Does it connect?
curl -sS -X POST -H "$auth" "$ASKDBLM_ADMIN/connections/warehouse/test" | jq -e '.ok' >/dev/null ||
  { echo "warehouse does not connect" >&2; exit 1; }

# 3. Index one database, and wait for it.
job=$(curl -sS --fail-with-body -X POST -H "$auth" -H "$json" \
  "$ASKDBLM_ADMIN/databases/warehouse/index" -d '{"databases": ["sales"]}' | jq -r '.items[0].id')
until status=$(curl -sS -H "$auth" "$ASKDBLM_ADMIN/jobs/$job" | jq -r '.status') &&
      [ "$status" != queued ] && [ "$status" != running ]; do sleep 2; done
[ "$status" = completed ] || { echo "indexing $status" >&2; exit 1; }

# 4. Have knowledge written for it. This runs in the background for a few minutes.
curl -sS --fail-with-body -X POST -H "$auth" "$ASKDBLM_ADMIN/knowledge/warehouse/sales/generate" | jq -r '.id'

Keep a fassad in version control

Store each fassad as a JSON file in your repository, and deploy it with PUT, or with POST the first time. It needs an editor token.

# deploy-fassad.sh fassads/top_genres.json
set -eu
name=$(jq -r '.name' "$1")
code=$(curl -sS -o /dev/null -w '%{http_code}' -X PUT \
  -H "Authorization: Bearer $ASKDBLM_TOKEN" -H "Content-Type: application/json" \
  "$ASKDBLM_ADMIN/fassads/$name" --data-binary "@$1")
if [ "$code" = 404 ]; then
  curl -sS --fail-with-body -H "Authorization: Bearer $ASKDBLM_TOKEN" -H "Content-Type: application/json" \
    "$ASKDBLM_ADMIN/fassads" --data-binary "@$1" >/dev/null
elif [ "$code" != 200 ]; then
  echo "deploying $name failed: HTTP $code" >&2; exit 1
fi

Issue an API key for a new integration

An owner token can provision the key an integration needs. The secret is in this one response, so hand it straight to your secret store:

curl -sS --fail-with-body -H "Authorization: Bearer $ASKDBLM_TOKEN" -H "Content-Type: application/json" \
  "$ASKDBLM_ADMIN/apikeys" \
  -d '{"name": "website", "scope": {"fassads": ["top_genres"]}, "expires_in_days": 90}' | jq -r '.secret'

Send a broadcast from a script

With an owner token, send this month's newsletter to a CSV exported from your own systems:

B=https://acme.askdblm.com/api/admin
AUTH="Authorization: Bearer $ASKDBLM_TOKEN"

# A draft for the template, then the list
id=$(curl -s -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"name": "October newsletter", "template": "newsletter"}' $B/broadcasts | jq -r .id)
curl -s -H "$AUTH" -H 'Content-Type: text/csv' --data-binary @customers.csv \
  "$B/broadcasts/$id/recipients?file_name=customers.csv" | jq '.counts, .review.problems, .review.warnings'

# Send to exactly as many people as the review counted
n=$(curl -s -H "$AUTH" $B/broadcasts/$id | jq .counts.pending)
curl -s -H "$AUTH" -H 'Content-Type: application/json' \
  -d "{\"confirm_recipients\": $n}" $B/broadcasts/$id/send | jq .status

Then follow GET /broadcasts/{id} until its status is completed, or paused, with the pause_reason to act on.

Rotate a connection's password

curl -sS --fail-with-body -X PUT -H "Authorization: Bearer $ASKDBLM_TOKEN" -H "Content-Type: application/json" \
  "$ASKDBLM_ADMIN/connections/warehouse" \
  -d "$(jq -n --arg pw "$NEW_PASSWORD" '{host: "db.acme.internal", port: 5432, username: "readonly", password: $pw}')"

A new password has to come with the host, port and username. Then test the connection, as in the first recipe.

Send a survey to a list of people

Put a CSV of people behind a form and mint one link each, for your own system to send. It needs an owner token. (The form itself can be built by hand with POST /survey-forms, or by the agent through POST /survey-forms/chat.)

#!/bin/sh
# survey.sh: make a form, upload a list of people, and issue their links.
set -eu
auth="Authorization: Bearer $ASKDBLM_TOKEN"
json="Content-Type: application/json"

# 1. The form: a screen per step, each field with an id, a kind and a label.
curl -sS --fail-with-body -H "$auth" -H "$json" \
  "$ASKDBLM_ADMIN/survey-forms" -d @form.json | jq -r '.name'

# 2. A broadcast that sends the form, one link per person.
id=$(curl -sS --fail-with-body -H "$auth" -H "$json" \
  "$ASKDBLM_ADMIN/survey-broadcasts" \
  -d '{"name": "March onboarding", "form": "onboarding"}' | jq -r '.id')

# 3. The list of people, as a CSV with a column of ids (and, if you like, names).
curl -sS --fail-with-body -X PUT -H "$auth" -H "Content-Type: text/csv" \
  --data-binary @people.csv \
  "$ASKDBLM_ADMIN/survey-broadcasts/$id/recipients?file_name=people.csv" \
  | jq '{ready: .review.ready, will_issue: .review.will_issue, skipped: .review.skipped, problems: .review.problems}'

# 4. Issue a link to exactly as many people as the review counted.
n=$(curl -sS -H "$auth" "$ASKDBLM_ADMIN/survey-broadcasts/$id" | jq -r '.review.will_issue')
curl -sS --fail-with-body -X POST -H "$auth" -H "$json" \
  "$ASKDBLM_ADMIN/survey-broadcasts/$id/issue" -d "{\"confirm_recipients\": $n}" \
  | jq '{status, total}'

# 5. Take the links and send them yourself; read the answers the same way.
curl -sS --fail-with-body -H "$auth" \
  "$ASKDBLM_ADMIN/survey-broadcasts/$id/links.csv" -o links.csv
curl -sS --fail-with-body -H "$auth" \
  "$ASKDBLM_ADMIN/survey-broadcasts/$id/results.csv" -o results.csv

Each link is https://<survey host>/s/<token>; the host comes from the instance's survey settings. A person's answers are saved screen by screen, so a form left half-finished is resumed on the next visit, and one person keeps one submission. For a single person, POST /survey-forms/{name}/link with {"user_id": "…"} returns their url too. The people and their answers are read through the read-only survey connection, and a person can be forgotten with POST /survey-responses/forget (see Survey responses).

7. Security

A personal access token is as powerful as its role. An owner token can:

• read every setting;
• change connections and their credentials, including pointing a connection at a different server;
• change which AI model answers questions, and so where your questions and schemas are sent;
• issue API keys that keep working after the token is revoked;
• change who may use the instance.

Treat an owner token like the password to the whole instance.

• Give a token the smallest role that does the job. Deploying fassads needs editor. Reading the configuration needs viewer.
• Give each script its own token, with a short expiry, so that revoking one stops one thing.
• Keep tokens in a secret manager or your CI system's secret store, never in a repository, a web page or an app you ship. The API sends no CORS headers, so browsers will not let a web page call it anyway.
• Revoke a token at once if it may have leaked, on the Access tokens page. Then check the Audit page for what was done with it, including any API keys it issued.
• When somebody leaves, their tokens stop working with their access. You don't need to hunt them down.

Nothing in this API can write to your databases. Every query the instance runs against them is checked to be read-only, and fassads and widgets whose queries would change data are refused.

8. Troubleshooting

401 invalid_token. The token was revoked, or it was copied incompletely. A token is one unbroken string that starts with dblm_pat_.

401 access_revoked. The token's owner no longer has access to the instance. Tokens stop working when their owner does.

403 insufficient_role with a token you made as an owner. The token acts at the lesser of its own role and yours. If your role was lowered, so was your tokens'.

403 tokens_cannot_create_tokens. Create tokens on the Access tokens page, signed in as yourself.

409 managed_by_portal. In a hosted instance, invite and remove people in askDBLM rather than through this API.

409 jobs_running. Wait for the job working on that database (see GET /jobs), or cancel it, then try again.

503 portal_unavailable. A hosted instance could not reach askDBLM to confirm the token's owner. Tokens keep working through a short outage; retry in a minute.

My change seems to be ignored. Fields an endpoint does not use are ignored rather than refused. Check the field names against this guide.

9. Compatibility

The configuration API is the API the control panel is built on, so it grows with the panel. Endpoints and fields documented here keep working. New endpoints and new response fields may appear at any time, so ignore fields you don't recognise. A change that would break a documented call will be listed here before it ships.

Changes