Convert from AsyncAPI - Markdown API (MAPI)

When to use this

AsyncAPI is the specification for event-driven architectures—WebSocket connections, message queues, SSE streams. If your API pushes data to clients or uses bidirectional communication, you probably have (or should have) an AsyncAPI spec.

MAPI supports these patterns natively with:

WS /path transport for WebSocket endpoints
HTTP POST /path (SSE) for Server-Sent Events
~~~events blocks to define message types
Separate ### Client Messages and ### Server Messages sections

LLM-assisted conversion

Attach your AsyncAPI spec and the conversion reference card:

AsyncAPI to MAPI Reference Card

Raw markdown for LLM consumption — event mappings and transport patterns

Fetch this page: https://markdownapi.org/specs/ASYNCAPI-TO-MAPI.md

Or paste this prompt directly into your LLM chat

You

Convert this AsyncAPI spec to MAPI. Map channels to capabilities and write clear Intentions for when to use each one.

ASYNCAPI-TO-MAPI.md

asyncapi.yaml

Claude

I'll convert your AsyncAPI spec to MAPI, mapping WebSocket channels to capabilities...

## Capability: Real-time Updates

[Converts publish/subscribe to Client/Server messages with TypeScript types...]

Key mappings

The reference card has complete details, but the key translations are:

Channels become Capabilities — each channel is one capability
Protocol determines transport — ws → WS /path, http with SSE → HTTP POST /path (SSE)
Subscribe operations become Server Messages — what the server sends to clients
Publish operations become Client Messages — what clients send to the server
Message payloads go in ~~~events blocks with TypeScript types

Event ordering

AsyncAPI's oneOf for multiple message types becomes a MAPI events block. List events in the order they typically occur in a session—this helps both humans and LLMs understand the flow.

Example output

Here's what a WebSocket capability looks like in MAPI:

## Capability: Real-time Updates

~~~meta
id: updates.stream
transport: WS /ws/updates
auth: connection
~~~

### Intention

Subscribe to real-time updates for a user's activity feed. Use this when you
need push notifications for new events rather than polling. The connection
stays open indefinitely; send heartbeats every 30 seconds to keep it alive.

### Client Messages

```typescript
type ClientMessage =
  | { type: 'subscribe'; topics: string[] }
  | { type: 'unsubscribe'; topics: string[] }
  | { type: 'heartbeat' };
```

### Server Messages

```typescript
type ServerMessage =
  | { type: 'event'; topic: string; payload: unknown; timestamp: string }
  | { type: 'subscribed'; topics: string[] }
  | { type: 'error'; code: number; message: string };
```

Next steps

Have an LLM write a spec Validate your spec Also convert REST endpoints