Developers

Authentication

Send an InterfaceDelta REST API token as Authorization: Bearer …. Create the token from a browser-authenticated Account and select only the scopes the integration needs. The exact-observation share route is the deliberate public exception.

Base URL

The deterministic OpenAPI 3.1.2 document lists only supported v1 operations.

Inspection

Endpoint

POST /api/v1/inspect

Authentication

REST bearer token

Scope

inspect:run

Request

Public HTTPS url and optional public mcpEndpoint

Response

Discovery report and canonical Passport

Persistence

None. This standalone inspection does not create an observation, comparison, or monitor.

Passport reads

Exact observation

GET /api/v1/passports/:observationId · public read-only interfacedelta-share-v1

Target history

GET /api/v1/targets/:targetKey/history · passport:read

Target changes

GET /api/v1/targets/:targetKey/changes · passport:read

These routes read existing records. They do not start a target scan or recompute retained historical Passport schemas and compatibility rules.

Monitor operations

List

GET /api/v1/monitors · monitors:read

Create

POST /api/v1/monitors · monitors:write · initial recorded observation

Remove

DELETE /api/v1/monitors/:subscriptionId · monitors:write

Monitor operations are limited to the authenticated token account. Subscription ownership remains separate from shared target scheduler state.

Pagination

History and change collections use opaque keyset cursors. The default page size is 20 and the maximum is 100. Malformed cursors and limits outside 1–100 are rejected. Monitor listing is bounded independently and returns at most 100 active subscriptions.

Errors and request IDs

Protected v1 endpoints return a stable error code, a bounded message, and a request ID. The request ID also appears in the x-request-id response header. Authentication failure is 401, insufficient scope is 403, malformed input is 400, absent records are 404, conflicts are 409, and bounded service or rate failures retain their documented status.

Protocol observation states such as auth_required, forbidden, incomplete inventory, and indeterminate compatibility are evidence—not generic HTTP API failures.

Target safety

API authorization permits use of InterfaceDelta; it does not authorize a target. Tokens bypass neither public-HTTPS policy, DNS and redirect revalidation, request and response bounds, nor current beta abuse controls. Requests cannot supply target credentials, arbitrary headers, TLS bypasses, or private-network access.

Example

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"}'

Resource and access

This resource reads evidence InterfaceDelta has already recorded. Anonymous use remains supported. A separately managed WorkOS authorization may identify a connected-agent relationship, but it does not expand this resource beyond its four read tools.

Tools

• get_passportRead one exact recorded observation.
• get_latest_passportRead the latest Passport for an exact target.
• list_target_historyRead bounded target observation history.
• list_target_changesRead bounded deterministic change records.

Read boundary

The public MCP resource does not initiate a scan, create or alter a monitor, expose account-private state, or accept a REST API token. A presented invalid bearer fails closed rather than silently falling back to anonymous access.

Connect

Choose your client. Every recipe connects the same anonymous, read-only recorded-evidence resource.

codex mcp add interfacedelta --url https://interfacedelta.com/mcp

Connect

Add this as a separate server. Headless status is shown per client without changing the exact Inspector resource.

codex mcp add interfacedelta_inspector --url https://interfacedelta.com/mcp/inspect --oauth-client-registration cimd --oauth-resource https://interfacedelta.com/mcp/inspect
codex mcp login interfacedelta_inspector --oauth-client-registration cimd

Authorization

WorkOS is the sole MCP OAuth provider. The website's magic-link/database session is separate and is not an MCP client credential. A valid Inspector token must also resolve to a live local InterfaceDelta account before target input or network work is accepted.

Resource indicator

The Inspector audience is isolated from the public/read resource. A token for https://interfacedelta.com/mcp cannot authorize https://interfacedelta.com/mcp/inspect, or vice versa. No default WorkOS Resource Indicator is configured; the MCP client authorizes the exact resource announced by protected-resource metadata.

Tool

Tool

inspect_public_service

Input

Public HTTPS url and optional public mcpEndpoint

Tools on this resource

Exactly one

Inspection behavior

Each successful invocation performs one bounded passive inspection of a public service. It never calls a target's tools or other capabilities, mutates the inspected service, creates a monitor, or accepts credentials for the target.

Persistence and retries

A successful invocation records one durable public Passport observation and its normal deterministic comparison. The operation is intentionally not idempotent: after a lost response, an explicit retry can consume another quota reservation and create another observation.

Security boundary

Authorization proves only that an InterfaceDelta account requested the observation. It does not prove ownership of the inspected target.

The caller's WorkOS bearer ends at InterfaceDelta's inbound authorization adapter and is never forwarded to the target. Public-HTTPS, DNS-pinning, redirect, time, size, and passive-scan restrictions remain in force.

Example

{
  "url": "https://example.org"
}

Account flow

1. Sign in to InterfaceDelta in the browser.
2. Create a REST API token in Account.
3. Use that bearer with Developer REST API v1.

Scopes

inspect:run

Run standalone non-persistent inspection.

passport:read

Read protected target history and changes.

monitors:read

List the token account's monitor subscriptions.

monitors:write

Create or remove account-owned subscriptions.

workflows:read

List the token account's workflows and read their change relevance.

Credential boundary

InterfaceDelta REST Developer API tokens are not WorkOS MCP OAuth credentials.

REST tokens are not MCP OAuth credentials. A REST bearer token cannot connect to /mcp or /mcp/inspect. MCP clients use the authentication boundary of the exact MCP resource instead.

Lifecycle

Choose explicit scopes at creation. The raw token is displayed once; existing rows show only label, non-secret prefix, scopes, creation time, last-used state, and revocation state. Lost raw tokens cannot be recovered or displayed again.