Maenen Labs WaveInform™ / WaveReturn™ — API Documentation: Semantic Normalisation & Transport API

:: WaveInform™ / WaveReturn™ — API Documentation

: Orientation

Faces of the same service:

➤ WaveInform™ prepares structured or unstructured inputs for safe LLM ingest and multi-step AI workflows. It performs deterministic boundary preparation — stabilising inputs without interpreting or modifying their intent.

➤ WaveReturn™ is called via its own endpoint. It verifies continuity after transformation or LLM return. It does not reverse-translate. Instead, it confirms boundary integrity before downstream processing continues.

➤ WaveTransform™ provides both services in one via a convenience endpoint.

The API is optimised for agent chains, multi-model routing, and parsable compression. Its operate strictly within the scope of the input you provide.

: What WaveInform Is

WaveInform provides:

Deterministic boundary preparation across model environments
Reduced downstream variance
Stable input preparation for multi-step pipelines
Reusable transformation artifacts

WaveInform does not generate content. It prepares content for reliable downstream use..

: Design Principle

WaveInform and WaveReturn are distinct mutation boundaries.

Each emits its own deterministic Receipt v1.0 envelope.
Verification does not recompute transformation.
Integrity is enforced through chain continuity and hash validation.

Note:

➤ WaveReturn requires a prior WaveInform call
➤ It is not mandatory to use both endpoints.

If you only need boundary preparation for LLM ingestion and to remain within that domain, one call to WaveInform is sufficient.

WaveReturn is recommended when:

Crossing transport boundaries
Verifying post-hop continuity
Preparing artifacts for parsable compression
Returning to a relay or pipeline stage

Architecturally:

➤ prepare → X. One boundary crossed = One call
➤ + verify → Y. Two boundaries crossed = Two calls
➤ If using the dual endpoint → transform = X + Y = Two call bundle_discount.

: Typical Use Cases

WaveInform is suited for workflows where meaning must remain stable across steps, such as:

Agent chains and swarms
Long or multi-stage pipelines
Cross-model or cross-vendor routing
Compliance-sensitive or high-stakes inputs
Reusable prompts, instructions, or policies

: Best Practice

Use WaveInform at the start of multi-step workflows
Cache normalised outputs for reuse
Store your receipts when auditability matters
Treat normalised outputs as immutable inputs to downstream stages
Pair with WaveReturn for cross-hop integrity

: Getting Started

Review the request / response schema
Try the demo on a controlled input
Integrate into the start or relays nodes of your pipeline

For production access, see the main API access page.

: Basic Usage

➤ WaveInForm and WaveReturn or the bundled Transform combination are accessed via dedicated POST endpoints.
➤ WaveReturn accepts a chain reference and output hash, and verifies continuity.
➤ Respectively the ACCEPT semantic input payloads, and RETURN a normalised transport-safe representation for reuse / downstream processing.

3x Endpoints (overview)

POST /v1/maenen/waveform/inform

Outbound boundary preparation (heavy transform)
Emits: Receipt v1.0 (wave_prepare)

POST /v1/maenen/waveform/return

Lightweight boundary verification
Emits: Receipt v1.0 (wave_verify)

POST /v1/maenen/waveform/transform

Convenience endpoint (inform → return internally)

Request Headers

Header	Description
`Authorization`	`API key using Bearer format`
`Accept`	`application/json`

: WaveInform API

Endpoint

POST /v1/maenen/waveform/inform

Request JSON (example)


{

 "chain_id": "acct_123.session_456",

 "waveform": {

  "payload": "example text",

  "metadata": {

    "mime_type": "text/plain"

  }

 }

}

Response JSON




{

 "wave_packet": {

  "output_hash": "sha256(...)",

  "encoded_payload": "...",

  "boundary_version": "v1"

 },

 "legacy_receipt": { ... },

 "receipt_v1": { ... }

}



receipt_v1.action.action_type = "wave_prepare"

: WaveReturn API

Endpoint

POST /v1/maenen/waveform/return

Request JSON (example)


{

 "chain_id": "acct_123.session_456",

 "output_hash": "sha256(...)"

}

Response JSON


{

 "verification": {

  "status": "verified",

  "match": true,

  "verified_against_receipt_id": "rct_20260215_ab12cd34"

 },

 "receipt_v1": { ... }

}

receipt_v1.action.action_type = "wave_verify"

: Response (success)

➤ A successful response returns a normalised semantic payload along with optional receipt metadata.

Endpoint

{

 "output": {

  "normalised": "…"

 },

 "receipt": {

  "status": "verified"

 }

}

output.normalised field is designed to be:

reusable
deterministic
safe to cache
suitable for downstream APIs

: The Receipt

➤ WaveInform can return a receipt object that documents the outcome of the normalisation step.

Receipt Fields (High-Level)

Field	Description
`status`	Verification result
`determinism`	Deterministic outcome indicator
`scope`	Processing boundary classification
`warnings`	Optional non-fatal notices
`receipt_id`	Unique receipt identifier

Example (redacted)


{
 "receipt": {

  "status": "verified",

  "determinism": "stable",

  "scope": "bounded",

  "warnings": [],

  "receipt_id": "wrf_…"

 }

}

Receipts are designed for:

audit & compliance
pipeline debugging
post-hoc analysis

: Error Model

Code	HTTP	Meaning
`missing_dependency`	`400`	No prior wave_prepare receipt found
`invalid_sequence`	`400`	Previous receipt is not wave_prepare
`hash_mismatch`	`400`	output_hash does not match
`validation_error`	`400`	Invalid request schema
`append_conflict`	`409`	append_conflict
`internal_error`	`500`	Unexpected server error

: Failure Response Examples

➤ WaveInform uses explicit, bounded error responses. Failures never return partial or ambiguous output.

❌ Invalid Request


{
 "error": {

  "code": "invalid_request",

  "message": "Malformed or unsupported input payload"

 }

}

❌ Input Exceeds Limits


{
 "error": {

  "code": "input_limit_exceeded",

  "message": "Input size exceeds allowed limits"

 }

}

❌ Verification Failed


{
 "error": {

  "code": "verification_failed",

  "message": "Semantic normalisation could not be verified"

 }

}

❌ Authentication Error


{
 "error": {

  "code": "unauthorized",

  "message": "Invalid or missing API key"

 }

}

: Limits & Guardrails

WaveInform enforces strict boundaries to ensure predictable behaviour.

Input Limits

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

Processing Guardrails

Bounded semantic scope
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

WaveInform / WaveReturn is designed with minimal data exposure.

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

Receipts may be safely stored by the client for audit or compliance purposes. For full details, see the Maenen privacy policy.

: Capability Scoping

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

403 capability_not_permitted

Some capabilities may instead return payment or quota challenges depending on key tier.

: 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 surface: v0.1 (beta)

Receipt schema: v1.0 (stable)

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