API Reference

The Dataplane API lets you create, manage, and monitor data pipelines programmatically. Use it to integrate pipeline management into your existing workflows, CI/CD systems, or internal tools.

All endpoints return JSON. Authentication uses Bearer tokens — either session tokens or API keys.

Authentication

Every authenticated request requires a Bearer token in the Authorization header.

API Keys

API keys are the recommended way to authenticate programmatic access. Create them in Settings → API Keys in the dashboard.

Key format: API keys start with dp_ followed by 64 hex characters. The full key is shown once at creation — copy it immediately.

Request with API key

curl https://trydataplane.dev/api/pipelines \
  -H "Authorization: Bearer dp_a1b2c3d4e5f6..."

Key lifecycle

Action	Endpoint	Notes
Create	`POST /api/settings/api-keys`	Returns the full key once. Store securely.
List	`GET /api/settings/api-keys`	Shows prefix only (`dp_xxxxxxxxx`).
Revoke	`DELETE /api/settings/api-keys/:id`	Immediately invalidates the key.

Session tokens

Returned by POST /api/auth/login and POST /api/auth/signup. Same Bearer format. Expire after 30 days. Primarily for browser use — prefer API keys for integrations.

Base URL

https://trydataplane.dev

All API paths are relative to this base. Requests must use HTTPS.

List pipelines

Returns all pipelines belonging to the authenticated user, ordered by creation date (newest first). Maximum 50 results.

GET /api/pipelines

Request

curl

curl https://trydataplane.dev/api/pipelines \
  -H "Authorization: Bearer dp_YOUR_API_KEY"

Response

200 OK

{
  "success": true,
  "pipelines": [
    {
      "id": 42,
      "name": "Stripe Revenue Dashboard",
      "description": "Pull Stripe charges into Postgres, aggregate by day",
      "source_type": "api",
      "destination_type": "postgres",
      "status": "completed",
      "generated_summary": "Fetches Stripe charges via API, transforms...",
      "error_message": null,
      "created_at": "2026-04-08T14:30:00.000Z",
      "updated_at": "2026-04-08T14:31:12.000Z"
    }
  ]
}

Create pipeline

Creates a new pipeline and triggers async AI generation. The response returns immediately with status "generating". Poll GET /api/pipelines/:id to check when generation completes.

POST /api/pipelines

Body parameters

Parameter	Type	Description
description required	string	Natural-language description of what the pipeline should do. This is the AI prompt.
name optional	string	Display name. Defaults to `Pipeline YYYY-MM-DD`.
source_type optional	string	Data source type. Defaults to `"csv"`. Options: `csv`, `api`, `database`, `s3`, `webhook`, `spreadsheet`.
destination_type optional	string	Destination type. Defaults to `"postgres"`.
requirements optional	string	Additional requirements or constraints for the AI generator.

Request

curl

curl -X POST https://trydataplane.dev/api/pipelines \
  -H "Authorization: Bearer dp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe Revenue Dashboard",
    "description": "Pull Stripe charges via API, aggregate revenue by day and plan, load into Postgres",
    "source_type": "api",
    "destination_type": "postgres"
  }'

Response

200 OK

{
  "success": true,
  "pipeline": {
    "id": 42,
    "name": "Stripe Revenue Dashboard",
    "status": "generating",
    "created_at": "2026-04-08T14:30:00.000Z"
  }
}

Async generation: Pipeline code is generated by AI in the background. Status transitions from generating → completed (or failed). Poll the get endpoint to check progress.

Free plan limit: Free accounts are limited to 1 pipeline. Attempting to create more returns 403 with upgrade_required: true.

Get pipeline

Retrieves a single pipeline with all generated code, architecture, SQL transformations, and configuration.

GET /api/pipelines/:id

Path parameters

Parameter	Type	Description
id required	integer	Pipeline ID.

Request

curl

curl https://trydataplane.dev/api/pipelines/42 \
  -H "Authorization: Bearer dp_YOUR_API_KEY"

Response

200 OK

{
  "success": true,
  "pipeline": {
    "id": 42,
    "name": "Stripe Revenue Dashboard",
    "description": "Pull Stripe charges via API...",
    "source_type": "api",
    "destination_type": "postgres",
    "status": "completed",
    "generated_architecture": "{...}",
    "generated_sql": "CREATE TABLE stripe_charges ...",
    "generated_schema": "CREATE TABLE ...",
    "generated_cron": "0 */6 * * *",
    "generated_api": "// Express route handler...",
    "generated_summary": "Fetches Stripe charges via API...",
    "metadata": {
      "recommendations": ["Add retry logic", "Monitor row counts"],
      "pipeline_name": "stripe_revenue_dashboard"
    },
    "created_at": "2026-04-08T14:30:00.000Z",
    "updated_at": "2026-04-08T14:31:12.000Z"
  }
}

Delete pipeline

Permanently deletes a pipeline. Requires ownership — you can only delete pipelines you created.

DELETE /api/pipelines/:id

Path parameters

Parameter	Type	Description
id required	integer	Pipeline ID to delete.

Request

curl

curl -X DELETE https://trydataplane.dev/api/pipelines/42 \
  -H "Authorization: Bearer dp_YOUR_API_KEY"

Response

200 OK

{
  "success": true,
  "message": "Pipeline deleted"
}

List pipeline runs

Returns paginated execution history for a pipeline, including summary statistics (total runs, success rate, average duration).

GET /api/pipelines/:id/executions

Path parameters

Parameter	Type	Description
id required	integer	Pipeline ID.

Query parameters

Parameter	Type	Description
page optional	integer	Page number, starting at 1. Default: `1`.
limit optional	integer	Results per page. Range: 1–100. Default: `20`.

Request

curl

curl "https://trydataplane.dev/api/pipelines/42/executions?page=1&limit=10" \
  -H "Authorization: Bearer dp_YOUR_API_KEY"

Response

200 OK

{
  "success": true,
  "executions": [
    {
      "id": 108,
      "pipeline_id": 42,
      "status": "success",
      "started_at": "2026-04-08T14:30:00.000Z",
      "completed_at": "2026-04-08T14:31:12.000Z",
      "duration_ms": 72000,
      "rows_processed": null,
      "error_message": null,
      "trigger_type": "manual",
      "created_at": "2026-04-08T14:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "pages": 1
  },
  "stats": {
    "total_runs": 1,
    "successful_runs": 1,
    "success_rate": 100,
    "avg_duration_ms": 72000,
    "last_run_at": "2026-04-08T14:31:12.000Z"
  }
}

Response format

All API responses are JSON with a consistent structure.

Success responses

Every successful response includes "success": true alongside the resource data:

Success pattern

{
  "success": true,
  "pipeline": { /* ... resource data */ }
}

Error responses

Errors include "success": false and a human-readable message:

Error pattern

{
  "success": false,
  "message": "Pipeline not found"
}

Some error responses include additional fields for client-side handling:

Upgrade required (403)

{
  "success": false,
  "message": "Free plan is limited to 1 pipeline. Upgrade to Pro for unlimited pipelines.",
  "upgrade_required": true,
  "current_plan": "free"
}

Rate limits

The API currently does not enforce hard rate limits. Use reasonable request volumes — if you're polling, use intervals of 5 seconds or more.

Pipeline creation involves AI generation which takes 30–90 seconds. There's no benefit to rapid creation requests.

Fair use policy: Sustained bursts above 60 requests/minute per key may be throttled in the future. We'll add X-RateLimit-* headers before enforcing limits.

Error codes

Standard HTTP status codes are used throughout the API.

Status	Meaning	Common causes
400	Bad Request	Missing required fields (e.g., `description` on create).
401	Unauthorized	Missing or invalid Bearer token. API key may be revoked.
403	Forbidden	Plan limits reached (`upgrade_required: true`), or attempting to access another user's resource.
404	Not Found	Pipeline ID doesn't exist, or was deleted.
500	Internal Server Error	Unexpected failure. These are logged and investigated.

Example error response

401 Unauthorized

{
  "success": false,
  "message": "Authentication required"
}

404 Not Found

{
  "success": false,
  "message": "Pipeline not found"
}

Questions? Reach out at support@trydataplane.dev