# What Data Formats Are Supported for OpenAI Plugin Requests and Responses?

> Discover supported data formats for OpenAI plugin requests and responses including JSON multipart form data and text plain Learn how to structure your plugin interactions efficiently.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: api-reference
- Published: 2026-07-05

---

**OpenAI plugins support `application/json`, `multipart/form-data`, and `text/plain` for requests, with responses strictly required to be JSON, while also allowing base64-encoded binary data within JSON payloads.**

The `openai/plugins` repository defines the HTTP communication contract between language models and external tools. Understanding the supported data formats for plugin requests and responses is essential for developers building integrations that handle everything from structured API calls to large file uploads.

## Standard JSON Payloads

The primary format for plugin communication is `application/json`. According to the specification in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md), the plugin runtime parses incoming request bodies as JSON objects and expects responses to be JSON-encoded.

This format integrates cleanly with the model's function-calling mechanism. The plugin's OpenAPI-style schema (defined in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)) declares the exact structure of the request and response bodies.

```http
POST https://api.example.com/v1/analyze
Content-Type: application/json

{
  "text": "Summarize the following article …",
  "options": { "max_tokens": 150 }
}

```

The response must follow the JSON structure defined in the manifest:

```json
{
  "summary": "The article discusses …",
  "metadata": { "length": 1234 }
}

```

## Multipart Form Data for File Uploads

For binary data such as PDFs or images, plugins accept `multipart/form-data`. This format allows the request to contain multiple parts including raw file bytes, while the plugin typically returns JSON metadata about the uploaded content.

As implemented in `openai/plugins`, this approach prevents request size limitations by streaming file parts directly to storage. The response remains JSON even when accepting binary uploads.

```bash
curl -X POST https://api.example.com/v1/upload \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F "file=@report.pdf" \
  -F 'metadata={"title":"Annual Report"};type=application/json'

```

The plugin processes the raw bytes and returns structured metadata:

```json
{
  "file_id": "abc123",
  "url": "https://cdn.example.com/files/abc123"
}

```

## Base64-Encoded Binary in JSON

Plugins can also receive binary data as **base64-encoded strings** embedded within JSON fields. This hybrid approach allows a single `application/json` request to carry binary payloads without requiring a multipart envelope.

The field is declared as a string in the plugin schema, and the plugin decodes the base64 representation internally.

```http
POST https://api.example.com/v1/ocr
Content-Type: application/json

{
  "image_base64": "iVBORw0KGgoAAAANSUhEUgAA..."
}

```

The response follows standard JSON formatting:

```json
{
  "text": "Extracted OCR text …"
}

```

## Plain Text Support (Rare)

In limited scenarios, plugins may accept `text/plain` for simple scalar values. However, the response must still be JSON. This format is uncommon and typically used when the plugin intentionally processes raw string input without structural nesting.

## How Formats Are Defined in the Plugin Manifest

The supported content types are formally declared in the plugin's manifest file. The [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md) document specifies that `requestBody` and `responses` sections must list allowed content types such as `application/json` and `multipart/form-data`.

For example, in [`plugins/finn/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/finn/.codex-plugin/plugin.json), the schema defines the exact media types the model can use when calling the plugin. This ensures the runtime knows whether to serialize the request as JSON or construct a multipart form.

The [`.agents/skills/plugin-creator/SKILL.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md) file provides additional guidance for developers implementing these formats, ensuring seamless integration with the OpenAI model runtime.

## Summary

- **JSON** (`application/json`) is the standard format for both requests and responses, required for structured data exchange with the model.
- **Multipart form data** (`multipart/form-data`) enables file uploads while maintaining JSON responses for metadata.
- **Base64 encoding** allows binary data to travel inside JSON fields without multipart overhead.
- **Plain text** (`text/plain`) is supported for rare scalar use cases but responses must remain JSON.
- All formats are declared in the plugin's [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest according to the OpenAPI-style schema defined in the repository's specification files.

## Frequently Asked Questions

### Can OpenAI plugins accept raw binary data directly in the request body?

No, raw binary data must be sent either via `multipart/form-data` encoding or as base64-encoded strings within JSON fields. The plugin runtime expects specific content type headers and does not support raw binary blobs without these encapsulation methods.

### Why must plugin responses always be JSON?

The OpenAI model runtime requires JSON responses to parse and integrate the results into the conversation context. While requests can use various formats to accommodate different data types, responses must conform to the JSON schema defined in the plugin manifest to ensure the model can process the returned data structure.

### How do I configure my plugin to accept file uploads?

Define the `requestBody` content type as `multipart/form-data` in your [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest, referencing the schema in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md). Specify the file parameter types in your OpenAPI definition, and ensure your endpoint handles the multipart parsing while returning JSON metadata about the uploaded files.

### What is the maximum size for multipart file uploads in OpenAI plugins?

The specification does not define a universal size limit within the plugin manifest itself; instead, individual plugin implementations and hosting infrastructure determine size constraints. Check your specific deployment documentation and the [`README.md`](https://github.com/openai/plugins/blob/main/README.md) in the `openai/plugins` repository for guidance on handling large file streams and potential truncation limits.