Observations and corrections

Integration routes are project-scoped and use ontology access. They exchange evidence/correction state; they are not plugin installation or arbitrary webhook registration routes.

GET /projects/{projectId}/integrations/status requires ontologies:read and returns connection/status information without caching. POST observations requires ontologies:write and an accountable organization member. The observation body must match the ingestion contract and the project's definitions; successful HTTP ingestion does not prove a downstream correction was applied.

GET corrections requires ontologies:read and accepts a correction UUID cursor. POST /corrections/{correctionId}/ack requires ontologies:write and a valid acknowledgment body. Preserve the correction ID and report the actual applied outcome; do not acknowledge merely because you downloaded it.

curl --fail-with-body -H "Authorization: Bearer $SEMOGRAM_API_KEY" \
  "https://platform.semogram.com/api/v1/projects/$SEMOGRAM_PROJECT_ID/integrations/status"

Set a workspace secret and the actual project UUID before running this read. Inspect connected status before submitting observations. A disconnected integration needs configuration in the appropriate platform workflow; repeated ingestion cannot repair missing setup.

Use the exact observation/correction schemas for your integration. Endpoint writes and action approvals are separate resource families, so posting an observation does not automatically authorize a source mutation.

Observation contract

The body includes contractVersion 1, operationKey, clientNamespace, provider {namespace,id,revision}, kind (entity or signal), ontologyPackageId, typeRef, observedAt, validFrom/validTo (nullable), names, attributes, evidence and nullable localStateRef. Evidence requires locator and capturedAt, with nullable selector, mediaType and sha256. Provide at least one name and evidence item. Validity is a nonempty half-open interval when both endpoints are supplied.

operationKey deduplicates within the project: replaying the same parsed observation returns its reference, while reusing the key with different input returns a conflict. This is body-level deduplication, independent of the shared Idempotency-Key header.

Acknowledgment uses contractVersion 1, operationKey, provider, status (committed, not_committed, conflict, unknown), nullable committedAt, currentProviderRevision and detail. Only a committed receipt has a commit time. Preserve provider-local revision evidence instead of claiming a successful correction on an uncertain result.