---
title: "Execute an externally initiated route exposure read"
method: POST
path: "/route/exposures/{exposureDescriptorId}/read"
tags: ["RouteExposures"]
---

# Execute an externally initiated route exposure read

`POST /route/exposures/{exposureDescriptorId}/read`

Executes an explicitly registered external-read route exposure. The caller supplies the
authenticated Party context, governed canonical fields already eligible for projection,
governance metadata and optional cursor state. VDX evaluates policy server-side before
any grant or throttle consumption. The response is an
approved governed view with manifest, policy lineage, selected fields, and cursor state.
This endpoint does not expose internal connector records, Party tables, vault rows, or
semantic stores directly.

## Path parameters

- `exposureDescriptorId` string, required — Stable identifier of an externally callable route exposure descriptor.

## Request body

- RouteExposureExternalReadRequest — Governed request envelope for an externally initiated read through a route exposure descriptor.
  - `authMethod` string, required — Auth or trust method accepted by the exposure descriptor.
  - `callerParty` PartyRef, required — Neutral Party reference carried by EDK connector envelopes without importing the VDX Party repository.
    - `partyId` string
    - `externalId` string
    - `partyType` string
    - `displayName` string
    - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
  - `canonicalFields` object, required — Canonical field values eligible for projection through the governed exposure.
  - `governance` ConnectorGovernanceEnvelope — Governance metadata attached to connector records, invocations, and runs before data crosses a protocol, form, vault, dataspace, or external-exchange boundary.
    - `classification` string
    - `sensitivity` string
    - `specialCategory` boolean
    - `legalBasis` string
    - `purpose` string
    - `b2bUsagePurpose` string — B2B or dataspace usage purpose, separate from privacy legal basis and processing purpose.
    - `frameworkAgreementRef` string
    - `contractReference` string
    - `minimizationStatus` 'NOT_EVALUATED' | 'MINIMIZED' | 'REDACTED' | 'FULL_DATASET' | 'EXCESSIVE'
    - `retentionProfileId` string
    - `retention` RetentionSpec — Retention metadata used by governance and future compliance checks. It can be applied to fields, resources, materialized data, or dead-letter payloads.
      - `purpose` string — Processing purpose.
      - `legalBasis` string — Legal or contractual basis for retention.
      - `retentionPeriod` string — ISO-8601 duration, for example P30D or P7Y.
      - `deleteAction` 'DELETE' | 'ANONYMIZE' | 'PSEUDONYMIZE' | 'TOMBSTONE' | 'REVIEW' — Action to apply when retention expires or deletion is required by policy.
      - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
    - `crossBorderRestriction` 'NONE' | 'SAME_COUNTRY' | 'EEA_ONLY' | 'APPROVED_COUNTRIES' | 'CONTRACT_REQUIRED' | 'BLOCKED'
    - `encryptionRequirement` 'NONE' | 'IN_TRANSIT' | 'AT_REST' | 'AT_REST_AND_IN_TRANSIT' | 'CUSTOMER_MANAGED_KEY'
    - `dpiaRequired` boolean
    - `integrity` ConnectorIntegrityReference — Integrity and evidence references carried with governed connector ingress, egress, and run lineage.
      - `originalPayloadHash` string
      - `canonicalPayloadHash` string
      - `transformationHash` string
      - `evidenceRef` string
      - `vaultRef` string
      - `signatureRef` string
      - `sealRef` string
      - `timestampRef` string
      - `sourceAuthenticityVerdict` string
      - `outputManifestHash` string
    - `policyDecisionId` string
    - `relianceVerdict` 'NOT_EVALUATED' | 'RELIABLE' | 'CONDITIONAL' | 'NOT_RELIABLE'
    - `auditCategory` 'PROTOCOL_ISSUANCE' | 'PROTOCOL_VERIFICATION' | 'FORM' | 'PORTAL' | 'WORKFLOW' | 'DATASPACE' | 'INDUSTRIAL' | 'EXTERNAL_EXCHANGE' | 'VAULT' | 'SYSTEM_CATALOG'
  - `cursor` ConnectorCursor — Opaque cursor or watermark returned by connector runtimes and external exposure reads.
    - `value` string, required
    - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.

## Response `200`

Governed external-read view.

- ConnectorExternalReadResponse — Approved governed view returned by an externally initiated read exposure.
  - `state` string, required
  - `runId` string, uuid — Stable identifier for a connector route or operation run.
  - `exposureDescriptorId` string, required — Stable identifier of an externally callable route exposure descriptor.
  - `logicalConnectionBindingId` string, required — Stable identifier of a tenant, OU, brand, legal-entity, or channel usage binding for a physical connector instance.
  - `policyDecisionId` string, required
  - `selectedFieldPaths` string[], required
  - `manifest` ConnectorExportManifest, required — Governed egress manifest for an external-read response.
    - `manifestId` string, required
    - `destinationIdentity` string, required
    - `selectedFields` ConnectorExportedField[], required
      - `fieldPath` string, required
      - `value` object, nullable
      - `redacted` boolean
      - `minimized` boolean
      - `integrityHash` string, required
    - `mappingVersion` string, required
    - `mappingProvenance` string
    - `policyDecisionId` string, required
    - `retentionProfileId` string, required
    - `agreementRef` object
    - `participantIdentity` object
    - `transferProcess` object
    - `obligations` object[]
    - `manifestHash` string, required
  - `cursor` ConnectorCursor — Opaque cursor or watermark returned by connector runtimes and external exposure reads.
    - `value` string, required
    - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
  - `sourceSurface` string

## Other responses

- `400` — Validation error.
- `401` — Authentication is required.
- `403` — The caller is authenticated but not authorized for this connector operation.
- `404` — The requested resource was not found.

---

[API](https://skmtc.net/sphereon-opensource/apis/connector-integration-profile-api.md) · [All operations](https://skmtc.net/sphereon-opensource/apis/connector-integration-profile-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sphereon-opensource/connector-integration-profile-api/versions/60cb8c70871b/schema)