Developer docs

De Pluvo API geeft je programmatische toegang tot je leeromgeving. Beheer gebruikers, groepen, trainingen, inschrijvingen en certificaten vanuit je eigen systemen.

De API is gebaseerd op GraphQL. Je bepaalt zelf welke data je opvraagt of muteert, zonder overbodige velden. Authenticatie verloopt via OAuth 2.0 met client credentials. Webhooks houden je systemen real-time op de hoogte van wijzigingen.

Datei-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.

cURL example

curl -X POST https://[organization].pluvo.com/graphql/ \
  -H "Authorization: Bearer <token>" \
  -F operations='{"query": "mutation ($file: Upload!) { uploadFile(file: $file) { ok file { id url } } }", "variables": {"file": null}}' \
  -F map='{"0": ["variables.file"]}' \
  -F 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)

For larger files, use the two-step presigned upload flow:

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 the file to the s3Url with the fields from s3Data:

curl -X POST <s3Url> \
  -F key=<from s3Data> \
  -F policy=<from s3Data> \
  -F ... \
  -F file=@/path/to/training-photo.jpg

Using the file UUID

Once you have the file UUID, use it in other mutations:

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.