> ## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.