# Free tier and paid tier

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

What each tier runs, how the free allowance is counted, what a paid stage answers without a token, and what a conversion is allowed to keep.

Two tiers, one core. The free testing tier needs no credential and runs everything that is native - every format that has a native reader, every protocol, and every parameter that asks no model for an answer - within a daily allowance of 10 conversions for one caller, out of a quota allocated for the whole service, so the full allowance is not guaranteed. The paid tier is opened by a token carrying a prepaid balance (or by an x402 payment that mints one): it adds the stages that cost a model call - `prompt`, `schema` and `ocr` (the reading of a picture, whether the source is a picture, the picture sits inside a document, or the document's pages are pictures) - and the render of a page whose text is assembled in the browser. The free tier does not run them: a page whose text is assembled in the browser is converted from the markup as it arrived and the answer says so, and a picture is answered with the payment terms. Every conversion is charged from that balance, with no daily allowance. A paid stage the answer would use is never skipped silently: on the free tier the answer is `402` with the payment terms and the free route for the same input, and nothing is charged.

| Aspect             | Free testing tier                         | Paid tier                                                                                                |
| ------------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Credential         | None                                      | A token with a prepaid balance                                                                           |
| Charge             | None: a daily free allowance              | min $0.01 per conversion (USDC via x402); a wider `capacity` step is charged the price of its own window |
| `prompt`, `schema` | Refused with the payment terms            | Answered (model answer over the document)                                                                |
| `ocr`              | Refused with the payment terms            | Answered (paid vision pass)                                                                              |
| Cache and address  | A one-day default entry, never extended   | Only a named `ttl`; otherwise nothing is kept, no address                                                |
| Everything else    | Same core, protocols, formats, parameters | The same                                                                                                 |

## The free allowance

- `free_remaining` / `X-MDAPI-Free-Remaining` - How many free conversions are left to this caller today, counted after the one being answered. The free tier carries 10 conversions a day to a caller, within a quota allocated for the whole service, so the full allowance is not guaranteed
- `free_reset` / `X-MDAPI-Free-Reset` - Unix timestamp when the free allowance is restored: the start of the next day (UTC)

The counters travel as `X-MDAPI-Free-Remaining` and `X-MDAPI-Free-Reset` headers on every protocol, and beside them as `free_remaining` and `free_reset` where the answer has a JSON body (POST /, MCP, OpenAI) - so a client reading either one knows where it stands. They are absent on a request answered by a paid token, which is not drawn from the free allowance. A request the service refuses - an invalid parameter, an unsupported format, a document over the input gate - does not consume it. That allowance sits inside a quota allocated for the whole service, so a caller may find fewer conversions left than a full day's allowance.

## A paid stage asked for without a token

Each stage that costs a model call answers for itself, naming the payment terms and the free route for the same input. Nothing is charged for that answer:

- A `prompt` or `schema` request runs a model answer over the document: it is answered on the paid tier only. Conversion without `prompt` or `schema` runs on the free tier: resend with `result=markdown` (the default) and the document comes back as Markdown.
- A picture is read by a model - the `ocr` pass over the images of a document, and a source that is itself a picture - and that reading is answered on the paid tier only. The free tier converts every format that has a native reader - documents, office files, archives, data and text - and reads no picture: resend without `ocr`, or with a source that is not a picture, and the same input is free.
- A page whose text is assembled in the browser is rendered on the paid tier only. The free tier still converts the same input, as the markup arrived, and the answer carries a content warning saying the page needs a browser.

## What a conversion costs

The quoted figure is the minimum: it buys the floor `capacity` step. A wider step is charged the price of its own window, so a request that asks for `max` costs more than one that takes the default, and the charge follows the step actually served. A balance below the minimum answers `402` until it is topped up.

`capacity` is the window of one model call, symmetric in input and output tokens. It bounds both sides - what is sent to the model and how long its answer may be - and it never cuts the document markdown the caller receives.

## A window wider than one call

A window wider than one call is delivered in parts. The first answer carries `job`: `{id, parts, partTokens, type, expiresAt}` - it charges the window as usual, delivers part 0, and stays `200`; the remaining parts are read at `GET /result/<id>` (the manifest: `parts`, `partTokens`, `type`, `expiresAt`, `chargedUsdc`, `inputRequired`) and `GET /result/<id>?part=k` (exactly the text of part k - no envelope, no index; every other fact lives in the manifest). Each part request makes one model call and spends no balance: the job, not the balance, is what the window was paid with. A part is reproducible while the document it was cut from is held by the cache; a job whose input is not held answers `inputRequired: true` in its manifest, and the part request then brings the input along. A part that can no longer be reproduced answers `410` (`result_input_gone`) with the reason. A foreign or unknown id answers `404` - existence is never confirmed; an index outside the job answers `400`. The parts of a job concatenate in order (a blank line between parts) into the whole answer the window bought; `result=both` has no meaning for a job and names itself when asked - the full string never exists in one piece.

## The token is an account

A memo payment issued for a token the caller already holds adds to its balance instead of minting a second token: the whole amount received is credited, and a fresh year starts from the moment the payment lands. A token that has lapsed keeps its balance and is revived by the same payment.

A token carries a prepaid balance and is charged per conversion, with no daily allowance.

## What a conversion is allowed to keep

The cache is opened by asking for it. A named `ttl` is the caller's own lease: the converted markdown is kept for that lifetime, honored as named up to the one-year ceiling on the paid tier and up to one day (86400 seconds) on the free testing tier; an identical request inside the window is answered without re-converting it, and reuse never extends it. Without `ttl` a paid request stores nothing at all - the document is converted, the answer returned, and no copy is kept, so a paying caller is never the reason something is held. The free testing tier keeps a one-day entry instead (the documentation examples the same), and a repeat neither extends nor shortens it: everything that tier holds lives at most a day, because that tier is meant for testing, not for production documents. `ttl=0` stores nothing. Reading a resource address is asking to read, and needs no `ttl`. A request that carries a `password` is never cached: it neither reads a stored conversion nor stores one, so a document that was unlocked with a secret is never handed to a caller who did not name the same secret.

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