THIS vs THAT APIs

: API Overview

CompareThisThat™ offers two document and code comparison APIs that return structured findings about literal change, semantic equivalence, meaning drift, consequence and evidence. Both APIs produce evidence receipts.

They are semantic evaluation tooling designed to determine whether two artefacts are meaningfully equivalent or materially different.
They detect intent stability, not just simple surface similarity.

➤ Two versions are offered to use as suited.

Both are for workflows where subtle wording or structural shifts may alter obligation, scope, safety posture, or authority.

➤ They do not generate content. They evaluate semantic continuity under comparison.

Both calls are deterministic within bounded inputs, and are designed to be used stand-alone or within a chain of events (see 'Modular AI Pipeline' suggestion below).

: Typical Use Cases

This≠That provides semantic compare under constraint. It answers questions such as:

Policy and contract revision review.
Code permission boundary changes.
AI-generated output verification.
Safety constraint comparison.
Spec or product requirement validation.
Agent instruction stability checks.
"Is this intent substitution acceptable / allowed under defined rules?"

: Supported files

Current supported formats: TXT, RTF, DOCX, CSV, text-based PDF, JSON/config-style code text.

Unavailable in Release Set v1: legacy .doc, scanned/image-only PDFs, OCR, image, visual, CAD and schematic interpretation. Text admission does not qualify these capabilities.

: 2x Available APIs

Key-authenticated direct and product entrances share the Compare API allowance in Compare credits. Browser sessions use the separate web-use allowance. Neither uses the MeaningSystem wallet. Qualified successes consume registered capacity; failures do not. Usage deduplication is subject-bound within the same entrance/endpoint/key; execution can repeat. Retries still require admission and may be rejected after exhaustion or revocation. Switching entrance creates a separate usage identity. Tariff quantities remain pending separate pricing reconciliation.

Direct Core returns a signed-receipt reference. Product Core and both Review entrances return attributed unsigned comparison evidence with current receipt and retained usage linkage.

Endpoint	Input mode	Output mode	Audience
/v1/meaning/compare	Direct: this.payload/that.payload; product: text_a/text_b	compact evaluation	agents, devs, pipelines
/v1/this-vs-that/review	multipart file_a/file_b	rich review result v2	web app, human review, uploads

1. 'Compare Core Lite' ☯ Endpoint

`Copy Endpoint:-`

POST /v1/meaning/compare

`Input:-`

{

  "this": { "payload": "..." },

  "that": { "payload": "..." },

  "options": { "mode": "standard" }

}

: Description

Compare two inputs and detect semantic drift, continuity, and responsibility changes.

: Use cases

Agent pipelines
LLM tooling
Validation layers
Diff replacement

2. This≠That 'Review' ☯ Endpoint

(as called via this web app)

`Copy Endpoint:-`

POST /v1/this-vs-that/review

`Input:-`

{

  "file_a": "...",

  "file_b": "...",

  "options": { "mode": "standard" }

}

`Review API request:-`

Content-Type: multipart/form-data

file_a=

file_b=

: Description

Full document comparison with extraction quality checks, normalization, and semantic evaluation.

: Use cases

document uploads
semantic normalization
rich report output
human-facing review and audit evidence

: Formats

Currently supported: TXT, RTF, DOCX, CSV, text-based PDF, JSON/config-style text/code.

Limited / pending: legacy .doc, scanned/image-only PDFs, OCR-dependent files, password-protected files.

: Results & Receipts

➤ This≠That APIs return: A comparison outcome Optional explanatory signals A receipt documenting the evaluation	➤ The receipts support: Audit & Compliance Debugging and Review Downstream Enforcement Logic
All issued receipt results are bounded and explicit. They can be utilised by agents and clients can retain these records for audit or compliance.

	Diff Tools	This≠That™

Measures:	`Closeness`	`Semantic Meaning Intent`
Output:	`Score`	`Decision`
Constraints:	❌	✅
Determinism:	⚠️	✅
Audit Trail:	❌	✅

: Getting Started

Review the request / response schema
Provide two artefacts for comparison
Inspect the evaluation result and receipt

`Request Headers:-`

Header	Description
`Authorization`	`API key using Bearer format`
`Accept`	`application/json`
`Content-Type`	`application/json` (Core) / `multipart/form-data` (Review uploads)

`Request Body:- (core API JSON) — POST /v1/meaning/compare`


{

 "this": { "payload": "Original artefact text or structured content" },

 "that": { "payload": "Modified or alternative artefact" },

 "options": { "mode": "standard" }

}

➤ The direct API requires this.payload and that.payload; mode is standard or fast.

➤ The same-origin product Core route uses text_a/text_b. It has a separate response envelope; both entrances use the canonical Compare domain.

[ IMPORTANT ]

Review API request uses uploaded files: (file_a, file_b) -via- multipart/form-data on:
POST https://api.maenen.ai/v1/this-vs-that/review

: Product entrance response (success)

The direct Core entrance instead returns equivalence, semantic_distance, lock_state, confidence, signals and a signed-receipt reference. The product envelope below is not its wire response.

➤ A successful response returns a structured semantic evaluation and receipt.

`Core API success shape:- POST /v1/meaning/compare`

{

 "schema": "meaning_compare_result_v1",

 "status": "ok",

 "request_id": "tnt_req_...",

 "evaluation": {

  "equivalence": "materially_different",

  "continuity": { "score": 48, "label": "meaning_divergence" },

  "risk": { "level": "high", "reasons": ["approval_control_removed"] },

  "verdict": "material_break",

  "summary": "Approval and validation controls were weakened."

 },

 "signals": [],

 "usage": { "charged": true, "mc_charged": 1, "remaining_mc": 961 },

 "receipt": { "status": "verified", "determinism": "stable", "scope": "bounded", "receipt_id": "tnt_req_..." }

}

`Review API success shape:- POST /v1/this-vs-that/review`

{

 "schema": "this_vs_that_review_result_v2",

 "status": "ok",

 "request_id": "tnt_req_...",

 "result": {

  "summary": {},

  "decision_view": {},

  "matrix": {},

  "findings": [],

  "audit_view": {},

  "extraction": {},

  "normalization": {},

  "warnings": []

 },

 "usage": { "charged": true, "mc_charged": 1, "remaining_mc": 961 },

 "receipt": { "status": "verified", "determinism": "stable", "scope": "bounded", "receipt_id": "tnt_req_..." }

}

`Review API hard-stop shape (no partial result):-`

{

 "schema": "this_vs_that_review_result_v2",

 "status": "hard_stop",

 "error": { "code": "unreliable_extraction", "title": "File Extraction Warning", "message": "...", "advice": "..." },

 "result": null,

 "usage": { "charged": false, "mc_charged": 0 },

 "receipt": { "status": "not_issued", "reason": "evaluation_not_performed" }

}

➤ The summary output offered provides interpretive guidance. It does not rewrite or alter the inputs.

: The Receipt

➤ This≠That returns a receipt documenting the evaluation boundary and determinism.

`Receipt Fields (High-Level):-`

Field	Description
`status`	Evaluation status; `verified` does not signify a cryptographic signature
`determinism`	Deterministic outcome indicator
`scope`	Evaluation boundary classification
`warnings`	Optional non-fatal notices
`receipt_id`	Unique identifier

`Example (redacted):-`


{
 "receipt": {

  "status": "verified",

  "determinism": "stable",

  "scope": "bounded",

  "warnings": [],

  "receipt_id": "tnt_req_…",

  "evidence_kind": "unsigned_comparison_receipt",

  "product_id": "comparethisthat",

  "entrance_id": "comparethisthat_product",

  "authorized_subject": "usr_…",

  "endpoint": "/v1/meaning/compare",

  "billing_namespace": "comparethisthat",

  "wallet_namespace": "compare_this_that_api",

  "usage_event_id": "use_…",

  "usage_receipt_id": "tnt_req_original…",

  "usage_idempotency_key": "comparethisthat:comparethisthat_product:/v1/meaning/compare:…"

 }

}

➤ Receipts are suitable for:

Audit & compliance review
Pipeline debugging
Agent chain validation
Governance workflows

Receipts can be stored by agents and clients for audit or compliance purposes.

: Failure Response Examples

➤ This≠That uses explicit, bounded error responses. Failures do not return partial evaluation results.

❌ Invalid Request


{
 "error": {

  "code": "invalid_request",

  "message": "Malformed comparison payload"

 }

}

❌ Scope Mismatch


{
 "error": {

  "code": "scope_mismatch",

  "message": "Inputs are not comparable within bounded evaluation scope"

 }

}

❌ Input Exceeds Limits


{
 "error": {

  "code": "input_limit_exceeded",

  "message": "Input size exceeds allowed limits

 }

}

❌ Authentication Error


{
 "error": {

  "code": "unauthorized",

  "message": "Invalid or missing API key"

 }

}

: Limits & Security Guardrails

➤ This≠That enforces strict evaluation boundaries.

Input Limits

Strict input validation
Maximum input size enforced
Structured validation prior to processing
Rejection of malformed payloads

Processing Guardrails

Bounded semantic comparison scope
Deterministic evaluation paths
No generation or rewriting
No free-form generation
No external data access

Output Characteristics

Stable structure
No hidden fields
No silent mutation
No adaptive variation across identical inputs

: Privacy & Data Handling

➤ This≠That is designed with minimal data exposure.

Inputs are processed ephemerally
No training on customer data
No secondary use of payloads
No cross-request retention

: Capability Scoping

Some API capabilities are gated by key scope. Keys without the requisite scope will receive:

403 capability_not_permitted

: Edge Rate Enforcement

Rate limits are applied at the network edge (via NGINX). Excess traffic will receive:

429 Too Many Requests

These limits are distinct from usage ceilings and do not imply SLA guarantees.

: Modular AI Pipeline Insertion

These are workflow examples of how you might sequence the Maenen suite tools.
This≠That can be used standalone to verify any shift in intent between documents - after inception, normalisation, or transformation - to ensure semantic constraints are respected before downstream reuse.

Inception ? This≠That └──▶ ParsAIble Compression └──▶ WaveInform → X → WaveReturn → → →

→ → → WaveInform → X → WaveReturn → This≠That └──▶ ParsAIble Compression

→ → → Agent → MeaningSystem.io └──▶ This≠That

: Support

For technical issues or questions, contact support via the site. Note that during public beta trial release, full support and any SLA is not offered, though your query or comment will be carefully considered. Please include:

A short description of the issue.
Example payloads (if possible and not sensitive / private).
The receipt from the relevant request.

Receipts significantly reduce back-and-forth and speed up diagnosis.

: Public Beta Notes

These new release APIs are currently in public beta.

Supported modes, payload limits, and capabilities may evolve.
Though endeavoured to be consistant, no uptime or performance guarantees are implied.
Breaking changes will be communicated ahead of time where possible.

Access Support

FOR-THE-DREAM-IS-WITH-FREEDOM-FOR-THE-INTEGRITY-OF-THE-INTELLIGENCE

THIS vs THAT APIs

: API Overview

: Typical Use Cases

: Supported files

: 2x Available APIs

Endpoint

Input mode

Output mode

Audience

1. 'Compare Core Lite' ☯ Endpoint

Copy Endpoint:-

Input:-

: Description

: Use cases

2. This≠That 'Review' ☯ Endpoint

Copy Endpoint:-

Input:-

Review API request:-

: Description

: Use cases

: Formats

: Results & Receipts

Diff Tools

This≠That™

: Getting Started

Request Headers:-

Header

Description

Request Body:- (core API JSON) — POST /v1/meaning/compare

[ IMPORTANT ]

: Product entrance response (success)

Core API success shape:- POST /v1/meaning/compare

Review API success shape:- POST /v1/this-vs-that/review

Review API hard-stop shape (no partial result):-

: The Receipt

Receipt Fields (High-Level):-

Field

Description

Example (redacted):-

: Failure Response Examples

: Limits & Security Guardrails

Input Limits

Processing Guardrails

Output Characteristics

: Privacy & Data Handling

: Capability Scoping

: Edge Rate Enforcement

: Modular AI Pipeline Insertion

: Support

: Public Beta Notes

`Copy Endpoint:-`

`Input:-`

`Copy Endpoint:-`

`Input:-`

`Review API request:-`

`Request Headers:-`

`Request Body:- (core API JSON) — POST /v1/meaning/compare`

`Core API success shape:- POST /v1/meaning/compare`

`Review API success shape:- POST /v1/this-vs-that/review`

`Review API hard-stop shape (no partial result):-`

`Receipt Fields (High-Level):-`

`Example (redacted):-`