Sandbox / API examples

Demo API examples

Every endpoint below is callable directly against this deployment. The examples use root-relative paths so they work on localhost, Vercel previews, and pdpp.dev. All responses are JSON; all carry an x-pdpp-demo header so agents can be sure they are looking at sandbox data.

The full surface map lives at /reference.

Public-shaped APIs (/sandbox/v1)

Schema graph

GET /sandbox/v1/schema

Use when discovering what streams and fields the demo dataset offers.

curl -s /sandbox/v1/schema

Returns connectors → streams → fields with semantic class.

List streams

GET /sandbox/v1/streams

Each summary includes stream key, label, record count, and field count.

curl -s '/sandbox/v1/streams?limit=10'

Paginated list of stream summaries.

Stream detail

GET /sandbox/v1/streams/pay_statements

Replace the path segment with any stream key from the schema graph.

curl -s /sandbox/v1/streams/pay_statements

Full stream descriptor with schema, retention, and counts.

List records

GET /sandbox/v1/streams/pay_statements/records

Supports cursor pagination via `limit` and `cursor`.

curl -s '/sandbox/v1/streams/pay_statements/records?limit=2'

Paginated record summaries newest-first, each with a preview string.

Record detail

GET /sandbox/v1/streams/pay_statements/records/rec_sb_paystmt_2026_03

Returns the full fictional record including its projection map.

curl -s /sandbox/v1/streams/pay_statements/records/rec_sb_paystmt_2026_03

Full field projection for one record.

Search

GET /sandbox/v1/search

Try queries like `payroll`, `Northwind`, `follow-up`.

curl -s '/sandbox/v1/search?q=payroll'

Lexical hits across all seeded records with snippets and matched fields.

Reference-only inspection APIs (/sandbox/_ref)

List grants

GET /sandbox/_ref/grants

Filter by `status` (issued, revoked, denied) or `client_id`.

curl -s '/sandbox/_ref/grants?status=revoked'

Reference-only grant summaries with status and stream.

Grant timeline

GET /sandbox/_ref/grants/grant_sb_quill_paystmt/timeline

See request → consent → grant → resource read events end-to-end.

curl -s /sandbox/_ref/grants/grant_sb_quill_paystmt/timeline

Per-event timeline for one grant.

Run timeline

GET /sandbox/_ref/runs/run_sb_acme_2026_04_22/timeline

Includes `started`, `records.synced`, and `succeeded`/`failed` events.

curl -s /sandbox/_ref/runs/run_sb_acme_2026_04_22/timeline

Per-event timeline for one connector run.

Trace timeline

GET /sandbox/_ref/traces/trace_sb_quill_paystmt

Shows the full PDPP interaction across grant + resource read.

curl -s /sandbox/_ref/traces/trace_sb_quill_paystmt

Trace-level timeline merging grant and run events.

Dataset summary

GET /sandbox/_ref/dataset/summary

Connector count, stream count, record count, retained-bytes approximation.

curl -s /sandbox/_ref/dataset/summary

Top-level dataset statistics for the demo instance.

OAuth-shaped metadata (/sandbox/.well-known)

Authorization server metadata

GET /sandbox/.well-known/oauth-authorization-server

Inspect the issuer, authorization endpoint, and supported scopes for the mock AS.

curl -s /sandbox/.well-known/oauth-authorization-server

Demo AS metadata advertising sandbox-prefixed endpoints.

Protected resource metadata

GET /sandbox/.well-known/oauth-protected-resource

Use to confirm the RS resource identifier and authorization servers list.

curl -s /sandbox/.well-known/oauth-protected-resource

Demo RS metadata advertising sandbox-prefixed endpoints.