:: hAIper Semantic Retrieval API Documentation

HOME MEANINGSYSTEM
KEYS 🤖


: hAIper Enhanced AI Data Retrieval

Maenen hAIper™ Retrieval API performs rapid deterministic semantic comparison over explicitly supplied artifacts.


Designed to support recall, alignment, and evaluation workflows where meaning has already been preserved.

Unlike search engines, RAG systems, or adaptive retrieval layers, the Maenen Retrieval API is strictly bounded, read-only, and non-learning. All retrieval operations are limited to the candidate set you provide, and all results are returned with an auditable receipt.

: How hAIper™ Retrieval API complements Parsable Compression API

Whilst independent, these two tools complement each other:


➤ ParsAIble Compression reduces payload size while preserving readability, structure and intent.

➤ hAIper™ Retrieval compares preserved meanings to support rapid recall, alignment, or equivalence checks.

: What hAIper Does

Given a query and a bounded set of candidate artefacts, the tool:

  1. Evaluates semantic similarity, alignment, or equivalence according to the selected mode.
  2. Ranks or filters results within the supplied scope.
  3. Returns:
    • - references to matched artefacts,
    • - relative scores and ranks,
    • - a receipt describing the scope and integrity of the retrieval.

: What hAIper API Does Not Do

To set expectations clearly:

  • ❌ Not a search engine
  • ❌ Not a RAG or knowledge retrieval system
  • ❌ Not a learning or adaptive model
  • ❌ Not a content generator or summariser
  • ❌ The API does not generate new content, expand the candidate set, or access external data.

If you need open-ended knowledge access or synthesis, other systems may be more appropriate. If you need deterministic, bounded semantic comparison you can rely on, this API is designed for that role.

: Basic Usage

Endpoint (click to copy)

POST /v1/retrieve

Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

: Retrieval Modes

Retrieval behaviour is selected via an explicit mode:

  • similarity — nearest semantic match (default)
  • alignment — directional or structural alignment
  • equivalence — semantic equivalence thresholding

Modes affect comparison behaviour only; result shape and receipt semantics remain consistent.

: Determinism & Predictability

The Retrieval API is designed to be predictable.

  • Identical inputs produce identical outputs
  • No hidden randomness
  • No adaptive learning between calls

This allows retrieval to be safely embedded inside infrastructure, evaluation loops, and automated pipelines.

: The Receipt

Every successful retrieval returns a receipt. The receipt is not telemetry or analytics. It is a verifiable statement of the retrieval process performed. The receipt tells you:

  • The number of candidates considered
  • The retrieval mode applied
  • Whether execution was bounded to the declared scope
  • Integrity and confidence indicators

What it does not claim:

  • Truth or factual correctness
  • Completeness
  • Global optimality

Receipts allow you to audit, log, and justify downstream decisions in your automated systems.


✅ Success Receipt for Retrieval (example)

{
  • "results": [
  •   {"reference": "0", "score": 0.923456, "rank": 1},
  •   {"reference": "3", "score": 0.891234, "rank": 2},
  •   {"reference": "7", "score": 0.845678, "rank": 3}
  • ],
  • "receipt": {
  •   "evaluation_mode": "estimated",
  •   "comparison_integrity": "verified",
  •   "scope": {
  •     "candidate_count": 50,
  •     "evaluated_count": 50,
  •     "limit_applied": 10,
  •     "scope_reduction_pct": 80.0
  •   },
  •   "retrieval": {
  •     "mode": "similarity",
  •     "ranking": "relative",
  •     "confidence_band": "high"
  •   },
  •   "latency_ms": {
  •     "retrieval_ms": 12
  •   },
  •   "integrity": {
  •     "state": "preserved",
  •     "class": "passed"
  •   },
  •   "class": "passed",
  •   "warnings": [],
  •   "receipt_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  •   "receipt_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  •   "schema_version": 1
  • }
}


Notes:

  • The receipt describes how retrieval was performed, not whether the result is “correct”.
  • All retrieval operations are bounded strictly to the supplied candidate set.
  • No external data sources are accessed.
  • Scores and ranks are relative to the provided candidates only.
  • The receipt is a process attestation and is suitable for logging, auditing, and downstream automation.
  • The receipt attests to comparison scope and mode; scores are relative to supplied candidates only.

: Limits & Guardrails

The Retrieval API inherits the same guardrails as Parsable Compression API:

  • Authentication and key-based access control.
  • Usage ceilings during beta.
  • Edge-enforced rate limiting.

Trial limits and error semantics mirror those documented for compression.

: Privacy & Data Handling

Retrieval operations follow the same privacy, data-handling, and retention guarantees as the Compression API.

Retrieval is read-only and does not store, learn from, or mutate user data. For details, see the [ Terms & Privacy ] page.


❌ Failure Response Examples

- Failure responses are shared across all Maenen APIs:


Trial key exhausted (403)

{
  • "type": "user_error",
  • "code": "trial_exhausted",
  • "message": "Trial limit of 15 requests exceeded. Upgrade to continue.",
  • "retryable": false,
  • "receipt_id": null
}

Invalid API key (401)

{
  • "type": "user_error",
  • "code": "invalid_api_key",
  • "message": "Invalid or missing API key",
  • "retryable": false,
  • "receipt_id": null
}

Payload too large (413)

{
  • "type": "user_error",
  • "code": "payload_too_large",
  • "message": "Request body exceeds 2MB limit for trial keys",
  • "retryable": false,
  • "receipt_id": null
}

Retrieval not permitted (403)

{
  • "type": "user_error",
  • "code": "capability_not_permitted",
  • "message": "Retrieval capability not enabled for this API key",
  • "retryable": false,
  • "receipt_id": null
}

Internal error (500)

{
  • "type": "system_error",
  • "code": "internal_error",
  • "message": "An unexpected error occurred",
  • "retryable": false,
  • "receipt_id": null
}

: 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.



: Support

For technical issues or questions, [ contact support ] via the site. Full support and service-level agreements are not offered during the beta trial, though your query or comment will be carefully considered. Please include:

  • A short description of the issue.
  • The receipt from the relevant request.
Receipts significantly reduce back-and-forth and speed up diagnosis.


: Beta Notes

This API is currently in limited beta.

  • Supported modes and limits may evolve.
  • No uptime or performance guarantees are implied.
  • Breaking changes will be communicated ahead of time where possible.

: Versioning

This documentation applies to:


API version: v0.1 (beta)

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