API docs by Redocly

Portflow Public API docs (0.1.0)

Download OpenAPI specification:

This specification contains the API documentation for the Portflow public api.

Authentication

Authentication happens via the /oauth/token endpoint, which will return an access token.

Errors

All actions can return errors, but those are not documented for brevity.

Pagination

All operations which support the page parameter will return a paginated list of results. A Link header will be returned in the response formatted according to RFC8288. The following links can be returned: - current - next - prev - first - last If a link is not relevant, for example a next link on the last page of results, it is not included in the header. The URLs included in the header should not be modified and should be used as-is.

AssessmentSnapshots

Operations related to assessment snapshots

Retrieve assessment snapshots based on filters

Query parameters are not taken into account if they are not valid (for example, empty string).

Authorizations:
OAuth2
query Parameters
page
integer >= 1
Default: 1
Example: page=2

The page of the results to retrieve.

Note: It's almost never necessary to use this parameter directly, the URL should be retrieved from the Link header.

per_page
integer [ 1 .. 20 ]
Default: 20
Example: per_page=10

The number of results to retrieve for this page.

user_uuid
string

Filter snapshots by user UUID.

created_before
string <date-time>

Filter snapshots created before the specified date-time.

created_after
string <date-time>

Filter snapshots created after the specified date-time.

"created_at" (any)
"asc" (any) or "desc" (any)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve an assessment snapshot

Endpoint to retrieve a specific assessment snapshot by its UUID.

Returns the details of the assessment snapshot.

Authorizations:
OAuth2
path Parameters
snapshot_uuid
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The uuid of a snapshot. Can be retrieved from the "Retrieve assessment snapshots based on filters" endpoint by supplying a user_uuid

Responses

Response samples

Content type
application/json
{
  • "uuid": "10fb17e5-305e-47b6-89fb-be4f2b430932",
  • "created_at": "2023-10-05T14:48:00.000Z",
  • "user_uuid": "75cabdfe-fd3b-4791-8a14-f53a97bc83fd",
  • "assessment_url": "https://app.portflow.app/a/8fHjO2so/nmtw5WW3bgGHX489GdHsqhrQ",
  • "assessment_password": "n3ecJU8fR1FH",
  • "lti_submission_count": 3,
  • "lti_portfolio_submissions": [
    ]
}

Create an export of the assessment snapshot

Endpoint to create an export of the assessment snapshot identified by its UUID.

If an export already exists or has already been scheduled, this endpoint will do nothing.

The export is created asynchronously. You can check the status of the export by retrieving the exports of the assessment snapshot.

Authorizations:
OAuth2
path Parameters
snapshot_uuid
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The uuid of a snapshot. Can be retrieved from the "Retrieve assessment snapshots based on filters" endpoint by supplying a user_uuid

Responses

Retrieve exports of a specific assessment snapshot

Endpoint to retrieve exports of a specific assessment snapshot by its UUID. All exports are returned, also those that are not yet ready.

Note that exports older than a week are automatically deleted.

If the exported assessment snapshot is big, it may take some time to generate the export files. The resulting export may also be split into multiple files.

Authorizations:
OAuth2
path Parameters
snapshot_uuid
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The uuid of a snapshot. Can be retrieved from the "Retrieve assessment snapshots based on filters" endpoint by supplying a user_uuid

query Parameters
page
integer >= 1
Default: 1
Example: page=2

The page of the results to retrieve.

Note: It's almost never necessary to use this parameter directly, the URL should be retrieved from the Link header.

per_page
integer [ 1 .. 20 ]
Default: 20
Example: per_page=10

The number of results to retrieve for this page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an assessment snapshot share link

Endpoint to create an assessment link for sharing the assessment snapshot with others.

If a share link already exists for the snapshot, an error will be returned.

Authorizations:
OAuth2
path Parameters
snapshot_uuid
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The uuid of a snapshot. Can be retrieved from the "Retrieve assessment snapshots based on filters" endpoint by supplying a user_uuid

Responses

Response samples

Content type
application/json
{
  • "uuid": "10fb17e5-305e-47b6-89fb-be4f2b430932",
  • "created_at": "2023-10-05T14:48:00.000Z",
  • "user_uuid": "75cabdfe-fd3b-4791-8a14-f53a97bc83fd",
  • "assessment_url": "https://app.portflow.app/a/8fHjO2so/nmtw5WW3bgGHX489GdHsqhrQ",
  • "assessment_password": "n3ecJU8fR1FH",
  • "lti_submission_count": 3,
  • "lti_portfolio_submissions": [
    ]
}

OAuth

Operations related to OAuth authentication

Get an OAuth token

This endpoint is used to get an access token for the client using OAuth 2.0 client credentials flow. The client must include the client ID and secret in the Authorization header. The credentials must be base-64 encoded and separated by a colon. A client can only have 1 valid token at a time. Requesting a new token will invalidate the previous one.

header Parameters
Authorization
required
string

Should contain the base-64 encoded client ID and secret, separated by a colon. Should be prefixed with Basic.

Request Body schema: application/json
required
grant_type
required
string

The grant type. Currently only client_credentials is supported.

Value: "client_credentials"
scope
string

The scope(s) of the token, separated by a space. Every endpoint specifies the required scope.

Responses

Request samples

Content type
application/json
{
  • "grant_type": "client_credentials",
  • "scope": "users:read users:write"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 0,
  • "scope": "string",
  • "created_at": 1616425200
}

ProgressReviews

Operations related to progress reviews

Retrieve progress review results

Endpoint to query progress review results for a given goal and user.

Returns all progress review results from all progress reviews this user created for this goal. Results are ordered by the date of submission, with the most recent results appearing first.

Authorizations:
OAuth2
path Parameters
user_uuid
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The uuid of a user. Can be retrieved from the "Retrieve users based on filters" endpoint by supplying a sourced_id

goal_uuid
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The uuid of a repository goal. Can be retrieved from the "Retrieve repository goals based on filters" endpoint by searching on a name or nickname

query Parameters
page
integer >= 1
Default: 1
Example: page=2

The page of the results to retrieve.

Note: It's almost never necessary to use this parameter directly, the URL should be retrieved from the Link header.

per_page
integer [ 1 .. 20 ]
Default: 20
Example: per_page=10

The number of results to retrieve for this page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

RepositoryGoals

Operations related to repository goals

Retrieve repository goals based on filters

Endpoint to query repository goals

Authorizations:
OAuth2
query Parameters
page
integer >= 1
Default: 1
Example: page=2

The page of the results to retrieve.

Note: It's almost never necessary to use this parameter directly, the URL should be retrieved from the Link header.

per_page
integer [ 1 .. 20 ]
Default: 20
Example: per_page=10

The number of results to retrieve for this page.

search
string

Search term to filter repository goals based on their name, nickname or sourced ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Statistics

Operations related to statistics

Retrieve user actions

Endpoint to retrieve user actions. Each user action includes details such as the type of action, the user who performed it, the resource on which the action happened, the timestamp, and any relevant metadata.

These user actions can be used to calculate various statistics. For example, you can determine how many evidence were created in a specific time period by filtering user actions with a resource type of "Evidence" and then counting the number of user actions where the event type is "created" and subtracting the number of user actions where the event type is "destroyed" within that time frame.

Authorizations:
OAuth2
query Parameters
cursor
string
Example: cursor=WyIyMDI1LTEyLTAyVDEyOjMyOjIxLjkwMFoiXQ

The cursor value to retrieve the next set of results.

Note: It's almost never necessary to use this parameter directly, the URL should be retrieved from the Link header.

per_page
integer [ 1 .. 20 ]
Default: 20
Example: per_page=10

The number of results to retrieve for this page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve admin statistics

Endpoint to query aggregated statistics concerning Portflow usage up to and including the provided date. These are also available within Portflow in the Admin > Statistics tab, but only for the previous day. Query parameters are not taken into account if they are not valid (for example, empty string). If no valid query parameter is passed, the request will fail with 400 Bad Request.

Authorizations:
OAuth2
query Parameters
date
required
string
Example: date=2023-05-10

The date, in ISO 8601 format ("YYYY-MM-DD"), for which you wish to retrieve statistics. Statistics are aggregated and stored early the day after this date, so statistics will be returned for any content created up until the end of day for the date parameter sent. Note that server dates are always in UTC, so a date of 2024-01-01 will show statistics valid at "2024-01-01 23:59 UTC". The maximum possible date value is the date previous to the request in UTC. The minimum possible value will be the first date that statistics were collected.

Responses

Response samples

Content type
application/json
{
  • "lms_user_count": 6456,
  • "external_user_count": 6456,
  • "collection_count": 6456,
  • "portflow_evidence_count": 6456,
  • "lms_evidence_count": 6456,
  • "storage_byte_size": 6456,
  • "comment_count": 6456,
  • "feedback_request_count": 6456,
  • "goal_count": 6456,
  • "progress_review_request_count": 6456,
  • "template_count": 6456,
  • "snapshot_count": 6456,
  • "alumni_account_count": 6456,
  • "date": "2021-05-10"
}

Users

Operations related to Portflow users

Retrieve users based on filters

Query parameters are not taken into account if they are not valid (for example, empty string). If no valid query parameter is passed, the request will fail with 400 Bad Request.

About sourced_id:

  • if a user has never launched Portflow, we cannot know their sourced_id. It is still possible that they are present in our database, for example if another user shared a portfolio with them.
Authorizations:
OAuth2
query Parameters
page
integer >= 1
Default: 1
Example: page=2

The page of the results to retrieve.

Note: It's almost never necessary to use this parameter directly, the URL should be retrieved from the Link header.

per_page
integer [ 1 .. 20 ]
Default: 20
Example: per_page=10

The number of results to retrieve for this page.

sourced_id
required
string

If empty or null, will be ignored.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update a user

Update a user based on their UUID. This endpoint can be used to plan the deactivation and deletion of a user.

About deactivation

If a user has a planned deactivation date (deactivation_planned_at), the user will be deactivated at that date. During deactivation, we:

  • Delete the active portfolio and all snapshots not used for assessment purposes. This includes all snapshots that did not have an active assessment link or were not submitted to an LMS assignment.
  • Remove all of the user's power user capabilities, this means any roles such as "template creator" or "rubric scales creator".
  • Remove all notifications where the user (or the user's portfolio) was the source of the notification.

However, we do not remove the user's feedback in other portfolios. If the user has created any templates or rubric scales, the author name will change to "deleted user".

Once a user has been deactivated, they will no longer be able to launch Portflow. They will also be informed of this when they try to launch Portflow.

Please note that deactivation happens in the background and might not be immediate.

About deletion

If a user has a planned deletion date (deletion_planned_at), the user will be deleted at that date. A user can only be deleted if they have been deactivated. During deletion, we:

  • Delete all remaining snapshots the user still has. This includes any snapshots used for assessment purposes.
  • Delete the user itself.

However, as with user deactivation, we do not remove the user's feedback in other portfolios. We also do not delete any templates or rubric scales the user has created.

Once a user has been deleted, they will no longer exist in Portflow. This means that they will be able to launch Portflow again which will create a new user in our system.

Please note that deletion happens in the background and might not be immediate.

About enabling alumnus access

If a user has a planned alumnus activation date (alumnus_enabled_from), they will be able to log in to Portflow after this date using any secondary login method they have set up. Before this date they will be able to check that the login method is set up correctly, but they will not be able to access Portflow with their secondary login method.

Authorizations:
OAuth2
path Parameters
uuid
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000
Request Body schema: application/json
required
deactivation_planned_at
string or null <date-time>

Date at which the user will be deactivated. Date must be in the future and must be before the deletion_planned_at date (if given or set). If the user's current deactivation date has already passed, this value cannot be updated.

deletion_planned_at
string or null <date-time>

Date at which the user will be deleted. Date must be in the future and must be after the deactivation_planned_at date (if given or set). If the user's current deletion date has already passed, this value cannot be updated.

alumnus_enabled_from
string or null <date-time>

Date after which the user will be able to access Portflow with any secondary login method that they have set up. Date must be before the deactivation planned date (if given or set). If the user's current deactivation date has already passed, this value cannot be updated.

Responses

Request samples

Content type
application/json
{
  • "deactivation_planned_at": "2019-08-24T14:15:22Z",
  • "deletion_planned_at": "2019-08-24T14:15:22Z",
  • "alumnus_enabled_from": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "sourced_id": "1234",
  • "uuid": "3c6c035e-f6ca-4c87-b8c3-f1907400284b",
  • "deactivation_planned_at": "2021-05-10T07:27:19.587Z",
  • "deletion_planned_at": "2021-05-10T07:27:19.587Z",
  • "deactivated_at": "2021-05-10T07:27:19.587Z",
  • "deleted_at": "2021-05-10T07:27:19.587Z",
  • "offboarding_status": "none",
  • "last_login": "2021-05-10T07:27:19.587Z",
  • "alumnus_login_enabled": true,
  • "alumnus_enabled_from": "2021-05-10T07:27:19.587Z"
}

Reactivate a deactivated user

Reactivate a deactivated user based on their UUID.

This endpoint can only be used for users that have been deactivated but not yet deleted.

About reactivation

When a user is reactivated, we:

  • Create a new active portfolio for the user.
  • Allow the user to launch Portflow again.

Only snapshots used for assessment purposes will be restored to the user. All other snapshots remain deleted.

Reactivation happens in the background and might take a few minutes to complete.

Authorizations:
OAuth2
path Parameters
uuid
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

Responses