Query Database

For an application or agent, query the Database through the Deepline API. Your Deepline API key selects the workspace; the API runs one bounded SQL statement against that workspace’s Database. You do not need to expose a PostgreSQL connection string. Use a direct PostgreSQL URI only when a database-native tool, such as BI or psql, genuinely needs one.

Query the API securely

Send the request from your server, worker, or trusted agent runtime. Keep DEEPLINE_API_KEY in server-side secret storage. Never put it in a browser application or commit it to source control.

curl -sS -X POST https://code.deepline.com/api/v2/db/query \
  -H "Authorization: Bearer $DEEPLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT domain, company_name FROM enrichments.companies ORDER BY updated_at DESC LIMIT 20",
    "max_rows": 20
  }'

A successful response returns rows, columns, row_count_returned, and truncated. An empty rows array means the query ran but found no matches.

The API accepts one SQL statement and up to 1,000 returned rows per request. Use max_rows to bound the result you need.

Use the SDK

The SDK uses the same API boundary:

import { DeeplineClient } from 'deepline';

const client = new DeeplineClient({
  apiKey: process.env.DEEPLINE_API_KEY,
});

const result = await client.db.query({
  sql: 'SELECT identity_key, display_name FROM dl_resolved.people ORDER BY updated_at DESC LIMIT 20',
  maxRows: 20,
});

Query rules

Operation	Where it is allowed
Read a managed Database view	`SELECT`, `EXPLAIN`, read-only `WITH`, and aggregates
Create or change agent-owned data	Schema-qualified `storage.<table>` only
Change Deepline-managed data	Never through this API

For example, an agent or application can create its own scratch table:

CREATE TABLE IF NOT EXISTS storage.agent_notes (
  id text PRIMARY KEY,
  note text NOT NULL,
  created_at timestamptz NOT NULL DEFAULT now()
);

These statements are intentionally blocked:

CREATE TABLE agent_notes (...);
CREATE TABLE tenant_custom.agent_notes (...);
DELETE FROM enrichments.companies WHERE domain = 'example.com';

Keep the boundary safe

Do not forward arbitrary browser input as SQL. Build queries in trusted server-side code and constrain the tables, columns, and filters your product permits.
Do not accept query text from an end user. Use fixed, allowlisted queries and validate request values before your server builds the SQL. Treat raw SQL as privileged input.
Set max_rows and select only the columns your caller needs.
Use the Database for working state. Write approved outcomes to your CRM; see Where data lives.

Direct PostgreSQL access

Use a Database URI only for a database-native application or BI tool. Obtain it from the dashboard’s Database Access flow, store it in server-side secret storage, and write only to storage.*. Provisioning, URI reveal, and password rotation are dashboard/admin-session controls; they are not the public query API.

SDK API reference

See the supported POST /api/v2/db/query contract and SDK method.

Get started

Build and automate

Common workflows

Data and integrations

Reference

Query the API securely

Use the SDK

Query rules

Keep the boundary safe

Direct PostgreSQL access

SDK API reference

​Query the API securely

​Use the SDK

​Query rules

​Keep the boundary safe

​Direct PostgreSQL access

SDK API reference

Query the API securely

Use the SDK

Query rules

Keep the boundary safe

Direct PostgreSQL access