# OpenAI-compatible endpoints

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

The `/v1/chat/completions` and `/v1/responses` endpoints: what a message may carry, the full request schema with every core parameter, and when custom instructions trigger a paid stage.

`/v1/chat/completions` and `/v1/responses` are the OpenAI-compatible face of the same conversion core, so a client written against the OpenAI API converts a document without a special case. Both read the source from the message and the credential from the request, and both answer beside the core's own products rather than instead of them.

## Chat completions

The `/v1/chat/completions` endpoint provides an OpenAI-compatible API for markdown conversion with streaming support.

**Supported features:**
- URL extraction from message content (any text containing https?://)
- image_url in messages (OpenAI format) - supports HTTP URLs and data URLs
- file in messages (OpenAI format) - base64 encoded files (field `file.data`, optional `file.mimeType`; built into a `data:` URI for the core - no `file.filename` required or used)
- Direct text content in messages (any text without a URL is sent to the core as the `input` source and converted to Markdown)
- Token and memo via headers (recommended for POST)
- Streaming SSE responses (`stream: true`)
- Custom instructions with LLM processing (system messages, or user messages containing instruction keywords such as *extract, summarize, analyze, format, convert to, write as, create, generate, json* → LLM-driven summary/extraction/transformation)
- `prompt` for LLM-processed output. The response surfaces `prompt_result` at the top level alongside the standard `choices[].message.content` (which carries `prompt_result` when prompt is set, otherwise the Markdown).

`model` is accepted but not required (any string; the service uses its own conversion pipeline, not a remote LLM chat model, unless custom instructions trigger LLM processing).

> **Content via message text:** the message text is passed to the core as the `input` parameter - the same unified source as every other protocol. URLs are auto-detected, data URIs are decoded as files, and plain text is processed directly.
> See [Source Parameters (all protocols)](https://mdapi.io/#source-parameters-all-protocols).

## Request Schema

```json
{
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "description": "Optional model identifier (any string accepted; not required)"
    },
    "messages": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {"type": "string", "enum": ["user", "system", "assistant"]},
          "content": {"oneOf": [{"type": "string"}, {"type": "array"}]}
        }
      },
      "description": "Chat messages. URL in content, image_url or file in content for input"
    },
    "stream": {
      "type": "boolean",
      "default": false,
      "description": "Enable streaming SSE responses"
    },
    "prompt": {
      "type": "string",
      "description": "Custom instructions for LLM processing (alternative to instruction keywords in messages)"
    },
    "result": {
      "type": "string",
      "enum": ["markdown","prompt","both","meta"],
      "description": "Response format when using prompt. `meta` answers with the index alone - parts, sizes, metadata - and no content"
    },
    "part": {
      "type": "string",
      "description": "Serves the parts of a document instead of the whole answer, so a one-page request of a 500-page document sends one page to the model and returns one page. The unit is the document's natural boundary - page (PDF), slide (presentations), sheet (spreadsheets), chapter (EPUB and archives, an expanded `.tar.zst` included) - or one A4 sheet of text for formats without one; the units table says which format owns which. Every response self-describes the range in `parts` (JSON body) and `X-MDAPI-Parts` / `X-MDAPI-Part-Unit` (headers), so the count never has to be guessed. `part` also decides how a resource larger than the input gate is read - see the addressability table."
    },
    "find": {
      "type": "string",
      "description": "Searches the converted document and answers with the ADDRESSES of the matches - the part number and the character offset inside that part - never the text itself, so a search costs one request instead of reading the document. Case is ignored, the match is literal, and matches do not overlap. Whitespace separates terms (`find=pay court`, percent-encoded in a URL as `find=pay%20court` or `find=pay+court`), and every term must occur in the same part, in any order, so the answer says where they meet; one term answers with every occurrence, as it always has. The needle is bounded: a string longer than 256 characters, or carrying more than 8 distinct terms, is refused by name rather than answered with no matches. Composes with `part`: without it the whole document is searched, with it only the parts named (and each hit still carries its own part number). A needle that does not occur is an honest empty answer (`matches: 0`) - with several terms `terms[]` says which one is nowhere - and `truncated: true` marks an answer that is not the whole set of matches: the hit ceiling was reached, or the document itself was cut while it was built. Read what you found with `part=N`. Where the source carries layout, a hit also carries `boxes`: the page and the text-space box of the line it lies in (`page`, `x`, `y`, `w`, `h`, origin at the bottom-left of the page), read from the reader's own glyph positions rather than computed - a source with no layout, or an answer served from a stored conversion, keeps the field absent. A `find` is a conversion - it converts what it searches - so it costs and consumes exactly what the same request without `find` would."
    },
    "select": {
      "type": "string",
      "description": "Converts the part of the document the selector names, so a page's navigation, banners and footer never reach the answer. The grammar follows the container, because a subtree is named by what it holds: an HTML or XML document holds elements, a JSON document holds keys. On HTML and XML the selector is deliberately a subset of CSS selectors rather than a CSS engine - a tag (`article`), a class (`.content`), an id (`#main`), those combined on one element (`article.content`), a descendant chain (`main article`) and a list separated by commas - matched by local name, so `item` names `atom:item` in a namespaced document; anything outside that grammar is refused with its own name instead of being ignored. On JSON the same parameter is a key path - a key (`items`), a chain of keys (`data.items`), an index (`items[0]`) or `[*]` for every member of an array or object (`items[*].title`) - and the selected subtree is returned as JSON; the dotted spelling (`items.0`, `items.*`) reads the same way and shares the same cache entry. A selector valid in both readings is kept in both and resolved by the input format at conversion time. What to keep is the caller's choice, so the service never scores or guesses the main content, and a selector that does not help is refused by name rather than answered with an empty body: the `400` says which it is - the selector names nothing in this document, or it names an element that carries no text - and always repeats the selector. A selector of one grammar on a document of the other is refused by name too, with the format and the applicable grammar stated. Other formats are refused with the format named rather than converted whole. The document's title and description still head the answer when it has them. `part` and `find` then describe the selection, not the document: the part numbering and the search run over the subtree the selector named. The selection is part of the cache key, because a selected document and the whole document are two different answers. It travels as `?select=` on REST GET and as the body field `select` on REST POST and OpenAI, and through the same argument slot on MCP, ACP and A2A. A SafeTensors weight file holds a table of tensors, so there `select` takes a tensor name: the exact name (`model.embed_tokens.weight`), a `*` pattern, or an unqualified tail (`weight`) when exactly one tensor carries it - a name that matches more than one tensor is refused with the candidates instead of resolved by picking one. The answer is that tensor's values as a table, in the dtype the file stores them, bounded to 256 rows by 64 columns; the window is stated in the answer together with the size of what it leaves out, so a large tensor is a named cut and never a silent truncation. A tensor whose header and data disagree, or whose dtype this reader does not decode, is refused by name rather than printed as numbers it does not hold."
    },
    "schema": {
      "type": "object",
      "description": "Imposes the shape of the answer: the paid LLM stage answers with JSON conforming to this schema, and the answer carries it parsed in `json` beside `prompt_result` - on every protocol, since the parsed value travels with the conversion, not with one endpoint. Each protocol takes it in its own place: the request body field on REST POST and OpenAI, `?schema=` on REST GET, MCP `arguments.schema`, ACP `params.schema`, A2A `data.schema` in a message part, and on OpenAI the native `response_format.json_schema.schema` as well - the OpenAI spelling of this same parameter, so a generic OpenAI client needs no special case. Providing it without `result` implies `result=prompt`; providing it without `prompt` leaves the schema itself as the task, because its property names and descriptions say what to extract. It travels the same way on both REST methods - a JSON object in the request body on POST, the same JSON object percent-encoded in `?schema=` on GET - and gets the same checks, the same answer and the same cache entry either way, because the key names the schema itself, not the spelling that carried it. A GET answers markdown by default and answers the JSON body instead when the caller asks for it with `Accept: application/json`; a markdown body cannot carry the verdict, so a GET also reports it in `X-MDAPI-Json-Conforms` and, when the answer did not conform, `X-MDAPI-Json-Error`. It contradicts nothing silently: `result=markdown` and `stream` are refused with the reason, a keyword the service cannot honor is refused with its name instead of being ignored, and an answer that still does not conform after one repair attempt comes back whole with `jsonConforms: false` and `jsonError` naming the first violation, because the answer is knowledge and is never thrown away. Asking for JSON in words keeps working exactly as before: a `prompt` that mentions JSON is answered as JSON with no schema needed."
    },
    "json": {
      "type": "boolean",
      "description": "Asks the paid stage to answer with a JSON value instead of prose. It is an input of the core, not a feature of one endpoint: it travels as the request body field `json` on REST POST and OpenAI, as `?json=true` on REST GET, as `arguments.json` on MCP, `params.json` on ACP and `data.json` in an A2A message part, and on OpenAI the native `response_format: {\"type\": \"json_object\"}` is the same request in that protocol's spelling, so a generic OpenAI client needs no special case. It changes the shape of the answer, never what is read from the document, and it needs an answer to shape: without `prompt` and without `schema` it asks for nothing and changes nothing, and a request that carries a `prompt` with `result=markdown` is refused instead of silently ignored. `schema` is the stricter request and already implies it. Asking in words keeps working exactly as before - a `prompt` that mentions JSON is answered as JSON with no flag. Because a JSON answer and a prose answer to one prompt are two different answers, the flag is part of the result cache key when it is on; when it is off the key is unchanged."
    },
    "password": {
      "type": "string",
      "description": "Opens a locked payload: the password of an encrypted archive, document or container. It is a credential, so it never travels in the query string - send it in the request body field `password` or in the `X-MDAPI-Content-Password` header, and a `?password=...` is refused with `400` before the URL is fetched. 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. Two codes say which way it went: `password_required` (the payload is locked and no password came) and `wrong_password` (a password came and did not open it)."
    },
    "response_format": {
      "type": "object",
      "description": "The OpenAI spelling of `json` and `schema`: `{"type": "json_object"}` asks for a JSON answer, and `{"type": "json_schema", "json_schema": {"name": ..., "schema": {...}}}` carries the schema. Both are the same request as the body fields above, so a generic OpenAI client needs no special case."
    },
    "capacity": {
      "type": "string",
      "enum": ["low","medium","high","max"],
      "description": "Working window of the paid LLM stage, symmetric in input and output tokens: `low` (the smallest window, the one the minimum price buys, and the default), `medium`, `high`, or `max` - the whole selected input. Each step is charged the price of its own window and bounds both sides of one model call - what is sent to the model and how long its answer may be. The document markdown a caller receives is never cut."
    },
    "ttl": {
      "type": "integer",
      "description": "How long the converted markdown may be reused. Reuse is the caller's to ask for: without `ttl` a paid request keeps nothing, the free testing tier keeps a one-day entry and never holds anything longer than that, and `ttl=0` stores nothing. A named `ttl` is also the consent to store what `attachments` delivers - the images then travel as temporary `GET /att/{id}` links with this lifetime instead of inline data URIs, under the same ceiling."
    },
    "attachments": {
      "type": "string",
      "description": "Delivers the resource's embedded images where the format carries them (office documents, PDF, EPUB, HTML/RTF, legacy DOC/XLS/PPT), inline as data URIs by default and as `GET /att/{id}` links when `ttl` is set. `all` is the explicit word for every image the answer's markdown names; a selection is a list or range of image ids, ordered by the document (`16,1` = `1,16`), and an id outside the answer is an honest error that names the real count. Each entry carries the image's name, type and size, plus its pixel size, source position and the part it stands in when those are known - enough to decide which image is worth fetching or looking at. The index describes the answer, never the document: only the images whose placeholder stands in the markdown being returned are listed, and only those are resolved - so `part=35` over a 500-page report lists and encodes the pictures of page 35 and leaves the other 199 alone. Without `part` the answer is the whole document and the index is the whole inventory. `find` and `result=meta` answer with the index and no bytes at all: they name which part each image sits in, and `part=N&attachments=all` then brings the bytes of the one worth having."
    },
    "ocr": {
      "type": "string",
      "description": "The paid vision pass over the pictures the answer carries: each selected image is read as its own conversion and the recognized text is printed in the markdown under its `img-N` placeholder. A document whose pages are pictures and carry no text layer - a scanned PDF - is read the same way, one pass per page, and the text is printed as `### Page N`. The pass is bounded by the answer, not by the document: with `part` only that part's pictures are read, with `select` only those inside the selection, so a slice costs a slice. The selection is independent of `attachments` (one can take image bytes without reading them, or read them without taking the bytes), and ids follow the same grammar and document order. `result=meta` and `find` describe or search and carry no image text, so `ocr` is refused with them. The free tier answers `402` with the payment terms rather than spending a paid call."
    },
    "input": {
      "type": "string",
      "description": "Content to convert: a URL (http(s)://...), a data URI (data:mime/type;base64,...), plain text, or a resource address (mdapi:...) returned by an earlier answer. Auto-detected: http(s):// → URL, data: → file, mdapi: → resource address, otherwise → text. A prompt that names the document - a URL or an `mdapi:` address written inside it - is used as the input when `input` is absent, so a command alone is a complete request."
    }
  },
  "required": ["messages"]
}
```

> **Token and memo never travel in the body:** this endpoint reads them from the request - `Authorization: Bearer TOKEN` and `X-MDAPI-Memo-Required: MEMO`, or the `token` and `memo` query parameters.

> **Note on streaming + custom instructions:** when custom instructions trigger LLM processing, the response is returned as a single completion (streaming is not applied to the LLM pass). Streaming SSE applies to the standard conversion path.

## Responses

`POST /v1/responses` speaks the OpenAI Responses API against the same conversion core. `input` takes a string or an array of items, and `instructions` becomes the system message.

- `input` - A string, or an array of items. A bare string, or an item whose `content` is a string, is read as one message; an item whose `content` is an array carries parts. `instructions` becomes the system message
- `input_text` / `text` - The text of a part
- `input_file` - One file per request. `file_data` is a data URI (`data:<mime>;base64,...`); `file_url` is an http(s) URL or a data URI. `file_id` on its own is refused with an explanation, because the service is stateless and has no Files API - alongside inline content it is accepted as a label
- `input_image` / `image_url` - An image part, `image_url` being a string or an object with `url`. A `data:` URI carries the bytes, an http(s) URL is fetched

The answer is a `response` object - `{id, object: "response", output: [...], usage: {...}}` - beside the core's own products (`parts`, `find`, `attachments[]`). With `stream: true` the stream carries the Responses event names in order: `response.created`, `response.in_progress`, `response.output_item.added`, `response.content_part.added`, `response.output_text.delta`, `response.output_text.done`, `response.content_part.done`, `response.output_item.done`, `response.completed`.

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