Scout API and Integration Reference

Use the product UI for human decisions and the REST API for controlled automation. The OpenAPI document for the deployed environment defines the exact fields and request formats; this page is intended for customer integration teams that already understand the operating workflow.

Authentication and Scope

• Use the platform authentication flow and an account in the intended tenant.
• Never accept a tenant ID from an untrusted caller as an authorization decision.
• Scout endpoints require the matching scout.* permission.
• Direct Harness API reads require platform.harness.read.
• Keep service-account credentials in the platform secret system; do not embed them in scripts or evidence artifacts.

Examples below assume:

export BASE_URL='https://your-factverse-host'
export ACCESS_TOKEN='<short-lived token>'

Prerequisites and Inputs

Obtain an account in the intended tenant, the minimum permission for each operation, and the current Mission ID. The product UI resolves application, asset, source, schema, and binding identities; customer automation should not ask a user to enter those internal IDs.

Implemented Scout Endpoints

Method	Endpoint	Permission	Purpose
POST	/api/v1/scout/missions	scout.write	Create a Mission and bind a governed snapshot.
GET	/api/v1/scout/missions	scout.read	Filter and page Missions.
GET	/api/v1/scout/missions/{missionId}	scout.read	Read Mission summary and next action.
POST	/api/v1/scout/missions/{missionId}/snapshot	scout.write	Append a refreshed snapshot binding.
POST	/api/v1/scout/missions/{missionId}/discovery	scout.write	Start discovery when the snapshot is admissible.
GET	/api/v1/scout/missions/{missionId}/coverage	scout.read	Read frozen coverage with filters and pagination.
GET	/api/v1/scout/missions/{missionId}/coverage/{rowKey}	scout.read	Read one frozen coverage row.
GET	/api/v1/scout/missions/{missionId}/workbench	scout.read	List binding candidates.
POST	/api/v1/scout/missions/{missionId}/workbench/candidates	scout.write	Create a candidate against a frozen row.
POST	/api/v1/scout/missions/{missionId}/workbench/candidates/{candidateId}/decision	scout.write	Accept or reject with a reason and expected version.
POST	/api/v1/scout/missions/{missionId}/validation	scout.write	Validate the complete required match set with a bounded read.
POST	/api/v1/scout/missions/{missionId}/validation/approval	scout.approve	Approve the latest passing Mission validation.
GET	/api/v1/scout/missions/{missionId}/application-preview	scout.read	Preview governed DFS create, update, and deactivate changes.
POST	/api/v1/scout/missions/{missionId}/application	scout.deploy	Apply approved Mission bindings through DFS governance.
GET	/api/v1/scout/missions/{missionId}/runtime-evidence	scout.read	Reconcile runtime evidence after bindings are applied.

The /api/v1/scout/contracts/** endpoints remain available for compatibility and technical audit. They are not the customer workflow and should not be used to build a second Scout release console.

Platform Harness Endpoints

Method	Endpoint	Purpose
GET	/api/v1/platform/harness/v1/capabilities	Discover supported snapshot components and limits.
POST	/api/v1/platform/harness/v1/snapshots	Create or resolve an authorized immutable snapshot.
GET	/api/v1/platform/harness/v1/snapshots/{snapshotId}	Read the frozen manifest.
GET	/api/v1/platform/harness/v1/snapshots/{snapshotId}/components/{component}	Page one frozen component.

Scout consumes Harness as a platform capability. Do not create a second Scout-private context assembler.

Canonical Automation Sequence

create Mission
-> read Mission and frozen snapshot
-> read Coverage
-> discover or generate candidates
-> decide candidate
-> validate Mission
-> approve Mission validation
-> preview and apply DFS changes
-> read Runtime Evidence

Completion requires the same Mission to show full required-observation closure, successful bounded validation, applied DFS bindings, readable ClickHouse evidence, and a target consumer result using CANONICAL_TIMESERIES. Route success alone is not completion evidence.

Idempotency and Concurrency

Mutation endpoints that create immutable workflow receipts use an Idempotency-Key UUID. Reuse the same key only when retrying the same logical request.

curl -fsS -X POST "$BASE_URL/api/v1/scout/missions/$MISSION_ID/snapshot" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"

Candidate decisions carry expectedVersion. Mission validation, approval, and application resolve internal versions on the server. A conflict means the evidence changed; reload the Mission before issuing a new command.

Pagination and Frozen Reads

List and coverage endpoints use zero-based API pages and explicit size. Preserve returned total/page metadata. Do not assemble a supposedly frozen view by mixing pages from different snapshot IDs or source versions.

Error Handling

Condition	Integration response
401	Refresh authentication; do not retry indefinitely.
403	Validate entitlement, module, tenant, and permission.
404	Validate tenant-scoped ID and route. Do not enumerate other tenants.
409 or version conflict	Reload current state and re-review.
Stale/rejected snapshot	Stop the mutation sequence and resolve the named evidence issue.
429	Respect the server window and back off.
5xx	Capture trace ID and first broken stage; retry only safe idempotent operations.

Integration Boundaries

• DFS owns connectors, source contracts, source points, Mapping V2, and native point bindings.
• Digital Twin owns Twin and schema/attribute identity.
• ClickHouse routing owns canonical time-series reads.
• Predictive Maintenance owns installation and consumer result semantics.
• Scout owns Mission goals, frozen coverage, candidate evidence, human decisions, bounded validation, DFS orchestration, and cross-stage readiness evidence.

The current release does not provide a public Scout MCP toolset or signed external snapshot export. Use only the endpoints published in the OpenAPI document for your environment.