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, check	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, hold	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. A browser session that omits mode binds pin, and its review without mode keeps the stored mode. Since 2026.10.42 a browser session cannot ask for follow: bind with follow, or review that would turn a held selection into follow, is refused with 403 and Versions are not applied for you automatically. Choose Get when you want a newer one. before anything is read or stored (reviewing one that already follows may keep it so). An access key or delegate that omits mode still binds follow, and its review without mode still sets follow: code that relied on following keeps doing so. Send mode explicitly in new code.

check (read scope) looks for updates to the caller’s own pinned selections in the project and only records them: a found update sets update_available and nothing moves. It skips followed selections, selections in failure backoff and selections checked in the last few seconds, takes the oldest-checked first, and stops after 16 selections or 8 seconds. The answer is checked, skipped (following, backoff, recent), remaining (call again to continue), the caller’s selections and checked_at. Another person’s selections are never read with the caller’s credentials.

hold (write scope, administration) turns a followed selection into a pin at the revision it holds now, without reading upstream, so it works when the connection has changed or gone. Holding a pin returns it unchanged; a stale expected_generation on a followed selection is refused with 409. 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.

SQL mapping pilot

schema accepts connection_id/key and returns detected columns, sample_rows, row_count, schema_digest, suggested_fields, current mapping and immutable versions. mapping-validate accepts the mapping and an optional scope (all or sample): with a scope a problem is not a refusal and the answer adds report (ophiolite.mapping-check/1: rows checked, ready, with problems and with warnings, and up to 50 groups of field, code, row count and up to five examples); only a complete check with no invalid or not-supported group is ready. mapping-save also requires expected_generation (0 for first save), project administration and write delegate scope. It re-reads the table, checks the digest, validates rows and records source.mapping-saved; with scope all it answers the report and saved, and writes only a ready mapping. Mapping fields: entity=well, fields {id,name,x,y,depth,operator}, crs, depth_unit, depth_kind, depth_reference, missing, extras, schema_digest; saved version assigned by server. Version storage is scoped by connection/upstream account/table, not shared credentials.

The sql-wells/1 export is JSON containing schema=ophiolite.sql-wells/1, source_schema, original source_rows, normalized wells and mapping. The standard source-snapshot manifest records namespace/key/revision, byte length and SHA256. The outer transport uses base64; unpacking produces independently readable JSON. The original database file is not exported. No SQL text or arbitrary table identifier is accepted from a browser.

An administrator provisions type: sqlite, absolute path, explicit principals: {account: true} and tables: {logical_key: {table: actual_table, name: display_name}}; for type: postgresql, principal values are paths to private 0600 DSN files and table entries also contain schema. Use a database account limited to the approved tables and SELECT. Configuration changes require gateway restart. This is not a customer credential-management UI or a released SDK.

Reviewed source edits

Experimental source routes additionally expose records and mapping-report. Records are bounded and retain an exact source reference. Mapping reports distinguish qualified OSDU reader associations from customer-reviewed SQL mappings.

All draft-* routes require project administration, the creating account, and browser CSRF or an automation write scope. draft-create takes selection_id. draft-save takes id, expected_generation and up to 1,000 absolute patches: {row_id, field, value}. Null means missing. draft-offset takes field/delta. draft-preview returns old/new changes, loss/readback report, output hash, destinations and review_digest. draft-publish requires that digest and generation. draft-list, draft-get and draft-discard manage account-scoped records. No source credentials or arbitrary SQL are accepted in these requests.

Portable publication returns payload_base64 and a ophiolite.edit-result/1 manifest with exact parent, changes, media type, SHA-256 and writer report. The UI packages these into a ZIP. Original SQL snapshot exports retain unmapped columns; edited well JSON is a normalized result, not a reversible database dump. LAS writing verifies numeric samples/nulls, curve names and units by readback; formatting is not preserved after edits. Unchanged output returns original bytes. Result payloads are capped at 32 MiB and retained privately for hash-checked repeat download.

SQL source publication requires separate write_principals and a table’s write_columns allowlist. SQLite grants use true; PostgreSQL uses private DSN files. Read/write DSNs must explicitly target the same host/port/database. A qualified base table must have the mapped ID as its sole primary key. Updates lock the table, recheck the exact source revision, parameterize values, verify edited cells and commit. No views, joins, inserts, deletes, schema changes or arbitrary-precision numeric editor. Unmapped columns are not assigned; database triggers require deployment qualification.

Draft generations prevent stale-tab saves. Source changes require a new draft. Publication intent is durable before SQL writes. Completed receipts are idempotent; an interrupted or uncertain publication is blocked from retry and requires source inspection. Gateway and SQL commits are not one distributed transaction. Receipt and activity are atomic locally. The activity coverage is source-edit/1, recording publication evidence, not invented internal execution spans for upstream software.

The current cap is 100 saved draft/result records per account/project, including discarded drafts. Archival/retention administration and production scaling are later gates. This is a pilot API, not a released SDK.

Source manifests add a descriptive connector semantics report covering mapping, fidelity and historical-read limits. Existing access checks still apply.