--- title: "Discover connector resources" method: POST path: "/connectors/{connectorInstanceId}/discoveryruns" tags: ["ConnectorResources"] --- # Discover connector resources `POST /connectors/{connectorInstanceId}/discoveryruns` Runs connector discovery and returns suggested resource descriptors and operation hints. Discovery results are advisory; callers must create resource descriptors and operation bindings explicitly before routes can use them. ## Path parameters - `connectorInstanceId` string, uuid, required — Stable platform identifier for a configured connector instance. ## Request body - DiscoverResourcesRequest — Request to ask a connector to discover available resources, fields, and operations. Discovery is advisory and returns suggested descriptors that still need to be persisted explicitly. - `includeFields` boolean — Whether discovery should include field-level descriptors when available. - `includeOperations` boolean — Whether discovery should include operation hints such as OpenAPI operation ids or database read/write capabilities. - `schemaDriftPolicy` 'IGNORE' | 'WARN' | 'FAIL' — Action to apply when a live discovered contract hash differs from the persisted resource descriptor contract hash. IGNORE suppresses drift findings, WARN returns findings, and FAIL rejects discovery. - `filters` 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` Discovery result with suggested resource descriptors. - DiscoveryResult — Discovery result returned by a connector. Suggested descriptors are not persisted until the caller creates them through the resource descriptor API. - `connectorInstanceId` string, uuid, required — Stable platform identifier for a configured connector instance. - `resources` DiscoveredResource[], required — Resources discovered from the connector. - `externalResourceName` string — Connector-local resource name such as path, table, bucket key, claim set, topic, or collection. - `resourceKind` 'OBJECT' | 'TABULAR' | 'DOCUMENT' | 'CLAIM_SET' | 'GRAPH' | 'EVENT_STREAM' | 'FILE' | 'SECRET' | 'CONFIGURATION' | 'CREDENTIAL' | 'PRESENTATION' | 'CUSTOM' — Logical kind of resource being accessed, independent of transport and serialization. For example, a CSV file with rows is ResourceKind TABULAR and RepresentationKind CSV. - `representationKind` 'JSON' | 'JSON_LD' | 'XML' | 'CSV' | 'PARQUET' | 'AVRO' | 'RDF' | 'JWT' | 'SD_JWT' | 'CBOR' | 'BINARY' | 'TEXT' | 'CUSTOM' — Data representation or serialization format, independent of transport. This is the data shape on the wire or at rest, not the connector implementation. - `suggestedDescriptor` ResourceDescriptor — Request to describe a resource shape independently from any connector instance or transport. A descriptor can later be attached to one or more connectors. - `displayName` string, required — Human-readable resource descriptor name. - `description` string — Description of the logical resource and intended use. - `resourceKind` 'OBJECT' | 'TABULAR' | 'DOCUMENT' | 'CLAIM_SET' | 'GRAPH' | 'EVENT_STREAM' | 'FILE' | 'SECRET' | 'CONFIGURATION' | 'CREDENTIAL' | 'PRESENTATION' | 'CUSTOM', required — Logical kind of resource being accessed, independent of transport and serialization. For example, a CSV file with rows is ResourceKind TABULAR and RepresentationKind CSV. - `representationKind` 'JSON' | 'JSON_LD' | 'XML' | 'CSV' | 'PARQUET' | 'AVRO' | 'RDF' | 'JWT' | 'SD_JWT' | 'CBOR' | 'BINARY' | 'TEXT' | 'CUSTOM', required — Data representation or serialization format, independent of transport. This is the data shape on the wire or at rest, not the connector implementation. - `shapeKind` 'SCHEMA' | 'OPENAPI_SCHEMA' | 'JSON_SCHEMA' | 'RDF_SHAPE' | 'SQL_TABLE' | 'CSV_HEADER' | 'CLAIMS_SCHEMA' | 'FREEFORM' — Type of structural shape information used to describe fields and validation rules for a resource. - `contract` ContractRef — Reference to the schema, contract, or discovery document that defines or constrains a resource. The contract is descriptive; transport is still represented by AccessProtocol. - `contractKind` 'OPENAPI' | 'JSON_SCHEMA' | 'SQL_SCHEMA' | 'RDF_SCHEMA' | 'CSV_PROFILE' | 'OIDC_DISCOVERY' | 'VAULT_POLICY' | 'CUSTOM', required — Contract or schema source used to describe an external resource. Use this to point at OpenAPI documents, JSON Schema, SQL metadata, RDF shapes, CSV profiles, OIDC discovery, or custom contracts. - `uri` string — URI or locator for the contract document. - `version` string — Contract version understood by the connector. - `contentHash` string — Optional hash of the contract content for integrity and drift detection. - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data. - `fields` object[] — Stored field descriptors for this resource descriptor. - `fieldPath` string, required — Path or column name within the resource representation. - `displayName` string — Human-readable field name. - `valueType` string, required — Logical value type, for example string, number, boolean, date, datetime, object, array, or binary. - `required` boolean — Whether the field is required for validation and mapping. - `multiValued` boolean — Whether the field can hold multiple values. - `semanticAttributeId` string, uuid — Optional semantic attribute binding used for validation, governance, and policy. - `sensitivity` string — Optional sensitivity or classification label used by governance and policy checks. - `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. - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data. - `fieldDescriptorId` string, uuid, required — Stable identifier for a field within a resource descriptor. - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data. - `resourceDescriptorId` string, uuid, required — Stable identifier for a described external or internal resource shape. - `createdAt` string, date-time, required — Creation timestamp. - `updatedAt` string, date-time, required — Last update timestamp. - `supportedOperations` OperationKind[] — Logical operations suggested by discovery. - `schemaDrift` SchemaDriftFinding — Governance fact emitted when a discovered resource contract no longer matches the pinned resource descriptor contract hash. - `resourceDescriptorId` string, uuid, required — Stable identifier for a described external or internal resource shape. - `externalResourceName` string — Connector-local resource name associated with the drift, when available. - `expectedContentHash` string, required — Persisted/pinned contract hash from the resource descriptor. - `discoveredContentHash` string, required — Hash reported by live connector discovery. - `expectedContractVersion` string — Version from the persisted contract reference. - `discoveredContractVersion` string — Version from the live discovered contract reference. - `policy` 'IGNORE' | 'WARN' | 'FAIL' — Action to apply when a live discovered contract hash differs from the persisted resource descriptor contract hash. IGNORE suppresses drift findings, WARN returns findings, and FAIL rejects discovery. - `detectedAt` string, date-time — Timestamp when drift was detected. - `message` string — Human-readable drift summary. - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data. - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data. - `schemaDrift` SchemaDriftFinding[] — Contract-hash drift findings detected while comparing live discovery with persisted resource descriptors. - `resourceDescriptorId` string, uuid, required — Stable identifier for a described external or internal resource shape. - `externalResourceName` string — Connector-local resource name associated with the drift, when available. - `expectedContentHash` string, required — Persisted/pinned contract hash from the resource descriptor. - `discoveredContentHash` string, required — Hash reported by live connector discovery. - `expectedContractVersion` string — Version from the persisted contract reference. - `discoveredContractVersion` string — Version from the live discovered contract reference. - `policy` 'IGNORE' | 'WARN' | 'FAIL' — Action to apply when a live discovered contract hash differs from the persisted resource descriptor contract hash. IGNORE suppresses drift findings, WARN returns findings, and FAIL rejects discovery. - `detectedAt` string, date-time — Timestamp when drift was detected. - `message` string — Human-readable drift summary. - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data. - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data. ## Other responses - `400` — Validation error. - `401` — Authentication is required. - `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/revisions/60cb8c70871b/schema)