REST API

The independent record of what every agent tool can do and when that changed. Read the public atlas record through a versioned, metered data feed.

Authentication and quotas

Create an API token in Account → API tokens with record:read. Send it as a Bearer token. Monthly UTC quotas are Free 1,000, Pro 10,000 and Team 100,000 accepted requests, shared by all tokens on an account. Quotas reset at midnight UTC on the first day of the next month. A 429 response includes error.resetAt and Retry-After. Authentication and invalid query errors do not count; accepted requests count even if the subsequent read fails. Existing v1 traffic controls still apply.

Endpoints

• GET /api/v1/record/services: service summaries. Optional filters: changedSince (UTC timestamp), protocol, hasReadings and declaredObservedDisagrees (true or false).
• GET /api/v1/record/services/{key}: latest public capabilities, readings and retained change history. URL-encode the exact atlas service key.
• GET /api/v1/record/changes?since=2026-11-01T00:00:00Z: changes strictly after that timestamp, oldest first, with revision pairs, classifications and rule codes.

Lists accept limit (1–100, default 20) and an opaque cursor. Follow nextCursor until null, even after an empty page. Reading filters examine at most 20 services per request. Keep filters and limit unchanged between pages. A refreshed snapshot returns 409 CURSOR_EXPIRED; restart from your last timestamp and deduplicate revision pairs. This is a bounded atlas snapshot, not a durable event archive. At most 20 observations per service are retained, sometimes fewer; snapshots refresh about every six hours.

curl -H "Authorization: Bearer $INTERFACEDELTA_API_TOKEN" \
  "https://interfacedelta.com/api/v1/record/services?protocol=mcp&limit=20"

{
  "recordVersion": "record-v1",
  "generatedAt": "2026-11-02T00:00:00.000Z",
  "coverage": {
    "boundedHistory": true,
    "truncated": false
  },
  "services": [

{
  "recordVersion": "record-v1",
  "generatedAt": "2026-11-02T00:00:00.000Z",
  "coverage": {
    "boundedHistory": true,
    "truncated": false
  },
  "services": [
    {
      "origin": {
        "value": "https://example.com",
        "evidence": "DIRECTLY_OBSERVED"
      },
      "latestRevision": {
        "value": "sha256 fingerprint",
        "evidence": "INTERFACEDELTA_DERIVED"
      }
    }
  ],
  "nextCursor": null
}

Field glossary

recordVersion versions this representation; generatedAt dates its snapshot. Service fields carry value and evidence. Evidence classes are DIRECTLY_OBSERVED, PUBLISHER_DECLARED, INTERFACEDELTA_DERIVED and INTERFACEDELTA_INFERRED. Nested fields inherit the enclosing evidence class; change events carry their class alongside their fields.

key identifies an exact atlas target, not ownership. origin excludes paths. protocols lists detected protocols. latestRevision is the semantic fingerprint. lastObserved dates the latest observation; lastChanged is the most recent retained comparable change, or null. counts reports capabilities, incomplete inventories and retained observations.

capabilities contains plain names, method, up to four plain input names with required flags, additional input count, declared sign-in schemes and boolean hints. Readings are counted or disputed claims with probabilities; they remain inferences. Declared-versus-observed facts record disagreements, never safety verdicts. Null capabilities means the public Passport projection is unavailable; null readings means no reading is displayed.

history and the change feed carry timestamp, revision, and classification, exactly as shown by the atlas. The feed excludes baselines and unchanged observations. Publisher prose, endpoint paths, non-origin URLs and observation identifiers are excluded.

Atlas change webhooks are not available in this version.

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.

The deterministic OpenAPI 3.1.2 document lists only supported v1 operations.

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.

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.

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.

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.

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.

Every code is listed under Result and error states.

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.

For repository watching and the Action, create a watch token in Routing → Watch tokens; Account API tokens are for the REST API.

The REST API section covers token setup and practical request examples. This contract records the versioned transport boundary and its relationship to retained evidence.

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. Only for targets the token's account monitors; other keys return the same 404 as an unknown key.
• 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 each account’s plan limit (five targets on the Free plan), 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.

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.

Workspace account APIs return 401 AUTH_REQUIRED when signed out, and 403 WORKSPACE_FORBIDDEN when the selected workspace role cannot perform the action. Unavailable selections return 403 with WORKSPACE_NOT_FOUND, WORKSPACE_PLAN_SUSPENDED, WORKSPACE_MEMBERSHIP_NOT_FOUND, or WORKSPACE_SELECTION_INVALID. Choose an available workspace under Team before retrying; these requests never fall back to acting on your personal account.

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.