DBConvert Streams API Reference

Use this page to find the exact endpoint contract for the current DBConvert Streams backend.

Jump to full API contract — interactive Swagger UI with all endpoints, schemas, and Try it out.

Start here when you need:

• the required headers for an API request
• the correct endpoint group for a workflow
• the exact request body, response schema, or status code for an operation
• the live Swagger UI for the checked-in OpenAPI contract

For copy-paste examples and workflow walkthroughs, use the linked guides in Choose the right guide.

Prerequisites

• A running DBConvert Streams API server
• Your API base URL
• Access to the authentication values described in Authentication headers

On a new installation, open DBConvert Streams once, connect your account, and obtain the required authentication values before starting API-only workflows.

Verify the API is reachable

Check the unauthenticated health endpoint first:

curl -X GET "http://127.0.0.1:8020/api/v1/health"

Expected response:

{
  "ping": "ok"
}

If your deployment is not listening on 127.0.0.1:8020, keep the same API path and replace the host and port with your own base URL.

Authentication headers

Most endpoints in the current contract require both of these headers:

• X-API-Key
• X-Install-ID

You can obtain both values on the Account page.

Use this request pattern for authenticated REST calls unless the endpoint description says otherwise:

curl -X GET "http://127.0.0.1:8020/api/v1/user" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Install-ID: YOUR_INSTALL_ID"

Current exceptions in the embedded contract:

• /health
• /ready
• /system/defaults

Special case for WebSocket LSP endpoints:

• /lsp/ws and /lsp/duckdb/ws also accept api_key and install_id query parameters when the client cannot send custom headers during the WebSocket handshake

Choose the right guide

Use the Swagger UI on this page for exact schemas. Use the pages below when you need workflow steps or copy-paste examples.

Use the Swagger contract effectively

1. Confirm the base URL shown in Swagger matches your deployment.
2. Open Authorize and enter the authentication values from Authentication headers if you need authenticated routes.
3. Open the tag that matches your task:
   • User Management for user state and optional config warm-up
   • Connections Management for database, files, metadata, and query endpoints
   • Stream Configuration and Stream Operations for stream lifecycle work
   • Files for file reads, row edits, summaries, counts, and S3 helpers
   • Health for readiness and runtime checks
4. Expand the operation you need and inspect:
   • required path and query parameters
   • request body schema
   • response examples and status codes
5. Use Try it out only after you confirm the selected server and headers are correct.

Verification checks

Use these checks before relying on a route in automation:

curl -X GET "http://127.0.0.1:8020/api/v1/ready"

• 200 means the API is ready to serve requests
• 503 means the API is not ready

Optional config warm-up for diagnostics or post-restart validation uses the same authenticated request pattern:

curl -X GET "http://127.0.0.1:8020/api/v1/user/configs" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Install-ID: YOUR_INSTALL_ID"

/user/configs is available for manual warm-up or forced refresh, but the current backend also auto-initializes user configs on the first authenticated request.

Troubleshooting

401 Unauthorized

• Confirm the authentication headers from Authentication headers are present on the request
• Re-check the Swagger server selector before using Try it out

Swagger points to the wrong host or port

• The embedded contract includes local server entries
• If your deployment uses a different host, keep the same route path and substitute your own base URL when issuing requests outside Swagger

Missing user configs after restart or cache clear

• Call /user/configs once to force a refresh
• Retry the original authenticated request after the warm-up returns 200

Full contract

The embedded Swagger UI below is the canonical checked-in endpoint contract used by this docs site. Use it for exact request and response shapes.