> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Discovery run

> The discovery-run resource: evidence-gated workflow discovery, its process cards, and the propose step that feeds operating processes.

A discovery run scans connected sources (and, in deep-search mode, cited
external research) for how work actually flows through a workspace. It
returns observations and **process cards** — observed workflow candidates
with confidence scores and confirmation questions. A card never becomes an
operating process silently: you explicitly propose it, and a person still
confirms it afterwards.

## Wire shape

The run object (camelCase on the wire):

| Field                       | Type                                     | Meaning                                                                                                                                                                      |
| --------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schemaVersion`             | string                                   | Contract version.                                                                                                                                                            |
| `id`                        | UUID                                     | Discovery run ID.                                                                                                                                                            |
| `workspaceId`               | UUID                                     | Tenant scope.                                                                                                                                                                |
| `mode`                      | `bounded_sync` `deep_search` `reconcile` | Evidence depth. Default `bounded_sync`.                                                                                                                                      |
| `status`                    | enum                                     | `queued`, `running`, `succeeded`, `partial`, `failed`, `cancelled`. The synchronous writer returns `succeeded` (or fails the request); the intermediate states are reserved. |
| `initiatedBy`               | actor ref                                | Who started it.                                                                                                                                                              |
| `query`                     | string, nullable                         | The discovery question.                                                                                                                                                      |
| `sourceKinds`               | string\[]                                | Requested source kinds (`github`, `notion`, ...).                                                                                                                            |
| `sourceCursors`             | object                                   | Per-source sync cursors.                                                                                                                                                     |
| `observationCount`          | number                                   | Observations captured.                                                                                                                                                       |
| `candidateProcessCardCount` | number                                   | Process cards returned.                                                                                                                                                      |
| `citationCount`             | number                                   | Citations (deep search).                                                                                                                                                     |
| `costMicros`                | string                                   | Provider cost, micro-units as a decimal string.                                                                                                                              |
| `confidence`                | number 0–1, nullable                     | Overall confidence.                                                                                                                                                          |
| `startedAt`, `completedAt`  | ISO datetime (nullable end)              | Timing.                                                                                                                                                                      |
| `sourceHealth`              | array                                    | Per-source status: `connected`, `syncing`, `stale`, `degraded`, `disconnected`, `permission_required`.                                                                       |
| `limitations`               | string\[]                                | What the run could not see.                                                                                                                                                  |

The full result envelope is `{ "run", "observations", "processCards", "confirmedProcessRefs" }`.
Each process card carries `processCandidateRef.id` (the ID you propose),
`displayName`, `confidence`, `nextConfirmationQuestion`, `riskFlags`, cycle
time estimates, and `automationReadiness`.

## Operations

All routes accept `Authorization: Bearer oxk_...` or a web-app session;
mutations require an `Idempotency-Key` header.

| Operation       | Method + path                                 | Body / params                                                                                        |
| --------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Start           | `POST /api/v1/discovery-runs`                 | `workspace_id`\*, `mode` (default `bounded_sync`), `query` (≤2000, nullable), `source_kinds` (≤20)   |
| List            | `GET /api/v1/discovery-runs`                  | `workspace_id`, `limit` (default 20, max 50)                                                         |
| Get             | `GET /api/v1/discovery-runs/{runId}`          | `workspace_id`                                                                                       |
| Propose         | `POST /api/v1/discovery-runs/{runId}/propose` | `workspace_id`*, `process_candidate_id`* — materializes one card as a confirmation-required proposal |
| Update / delete | Not exposed                                   | Runs are immutable records of what was observed.                                                     |

```bash theme={"dark"}
# Start a bounded discovery run
curl https://useorgx.com/api/v1/discovery-runs \
  -X POST \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: map-intake-2026-08' \
  -d '{
    "workspace_id": "3d7e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a",
    "mode": "bounded_sync",
    "query": "Map customer intake, handoffs, and completion criteria",
    "source_kinds": ["github"]
  }'

# Propose the selected card as an operating process
curl https://useorgx.com/api/v1/discovery-runs/7d6c5b4a-.../propose \
  -X POST \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: map-intake-2026-08-propose-1' \
  -d '{
    "workspace_id": "3d7e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a",
    "process_candidate_id": "8e7d6c5b-4a3b-2c1d-0e9f-8a7b6c5d4e3f"
  }'
```

Start returns `201` with the full result (`200` with `meta.duplicate: true`
when the idempotency key replays); a second concurrent start with the same
key returns `409 discovery_run_in_progress`. Propose returns `201` with
`meta.requiresConfirmation: true` — the resulting operating process is
`proposed` and still needs [confirm and activate](/docs/api/entities/operating-process).

## Where the IDs come from

| Field                  | Obtain it from                                                                         |
| ---------------------- | -------------------------------------------------------------------------------------- |
| `runId`                | `POST /api/v1/discovery-runs` response `data.run.id`, or the list operation            |
| `process_candidate_id` | The start/get response: `data.processCards[].processCandidateRef.id`                   |
| `workspace_id`         | `GET /api/v1/me` → `data.default_workspace_id` or `data.workspaces[].id`               |
| proposed process `id`  | The propose response's ledger data — then visible in `GET /api/v1/operating-processes` |

## CLI and MCP equivalents

The wizard's [`map` command](/docs/guides/wizard-cli-onboarding#map) drives this
exact flow from the terminal (`--deep-search` selects `deep_search` mode;
`--candidate` runs the propose step). No MCP tool operates on discovery runs
today — this resource is REST-first.