Skip to main content

Quick start 3 — expose a governed Data API service

Goal: give another app or partner a read-only JSON endpoint over your data — without exposing SQL, credentials or your database. ~10 minutes.

Agent Flows → Data API: define service  →  test  →  mint token  →  consumers call /v1/<slug>

1. Define the service (Agent Flows → Data API)​

Open Agent Flows, switch to the Data API tab, and + New service:

  • Slug — the URL name, e.g. top-customers.
  • Source — which connector it reads.
  • Kind — sql (a stored SELECT with :name parameter placeholders), routine (stored procedure / SAP BAPI), or api (a SaaS object fetch, e.g. HubSpot contacts).
Example service body (kind: sql)
SELECT customer_id, company_name, SUM(amount) AS revenue
FROM   orders JOIN customers USING (customer_id)
WHERE  order_date >= :since
GROUP  BY 1, 2
ORDER  BY revenue DESC
LIMIT  :top

Callers may only pass the parameters you declare (since, top) — never arbitrary SQL. Optionally add a mediation transform (filter rows, cast/rename columns, computed columns) and set concurrency, timeout, retries and a per-service rate limit.

Defining a Data API service

2. Test, then mint a token​

Test runs the service with sample parameters and shows the exact JSON consumers will get. When it looks right, + Token — copy it once (tokens are stored hashed), set an expiry, and later rotate (successor with a grace window) or revoke it without touching the service.

3. Call it​

curl "https://your-dataapi-host/v1/top-customers?since=2026-01-01&top=10" \
  -H "Authorization: Bearer <token>"
# → { "columns": [...], "data": [...], "meta": {...} }

Three call styles, no extra work:

  • Paged extracts — ?offset=N&limit=M; meta.next_offset walks millions of rows in bounded pages.
  • Async — ?async=1 returns a job id to poll; the run goes through a durable Postgres-backed queue.
  • Scheduled — give the service a cadence and AgentData enqueues the call itself — a lightweight recurring sync.

4. Watch it​

The Data API monitor (Monitoring) shows queue depth, per-service call counts, error rates, p95 latency and the recent-call log — every call is audited.

Where this fits

The Data API is one of three data-movement paths — batch Flows, real-time Streamer, governed Data API out. Data movement compares them.