Discovery run

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.

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

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

Getting Started

Connect Your Tools

Agent Ops

Platform

Build with the API

REST API v1 Reference

Entity Reference

Content Studio API

MCP and Plugins

Resources

Wire shape

Operations

Where the IDs come from

CLI and MCP equivalents

​Wire shape

​Operations

​Where the IDs come from

​CLI and MCP equivalents

Wire shape

Operations

Where the IDs come from

CLI and MCP equivalents