# Response metadata

The facts an answer carries in its headers: the service that replied, the document validators and the integrity field.

Some facts about an answer are not in its body: what service replied, whether a stored copy of a document is still current, whether the bytes are the ones that were sent. They ride in the response headers, and every one of them is readable by any client - the self-describing fields are on every answer, the validators and the integrity field on the published documents.

| Header                                                                                                            | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-MDAPI-Service`, `X-MDAPI-Version`, `X-MDAPI-AI-Discovery`, `X-MDAPI-Skill`, `X-MDAPI-MCP`, `X-MDAPI-Protocols` | Every response identifies the service that answered and points at its discovery layer: `mdapi.io` for `X-MDAPI-Service`, `1.0.0` for `X-MDAPI-Version`, `/.well-known/ai-discovery.json` for `X-MDAPI-AI-Discovery`, `/.well-known/skill.md` for `X-MDAPI-Skill`, `/mcp` for `X-MDAPI-MCP`, `rest,mcp,acp,a2a,openai` for `X-MDAPI-Protocols`. A consumer that has never read a discovery file can name the service and reach its hub from any answer.                                                                                                         |
| `ETag` / `If-None-Match`                                                                                          | A validator on the published documents - the canonical path, no query string, `GET` or `HEAD`, status `200`. Send the tag back as `If-None-Match` and an unchanged document is answered `304` with no body. The tag is the digest of exactly the bytes served, so it never matches a different representation of the same address.                                                                                                                                                                                                                             |
| `Repr-Digest` / `Want-Repr-Digest`                                                                                | The integrity field of the same published documents (RFC 9530), `sha-256=:<base64>:` over the same bytes the entity tag covers. It answers a different question than `ETag`: the tag asks whether a stored copy is still current, the digest whether the bytes are the ones the service sent - so a consumer that kept a body can verify it later, without a second request. Sent on every published document, whether the body was built now or reused, so the value is the same either way; `Want-Repr-Digest` is accepted and the field is sent regardless. |
| `Cache-Control`                                                                                                   | The static discovery and manifest documents are reusable for public, max-age=3600, s-maxage=3600, so resolving a service to its documents need not reach the worker every time.                                                                                                                                                                                                                                                                                                                                                                                |
| `Retry-After`                                                                                                     | How long to wait before asking again, on a throttled answer and on an AI provider failure. It is the service's own estimate, so a caller that waits it out does not have to guess a backoff.                                                                                                                                                                                                                                                                                                                                                                   |

## Links

- **About service:** https://mdapi.io/about
- **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
- **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
- **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

## 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.