> ## Documentation Index > Fetch the complete documentation index at: https://docs.enfinitos.com/llms.txt > Use this file to discover all available pages before exploring further. # Observe a delivery > Observe a delivery event against an ACTIVE right. The substrate-specific constraint gate runs before the receipt is emitted; constraint violations come back as `412 PRECONDITION_FAILED`. The signed receipt is appended to the event stream and folded into the next proof pack on `POST /v1/proof-packs/seal`. Requires scope `delivery:write`. ## OpenAPI ````yaml /openapi-v1.yaml post /v1/delivery openapi: 3.1.0 info: title: EnfinitOS API version: v1.0 description: >- The governed-execution `/v1` developer API for EnfinitOS — rights, delivery, proof, and settlement. Use this API to register the legal **bases** a right rests on, **issue** and lifecycle-manage rights across delivery substrates (DOOH, CTV, spatial/AR, mobile, audio, and more), negotiate **offers**, raise and resolve **challenges**, observe constraint-gated **deliveries**, seal signed **proof packs**, read **metering** + **settlement** projections, configure settlement **rules** and **counterparties**, fulfil GDPR **compliance** requests, and subscribe to **webhooks**. Every state-changing action is appended to an immutable, signable audit log; delivery and proof artefacts are Ed25519-signed so a downstream auditor can verify them offline. ## Response envelope Every response wraps its payload in a canonical envelope. Success (HTTP 200): ```json { "ok": true, "data": { ... }, "contractVersion": "v1.0" } ``` Error (4xx / 5xx): ```json { "ok": false, "error": "VALIDATION_FAILED", "message": "human text", "contractVersion": "v1.0" } ``` Some error responses carry additional context fields alongside `error` and `message` (for example `field`, `validationErrors`, `requiredScopes`, `keyScopes`). ## Authentication All endpoints except `GET /v1` and `GET /v1/healthz` require an API key sent as `Authorization: Bearer `. Keys carry a set of named scopes; each operation documents the scope it requires. A key carrying the `*` wildcard scope passes every scope check. Pre-launch, sandbox keys are issued through the apply flow: request access at `/apply`, receive an activation email on approval, and exchange it for a `/v1` sandbox key in the integration playground at `/developers/playground`. Self-service key issuance from the developer dashboard at `/developers/dashboard` lands at the April 2027 production launch. ## Identifiers Resource ids are prefixed: bases `bas_…`, rights `rgh_…`, offers `ofr_…` (passed as `rightId`/`offerId`), settlement rules `rule_…`, counterparties `cp_…`, webhook subscriptions, and webhook deliveries `dlv_…`. All timestamps are ISO-8601 strings. contact: name: EnfinitOS Developer Support url: https://docs.enfinitos.com email: developers@enfinitos.com servers: - url: https://sandbox.api.enfinitos.com description: Sandbox — live today - url: https://api.enfinitos.com description: Production — at the April 2027 launch security: - bearerAuth: [] tags: - name: Discovery description: Unauthenticated contract + health probes. - name: Tenant description: Read the caller's sandbox tenant snapshot. - name: Rights description: Bases and the right lifecycle (issue, suspend, resume, revoke). - name: Offers description: Propose, accept, reject, counter, and withdraw offers. - name: Challenges description: Open, resolve, and withdraw challenges against rights. - name: Delivery description: Observe constraint-gated delivery events. - name: Audit description: The append-only event log. - name: Proof description: Signed proof packs. - name: Metering & Settlement description: Metering and settlement projections. - name: Settlement config description: Settlement rules and counterparties. - name: Compliance description: GDPR Article 15 export and Article 17 erasure. - name: Webhooks description: Webhook subscriptions and delivery history. - name: Disputes description: Delivery disputes — open, investigate, respond, resolve. paths: /v1/delivery: post: tags: - Delivery summary: Observe a delivery description: >- Observe a delivery event against an ACTIVE right. The substrate-specific constraint gate runs before the receipt is emitted; constraint violations come back as `412 PRECONDITION_FAILED`. The signed receipt is appended to the event stream and folded into the next proof pack on `POST /v1/proof-packs/seal`. Requires scope `delivery:write`. operationId: observeDelivery requestBody: required: true content: application/json: schema: type: object required: - rightId - spatialAnchorId - dwellMs properties: rightId: type: string description: The ACTIVE right being exercised (prefixed `rgh_`). spatialAnchorId: type: string minLength: 1 spatialPlacementId: type: - string - 'null' description: Optional placement within the anchor. dwellMs: type: number minimum: 0 description: Milliseconds of dwell on the surface (non-negative). correlationId: type: - string - 'null' description: Optional correlation id for upstream tracing. telemetry: type: object description: >- Optional substrate-specific telemetry passed to the constraint gate and, where consented, to metering. Accepts the full substrate signal set — DOOH-era, spatial AR/VR (presence, placement, consent), satellite/space-delivered, and screen/video/app signals. Canonical shape: `DeliveryTelemetry` in `packages/sandbox-core/src/types.ts`. Known fields below; additional fields are accepted. properties: speedMph: type: number description: e.g. AUTOMOTIVE remoteIdActive: type: boolean description: e.g. DRONE bvlosWaiverId: type: - string - 'null' description: e.g. DRONE voicePromptActive: type: boolean description: e.g. AUDIO headsetWorn: type: boolean description: Headset/glasses actually worn (OpenXR user presence). immersionLevel: type: string enum: - mixed - progressive - full description: >- visionOS-style immersion — mixed (passthrough) | progressive | full (VR). passthroughActive: type: boolean description: Passthrough (see-through) active. roomScaleBounded: type: boolean description: A guardian/boundary play-area is defined. boundaryProximity: type: string enum: - inside - near_edge - outside description: Proximity to the guardian boundary. locomotionState: type: string enum: - stationary - seated - walking - in_vehicle description: Derived user motion state. comfortVectionRisk: type: string enum: - low - med - high description: >- Derived motion-sickness (vection) risk for immersive motion. lightingState: type: string enum: - ok - too_dark - too_bright description: >- Ambient lighting suitability for an overlay (estimate, not calibrated lux). visibilityState: type: string enum: - visible - blurred - hidden description: >- WebXR session visibility — metering is suppressed when not visible. spatialAnchorPersistent: type: boolean description: >- Anchor persists across sessions (VPS / anchor persistence). geoAnchored: type: boolean description: Anchor is georeferenced to a real-world location. occlusionResolved: type: boolean description: >- Real-world occlusion was resolved (depth/scene reconstruction). fovPresence: type: boolean description: >- Content fell within the viewer's field of view (IAB/MRC AR viewability). gazeInView: type: boolean description: >- Derived looked-at-it — ONLY valid with eyeTrackingConsent. Never raw gaze. dwellInViewMs: type: number description: >- Derived dwell-in-view ms — ONLY valid with eyeTrackingConsent. eyeTrackingConsent: type: boolean description: Explicit, revocable eye-tracking consent (biometric). spatialMappingConsent: type: boolean description: >- Explicit spatial-mapping consent for the space being anchored. minorMode: type: boolean description: Viewer is (or may be) a minor — stricter gating. bystanderCaptureRisk: type: string enum: - none - possible description: >- Bystander capture risk when camera/passthrough is active in public. linkState: type: string enum: - acquired - degraded - lost description: Downlink state to the receiving terminal/screen. beamId: type: string description: Spot beam serving the terminal. coverageCellId: type: string description: Coverage / footprint cell id the terminal fell in. groundStationId: type: string description: Serving gateway / ground-station id. footprintRegion: type: string description: >- Licensed footprint region the serving cell sits in (ITU/territory code). spectrumBand: type: string description: Spectrum band (Ka/Ku/C/L/S/X…). dopplerLocked: type: boolean description: LEO Doppler / tracking lock established. weatherAttenuationDb: type: number description: >- Rain-fade / weather attenuation in dB (signal-quality estimate). licensedRegionMatch: type: boolean description: >- Serving cell falls WITHIN the right's licensed footprint — the gate refuses the render when explicitly false (runtime complement of a SPECTRUM_LICENCE basis). onboardProcessed: type: boolean description: Content was processed on-orbit (on-board compute). viewable: type: boolean description: >- Met the viewability bar (MRC: >=50% pixels, >=2s video / 1s display). completionState: type: string enum: - started - first_quartile - midpoint - third_quartile - complete description: VAST-style playback progress for video substrates. muted: type: boolean description: >- Player muted (CTV/video audibility — affects billable attention). audible: type: boolean description: Audio actually audible (volume > 0 and not ducked). appState: type: string enum: - foreground - background description: Host app foreground/background (mobile / CTV / gaming). additionalProperties: true responses: '200': description: The signed receipt payload and the substrate it landed on. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object properties: receipt: $ref: '#/components/schemas/ProofReceiptPayload' substrate: $ref: '#/components/schemas/Substrate' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/StateConflict' '412': $ref: '#/components/responses/PreconditionFailed' '422': $ref: '#/components/responses/ValidationFailed' components: schemas: SuccessEnvelope: type: object required: - ok - data - contractVersion properties: ok: type: boolean const: true data: description: Route-specific payload. Operation responses refine this. type: object contractVersion: type: string const: v1.0 ProofReceiptPayload: type: object description: The exact signed receipt payload the platform emits (version "1"). properties: version: type: string const: '1' receiptId: type: string correlationId: type: - string - 'null' spatialAnchorId: type: string spatialPlacementId: type: - string - 'null' issuedAt: type: string format: date-time renderedAt: type: string format: date-time dwellMs: type: number nonce: type: string witness: type: - string - 'null' Substrate: type: string description: >- Delivery substrate. The platform runtime recognises every value; which ones ship a dedicated client SDK varies (see the substrate readiness matrix). `ANY` matches all substrates. enum: - DOOH - CTV - MOBILE - STREAMING - AUDIO - MESSAGING - GAMING - GLASSES - AR_CONTACTS - HUD - VOLUMETRIC - HOLOGRAM - WEARABLES - AMBIENT - NEURAL - AUTOMOTIVE - SMART_HOME - ROBOTICS - DRONE - SATELLITE - AVIATION - MARITIME - SOCIAL_FEED - ANY ErrorEnvelope: type: object required: - ok - error - message properties: ok: type: boolean const: false error: $ref: '#/components/schemas/ErrorCode' message: type: string description: Human-readable explanation. contractVersion: type: string const: v1.0 field: type: string description: Present on some VALIDATION_FAILED errors — the offending field. validationErrors: type: array description: Present on settlement-rule / counterparty validation failures. items: type: object additionalProperties: true requiredScopes: type: array description: Present on SCOPE_MISSING — the scopes the operation needs. items: type: string keyScopes: type: array description: Present on SCOPE_MISSING — the scopes the presented key carries. items: type: string additionalProperties: true ErrorCode: type: string description: Machine-readable error code. Drives the HTTP status. enum: - AUTH_REQUIRED - AUTH_INVALID - SCOPE_MISSING - BAD_REQUEST - VALIDATION_FAILED - RESOURCE_NOT_FOUND - STATE_CONFLICT - PRECONDITION_FAILED - RATE_LIMITED - INTERNAL_ERROR responses: Unauthorized: description: >- Missing/malformed Authorization header (AUTH_REQUIRED) or an invalid key (AUTH_INVALID). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Forbidden: description: >- The key is valid but missing one or more required scopes (SCOPE_MISSING). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' NotFound: description: >- The referenced resource does not exist in this tenant (RESOURCE_NOT_FOUND). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' StateConflict: description: >- The resource is in a state that forbids this transition, or a concurrent write lost (STATE_CONFLICT). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' PreconditionFailed: description: >- A precondition failed — a constraint violation or a missing confirmation token (PRECONDITION_FAILED). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' ValidationFailed: description: >- A field was missing or wrong-typed (VALIDATION_FAILED). May carry `field` or `validationErrors`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: bearerAuth: type: http scheme: bearer description: 'API key sent as `Authorization: Bearer `.' ````