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.

Portfolio-Elemente

Use Cases

Portfolio items are evidence or achievements linked to a user. These items can be created manually or automatically (e.g., when a training is completed or a certificate is issued). Each item contains a title, description, dates, and optional attachments.

Get single portfolio item

query {
  portfolioItem(id: "uuid-here") {
    id
    title
    description
    startDate
    endDate
    files
    user { id name }
  }
}

List portfolio items for a user

query {
  portfolioItems(userId: "uuid-user") {
    id
    title
    startDate
    endDate
  }
}

Create a new portfolio item

Adds a portfolio item to a user, with optional attachments and validity period.

mutation {
  createPortfolioItem(
    input: {
      userId: "uuid-user"
      title: "Safety Certificate Obtained"
      description: "Completed at location X"
      startDate: "2023-08-05"
      endDate: "2025-08-05"
    }
  ) {
    portfolioItem {
      id
      title
    }
  }
}

Update existing item

mutation {
  updatePortfolioItem(
    id: "uuid-item"
    input: {
      description: "Updated description"
    }
  ) {
    portfolioItem {
      id
      description
    }
  }
}

Delete item

Permanently deletes a portfolio item.

mutation {
  deletePortfolioItem(id: "uuid-item") {
    success
  }
}

GraphQL Definitions

Type

type PortfolioItem {
  id: ID!
  user: User!
  title: String!
  description: String
  startDate: DateTime!
  endDate: DateTime
  files: [String!]
  createdAt: DateTime
  updatedAt: DateTime
}

Queries

portfolioItem(id: UUID!): PortfolioItem
portfolioItems(userId: UUID): [PortfolioItem!]!

Mutations

createPortfolioItem(input: CreatePortfolioItemInput!): PortfolioItemPayload
updatePortfolioItem(id: UUID!, input: UpdatePortfolioItemInput!): PortfolioItemPayload
deletePortfolioItem(id: UUID!): DeletePortfolioItemPayload

Notes

  • startDate represents the moment of acquisition (e.g., date obtained or started).
  • endDate is optional and represents validity period (e.g., certificate expiry).
  • Portfolio item changes trigger webhooks: PORTFOLIO_ITEM_CREATED, PORTFOLIO_ITEM_UPDATED, PORTFOLIO_ITEM_DELETED.
  • Do not use createPortfolioItem for certificates — use generateCertificate instead, which automatically creates the portfolio item.
  • For reporting across users and trainings, use portfolioReport (see PortfolioReport page).