Toggle

:: Parsable Compression™ — API Documentation

HOME DEMO
Compression Docs
 TERMS


: Overview

Parsable Compression™ API reduces payload size while preserving structure, intent, and machine-read usability. Unlike token-based summarisation or heuristic compression — Maenen outputs remain parsable, auditable, and reusable across systems.

This makes the API highly suitable for AI pipelines that consume embeddings or other machine-readable semantic representations — including storage, retrieval, comparison, and downstream automated processing — not just one-off human-readable reductions.

➤ The compression value achieved is dependant on the nature of the content being processed. Content such as Smart Contracts can prove especially efficient.


: What Parsable Compression™ API Does

Given an input payload (text or structured data), the API:

  1. Analyses structure and semantic intent.
  2. Applies a selective, deterministic, rule-governed compression primitive.
  3. Returns:
    4. - a compressed output for reuse.
    - a receipt describing exactly what was done, - inc. measure to if structure and intent fidelity were successfully preserved.
➤ The output is designed to be repeatedly used by machines, or read by humans.



: Basic Usage

Endpoint

POST https://api.maenen.ai/v1/maenen/compress

Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Example Request

{
  "input": "Long text or structured payload here",
  "mode": "default"
}
- During beta, supported modes and limits may change.


: The Receipt (Important)

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

This allows you to:

➤ The receipt is the contract between your system and the compression layer.


✅ Success Receipt for Compression (example)

{
  • "compressed": [ [0.38,0.335,0.55,0.495,0.495,0.55,0.335,0.40] ],
  • "receipt": {
  •   "evaluation_mode": "estimated",
  •   "input_integrity": "verified",
  •   "fidelity": "sufficient",
  •   "tokens": {
  •     "accounted_input_tokens": 1024,
  •     "accounted_output_tokens": 412,
  •     "efficiency_tier": "significant_savings"
  •   },
  •   "latency_ms": {
  •     "optimisation": 45,
  •     "model": 0,
  •     "total": 45
  •   },
  •   "integrity": {
  •     "state": "preserved",
  •     "class": "passed",
  •     "confidence_band": "high"
  •   },
  •   "class": "passed",
  •   "warnings": [],
  •   "receipt_id": "a8f92d9c-1e4b-4f8a-9c2d-3e5f6a7b8c9d",
  •   "receipt_token": "eyJhbGciOi...",
  •   "schema_version": 4
  • }
}

➤ Notes:
  • Receipt attests to transformation integrity and efficiency; it does not include retrieval scope.
  • Token estimates are informational only and provided to help you assess scalable cost and efficiency impacts.
  • Actual token usage depends on target model and config. Run independant baseline to confirm comparative savings.
  • "efficiency_tier" classes indicate order-of-magnitude improvements, not exact savings, and should be interpreted comparatively rather than numerically.
    • "Moderate" and above results generally indicate meaningful structural compression.
    • "Significant" & "Exceptional" indicate strong to very strong reductions typical of well-structured or repetitive inputs.
    • The economy classes offered are ordinal, not numeric. Each represents a relative material step in effectiveness.
- See below for "Failure Response" examples.


: Public Contract Behavior

➤ Clients of the API can expect:

  • **POST /compress** as the documented entrypoint.
  • Auth via `Authorization: Bearer. `
  • Trial limits: XX calls, XXMB payload maximum.
    •
  • Clear error semantics:
    • `401` Invalid or missing API key.
    • `403` Trial limit exhausted, or capability not permitted.
    • `413` Payload too large.
    • `429` Rate limit exceeded (edge-enforced).
    • `500` Internal error.

- Receipts accompany successful operations.


: Determinism & Predictability

Maenen compression is designed to be predictable.

- This is intentional. The API is meant to sit inside infrastructure, not on the edge of UX.



: What This Is / Is Not

To set expectations clearly:

If you ONLY need a shorter paragraph for display, other tools may be sufficient.
If you NEED compressed data you can rely on, this API is designed for that role.



: Limits & Beta Notes

This API is currently in limited beta.

Breaking changes will be communicated ahead of time whenever possible



: API Keys

Access is permission-gated during beta.
Use the Key Request link on the home page to request access.
Keys are issued manually and may be revoked if terms are violated.



❌ 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 XX 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:

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

: Beta Notes

This API is currently in limited beta.


: Versioning

This documentation applies to:

API version: v0.3 (beta)
FOR-THE-DREAM-IS-WITH-INTEGRITY-FOR-THE-FREEDOM-OF-INTELLIGENCE