Automate with the API

Drive Datasentinel programmatically — provision monitored instances, manage users and roles, export metrics, schedule reports, and control agents through the REST API.

Almost everything you can do from the Datasentinel user interface can also be done through its REST API. The API is the foundation for automation — provisioning instances from your CI/CD pipelines, synchronizing users and roles with your identity processes, exporting metrics into your own data stores, scheduling reports, and integrating alerting with your incident-management tooling.

This guide walks you through the two API surfaces Datasentinel exposes, how to authenticate against each, and the most common automation recipes — end to end.

A comprehensive toolkit, with ready-to-use examples, is published on GitHub and ships pre-installed with the on-premises platform at /datasentinel/soft/datasentinel_toolkit.

Two API surfaces

Datasentinel exposes two distinct APIs, each serving a different layer of the architecture. Choosing the right one is the first decision you make.

Platform API

Centralized control

Runs on the platform. Manage agentless connections, users, roles, alerting, and pull workload metrics and PDF reports across all monitored instances.

Agent API

Per-agent control

Runs on each host where an agent is installed. Manage that agent's own connections, upload server, proxy, and per-connection collection settings.

At a glance:

	Platform API	Agent API
Base URL	https://<<platform-server>>/ds-api	https://<<agent-host>>:8282/api
Auth header	user-token (generated, valid 24h)	api-token (your Datasentinel license key)
Scope	The whole platform / all instances	A single agent and its connections
Availability	On-premises platform installations	Wherever an agent is installed
Use it for	Agentless provisioning, RBAC, reports, metric export, alerting	Agent lifecycle, agent-side connections, collection tuning

---

Platform API

Authenticate

Every Platform API call (except token creation itself) requires a short-lived access token passed in the user-token header. You obtain it by authenticating once with a valid platform username and password.

1

Generate an access token

Authenticate with your credentials to receive a token. Store it in an environment variable so the following calls can reuse it.

export ACCESS_TOKEN=$(curl -sk -u myUser:myPassword \
  -X POST https://$DATASENTINEL_HOST/ds-api/user-token \
  | sed -E 's/.*"user-token" *: *"([^"]+)".*/\1/')

The raw response is a single JSON field:

{
  "user-token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1ODAyMTYyMjQ..."
}

2

Use the token in subsequent calls

Pass the token in the user-token header of every request:

curl -sk --header "user-token: $ACCESS_TOKEN" \
  https://$DATASENTINEL_HOST/ds-api/users

3

Check token validity (optional)

You can inspect a token's owner and expiry at any time:

curl -sk -u myUser:myPassword \
  "https://$DATASENTINEL_HOST/ds-api/user-token?token=$ACCESS_TOKEN"

{
  "email": "[e-mail]",
  "expire_time": "2026-05-26 13:58:53",
  "organization_name": "ds-data",
  "user": "datasentinel"
}

Access tokens are valid for 24 hours. For long-running automation, generate a fresh token at the start of each run rather than persisting one.

Access Token

Register a monitored instance (agentless)

With the Agentless feature, you can declare a PostgreSQL instance directly on the platform or use the API.

Tags drive dashboards, consolidation, and role-based access.

1

Build the connection payload

cat > /tmp/connection.json <<EOF
{
  "host": "pg-sales-1734",
  "port": 9342,
  "user": "datasentinel",
  "password": "sentinel",
  "tags": "application=sales,environment=production,provider=amazon,datacenter=lyon"
}
EOF

2

Create the connection

The connection name becomes its identifier on the platform.

curl -sk --header "user-token: $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  -X POST https://$DATASENTINEL_HOST/ds-api/pool/pg-instances/sales-production \
  -d @/tmp/connection.json

{ "status": "Connection created and connected!" }

3

Verify, then enable or disable as needed

# Read it back
curl -sk --header "user-token: $ACCESS_TOKEN" \
  https://$DATASENTINEL_HOST/ds-api/pool/pg-instances/sales-production

# Temporarily pause monitoring
curl -sk --header "user-token: $ACCESS_TOKEN" \
  -X PATCH https://$DATASENTINEL_HOST/ds-api/pool/pg-instances/sales-production/disable

Tags follow the format key=value,key=value. A consistent tagging strategy is the single most important input for filtering, consolidation, and RBAC. See Organize Content using Tags.

Connection

Provision users and roles

Roles are tag-based access rules; users are granted one or more roles. Together they implement role-based access control.

The example below grants a user access to production instances in the London datacenter only.

1

Create a tag-based role

A role's access array holds one or more filter sets. Tags inside the same filters array are combined with AND; separate filter sets are combined with OR.

cat > /tmp/role.json <<EOF
{
  "access": [
    {
      "filters": [
        { "tag": "environment", "value": "production" },
        { "tag": "datacenter",  "value": "london" }
      ]
    }
  ]
}
EOF

curl -sk --header "user-token: $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  -X POST https://$DATASENTINEL_HOST/ds-api/roles/london-prod \
  -d @/tmp/role.json

{ "status": "Role name london-prod created successfully" }

Every tag key/value pair referenced by a role must already exist on at least one monitored instance. New instances matching the rules are added to the role scope automatically.

2

Create a user

Provide a password for a regular user (or set "ldap": true for an LDAP-authenticated account).

Assign roles with the roles array.

cat > /tmp/user.json <<EOF
{
  "password": "myPassword",
  "privilege": "read",
  "profile": "data admin",
  "live_360": 1,
  "roles": ["london-prod"]
}
EOF

curl -sk --header "user-token: $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  -X POST https://$DATASENTINEL_HOST/ds-api/users/[e-mail] \
  -d @/tmp/user.json

{ "status": "User with login jane.doe created successfully" }

3

Adjust role assignments later

Roles can be added to or removed from an existing user at any time:

# Grant another role
curl -sk --header "user-token: $ACCESS_TOKEN" \
  -X POST https://$DATASENTINEL_HOST/ds-api/users/[e-mail]/role/sales-role

# Revoke a role
curl -sk --header "user-token: $ACCESS_TOKEN" \
  -X DELETE https://$DATASENTINEL_HOST/ds-api/users/[e-mail]/role/london-prod

The roles array replaced the single role field in version 2024.04. The role field is deprecated (use roles for new automation).

Role API

Create, replace, list roles and their assigned users.

User API

Create, update, delete users; assign and remove roles.

Export workload metrics

The Workload API returns raw metrics in JSON or CSV, ideal for feeding dashboards, capacity planning, or a data warehouse. All endpoints accept a time window (from/to) and a filters array of tags to scope the result.

JSON

cat > /tmp/query.json <<EOF
{
  "from": "2026-05-01",
  "to": "2026-05-25",
  "filters": [ { "tag": "application", "value": "crm" } ],
  "output": "json"
}
EOF

curl -sk --header "user-token: $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  -X POST https://$DATASENTINEL_HOST/ds-api/activity/top-queries \
  -d @/tmp/query.json

CSV

Frequently used Workload endpoints (all under /ds-api/activity/):

Endpoint	Returns
session-history	Active Session History samples
top-queries	Most resource-intensive queries
queries-summary	Aggregated query metrics per database
pg-instance-infos	Inventory: version, size, type (primary/replica), uptime
pg-instance / server	Cluster and host activity (summary or minute-by-minute)
tables / indexes	Table and index activity
top-consumers	Top consumers of a resource, grouped by any tag

Workload

Generate and email a PDF report

The Reporting API produces the same PDF reports available in the UI.

Add the email parameters to have the platform deliver the report directly to recipients.

cat > /tmp/report.json <<EOF
{
  "from": "2026-05-24",
  "to": "2026-05-25",
  "filters": [ { "tag": "environment", "value": "production" } ],
  "report_type": "email",
  "subject": "[Datasentinel] Daily production workload",
  "recipients": ["[e-mail]"]
}
EOF

curl -sk --header "user-token: $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  -X POST https://$DATASENTINEL_HOST/ds-api/activity/full-report \
  -d @/tmp/report.json

Swap full-report for session-history-report, top-queries-report, table-report, instance-report, server-report, query-report, or data-size-report to generate a single section.

Omit the report_type/subject/recipients fields to receive the PDF in the response body instead of by email.

Reporting

Pause alerting during maintenance

Suppress noisy notifications while you perform planned maintenance, then re-enable them — scriptable around your change windows. The instance is identified by <<server_name>>@<<pg_name>>.

INSTANCE="pg-crm-2031@:9342"

# Before maintenance — silence the instance
curl -sk --header "user-token: $ACCESS_TOKEN" \
  -X PATCH "https://$DATASENTINEL_HOST/ds-api/alerting/$INSTANCE/disable"

# After maintenance — restore alerting
curl -sk --header "user-token: $ACCESS_TOKEN" \
  -X PATCH "https://$DATASENTINEL_HOST/ds-api/alerting/$INSTANCE/enable"

You can also read current alert status, list active problems, or raise a custom alert from your own checks (for example, a failed backup):

cat > /tmp/alert.json <<EOF
{ "message": "Daily backup failed : No disk space" }
EOF

curl -sk --header "user-token: $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  -X POST "https://$DATASENTINEL_HOST/ds-api/alerting/$INSTANCE/problems" \
  -d @/tmp/alert.json

Alerting

---

Agent API

When you install a local agent on a host, that agent exposes its own API for managing its lifecycle and the connections it monitors.

Use it for agent-based deployments where each agent owns its connections directly.

Authenticate

The Agent API listens on port 8282 by default and authenticates with the api-token header. This token is your Datasentinel license key — the same one the agent uses to communicate with the platform.

export TOKEN=<<datasentinel_token>>
export AGENT_HOST=localhost      # or the host where the agent runs

Read-only calls such as status do not require the token; state-changing calls (stop, configuration, connection management) do.

Inspect an agent

curl -sk https://$AGENT_HOST:8282/api/agent/status

{
  "version": "3.4.1",
  "server": "pg-sales-3127",
  "port": 8282,
  "collection-rate": "low",
  "connections": { "connections": 1, "running": 1, "not running": 0 }
}

Add and monitor a connection

1

Create the connection

cat > /tmp/connection.json <<EOF
{
  "host": "pg-sales-3127",
  "port": 9342,
  "user": "datasentinel",
  "password": "sentinel",
  "tags": "application=sales,environment=production"
}
EOF

curl -sk --header "api-token: $TOKEN" \
  --header "Content-Type: application/json" \
  -X POST https://$AGENT_HOST:8282/api/connections/sales_prod \
  -d @/tmp/connection.json

{ "status": "Connection created and connected!" }

2

Toggle per-connection collection features

Each connection's collection level is tuned independently:

# Enable query sample collection
curl -sk --header "api-token: $TOKEN" \
  -X PATCH https://$AGENT_HOST:8282/api/connections/sales_prod/enable-samples

# Set the lock-monitoring delay to 90 seconds
curl -sk --header "api-token: $TOKEN" \
  -X PATCH https://$AGENT_HOST:8282/api/connections/sales_prod/lock-monitoring-delay/90

# Disable table monitoring
curl -sk --header "api-token: $TOKEN" \
  -X PATCH https://$AGENT_HOST:8282/api/connections/sales_prod/disable-table-monitoring

3

Enable or disable connections in bulk

curl -sk --header "api-token: $TOKEN" \
  -X PATCH https://$AGENT_HOST:8282/api/connections/enable

Collection settings reference

The toggles above map directly to the Collection Level feature. Common per-connection switches (all PATCH under /api/connections/{name}/):

Path suffix	Effect
enable-samples / disable-samples	Query sample collection
enable-lock-monitoring / disable-lock-monitoring	Lock monitoring
lock-monitoring-delay/{seconds}	Lock-monitoring delay
enable-table-monitoring / disable-table-monitoring	Table & index activity
enable-query-monitoring / disable-query-monitoring	Query monitoring
query-monitoring-min-calls/{n} / query-monitoring-min-time/{s}	Query monitoring filters
enable-query-monitoring-optimize / disable-query-monitoring-optimize	Query monitoring optimization

The Agent API also manages the agent lifecycle (status, stop, port), the upload server it sends metrics to (/api/server), and an optional outbound proxy (/api/proxy).

API Reference

---

Full API reference

This guide covers the most common automation patterns. For the complete list of endpoints, parameters, request bodies, and response shapes, see the reference pages:

Access Token

Connection

Role

User

Reporting

Workload

Alerting

Agent API

Best practices

• Generate a fresh access token per run. Platform tokens expire after 24 hours; don't persist them in pipelines.

• Tag at creation time. Tags drive filtering, consolidation, and RBAC — apply them when you register an instance, not after. See Organize Content using Tags.

• Drive RBAC from tags, not per-instance rules. Define roles against a consistent tagging strategy so new instances are scoped automatically. See Manage Users and Role-Based Access.

• Start from the toolkit. The datasentinel_toolkit provides working scripts for most of these recipes.

Conclusion

The Platform and Agent APIs together let you operate Datasentinel entirely as code — from onboarding instances and users to exporting metrics, scheduling reports, and integrating alerting into your existing workflows. Pick the Platform API for centralized, cross-instance automation, and the Agent API for per-agent and collection-level control.