# A2A Examples

> mdapi.io - Minimal Data API I/O: a content transformation layer primitive for AI systems.
>
> Transforms files and webpages into AI-ready Markdown and structured data, optimized for LLM efficiency and token usage.

Every A2A method called with `curl`: sending a message, a file and structured data, reading and listing tasks, subscribing, cancelling, and what a stored task keeps.

#### SendMessage

```bash
curl -X POST https://mdapi.io/a2a   -H "Content-Type: application/a2a+json"   -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "SendMessage",
    "params": {
      "message": {
        "messageId": "msg-uuid-1",
        "parts": [
          { "text": "https://example.com" }
        ]
      }
    }
  }'
```

## SendMessage with file (data URI)

```bash
curl -X POST https://mdapi.io/a2a   -H "Content-Type: application/a2a+json"   -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "SendMessage",
    "params": {
      "message": {
        "messageId": "msg-uuid-2",
        "parts": [
          { "text": "{"input":"data:text/plain;base64,SGVsbG8gV29ybGQ="}" }
        ]
      }
    }
  }'
```

## SendMessage with structured data

```bash
curl -X POST https://mdapi.io/a2a   -H "Content-Type: application/a2a+json"   -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "SendMessage",
    "params": {
      "message": {
        "messageId": "msg-uuid-3",
        "parts": [
          {
            "data": {
              "input": "https://example.com",
              "result": "markdown"
            },
            "mediaType": "application/json"
          }
        ]
      }
    }
  }'
```

## Token activation via A2A

```bash
curl -X POST https://mdapi.io/a2a   -H "Content-Type: application/a2a+json"   -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "SendMessage",
    "params": {
      "message": {
        "messageId": "msg-uuid-7",
        "parts": [
          {
            "data": {
              "input": "https://example.com",
              "token": "YOUR_TOKEN",
              "memo": "YOUR_PAYMENT_MEMO"
            },
            "mediaType": "application/json"
          }
        ]
      }
    }
  }'
```

> **Note on token activation:** Pass `token` and `memo` inside a `data` Part or as JSON inside a `text` Part. A2A does not use HTTP-level Authorization headers.

## Multi-turn conversation (follow-up)

`contextId` is what makes a second call a follow-up rather than a new conversation. Send the one
`SendMessage` answered with, or send your own on the first call - a context id you chose is kept as it
is, so a group of callers can name the thread before any task exists and every later task joins it. The
same id is what `ListTasks` is scoped by.

```bash
curl -X POST https://mdapi.io/a2a   -H "Content-Type: application/a2a+json"   -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "SendMessage",
    "params": {
      "contextId": "ctx-uuid-1",
      "message": {
        "messageId": "msg-uuid-4",
        "parts": [
          {
            "text": "{"input":"https://example.com","prompt":"Convert the tables to JSON"}"
          }
        ]
      }
    }
  }'
```

## GetTask

Read one task by its id:

- `id` - The task id from `SendMessage`, `SendStreamingMessage` or `ListTasks`. A task is read by its id alone: the id is what grants access, so no other credential is asked for and none is kept with the task.
- `historyLength` - How much of the task's message history to return: not set - the stored history; `0` - the `history` field is left out; a positive number - at most that many most recent messages. A negative value is rejected as invalid params.
- `tenant` - Accepted only empty. The service is single-tenant, so a named tenant has no meaning here and a non-empty value is rejected as invalid params.

```bash
curl -X POST https://mdapi.io/a2a   -H "Content-Type: application/a2a+json"   -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "GetTask",
    "params": { "id": "task_12345" }
  }'
```

## ListTasks

List the tasks that belong to one conversation:

- `contextId` - The conversation to list - the `contextId` returned by `SendMessage`, or one the caller chose and sent with it: a `SendMessage` that carries its own `contextId` keeps it, so a swarm can name the thread before the first task exists and every later task joins it. A listing is always scoped to one context: tasks are not filed under an account, so the context is what says which tasks belong together. Without it the answer is an empty list, never the whole store.
- `pageSize` - How many tasks one page carries. Defaults to 50, minimum 1, maximum 100; a value outside that range is rejected as invalid params. The size actually used comes back as `pageSize`.
- `pageToken` - The cursor from the previous page's `nextPageToken`. Opaque - pass it back unchanged. Absent or empty starts at the first page.
- `status` - Return only tasks in this state (`TASK_STATE_WORKING`, `TASK_STATE_COMPLETED`, `TASK_STATE_FAILED`, `TASK_STATE_CANCELED`, `TASK_STATE_REJECTED`). Any other value is rejected as invalid params.
- `statusTimestampAfter` - Return only tasks whose status was updated after this ISO 8601 timestamp - the way to ask for what changed since the previous call.
- `historyLength` - How much of each task's message history to carry, with the same value semantics as in `GetTask`: a positive number - at most that many most recent messages; `0` - the `history` field is left out. A listing carries no history unless it is asked for, so the default (not set) leaves `history` out as well. A negative value is rejected as invalid params. Credentials are never part of a stored history, so nothing secret is returned by asking for it.
- `includeArtifacts` - Whether each task carries its artifacts. Defaults to `false` to keep a page small; unless it is `true` the `artifacts` field is left out of every task rather than returned empty.
- `tenant` - Accepted only empty. The service is single-tenant, so a named tenant has no meaning here and a non-empty value is rejected as invalid params instead of being answered with tasks that are not the caller's.

A page carries at most `pageSize` tasks, most recently updated first. The result names the page size
that was used and how many tasks the whole query matches:

- `tasks` - The page of tasks, most recent status first, carrying `artifacts` and `history` only as far as the request asked for them.
- `nextPageToken` - Cursor for the following page; empty means this was the last page.
- `pageSize` - The page size the service actually used - the requested value, or the default 50.
- `totalSize` - How many tasks match the whole query, before pagination.

Walk a whole conversation by passing `nextPageToken` back as `pageToken` until it comes back empty:

```bash
# First page
curl -X POST https://mdapi.io/a2a   -H "Content-Type: application/a2a+json"   -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "ListTasks",
    "params": { "contextId": "ctx_12345", "pageSize": 2 }
  }'

# Result: {"tasks":[{...},{...}],"nextPageToken":"eyJ0IjoiMjAyNi0wNi0yNlQxNjowMDowMC4wMDBaIiwiaSI6InRhc2tfMTIzNDUifQ","pageSize":2,"totalSize":5}

# Next page - the token is opaque, pass it back unchanged
curl -X POST https://mdapi.io/a2a   -H "Content-Type: application/a2a+json"   -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "ListTasks",
    "params": { "contextId": "ctx_12345", "pageSize": 2, "pageToken": "eyJ0IjoiMjAyNi0wNi0yNlQxNjowMDowMC4wMDBaIiwiaSI6InRhc2tfMTIzNDUifQ" }
  }'
```

**Reading a task is what returns its content.** A listing is an inventory: it carries no history unless
`historyLength` asks for it, and no artifacts unless `includeArtifacts` is `true`, so one call over a
long conversation stays small. The result of a conversion is read with `GetTask`, one task
per call.

**Task records are bounded and temporary.** A record keeps the caller's message parts up to
65536 characters each - a file part keeps its `mediaType` but not its bytes -
and credentials (`token`, `memo`) are never written into a task. A record has a size ceiling, and what
does not fit is left out in a fixed order, with the record saying which of the two happened. The caller's
own message goes first, since they still hold it, and then the tail of the result: what stays is the
beginning of it, marked `metadata.contentTruncated: true`, so a large result is still readable in part
rather than missing. The response to `SendMessage` is never affected - it always carries the whole
result. `metadata.contentStored: false` is the stronger statement, and it means the result is not in the
record at all. A task that has finished stays readable for about
5 minutes and a task still running for up to
60 minutes, after which `GetTask` answers `-32001`.

## Links

- **About service:** https://mdapi.io/about
- **Privacy:** https://mdapi.io/privacy
- **Contact:** https://mdapi.io/contact
- **Agent entry point:** https://mdapi.io/AGENTS.md or https://mdapi.io/agents.md or https://mdapi.io/agent.md
- **Agent access:** https://mdapi.io/auth.md
- **API documentation and conversion:** https://mdapi.io
- **MCP server manifest:** https://mdapi.io/mcp
- **Health check:** https://mdapi.io/health
- **Documentation index:** https://mdapi.io/llms.txt
- **Full API documentation:** https://mdapi.io/llms-full.txt
- **AI discovery:** https://mdapi.io/.well-known/ai-discovery.json or https://mdapi.io/ai-discovery.json
- **AI Agent discovery:** https://mdapi.io/.well-known/agent.json or https://mdapi.io/agent.json
- **A2A Agent card:** https://mdapi.io/.well-known/agent-card.json or https://mdapi.io/agent-card.json
- **ACP manifest:** https://mdapi.io/.well-known/acp.json or https://mdapi.io/acp.json
- **x402 payment manifest:** https://mdapi.io/.well-known/x402.json or https://mdapi.io/x402.json or https://mdapi.io/.well-known/x402
- **OpenAPI specification (JSON):** https://mdapi.io/.well-known/openapi.json or https://mdapi.io/openapi.json
- **OpenAPI specification (YAML):** https://mdapi.io/.well-known/openapi.yaml or https://mdapi.io/openapi.yaml
- **MAPI specification:** https://mdapi.io/.well-known/mapi.md or https://mdapi.io/mapi.md
- **Skill specification:** https://mdapi.io/.well-known/skill.md or https://mdapi.io/skill.md
- **ARD manifest:** https://mdapi.io/.well-known/ard.json or https://mdapi.io/.well-known/ai-catalog.json or https://mdapi.io/ard.json
- **Agent Plugins manifest:** https://mdapi.io/.well-known/plugin/plugin.json or https://mdapi.io/.well-known/plugin.json
- **Agent Plugins MCP config:** https://mdapi.io/.well-known/plugin/mcp.json
- **Agent Plugins conversion skill:** https://mdapi.io/.well-known/plugin/skills/mdapi-conversion/SKILL.md
- **API documentation pages:** https://mdapi.io/docs
- **Example pages:** https://mdapi.io/docs/examples

## External Links

- **github.com** https://github.com/mdapiio/mdapi.io
- **skills.sh** https://www.skills.sh/mdapiio/mdapi.io
- **skillsmp.com** https://skillsmp.com/creators/mdapiio/mdapi.io
- **clawhub.ai** https://clawhub.ai/mdapiio
- **x.com** https://x.com/mdapiio

## Disclaimer

**The service is provided "AS IS".**


> mdapi.io is an edge-native service-transport primitive for AI, autonomous agents, and the Web4 ecosystem.
