Maenen Labs Documentation: Enhanced AI Data Retrieval API

:: Enhanced Data Retrieval — API Documentation

: Overview

The Maenen Enhanced Retrieval API performs deterministic semantic comparison over explicitly supplied artefacts.
It is designed to support recall, alignment, and evaluation workflows where meaning has already been preserved - for example via the Maenen Parsable Compression API.

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 Enhanced Retrieval API complements Parsable Compression API

Whilst independent, these two APIs are designed to further increase performance:

➤ Parsable Compression reduces payload size while preserving readability, structure and intent.
➤ Enhanced Retrieval compares preserved meanings to support rapid recall, alignment, or equivalence checks.

: What This API Does

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

Evaluates semantic similarity, alignment, or equivalence according to the selected mode.
Ranks or filters results within the supplied scope.
Returns:

The API does not generate new content, expand the candidate set, or access external data.

: What This 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

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

POST https://api.maenen.ai/v1/maenen/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 (Important)

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

What the retrieval 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 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.

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

❌ 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. Note that during beta trial, 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).
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