Semantic API and MCP
Connect authorized AI agents to Blocchi's semantic evidence without sharing provider credentials.
Semantic API and MCP
Blocchi offers a single governed API at /api/v1, described by /api/openapi/v1, and a compatible Model Context Protocol (MCP) gateway at /api/mcp. A connected agent uses its authorized Blocchi identity; it never receives connector secrets.
Available read operations
GET /api/v1/data-plus/semantic-catalog: bounded semantic dataset instances, source sync freshness and saved field mapping metadata. Filters:connectionId,page(1–100),limit(1–50).GET /api/v1/business-graph: paginated typed source-record links with allowlisted provenance and caller-specific seller/unit visibility. Focus withinstanceIdplusrecordId, orpartyId.GET /api/v1/business-graph/types: governed relationship type catalog.GET /api/v1/data-plus/quality: quality, source status and suggested steward work where authorized.GET /api/v1/findingsandGET /api/v1/findings/{id}/evidence: existing governed findings and their evidence.
The MCP equivalents include blocchi.list_semantic_catalog, blocchi.list_business_graph, blocchi.list_business_graph_relationship_types, blocchi.get_data_quality, and blocchi.get_finding_evidence. Tool listings and calls are subject to the same Blocchi actor and tenant controls as REST.
Preview without execution
POST /api/v1/data-plus/mapping-preview and MCP blocchi.preview_semantic_mapping accept a connection ID and up to 50 assignments, each with entityInstanceId, semanticAttributeId, and sourceField.
The response checks identifier ownership, semantic entity compatibility, duplicate assignments and sensitive column-name patterns. It always returns previewOnly: true, applied: false, and authorizesPublication: false. It does not validate provider-side column existence or supply AI confidence.
Permissions and boundaries
Read operations require a Data+ entitlement, headless:read, and the current tenant's access. The semantic catalog specifically fails closed for seller/unit-scoped users; the Business Graph uses its own record-level scope predicates. Disabled Data+ source-read policies exclude sources. Delegated user sources are excluded from semantic metadata until the connector can verify the caller's source-native identity. Request parameters cannot supply a tenant ID, role, access grant, or identity. No endpoint reads arbitrary provider records, source tokens, or credential material.
Saved mappings are marked saved_unverified: they are not automatically classified as reviewed/published. X-Ray, Cleanup Studio profile, mapping proposals and aggregate cleanup preview are available through their existing governed Data+ services; the legacy catalog still labels saved mappings as saved_unverified. No remote approval, merge, mastering, row-level cleanup output, or mapping publication is exposed by these new tools.
Responses are not shared-cacheable. Existing request rate limits, tenant headless quotas and usage telemetry continue to apply. Human approval and other governed writes remain in the first-party workflows.
Integration checklist
Use Blocchi OAuth/bearer authorization, not the provider account's API token. Begin with the capability listing, request only a narrow source/page, inspect source freshness and evidence provenance, handle 403, 422 and 429, and never treat unavailable fields as zero or approved truth.
Data+ governance and diagnostics APIs
After integrating Data+ services, use GET /api/v1/data-plus/semantic-mapping?connectionId=<uuid>&datasetId=<uuid> for a read-only proposal, GET /api/v1/data-plus/business-xray for governed diagnostics, and GET /api/v1/data-plus/cleanup-profile for human steward-only recipe metadata. Previews with source-row values and approval/publication decisions remain in authenticated first-party stewardship flows.
Aggregate cleanup dry run
POST /api/v1/data-plus/cleanup-preview uses the same simulator as the first-party Cleanup Studio and returns counts only for a sample of up to 500 stored records. Required payload: { "datasetId": "<uuid>", "rules": [{ "field": "name", "kind": "trim" }] }. Rules run in order, up to 100, and accept the same options as Cleanup Studio, except enum_map, which stays in the studio. The matching MCP tool is blocchi.preview_cleanup_recipe. Only an interactive tenant admin/manager with Data+ stewardship, tenant-wide headless read and source-read permission can use it. Delegated sources are excluded; enum-value mappings, raw before/after values, quarantine records, approval and publish tokens are not exposed. A preview cannot publish or activate a recipe.