Local REST API — step-by-step

When to use the API

The local API runs inside the NoSqlStudio desktop app on a configurable port (default 8081, loopback only). External tooling can call the same engines you use through the UI:

• CI/CD pipeline masks production data before refreshing dev/staging (DataMask).
• PR gate: run schema diff and block the merge when breaking changes appear (DB Compare).
• Datadog or Grafana scrapes slow-query metrics every 60s (Profiler).
• Cron job generates the quarterly ANPD/GDPR compliance report (Compliance Reports).
• Slack bot fires DB Copy + Slack thread + JIRA ticket in 5 minutes (cross-tool workflow).

Setup (one-time)

1. Open the NoSqlStudio desktop app, then Settings → API Access.
2. Toggle "Enable local API server" ON. The server starts on 127.0.0.1:8081 by default.
3. Click "Create token" — give it a label (e.g. "CI/CD GitHub Actions"). The raw token appears ONCE — copy it now into 1Password / Vault / AWS Secrets Manager. It cannot be retrieved later.
4. (Optional) Change Bind to 0.0.0.0 if you need cross-host access on a trusted network. The Bearer token is the only protection.

First request

Test the health endpoint with curl from any terminal:

curl -H "Authorization: Bearer nsk_..." \
  http://localhost:8081/api/health

Expected response:

{
  "status": "ok",
  "app": "NoSqlStudio",
  "time": "2026-05-25T18:42:11.123Z",
  "uptimeSec": 327
}

Endpoint reference (v1)

10 endpoints across 6 resource groups. Full OpenAPI 3.1 spec available at /api/openapi.json.

Authentication

Every authenticated endpoint requires a Bearer token in the Authorization header. Tokens are 32-byte random hex strings prefixed nsk_. We persist only the SHA-256 of the raw token on disk; a stolen tokens file is useless without the raw values.

Scopes

• * — Full access (default when you create a token without specifying scopes).
• datamask — DataMask jobs (create, status, abort).
• db-compare — DB Compare schema + index diff.
• profiler — Profiler slow-query feed.
• schema — Schema sampler.
• cosmos — Cosmos RU budget + forecast.
• connections — List saved connections (metadata only).

5 real-world use cases

1. Mask production data in a GitHub Actions pipeline

Refresh dev/staging on a schedule. Before the copy runs, fire DataMask via API and fail the pipeline if the job errors:

# .github/workflows/refresh-dev-db.yml
- name: Mask production data
  run: |
    curl -X POST http://nosql-jumpbox:8081/api/datamask/jobs \
      -H "Authorization: Bearer ${{ secrets.NOSQL_TOKEN }}" \
      -d '{"source":"mongodb://prod/...","target":"mongodb://dev/...","policy":"lgpd-prod"}'

2. Schema diff as PR gate

Block merge when the PR introduces breaking schema changes:

DIFF=$(curl http://localhost:8081/api/db-compare \
  -H "Authorization: Bearer $NOSQL_TOKEN" \
  -d '{"source":"main","target":"this-pr"}')
echo "$DIFF" | jq '.diff.breakingChanges | length' | xargs test 0 -eq

3. Slow-query feed in Datadog / Grafana

Custom metric scraped every 60 seconds — count queries above the p99 threshold so the dashboard shows live degradation:

# Datadog custom metric scrape (every 60s)
curl "http://localhost:8081/api/profiler/slow-queries?since=5m&p99_ms_gte=500" \
  -H "Authorization: Bearer $NOSQL_TOKEN" \
  | jq '.queries | length'

4. Quarterly ANPD/GDPR compliance report

Cron job generates the report and drops the PDF on the shared audit drive — DPO only signs:

# /etc/cron.d/quarterly-ropa
0 8 1 */3 * curl -X POST http://localhost:8081/api/compliance/reports/quarterly \
  -H "Authorization: Bearer $NOSQL_TOKEN" \
  -o /audit/$(date +%Y-Q%q).pdf

5. Slack bot → DataMask → JIRA ticket

Dev asks for masked production copy in Slack, bot fires DB Copy + Mask, posts status on thread, opens JIRA ticket with download link — 5 minutes end-to-end:

# Slack bolt handler
app.command('/db-copy', async ({ command, ack, say }) => {
  await ack();
  const job = await fetch('http://localhost:8081/api/db-copy/jobs', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${process.env.NOSQL_TOKEN}` },
    body: JSON.stringify({ source: command.text, target: 'dev-sandbox' })
  }).then(r => r.json());
  await say(`📋 Job ${job.jobId} queued`);
});

HTTP status codes

Security checklist

• Bind 127.0.0.1 unless you need cross-host access. 0.0.0.0 exposes the API on every NIC — token rotation becomes critical.
• Rotate tokens every 90 days. Revoke immediately when an employee leaves or when a token leaks (e.g. accidentally committed to a public repo).
• Use per-environment tokens (one for CI, one for Datadog scrape, one for Slack bot) with the minimal scope each needs.
• Every authenticated request is recorded in the consolidated audit log (Tools → Audit Log). Cross-reference token id + source IP if you suspect abuse.
• TLS is NOT auto-configured — use a reverse proxy (nginx, Caddy) in front of the API if you bind to 0.0.0.0.

OpenAPI spec

Download the full OpenAPI 3.1 spec and import it into Postman, Insomnia, or Bruno to explore every endpoint interactively:

curl http://localhost:8081/api/openapi.json -o nosqlstudio-api.json
# Import into Postman / Insomnia / Bruno