# Documentation - **Get started** - [Overview](/docs/overview): What Data Hub does, what it doesn't do, where your data shows up, and which page to read next. - [Deploy Data Hub](/docs/self-hosting): What deploying Data Hub involves, what you need before you start, and where the step-by-step runbooks live. - [Set up an instrument](/docs/set-up-an-instrument): Go from a fresh instrument PC to an active instrument uploading runs into Data Hub. - **Work with your data** - [Browse and analyze runs](/docs/browse-runs): Use the web app to find runs, inspect processed results, claim attribution, download files, comment, and manage run lifecycle. - [Instrument data preprocessing](/docs/instrument-preprocessing): What Data Hub does to a raw file after upload, which instrument types have a processor, and what supporting a new instrument takes. - [Configure notifications](/docs/configure-notifications): Choose in-app and Slack notifications for new runs, comments, service messages, and feedback, including per-instrument subscriptions and personal Slack direct messages. - [Send feedback and see what’s new](/docs/send-feedback): Report a bug or request a feature about Data Hub from the app or an AI assistant, follow the report’s status, and read the in-app changelog. - **Watcher** - [Install and update the watcher](/docs/install-the-watcher): Install, reinstall, verify, and manually update the Data Hub watcher on an instrument PC across operating systems. - [Run as a Windows service](/docs/windows-service): Install and operate the Data Hub watcher as a Windows service so it starts on boot, survives logouts, and can auto-update in the background. - [Configure run detection and uploads](/docs/configure-run-detection): Choose how the watcher groups files into runs, when files are ready to upload, and whether uploads are automatic or approved. - [Manage the watcher fleet](/docs/manage-watchers): Monitor watcher health, deregister watchers, and approve or request uploads from the admin dashboard. - [Roll out watcher releases](/docs/watcher-releases): Publish watcher versions to PyPI, advertise them per environment, set a minimum version, force mandatory updates, roll the fleet back, and see what each version adds. - [Troubleshoot a watcher](/docs/troubleshoot-a-watcher): Fix watcher problems by symptom: will not start, files not detected, uploads stuck, auto-update quiet, and where to find logs. - **Administration** - [Administration overview](/docs/administration): Admin entry point for instruments, watchers, tokens, members, and fleet releases. - [Manage instruments](/docs/manage-instruments): Confirm pending instruments, read an instrument’s watcher status, watched folder, and file patterns, and edit its name and type. - [Retire an instrument](/docs/retire-an-instrument): Retire an instrument so it stops accepting uploads and watchers, while keeping historical runs and files. - [Issue and revoke tokens](/docs/manage-tokens): Create, use, and revoke personal access tokens that authenticate the watcher and other Data Hub API clients, and see what a token can and can’t do. - [Manage members](/docs/manage-members): Promote and demote workspace admins from Settings → Members. - [Set up integrations](/docs/integrations): Connect Data Hub to Linear for feedback reports, and to Slack for personal direct messages and a shared new-run channel, from Settings → Integrations. - **API** - [Overview](/docs/api): Authenticate to the Data Hub REST API, make a first request, and understand pagination, filtering, token attribution, and errors. - Meta: Schema discovery - [Get the OpenAPI document](/docs/api/meta/getOpenApiDocument) - Instruments: Instrument catalog - [List instruments](/docs/api/instruments/listInstruments): Requires scope `instruments:read`. - [Create an instrument](/docs/api/instruments/createInstrument): Requires scope `instruments:write`. PAT only; browser sessions are rejected. - [Get an instrument](/docs/api/instruments/getInstrument): Requires scope `instruments:read`. - [Update an instrument](/docs/api/instruments/updateInstrument): Requires scope `instruments:write`. - Runs: Instrument runs, comments, attributions, uploads, and search - [List runs across instruments](/docs/api/runs/listInstrumentRuns): Requires scope `runs:read`. - [List an instrument's runs](/docs/api/runs/listInstrumentRunsForInstrument): Requires scope `runs:read`. - [Create an instrument run](/docs/api/runs/createInstrumentRun): Requires scope `runs:create`. PAT only; browser sessions are rejected. - [Get a run](/docs/api/runs/getInstrumentRun): Requires scope `runs:read`. - [Update a run](/docs/api/runs/updateInstrumentRun): Requires scope `runs:update`. PAT only; browser sessions are rejected. - [Soft-delete a run](/docs/api/runs/deleteInstrumentRun): Requires scope `runs:delete`. - [Restore a run](/docs/api/runs/restoreInstrumentRun): Requires scope `runs:delete`. - [Reprocess a run](/docs/api/runs/reprocessInstrumentRun): Requires scope `runs:reprocess`. Reprocesses every `uploaded`, `failed`, `completed`, or stalled `processing` raw file on the run. Processed artifacts are skipped. The instrument must have a Lambda processor. - [List a run's report items](/docs/api/runs/listRunReportItems): Requires scope `files:read`. Returns `{id, filename}` for the run's renderable images, PDFs, spectra, or videos, ordered by filename. Paged with `offset`/`limit` so viewers can seek by item index. - [Search Data Hub](/docs/api/runs/search): Requires scope `runs:read`. - [Queue selected files for upload](/docs/api/runs/requestRunUpload): Requires scope `runs:upload`. - [Queue all files for upload](/docs/api/runs/requestRunUploadAll): Requires scope `runs:upload`. - [Request a presigned upload URL](/docs/api/runs/requestRunUploadUrl): Requires scope `runs:upload`. PAT only; browser sessions are rejected. Watchers at 1.1.0 or newer send `relative_path` and `X-Data-Hub-Watcher-Version`. A file whose name is already used by a different folder is stored as `~.`, and the returned `s3_key` uses that stored name. Older watchers are looked up by filename only. Watchers at 1.2.0 or newer receive a multipart upload for files of 100 MB or more. Older watchers are refused when the file is over 5 GB. - [List run comments](/docs/api/runs/listRunComments): Requires scope `runs:read`. - [Create a run comment](/docs/api/runs/createRunComment): Requires scope `runs:comment`. - [Update a run comment](/docs/api/runs/updateRunComment): Requires scope `runs:comment`. - [Delete a run comment](/docs/api/runs/deleteRunComment): Requires scope `runs:comment`. - Files: Run files, downloads, and reprocessing - [Create a run file record](/docs/api/files/createRunFile): Requires scope `files:create`. PAT only; browser sessions are rejected. - [Update a file](/docs/api/files/updateFile): Requires scope `files:update`. PAT only; browser sessions are rejected. - [Dismiss a file](/docs/api/files/dismissFile): Requires scope `files:delete`. - [Redirect to file download](/docs/api/files/downloadFile): Requires scope `files:read`. Pass `disposition=inline` to override a stored `binary/octet-stream` type so browsers can render PDFs in an iframe. - [Sign URLs for multipart upload parts](/docs/api/files/signMultipartPartUrls): Requires scope `runs:upload`. PAT only. Returns a few presigned UploadPart URLs. Fetch the next batch when these expire. - [Finish a multipart upload](/docs/api/files/completeMultipartUpload): Requires scope `runs:upload`. PAT only. Sends the part list and the whole-file CRC64NVME checksum to S3, then marks the file uploaded. - [Cancel a multipart upload](/docs/api/files/abortMultipartUpload): Requires scope `runs:upload`. PAT only. Cancels the in-progress S3 upload and clears it from the file. - [Reprocess a file](/docs/api/files/reprocessFile): Requires scope `files:reprocess`. Raw files only. Eligible statuses: `uploaded`, `failed`, `completed`, or stalled `processing` (file must have an S3 location). The file's instrument must have a Lambda processor. - [Download a run archive](/docs/api/files/downloadRunArchive): Requires scope `files:read`. - Watchers: Watcher registration and telemetry - [List watchers](/docs/api/watchers/listWatchers): Requires scope `watchers:read`. - [Register a watcher](/docs/api/watchers/registerWatcher): Requires scope `watchers:report`. PAT only; browser sessions are rejected. - [Get a watcher](/docs/api/watchers/getWatcher): Requires scope `watchers:read`. - [Deregister a watcher](/docs/api/watchers/deleteWatcher): Requires scope `watchers:admin`. - [Update watcher configuration](/docs/api/watchers/updateWatcherConfig): Requires scope `watchers:report`. PAT only; browser sessions are rejected. - [Get watcher configuration checksum](/docs/api/watchers/getWatcherConfigChecksum): Requires scope `watchers:read`. PAT only; browser sessions are rejected. - [List watcher events](/docs/api/watchers/listWatcherEvents): Requires scope `watchers:read`. - [Report a watcher event](/docs/api/watchers/createWatcherEvent): Requires scope `watchers:report`. PAT only; browser sessions are rejected. - [Record a watcher heartbeat](/docs/api/watchers/recordWatcherHeartbeat): Requires scope `watchers:report`. PAT only; browser sessions are rejected. - [List watcher heartbeats](/docs/api/watchers/listWatcherHeartbeats): Requires scope `watchers:read`. - [Get watcher upload queue](/docs/api/watchers/getWatcherUploadQueue): Requires scope `watchers:read`. PAT only; browser sessions are rejected. - [Check watcher update availability](/docs/api/watchers/checkWatcherUpdate): Requires scope `watchers:read`. PAT only; browser sessions are rejected. - Archive: Run archive builds - [Update an archive job](/docs/api/archive/updateArchiveJob): Requires scope `archive-jobs:write`. PAT only; browser sessions are rejected. - Notifications: User notifications - [Send a notification to users](/docs/api/notifications/dispatchNotifications): Requires scope `notifications:create`. PAT only; browser sessions are rejected. Posts a free-text `generic` notification to each recipient, optionally anchored to a run. Delivery is per-recipient preference: in-app bell and/or Slack DM. Exact repeats of an unread message are skipped, so retries are safe. - **MCP** - [Overview](/docs/mcp): Connect an AI client to Data Hub over the Model Context Protocol, including OAuth sign-in, the read and write scopes, and per-client setup. - [Tools](/docs/mcp/tools): Catalog of Data Hub MCP tools for instruments, runs, files, watchers, and discovery. - [Prompts](/docs/mcp/prompts): Catalog of Data Hub MCP prompts: scripted workflows for summaries, troubleshooting, and attribution. - [Resources](/docs/mcp/resources): Catalog of Data Hub MCP resources clients can attach as reference context. - **Reference** - [Concepts](/docs/concepts): Short definitions of the Data Hub vocabulary: instruments, watchers, runs, statuses, processing, and access. - [Architecture](/docs/architecture): How Data Hub fits together: the watcher, S3 storage, the Lambda processor, the API and web app, and the data flow from instrument to dashboard. - [Watcher configuration](/docs/configuration-reference): Every config.yaml field, the ~/.data-hub file layout, environment variables, run-detection presets, upload modes, and the initial-scan behavior. - [Watcher CLI](/docs/cli-reference): Every data-hub-watcher command, subcommand, and flag in one place: init, watch, upload, config, service, state, and self-update. - [Security and permissions](/docs/security): Roles and what each can do, personal-access-token scopes, how authentication works, and good token hygiene.