Managed source API

Pilot API; not a stable SDK. Read the user workflow for availability and limitations.

POST /api/v1/projects/{project}/sources/{operation} uses an existing project-scoped bearer delegate. The JSON object includes matching project_id. Control mutations require write scope and project administration; result publication requires project publish access; reads require project access and the account’s upstream permission. Browser requests instead use /api/sources/ with session, exact Origin and CSRF proof. Desktop connectors use their independent OIDC bearer at /api/v1/connector/sources/.

Operation	Additional fields
connections, list	None
discover	connection_id, approved OSDU kind, optional offset
preview	connection_id, key, profile, optional revision
bind	Preview fields, preview_digest, acknowledge_unknowns, mode
refresh, export, head, map-describe	Selection id
map-snapshot	Selection id, optional exact revision; GeoTIFF only
pause, resume, remove	id, expected_generation
review	id, expected_generation, fresh preview_digest, consent, mode, optional revision

mode is follow or pin. Consent must be true. Extra properties are rejected. The preview digest binds the reviewed exact reference, bytes and meaning; a changed source requires a new preview. Control mutations use a generation to reject stale updates. Duplicate binding creation returns the existing selection without remapping it.

The export contains manifest and payload_base64. The manifest records source namespace/key, exact string revision, mapping profile, declared metadata, media type, byte length and SHA-256. No credentials or host paths appear in the export. OSDU metadata revision identifiers are also strings to avoid browser numeric rounding.

The journal stores control state and observations; bulk authority remains upstream. Inventory is a saved observation, not evidence of current upstream authorization. Fresh preview/export obtains source data with current credentials. An upstream notification only schedules reconciliation and cannot supply a ready revision.

Bounds: 32 configured connections, 100 selections/project, 16 MiB source response, 64 KiB metadata; Parquet limits are 100,000 rows, 128 columns and 64 MiB uncompressed row groups. These are pilot bounds, not throughput or latency guarantees.

Deployment configuration uses OPHIOLITE_SOURCES_CONFIG. IT provisions account credential-file references; OSDU token renewal is external to this pilot. Optional OPHIOLITE_SOURCE_WORKER_TOKEN_FILE enables serial reconciliation for that account. A public notification receiver and multi-account scheduler are not installed.

Experimental CLI: ophiolite-sources --url https://workspace.example --token-file /private/delegate --project study connections. Add --request request.json for operation fields and --output bundle.json for exports. Output files are created exclusively with owner-only permissions. Do not put bearer tokens in request JSON.

Interpretation and derived publication

Raster bind and review accept optional context and context_policy_revision. preview.context_policy supplies versioned unit and vertical-reference choices. Quantity and direction also use finite catalogs. The interpretation is user-declared, separate from unchanged source metadata, and included in exact exports.

result-preview and result accept the native GeoTIFF import fields (project_id, command_id, name, unit, geotiff, optional context and policy_revision) plus parent: {project_id, asset_id: selection_id, revision: source_sha256} and optional unchanged. Source and destination must belong to the same project in this pilot. replace_source must be false and processing null: native-reference telemetry cannot be substituted for external-source evidence. Upstream permission and exact source bytes are rechecked before committing. Retries reuse the command ID; changed input with that ID is refused. Derived publication preserves original result bytes, scientific values/nulls, declared context and upstream lineage. No upstream writes are issued. The same operations are available through the source CLI.