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

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, 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) declares the exact structure of the request and response bodies.

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:

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

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:

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

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

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

The response follows standard JSON formatting:

{
  "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 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, 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 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 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 manifest, referencing the schema in .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 in the openai/plugins repository for guidance on handling large file streams and potential truncation limits.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}