# 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 and comments, including per-instrument subscriptions, the workspace Slack channel, and Slack app setup for personal DMs.

- **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 manual uploads from the admin dashboard.
- [Roll out watcher releases](/docs/watcher-releases): Publish watcher versions to PyPI, advertise them per environment, force mandatory updates, and roll the fleet back.
- [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 instrument health, and understand instrument states.
- [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.
- [Manage members](/docs/manage-members): Promote and demote workspace admins from Settings → Members.

- **API**
- [Overview](/docs/api): Authenticate to the Data Hub REST API, make a first request, and understand pagination, filtering, 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`.
  - [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`.
  - [Get a run](/docs/api/runs/getInstrumentRun): Requires scope `runs:read`.
  - [Update a run](/docs/api/runs/updateInstrumentRun): Requires scope `runs:update`.
  - [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`, or `completed` file on the run. 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, or spectra, 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`.
  - [Remove your run claim](/docs/api/runs/unclaimRun): Requires scope `runs:attribute`.
  - [Claim a run](/docs/api/runs/claimRun): Requires scope `runs:attribute`.
  - [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`.
  - [Update a file](/docs/api/files/updateFile): Requires scope `files:update`.
  - [Dismiss a file](/docs/api/files/dismissFile): Requires scope `files:delete`.
  - [Redirect to file download](/docs/api/files/downloadFile): Requires scope `files:read`.
  - [Reprocess a file](/docs/api/files/reprocessFile): Requires scope `files:reprocess`. Eligible statuses: `uploaded`, `failed`, or `completed` (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`.
  - [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`.
  - [Get watcher configuration checksum](/docs/api/watchers/getWatcherConfigChecksum): Requires scope `watchers:read`.
  - [List watcher events](/docs/api/watchers/listWatcherEvents): Requires scope `watchers:read`.
  - [Report a watcher event](/docs/api/watchers/createWatcherEvent): Requires scope `watchers:report`.
  - [Record a watcher heartbeat](/docs/api/watchers/recordWatcherHeartbeat): Requires scope `watchers:report`.
  - [List watcher heartbeats](/docs/api/watchers/listWatcherHeartbeats): Requires scope `watchers:read`.
  - [Get watcher upload queue](/docs/api/watchers/getWatcherUploadQueue): Requires scope `watchers:read`.
  - [Check watcher update availability](/docs/api/watchers/checkWatcherUpdate): Requires scope `watchers:read`.
- Archive: Run archive builds
  - [Update an archive job](/docs/api/archive/updateArchiveJob): Requires scope `archive-jobs:write`.

- **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, 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.