Overview

The Data Hub API is served by the web application at /api/v1/. The watcher, Lambda, MCP clients, 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, Lambda, and MCP clients

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

Token requests are gated on scopes. Missing scope → 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 (typically 1–100)

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

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 /api/v1/mcp expose the MCP server over Streamable HTTP. MCP clients use Bearer tokens only. Tools enforce the same scopes as their REST counterparts. See MCP overview.