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, published requirement and scope identities, and the current Mission or contract IDs. Automation must preserve returned snapshot, row, source, Twin, version, binding, installation, and result identifiers; names alone are not stable integration inputs.
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. |
GET | /api/v1/scout/contracts | scout.read | List IDBC contracts. |
GET | /api/v1/scout/contracts/{contractId} | scout.read | Read versions and audit. |
POST | /api/v1/scout/contracts/{contractId}/versions/{version}/shadow | scout.write | Move DRAFT to SHADOW. |
POST | /api/v1/scout/contracts/{contractId}/versions/{version}/approve | scout.approve | Move SHADOW to APPROVED. |
POST | /api/v1/scout/contracts/{contractId}/versions/{version}/deploy | scout.deploy | Move APPROVED to DEPLOYED. |
GET | /api/v1/scout/missions/{missionId}/runtime-evidence | scout.read | Reconcile deployed runtime evidence. |
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
-> create candidate
-> decide candidate
-> read contract
-> Shadow
-> approve
-> deploy
-> read Runtime Evidence
Reconcile the same Mission, snapshot, row, candidate, contract/version, source, Twin, binding, installation, consumption-evidence, and result IDs. 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 and contract transitions also carry expectedVersion. A conflict means the record changed; reload and review 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, frozen coverage, binding decision, IDBC lifecycle, and cross-stage 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.