:: WaveForm Semantic Transport API Documentation

HOME MEANINGSYSTEM
KEYS 🤖


: WaveForm semantic normalisation & transport across AI models (docs)

WaveForm™ [WaveInform / WaveReturn / WaveTransform] prepares and verifies semantic representations as they move through AI workflows. It provides deterministic boundary handling designed to stabilise meaning without silently rewriting intent, and to measure continuity as representations change between systems.


WaveForm operates on machine-readable semantic representations; source extraction or embedding generation may occur upstream. Each boundary direction uses its own endpoint:

➤ WaveReturn™ verifies continuity after transformation / LLM return. It does not simply reverse the preparation step. Instead, it confirms the boundary integrity before downstream processing continues.

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

: What WaveForm Provides

  • Deterministic preparation across representation boundaries.
  • Reduced downstream variance.
  • Stable input preparation for multi-step pipelines.
  • Reusable transformation artifacts.

WaveForm does not generate content. It operates within the scope of the semantic representation provided. It is suited to agent chains, multi-model routing, and preparation for downstream processing or ParsAIble Compression.

: Design Principle

WaveInform and WaveReturn are distinct boundary operations within the same protocol.

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


Note:

➤ The WaveInform version does not require a WaveReturn call
— it is not mandatory to use both endpoints when using WaveInform.

➤ WaveReturn does, however, require the prior WaveInform call due to how it works.

— it is not simply the reverse of WaveInform. So if you only need boundary preparation for downstream AI processing, one WaveInform call is sufficient.


WaveReturn is recommended when:

  • Crossing transport boundaries.
  • Verifying post-hop continuity.
  • Preparing supported representations for ParsAIble compression.
  • Returning to a relay or pipeline stage.


Architecturally, the API calls like this:

➤   prepare → ../INFORM = X. One boundary crossed = One call.
➤   + verify → ../RETURN = Y. Two boundaries crossed = Two calls.
➤   If using the dual endpoint WaveTransform version → .../TRANSFORM = X+Y (= a discounted bundle of two boundary calls).

: Typical Use Cases

WaveForm 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 Practices

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 on a controlled input
  • Integrate it at the start or relay nodes of your pipeline

For production access, see the [ main API access page ].

: Basic Usage

➤ WaveInform, WaveReturn, or the bundled WaveTransform combination are accessed via their dedicated POST endpoints.

➤ WaveReturn accepts a chain reference and output hash, and verifies continuity.

➤ Respectively, the ACCEPT input and RETURN output use normalised, transport-ready representations for reuse and downstream processing.


3x Endpoints (click to copy)

POST /v1/waveform_2/inform
Outbound boundary preparation (heavy transform)
Emits: receipt (wave_prepare)
POST /v1/waveform_2/return
Lightweight boundary verification
Emits: receipt (wave_verify)
POST /v1/waveform_2/transform
Convenience bundled endpoint (combined /inform → /return operations internally)

Request Headers

Authorization API key using Bearer format
Accept application/json

: The WaveInform API

Endpoint

POST /v1/waveform_2/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"

: The WaveReturn API

Endpoint

POST /v1/waveform_2/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

WaveForm 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

WaveForm 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

The WaveForm version 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

WaveForm [WaveInform / WaveReturn / WaveTransform] 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, use the contact options below. 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
  • Example payloads (if possible)
  • The receipt from the relevant request
- Receipts significantly reduce back-and-forth and speed up diagnosis.


: v0.1 Beta Usage Notice

This API is currently available in limited public beta. Free assessment keys are subject to rate cap and payload limits.
No uptime or performance guarantees are implied. Features and behaviour may change between versions.


: Versioning

This documentation applies to:


API version: v0.1 (beta)

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