InterfaceDelta Docs

Getting started

Inspecting a service

Use the hosted inspector with whichever public HTTPS URL you have: a service root or a supported machine-readable endpoint. InterfaceDelta discovers the supported surfaces a service publishes, or inspects a known endpoint directly. Inspection is bounded and passive; it does not create a monitor.

1. Open Inspect.
2. Enter a public service URL, MCP endpoint, OpenAPI document, A2A Agent Card, or ARD manifest.
3. Review protocol, capability, access and consistency evidence.
4. Use the Type control only when a nonstandard endpoint cannot be identified safely from its URL.

Hosted product

The inspector is the starting point

The browser inspector accepts one primary public HTTPS URL, performs bounded passive observation, and renders the resulting Passport. A separate MCP endpoint belongs under Advanced only when it differs from the primary URL, including an explicitly authorized cross-origin endpoint. Its current POST /api/inspect transport is unversioned and subject to change; it is not presented as InterfaceDelta API v1.

Observed inputs

Protocol surfaces

InterfaceDelta observes public ARD discovery documents, A2A Agent Cards, and bounded MCP metadata inventories. Protocol-specific evidence is retained while deterministic normalization makes the result comparable as one Passport.

MCP discovery and explicit endpoints

InterfaceDelta does not crawl arbitrary website paths or guess every possible machine interface. Published discovery can lead from a service root to eligible endpoints. A submitted URL whose path is deterministically recognized as MCP, or whose Type is set to MCP endpoint, authorizes an MCP metadata probe only at that exact URL. An ordinary arbitrary URL is never blindly posted to as MCP.

OpenAPI observation

OpenAPI is a machine-readable description of a conventional web API. InterfaceDelta observes JSON or safe YAML OpenAPI 3.1 documents when a valid ARD declaration identifies the artifact or when the user supplies a known document directly. It does not guess Swagger paths, crawl API documentation pages, or call operations described by the document.

The same direct-input model applies to an A2A Agent Card or ARD manifest. Auto recognizes only reviewed path conventions; the explicit Type selector is the restrained escape hatch for a nonstandard endpoint.

Same-origin declarations may use the hardened HTTPS boundary. Cross-origin declarations are recorded but not fetched. Local references are bounded; remote references, servers, callbacks, webhooks, OAuth, OpenID, links, examples and externalDocs are never contacted. Unsupported semantics remain indeterminate.

OpenAPI to MCP checks require an exact valid publisher identifier and unambiguous schema slots. Names, descriptions, fuzzy matching, embeddings and LLM judgment are not evidence.

Primary protocol references: Agentic Resource Discovery (ARD), Agent2Agent (A2A), Model Context Protocol (MCP), and OpenAPI. These upstream specifications evolve; this page describes the exact versions and bounded behavior InterfaceDelta currently implements.

API

Current HTTP surface status

The hosted application has HTTP endpoints, but they do not all have the same stability or audience.

Authentication status. Hosted account and token management use the passwordless-email web session. Developer API v1 operations use a first-party bearer token created in Account. The public exact-observation share route remains unauthenticated.

InterfaceDelta does not use a password for your account. Enter your email address to receive a short-lived, single-use sign-in link. Signing in enables monitor subscriptions, alert preferences, Developer API token management, and account controls; public Passport and history records remain separate from your account.

Contract mechanics / beta

Developer API v1 contract

Developers owns access-surface choice, token setup, and practical request examples. This deeper reference records the versioned transport boundary and its relationship to retained evidence. Open the REST API integration guide →

curl -X POST https://interfacedelta.com/api/v1/inspect \
  -H "Authorization: Bearer $INTERFACEDELTA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.org"}'

const response = await fetch("https://interfacedelta.com/api/v1/inspect", {
  method: "POST", headers: { Authorization: `Bearer ${process.env.INTERFACEDELTA_API_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.org" })
});

import os, requests
response = requests.post("https://interfacedelta.com/api/v1/inspect", headers={"Authorization": f"Bearer {os.environ['INTERFACEDELTA_API_TOKEN']}"}, json={"url": "https://example.org"})

Scopes are inspect:run, passport:read, monitors:read, and monitors:write. Collections use opaque cursors, default 20 and maximum 100. Errors include a stable code, bounded message and request ID.

Supported v1 routes

• POST /api/v1/inspect — inspect:run; non-persistent.
• GET /api/v1/passports/:observationId — public exact-observation share contract.
• GET /api/v1/targets/:targetKey/history and /changes — passport:read; bounded cursor pagination.
• GET /api/v1/monitors — monitors:read.
• POST /api/v1/monitors and DELETE /api/v1/monitors/:subscriptionId — monitors:write.

Inspection uses the same public-HTTPS policy and is not persisted. Monitor creation preserves five targets per account, 50 shared global targets, and the approximately 24-hour cadence. Tokens bypass neither rate nor target controls.

OpenAPI: /api/openapi.json, OpenAPI 3.1.2. The public MCP interface is live; REST tokens are not MCP OAuth credentials and do not authenticate MCP accounts.

Canonical Passport

The current Passport schema version is 0.4.0. Major sections cover subject and observation identity, protocol surfaces, artifacts, endpoints, self-reported identity, access assertions, bounded inventory groups, capabilities, consistency findings and the semantic fingerprint.

Evidence taxonomy

Directly observed

Bounded network or protocol evidence, such as an HTTP response, retrieved document, negotiated MCP version, or listed inventory.

Publisher declared

A semantic statement supplied by publisher metadata. Retrieving the document is observed; the claim inside remains declared.

InterfaceDelta derived

A pure deterministic conclusion such as canonical identity, fingerprint, consistency finding, or compatibility classification.

Not observed / not fetched

A bounded unknown with its reason retained, including unreachable, forbidden, auth-required, policy-not-fetched, unsupported, or incomplete evidence.

The taxonomy is provenance, not a trust score. A Passport does not prove ownership, safety, security, legal compliance, active tool correctness, or universal compatibility.

Recorded history

Exact observation pages and the share API read already-recorded state and trigger no scan, observation write, or monitor mutation. Passport 0.2.0, 0.3.0, and 0.4.0 records remain faithful to their retained representations. Stored comparisons retain their historical compatibility rule version and are not recomputed on read.

{
  "schemaVersion": "0.4.0",
  "subject": {
    "origin": "https://sample-agent.invalid",
    "hostname": "sample-agent.invalid",
    "scheme": "https",
    "effectivePort": 443,
    "inputUrl": "https://sample-agent.invalid"
  },
  "protocols": [
    {
      "protocol": "a2a",
      "status": "valid"
    },
    {
      "protocol": "ard",
      "status": "valid"
    },
    {
      "protocol": "mcp",
      "status": "valid",
      "revision": "2026-07-28"
    },
    {
      "protocol": "mcp-server-card",
      "status": "not_detected"
    },
    {
      "protocol": "openapi",
      "status": "valid",
      "revision": "3.1.2"
    }
  ],
  "capabilities": [
    {
      "kind": "mcp.tool",
      "protocolKey": "create_order",
      "inventory": {
        "complete": true
      }
    },
    {
      "kind": "openapi.operation",
      "protocolKey": "POST /orders",
      "inventory": {
        "complete": false,
        "truncatedReason": "OPENAPI_SCHEMA_KEYWORD_UNSUPPORTED:pattern"
      }
    },
    {
      "kind": "mcp.resource",
      "protocolKey": "sample://catalog",
      "inventory": {
        "complete": true
      }
    },
    {
      "kind": "a2a.skill",
      "protocolKey": "research_brief",
      "inventory": {
        "complete": true
      }
    },
    {
      "kind": "mcp.tool",
      "protocolKey": "search_catalog",
      "inventory": {
        "complete": true
      }
    },
    {
      "kind": "mcp.prompt",
      "protocolKey": "brief_template",
      "inventory": {
        "complete": true
      }
    }
  ],
  "fingerprints": {
    "passport": {
      "algorithm": "sha256",
      "canonicalization": "RFC8785",
      "projectionVersion": "passport-semantic-v3",
      "value": "ebfd44368029af9a9114cfebf57eb96b22bc186e61d742ba144051aeb3374e54",
      "complete": false
    }
  }
}

AI applications

Public and account-authorized MCP

InterfaceDelta serves /mcp using MCP2026-07-28. The public read-only connection remains usable without signing in and is limited to already-recorded public state. The same read endpoint can also accept a WorkOS authorization issued for that exact resource. The canonical endpoint is https://interfacedelta.com/mcp; the connection command remains on the Developers page.

Two separate authorization resources

WorkOS Connect does not currently represent InterfaceDelta custom scopes. InterfaceDelta uses separate exact OAuth Resource Indicators and JWT audiences so fresh inspection authority cannot ride on the public/read authorization.

https://interfacedelta.com/mcp
  anonymous-compatible → four recorded-data read tools

https://interfacedelta.com/mcp/inspect
  WorkOS authorization required → inspect_public_service only

The read tools remain get_passport, get_latest_passport, list_target_history, and list_target_changes. The inspection resource accepts the same url, optional type, and optional mcpEndpoint inputs as the Web Inspector. A successful call records exactly one durable public-target Passport observation and its normal comparison; it does not create, remove, or alter a monitor.

Input
{ "url": "https://service.example/mcp", "type": "auto" }

Compact durable result
{
  "observationId": "…",
  "targetKey": "sha256:…",
  "passportUrl": "https://interfacedelta.com/passport/…/observations/…",
  "observedAt": "…",
  "fingerprint": "sha256:…",
  "comparison": { "state": "baseline|unchanged|changed|incompatible_version", "highestClassification": "…", "counts": { "breaking": 0, "nonBreaking": 0, "indeterminate": 0, "informational": 0 } },
  "summary": { "surfacesObserved": 0, "capabilitiesObserved": 0 }
}

The inspection resource is live and WorkOS-authorized. Keep the public/read MCP resource separate from the Inspector resource and its audience. InterfaceDelta Developer API tokens are not MCP OAuth tokens, and the caller's WorkOS credential is never passed to the inspected service.

Requesting an inspection proves only that an InterfaceDelta account requested the observation, not that it owns the target. The resulting observation may be available through existing public Passport and share surfaces. Connected-agent entries show read and inspection resource authorizations separately so either can be disconnected without presenting the other as revoked. The beta implementation permits 10 accepted fresh-inspection attempts per rolling hour per account; an explicit retry may record another observation.

Discovery publication

InterfaceDelta publishes ARD v0.91 at /.well-known/ard.json, advertises it from the root page with rel="ard", retains /.well-known/ai-catalog.json only for predecessor compatibility, and publishes experimental Server Card metadata at /mcp/server-card. The chain is ARD entry → experimental MCP Server Card → live MCP endpoint. Runtime server/discover and tools/list remain authoritative. These routes are live in the public beta.

Public share API

Exact observation JSON

GET /api/v1/passports/:observationId returns interfacedelta-share-v1 for an exact recorded observation. It is read-only, triggers no scan, requires a known observation UUID, and excludes account identity, session data, notification destinations, delivery records and raw remote bodies.

{
  "formatVersion": "interfacedelta-share-v1",
  "observation": {
    "id": "00000000-0000-4000-8000-000000000001",
    "observedAt": "2026-08-26T12:00:00.000Z",
    "recordedAt": "2026-08-26T12:00:01.000Z"
  },
  "target": {
    "targetKey": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "origin": "https://sample-agent.invalid",
    "explicitMcpEndpoint": null
  },
  "passport": {
    "schemaVersion": "0.4.0",
    "fingerprints": {
      "passport": {
        "algorithm": "sha256",
        "canonicalization": "RFC8785",
        "projectionVersion": "passport-semantic-v3",
        "value": "ebfd44368029af9a9114cfebf57eb96b22bc186e61d742ba144051aeb3374e54",
        "complete": false
      }
    }
  },
  "comparison": {
    "state": "changed",
    "highestClassification": "breaking",
    "counts": {
      "breaking": 1,
      "nonBreaking": 1,
      "informational": 0,
      "indeterminate": 1
    }
  }
}

Errors

400

INVALID_OBSERVATION_ID

404

OBSERVATION_NOT_FOUND

503

PERSISTENCE_UNAVAILABLE

Evidence

Example provenance

Public specimens distinguish observed network evidence from product-response examples and pinned protocol fixtures. The observed examples were captured by InterfaceDelta from its stateless controlled demonstration target at https://interfacedelta-demo-observed.vercel.app.

{
  "schemaVersion": "0.2.0",
  "subject": {
    "origin": "https://interfacedelta-demo-observed.vercel.app"
  },
  "observedAt": "2026-08-26T20:38:42.159Z",
  "fingerprint": {
    "algorithm": "sha256",
    "canonicalization": "RFC8785",
    "projectionVersion": "passport-semantic-v1",
    "value": "499b2050aad01e1c8cb3d685381da22bc185e232603bd1815f5f88c152c00829",
    "complete": true
  }
}

Observed example

Real InterfaceDelta target observation.

Controlled demo comparison

Real deterministic comparison between two observed demo Passports.

Product response example

Contract-valid hosted-product response, not target evidence.

Protocol fixture

Pinned standards artifact, not observed from the demo.

Reference

Result and error states

Protocol result states and top-level API errors remain distinct; consumers should not flatten them into one generic failure.

Reference

Compatibility rules

The current comparison rule version is compatibility-rules-v3. Historical v1 records keep their original meaning. New comparisons emit breaking, non_breaking, informational and indeterminate changes. A changed fingerprint signals a semantic difference; it is not itself a breaking conclusion.

MCP tool schema analysis is directional: inputs prove every previous request remains accepted; outputs prove every current producer value remains valid for a previous consumer. The bounded Draft 2020-12 fragment covers boolean schemas, type sets, const and enum, numeric and string bounds, conservative objects, homogeneous arrays, and bounded local references. Remote references are never fetched. Unsupported dialects, keywords such as pattern or oneOf, and reached limits produce explicit indeterminate findings. Developer API and list_target_changes reads include bounded field paths, before/after facts, reason codes, and rule version.

{
  "state": "changed",
  "ruleVersion": "compatibility-rules-v3",
  "counts": {
    "breaking": 1,
    "nonBreaking": 1,
    "informational": 0,
    "indeterminate": 1
  },
  "highestClassification": "breaking",
  "changes": [
    {
      "code": "CAPABILITY_REMOVED",
      "classification": "breaking",
      "entityKind": "capability",
      "entityId": "capability:e7c59cb6728b12f610ed630e",
      "reasonCode": "PREVIOUSLY_PRESENT_CURRENTLY_ABSENT_COMPLETE_INVENTORIES"
    },
    {
      "code": "INVENTORY_COMPARISON_INDETERMINATE",
      "classification": "indeterminate",
      "entityKind": "inventory",
      "entityId": "artifact:ad0bcdeee448ac869c66297a|openapi.operation",
      "reasonCode": "INVENTORY_INCOMPLETE_ON_ONE_OR_BOTH_SIDES"
    },
    {
      "code": "CAPABILITY_ADDED",
      "classification": "non_breaking",
      "entityKind": "capability",
      "entityId": "capability:a55ac47a48c9a53129a27418",
      "reasonCode": "CURRENTLY_PRESENT_PREVIOUSLY_ABSENT_COMPLETE_INVENTORIES"
    }
  ]
}

Incomplete inventory can suppress removal inference. InterfaceDelta reports an indeterminate comparison instead of manufacturing certainty from missing evidence.

Hosted accounts

Monitoring and alerts

Signed-in users can subscribe to recurring target observations through the browser product. Breaking changes notify by default; indeterminate notifications are optional. Current limits are beta guardrails, not service-level guarantees.

Programmatic access. Developer API v1 supports token-authenticated account monitor automation. Email-delivery internals remain browser-private.

Security model

Passive MCP boundary

Targets are public HTTPS only. Observation uses DNS/IP classification, DNS-pinned HTTPS, bounded redirects, bounded request and response sizes, and bounded pagination. No inspected-service credentials or arbitrary request headers are accepted.

This is a bounded observation model, not a security certification or a general-purpose MCP client.