---
title: "Start Scan"
method: POST
path: "/chat/workspace-scans"
tags: ["workspace scans"]
---

# Start Scan

`POST /chat/workspace-scans`

## Request body

- StartWorkspaceScanRequest
  - `integration_id` string, uuid, required

## Response `200`

Successful Response

- WorkspaceScanResponse
  - `scan` APIApiSchemaChatWorkspaceScansChatWorkspaceScan, required
    - `id` string, uuid, required
    - `organization_id` string, uuid, required
    - `integration_id` string, uuid, required
    - `started_by_user_id` string, uuid, required
    - `status` 'pending' | 'running' | 'partial' | 'completed' | 'failed', required
    - `stage` 'resolving_integration' | 'preparing_inventory' | 'selecting_candidates' | 'analyzing' | 'finalizing' | 'ready', required
    - `deadline_at` string, date-time, required
    - `inventory_refreshed_at` string, date-time, nullable, required
    - `progress` WorkspaceScanProgress, required
      - `schema_version` integer, required
      - `channels_discovered` integer, required
      - `channels_eligible` integer, required
      - `channels_enriched` integer, required
    - `error_code` string, nullable, required
    - `error_message` string, nullable, required
    - `revision` integer, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `completed_at` string, date-time, nullable, required
  - `channel_recommendations` ChannelRecommendation[], required
    - `channel_id` string, uuid, required
    - `decision` 'recommend' | 'consider', required
    - `reason` string, required
    - `evidence` string[], required
    - `activity_coverage` 'complete' | 'sampled' | 'stored_only' | 'unavailable' | 'inaccessible' | 'unsupported' | 'rate_limited' | 'failed', required
    - `position` integer, required
  - `pattern_recommendations` PatternRecommendation[], required
    - `conditions` ChannelNameCondition[], required
      - `field` 'channel_name', required
      - `operator` 'contains' | 'starts_with' | 'ends_with' | 'equals' | 'not_equals' | 'does_not_contain', required
      - `value` string, required
    - `decision` 'recommend' | 'consider', required
    - `reason` string, required
    - `evidence` string[], required
    - `mode` 'incident' | 'alerts' | 'custom', required — The kind of channel the agent lives in — its standing mission. Drives the swappable mode block in the system prompt (and, later, the toolset). ``escalation`` and others land as localized drop-ins (their standing block + tooling) when that work begins. ``incident`` and ``alerts`` each state a mission the worker owns whatever the operator writes. ``custom`` states none: it supplies only the conduct floor the identity block forward-references, and the operator's ``custom_instruction`` is what gives the worker something to do. A channel that is neither working an incident nor triaging alert fires gets this one rather than being told it is in an incident (PRD-3766). The value is what customer-facing surfaces render, so it reads as the operator's own word for it rather than as an internal category. A member's *name* is persisted, in ``resident_agent_workflow.mode`` and ``resident_agent_template.mode`` — plain varchars with no DB-side value set — and read back through this enum, so adding a member is one deploy but removing or renaming one orphans every row holding it. It also makes a member forward-only: code that predates it raises on a row that carries it, rather than degrading. So a new member wants its read deployed everywhere before anything can write it — either landing the member ahead of the paths that create it, or gating creation while it rolls out.
    - `custom_instruction` string, nullable, required
    - `example_channel_names` string[], required
    - `matching_channel_count` integer, required
    - `position` integer, required
  - `warnings` ScanWarning[], required
    - `code` 'stale_inventory' | 'partial_inventory' | 'missing_authorization' | 'rate_limited', required
    - `message` string, required

## Other responses

- `422` — Validation Error

## Changes

> 28 revisions in range; 7 not diffed.

- **2026-09-02** `3025330cc50d` — 1 warning
  - added the new `custom` enum value to the `pattern_recommendations/items/mode` response property for the response status `200`
- **2026-08-28** `6bbc7dd4088c` — 3 breaking, 1 warning, 5 info
  - the `schema_version` response property const value `1` was removed for the status `200`
  - removed the required property `channel_recommendations/items/concerns` from the response with the `200` status
  - removed the required property `pattern_recommendations/items/prefix` from the response with the `200` status
  - removed the request property `force_refresh`
  - …5 more
- **2026-08-24** `ca8396674832` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/traversal/apis/fastapi/changes/chat/workspace-scans/post.md)

---

[API](https://skmtc.dev/traversal/apis/fastapi.md) · [All operations](https://skmtc.dev/traversal/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/traversal/fastapi/revisions/b68d9bf4b28f/schema)