> ## Documentation Index
> Fetch the complete documentation index at: https://wundergraphinc-brendan-add-sof-link.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# File Upload

> Upload files through the router using GraphQL multipart request.

## Overview

This feature is implemented according to the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec), utilizing the `multipart/form-data` content type. Cosmo supports both single and multiple file uploads, but batch uploads are not supported.

The router can be configured for file uploads with [these options](/router/configuration#file-upload).

## Multipart Request Structure

#### operations

A JSON-encoded operations object with files replaced by `null`. This object defines the GraphQL query or mutation to be executed, along with the necessary variables.

#### map

A JSON-encoded map indicating where files appear in the operations. For each file, the key is the file's multipart form field name, and the value is an array of operations paths. This map ensures the correct association between the files and their respective variables in the GraphQL operation.

#### File Fields

Each file extracted from the operations object is assigned a unique, arbitrary field name. These fields are included in the multipart form data and correspond to the file paths specified in the map.

## Sample Setup

#### Define Custom Scalar

You need to define a custom scalar `Upload` in your schema. This scalar will be used for the field type where you intend to upload files.

```js theme={null}
scalar Upload

type Mutation {
  singleUpload(file: Upload!): Boolean!
  multipleUpload(files: [Upload!]!): Boolean!
}
```

#### Single File Upload

To upload a single file, use the following `curl` command:

```bash theme={null}
curl localhost:3002/graphql \
  -F operations='{ "query": "mutation ($file: Upload!) { singleUpload(file: $file) }", "variables": { "file": null } }' \
  -F map='{ "0": ["variables.file"] }' \
  -F 0=@a.txt
```

This command sends a multipart request where:

* `operations` defines the GraphQL mutation with the `file` variable set to `null`.

* `map` associates the form field `0` with `variables.file`.

* `0=@a.txt` uploads the file `a.txt` with the form field name `0`.

#### Multiple Files Upload

To upload multiple files, use the following `curl` command:

```bash theme={null}
curl localhost:3002/graphql \
  -F operations='{ "query": "mutation($files: [Upload!]!) { multipleUpload(files: $files) }", "variables": { "files": [null, null] } }' \
  -F map='{ "0": ["variables.files.0"], "1": ["variables.files.1"] }' \
  -F 0=@a.txt \
  -F 1=@b.txt
```

This command sends a multipart request where:

* `operations` defines the GraphQL mutation with the `files` variable set to an array of `null` values.

* `map` associates the form fields `0` and `1` with `variables.files.0` and `variables.files.1` respectively.

* `0=@a.txt` and `1=@b.txt` upload the files `a.txt` and `b.txt` with form field names `0` and `1`.

By following these examples, you can configure your router to handle single and multiple file uploads effectively using GraphQL multipart requests. For more details, refer to the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec).