Handling File Uploads in REST API Tools

A REST API tool can send the files that people attach in a conversation to an external API. This guide shows how to configure the OpenAPI schema so that the Mate hands over a file as a URL, as Base64 data, or as a file part of a multipart/form-data request. It is for the people who build REST API tools.

The Tool Builder Mate from the Mates Store writes the schema from the API documentation: see Tool Building Resources.

How the attachment placeholder works

The Mate never reads or encodes the file itself. The Mate writes a short placeholder in the request; the file takes its place when the call runs.

{{mode:<mode>|attachmentId:<ATTACHMENT_ID>}}

• mode tells the platform how to deliver the file: url or b64.

• attachmentId identifies the file. Each file attached in the conversation has an ID that the Mate can use.

Method 1: pass the file as a URL (recommended)

Use it when the external API can download a file from a link.

The platform puts a temporary link to the file in place of the placeholder.

# In components/schemas/YourRequest/properties
image_url:
  type: string
  format: uri
  description: |
    URL of the source image to process.
    ## For LLMs
    - MUST contain the processing mode and the attachment ID.
    - Syntax: {{mode:url|attachmentId:123456788999}} where 123456788999 is the attachment ID.
  example: '{{mode:url|attachmentId:123456788999}}'

Method 2: pass the file as Base64 data

Use it when the API expects the file content inside the JSON body.

The platform reads the file and puts its content, encoded in Base64, in place of the placeholder. The value is the raw Base64 string. It has no data:<type>;base64, prefix. If the API expects a data URI, say so in the parameter description, or use the URL method.

# In components/schemas/YourRequest/properties
image_data:
  type: string
  description: |
    The source image, as a Base64-encoded string.
    ## For LLMs
    - MUST contain the processing mode and the attachment ID.
    - Syntax: {{mode:b64|attachmentId:123456788999}} where 123456788999 is the attachment ID.
  example: '{{mode:b64|attachmentId:123456788999}}'

Method 3: send the file in a multipart/form-data request

Use it when the API expects a file upload form, like a browser upload.

Declare the operation's request body as multipart/form-data and use the b64 mode in the file field. For this content type, the platform sends the file itself as a file part, with its original file name and content type, instead of Base64 text.

requestBody:
  required: true
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          file:
            type: string
            description: |
              The document to upload.
              ## For LLMs
              - Syntax: {{mode:b64|attachmentId:ATTACHMENT_ID}}
            example: '{{mode:b64|attachmentId:123456788999}}'

Several files in one call

The placeholder works in arrays too. Use one placeholder per file.

# In components/schemas/YourRequest/properties
images:
  type: array
  minItems: 1
  description: An array of source images to combine.
  items:
    type: object
    required: [url]
    properties:
      url:
        type: string
        format: uri
        description: |
          A source image to use in the operation.
          ## For LLMs
          - Use one placeholder for each attached image, with its own attachmentId.
          - Syntax: {{mode:url|attachmentId:ATTACHMENT_ID}}
        example: '{{mode:url|attachmentId:9876543210}}'

Good to know

• Prefer the URL method. Unless the API requires the content itself, a link keeps the request small and fast.

• Be explicit in the ## For LLMs section. Give the exact placeholder syntax and say that ATTACHMENT_ID is the ID of an attachment from the conversation.

• Check what the API expects: a link, raw Base64, a data URI or a form upload. That decides the mode and the content type.

• Use clear operationIds, such as uploadDocument or editImageWithText, so the Mate picks the right operation.

• The link expires. The temporary URL is meant for the call. The external service must not store it for later use.

• To send the latest attachment without an ID, or a file from the Mate's knowledge, use the attachment placeholders described in "Placeholders Reference: Injecting Context Into Your Tools and Mates".

Related articles

• Master the REST API Tool

• Handling REST API Tools Response

• Placeholders Reference: Injecting Context Into Your Tools and Mates