Overview

The Data Hub API is served by the web application at /api/v1/. The watcher, Lambda, and dashboard all call it. Data Hub is self-hosted, so the base URL is your deployment host plus /api/v1. Examples use https://datahub.example.com; substitute your host.

Per-endpoint request and response shapes live in the generated pages under this section (same sidebar). Each deployment also publishes OpenAPI 3.1 at /api/v1/openapi.json.

Authentication

Two methods (full model in Security and permissions):

• Session cookies: web dashboard (Google OAuth). Session callers implicitly hold every scope.
• Bearer tokens: Authorization: Bearer dhub_… for the watcher, the Lambda, and scripts

curl https://datahub.example.com/api/v1/instruments \
  -H "Authorization: Bearer dhub_your_token_here"

Every token request needs a scope. A missing scope returns 403 FORBIDDEN. Some mutations also require the admin role; see Admin-gated operations.

Mint tokens in the UI: Issue and revoke tokens.

First request

List instruments:

curl https://datahub.example.com/api/v1/instruments \
  -H "Authorization: Bearer dhub_your_token_here"

Fetch the OpenAPI document (no auth required):

curl https://datahub.example.com/api/v1/openapi.json

The document covers the integrator surface (instruments, runs, files, watchers, archive jobs, search). Session-only admin routes (/tokens, /users, /notifications, /settings/*) and the MCP transport are documented elsewhere.

Pagination and filtering

List endpoints that return pages (notably run search) accept:

• page: 1-based page index
• per_page: page size, 1 to 100

Responses include pagination metadata such as page, per_page, total, and total_pages.

Run report items page by index instead, with offset and limit (max 200). Their responses return offset, limit, and total.

Run search also supports filters (instrument, date range, attribution via ranBy, and instrument-specific metadata). Exact query parameters are on each generated operation page in the sidebar under this API section.

Error responses

Errors use a nested envelope:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Instrument not found.",
    "details": null
  }
}

Common codes: VALIDATION_ERROR (400), UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), CONFLICT (409). Scope failures use code: "FORBIDDEN" with a message naming the missing scope.

MCP

GET and POST /mcp/v1 expose the MCP server over Streamable HTTP, outside the /api/v1 tree. Clients authenticate with OAuth rather than a personal access token, and hold read to connect plus write to call any tool that changes data. See MCP overview.