File Uploads

Overview

Several mutations accept file references as UUID parameters (e.g., profileImage on users, imageId on offers). To use these, you first need to upload the file and obtain its UUID.

Pluvo provides two upload methods:

Method 1: Direct Upload (simple)

Use the uploadFile mutation for small files. This sends the file directly in the GraphQL request.

mutation {
  uploadFile(file: <Upload>) {
    ok
    file {
      id
      url
    }
  }
}

This mutation uses the GraphQL multipart request specification. The file is sent as a multipart form upload, not as a regular JSON field.

Example request

POST https://[organization].pluvo.com/graphql/
Authorization: Bearer <token>
Content-Type: multipart/form-data

operations: {"query": "mutation ($file: Upload!) { uploadFile(file: $file) { ok file { id url } } }", "variables": {"file": null}}
map: {"0": ["variables.file"]}
0: @/path/to/photo.jpg

The response contains the file's id (UUID) which you can use in other mutations:

{
  "data": {
    "uploadFile": {
      "ok": true,
      "file": {
        "id": "abc-123-def-456",
        "url": "https://files.pluvo.co/..."
      }
    }
  }
}

Method 2: Presigned S3 Upload (recommended for large files)

Step 1: Create a file record

mutation {
  createFile(file: {
    name: "training-photo.jpg"
    public: true
  }) {
    file {
      id
    }
    s3Url
    s3Data
  }
}

The response contains:

• file.id — The UUID you'll use in other mutations
• s3Url — The URL to POST the file to
• s3Data — Form fields to include in the POST

Step 2: Upload to S3

POST <s3Url>
Content-Type: multipart/form-data

key: <from s3Data>
policy: <from s3Data>
...
file: @/path/to/training-photo.jpg

Using the file UUID

Set user profile image

mutation {
  updateUser(
    ref: "EMP-12345"
    user: {
      profileImage: "file-uuid-from-upload"
    }
  ) {
    user {
      id
      profileImage { url }
    }
  }
}

Set offer image

mutation {
  updateOffer(
    id: "offer-uuid"
    offer: {
      imageId: "file-uuid-from-upload"
    }
  ) {
    offer { id }
  }
}

Notes

• Method 1 (direct upload) is simpler but limited by request size.
• Method 2 (presigned S3) is recommended for files larger than a few MB.
• File UUIDs are stable — once uploaded, you can reuse the same UUID in multiple places.
• The public flag on createFile controls whether the file is accessible to all organization users.