INVITATION-ONLY BETA PREPARATION

Evidence API
integration notes.

Contract: realityengine.business.v1. Local prototype; public production endpoints are unavailable.

Examples below are synthetic or local-fixture integrations. They do not authorize paid execution or describe a generally available service.

Authentication and versioning

Future pilot keys are issued privately by the owner. A key has a public identifier and a 256-bit secret; the database stores a SHA-256 verifier. Organization identity is resolved from the credential, never a supplied organization header. The local administrative functions require a trusted fixture/owner context; no production credential manager exists yet.

Use Authorization: Bearer YOUR_PRIVATE_PILOT_KEY on a secure server connection. Never use URL parameters, consumer cookies, public JavaScript, mobile bundles or Cloudflare credentials.

Rotation revokes the previous key. Keys support expiry and revocation; local fixture issuance is capped at seven days. There is no production retention SLA or compatibility promise during preparation. Breaking contract changes will receive a new version before a private beta.

Local endpoints

All paths use /api/business/v1. Every endpoint requires scoped authentication, including health and capabilities. None is routed publicly in production.

Supported request

POST /api/business/v1/investigations
Authorization: Bearer YOUR_PRIVATE_PILOT_KEY
Content-Type: application/json

{
  "question": "Why does ice float on liquid water?",
  "mode": "deep",
  "idempotencyKey": "your-unique-request-001",
  "approvalToken": "OWNER_ISSUED_REQUEST_BOUND_PERMIT"
}

V5 accepts question, mode, idempotencyKey, approvalToken and optional approved contextLinks. Question: 1–6,000 characters; JSON: at most 12 KiB; idempotency key: 16–80 letters, digits, underscores or hyphens. Mode: Deep only in the local commercial prototype. Direct source-link fetching, uploads and consumer file references are not supported; V5 permits owner-allowlisted public links as approved query hints. Consumer Quick discovery is a separate existing product.

Lifecycle, idempotency and usage

Ambiguity returns CLARIFICATION_REQUIRED and HTTP 422 without a provider reservation. A clear request can become QUEUED only when authenticated organization limits and trusted cost gates pass. A trusted local runner advances RUNNING to COMPLETE or FAILED_UNCERTAIN. GET never starts execution.

Reuse an idempotency key only for the exact same question and mode. A mismatch returns 409. Duplicate requests return the existing record without another reservation. Uncertain network outcomes must never be automatically retried; reconcile the existing job first.

Local quotas reserve jobs, provider calls and conservative micro-dollar estimates atomically. Estimates are not invoices or observed token charges. Reservations remain counted after uncertainty. Five new jobs per minute per organization and a conservative 120 metering-event operations per minute apply locally; per-organization lifetime budgets are configured privately, not a subscription allowance.

Webhooks, paid business plans, automatic retention scheduling and customer invoice reconciliation are not implemented. Private beta operations remain gated.

Errors that stay explicit

Do not retry 429, 503, timeout or uncertain outcomes automatically. Error bodies contain a stable code without credentials or provider error details.

Private evidence, practical limitations

Consumer investigations are never reassigned to business organizations. Every local data lookup includes authenticated organization ownership. Credential rotation retains ownership. Results use private/no-store responses and do not support public sharing.

Local content access expires after a configured one-to-seven days. Bounded owner-invoked fixture cleanup removes question/result content while preserving usage and duplicate-execution tombstones. Automatic production retention, deletion requests, incident handling and organizational agreements must be validated before onboarding; no retention service is live.

Deep evidence contains captured source passages and support/contradiction/insufficient-evidence relationships. It is not independent fact certification. Incomplete results are unavailable as completed evidence; missing dates remain null. Retrieved material is untrusted and must never be executed as instructions.

Do not submit sensitive personal information, regulated data, private documents or high-stakes automated decisions during preparation. Provider contract permissions and source redistribution rights require review. No SOC 2, HIPAA, guaranteed accuracy or uptime claim is made.

Legacy V1 fixture client (superseded for V5)

This earlier V1 client works with its original isolated fixture schema; V5 requires the new client and owner approval shown above. The client below works with a local fixture transport; it does not expose a live production integration. Each method makes exactly one request, without retries or automatic execution/polling. Never paste a real key into public code.

import {createRealityEngineClient} from './realityengine-client-v1.mjs';
const api = createRealityEngineClient({
  baseUrl: process.env.REALITYENGINE_PILOT_URL,
  apiKey: process.env.REALITYENGINE_PILOT_KEY
});
const job = await api.createInvestigation({
  question: 'Why does ice float on liquid water?',
  mode: 'deep', idempotencyKey: crypto.randomUUID()
});
// Explicit later reads; these never run providers:
const state = await api.getInvestigation(job.investigationId);
if (state.state === 'COMPLETE') {
  const evidence = await api.getEvidence(job.investigationId);
  // Your application inspects captured passages and unknowns.
}

Download the server-side prototype client · Inspect JSON contract

Synthetic response — not live evidence

{
  "contract": "realityengine.business.v1",
  "investigationId": "00000000-0000-4000-8000-000000000001",
  "state": "COMPLETE",
  "mode": "deep",
  "result": {
    "schema": "realityengine.evidence.v3",
    "question": "Why does ice float?",
    "sources": [
      {
        "id": 1,
        "url": "https://example.org/synthetic-water",
        "title": "Synthetic example",
        "publicationDate": null,
        "retrievedAt": null
      }
    ],
    "findings": [
      {
        "id": "example:1",
        "text": "Illustrative finding, not a verified investigation.",
        "disposition": "SUPPORTED",
        "evidence": [
          {
            "sourceId": 1,
            "passage": "Synthetic excerpt.",
            "relationship": "SUPPORT"
          }
        ]
      }
    ],
    "unknowns": [
      "Example data only. Missing dates remain null."
    ]
  }
}

V5 · REST and MCP, one investigation service

LOCAL SYNTHETIC PILOT · NOT A LIVE COMMERCIAL SERVICE. V5 adds request-bound execution approval, safe queued cancellation and an isolated authenticated MCP resource server. Consumer prices, credits and private cases remain separate.

Machine clients use privately issued, scoped API keys. ChatGPT connections require an OAuth authorization-code server with PKCE S256, resource-bound access tokens and approved redirect URIs. The local resource server verifies pinned RSA signatures, issuer, exact audience, expiry, scopes and a durable owner-approved organization binding. A production authorization server is not configured; this is not an approved ChatGPT integration.

Connection and approval

1. The owner verifies the applicant and privately provisions an isolated organization and scoped credential. Secrets are shown once; store them on your server.
2. Clarify the question without research or credits. Request an owner-issued permit for its exact question, mode, context links and unique request ID.
3. Submit that permit as approvalToken. Only Deep mode is supported. Public context links are owner-allowlisted query hints, never direct URL downloads. Private files and consumer case identifiers are rejected.
4. Read status and evidence. Polling never executes research. Queued cancellation preserves budget reservations; running or uncertain work cannot be cancelled safely or retried automatically.

The isolated MCP endpoint is /mcp. Six tools: get_capabilities, clarify_question, create_investigation, get_investigation, get_evidence and get_usage. No administration, keys, payments or unrestricted files are exposed as tools.

Streamable HTTP supports 2026-07-28 per-request discovery/metadata and 2025-11-25 initialization. Send JSON and SSE in Accept. Modern calls also send MCP-Protocol-Version, Mcp-Method and Mcp-Name matching the request body. Protected-resource metadata is prepared at /.well-known/oauth-protected-resource/mcp.

All tools are annotated as state-changing because they record a durable privacy-safe request counter; clarification still makes zero provider calls and consumes zero credits. Source passages remain untrusted evidence, never executable instructions. MCP output above 64 KiB returns an explicit truncation notice and an authenticated REST evidence path.

Runnable isolated examples

Run node scripts/business-v5-demo.mjs from the project. It provisions a synthetic owner organization, keeps its key in memory, uses the JavaScript REST/MCP clients and returns synthetic source-linked evidence through the existing pipeline. All provider stages are mocked; no external requests or charges occur.

import {createEvidenceClient, createMCPClient}
  from './realityengine-client-v5.mjs';
// Server-only credentials and a separately approved endpoint.
const api = createEvidenceClient({origin, token});
await api.clarify('Who am I?');
const job = await api.create({question, mode: 'deep',
  idempotencyKey: uniqueRequestId, approvalToken: ownerPermit});
await api.status(job.investigationId); // inspect; never auto-resume
await api.evidence(job.investigationId); // only after COMPLETE
await api.usage(); // reserved estimates, not customer charges
const mcp = createMCPClient({endpoint, token: oauthAccessToken});
await mcp.connect();
await mcp.list();
await mcp.call('clarify_question', {question: 'Who am I?'});

Handle 401/403 by correcting authorization; 409 means conflict or unsafe state. 422 requests clarification. 429/503, timeouts and uncertain outcomes must be reconciled without blind retries. No recurring commercial billing is available. Inspect the server-side V5 example client.