:: ParsAIble Context Compression API Documentation

HOME MEANINGSYSTEM
KEYS 🤖


: ParsAIble (docs)
AI readable compression

ParsAIble Compression™ reduces representation size while preserving machine-useful structure and intent.


This API is designed for AI pipelines working with embeddings and other numerical or machine-readable semantic representations, including storage, retrieval, comparison and downstream automated processing.


➤ Compression efficiency depends on the nature of the representation being processed.

➤ Structured and repetitive representations can prove especially efficient.

: What ParsAIble Compression™ Does

Given a supported machine-readable representation:

  1. analyses structural characteristics of the supplied representation;
  2. selects an appropriate deterministic compression mode;
  3. selects an appropriate deterministic compression mode;

    4. The resulting artifact is designed for repeated machine use without requiring conventional decompression first.
    hAIper™ is especially suited to work alongside ParsAIble for policy-driven selection and rapid retrieval.
➤ The output is designed to be repeatedly used by machines, or read by humans.
➤ hAIper Retrieval API is especially suited to work alongside ParsAIble for policy-driven selection and rapid retrieval.

: Basic Usage

Endpoint (click to copy)

POST /v1/compression

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)

As with all Maenen tools, 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:

  • Original payload size.
  • Compressed payload size.
  • Reduction ratio.
  • Whether output is deterministic.
  • Whether structure and intent were preserved.
  • Any warnings or constraints encountered.


This allows you to:

  • Audit results.
  • Log compression behaviour.
  • Compare runs.
  • Justify downstream decisions.
➤ 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.
  • Preservation metrics describe the integrity of the transformed representation according to the configured policy.
  • Token estimates are informational only and depend on the target model and configuration.
  • Independent baselines are recommended when measuring comparative savings.
  • Actual token usage depends on target model and config. Run independent baseline to confirm comparative savings.
  • Efficiency tiers are comparative rather than exact numerical guarantees.
    • "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

Users of the API can expect:


  • Use: POST https://api.maenen.ai/v1/compression as the documented entrypoint.
  • Auth via ``Authorization: Bearer ``
    •
  • 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.

: Determinism & Predictability

Maenen compression is designed to behave predictably.

  • Identical inputs under identical conditions produce identical outputs.
  • No hidden randomness.
  • Compression mode selection is governed by the characteristics of the supplied representation and configured policy.
The API is intended for infrastructure use rather than creative rewriting.

: What This Is / Is Not

To set expectations clearly:

  • ❌ Not a creative summariser.
  • ❌ Not a human-facing text shortening tool.
  • ❌ Not conventional archive compression.
  • ❌ Not a raw-text-to-embedding service.
ParsAIble is designed for systems that already work with machine-readable semantic representations and need those representations made more compact while remaining directly usable.

: Limits & Beta Notes

This API is currently in limited beta.

  • A 15-call rate limit per key applies during beta
  • A 2 MB maximum payload-size limit applies during beta
  • Behaviour may evolve as the service matures
  • No uptime or performance guarantees are implied
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. 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.31 (beta)

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