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

Send a multipart POST request to your GraphQL endpoint with:

• An operations field containing the query and variables
• A map field mapping the file to the variable
• The file itself as a form field

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 will 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

Send a POST request to the s3Url with all fields from s3Data plus the file. This uploads the file directly to cloud storage.

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.