API docs by Redocly

Talent API V2 (1.0.0)

Download OpenAPI specification:

Logo

API URL

Make sure to use the API URL instead of the web domain. Instead of https://torshtalent.com/api/v2/, use https://api.torshtalent.com/api/v2/

Explanation

There are two different APIs: Users API and Insights API:

  • Users API includes the endpoints for Users, Groups, Tags and Systems;
  • Insights API includes the endpoints for Reports and Systems.

Authentication

We use Bearer token authentication. You will need to include your Bearer token in the Authorization header:

  • Bearer Token Authentication: Include Authorization: Bearer <your_token> in your request headers
  • Token Types: Different tokens provide different access levels:
    • User tokens: Access as a specific user (standard API access)
    • System tokens: Access as a system (elevated permissions within that system)
    • Network tokens: Access as a network (can access multiple systems within the network)

Network vs System Requests: The type of request (network vs system/user) is automatically determined based on your Bearer token type. Network tokens automatically enable network-level access without needing additional parameters.

The Authorization header should be included in all API requests

Users

Retrieve a list of users

This endpoint retrieves a paginated list of users based on optional filters such as role and status.

query Parameters
pageNumber
required
integer >= 1

The page number to retrieve.

limit
required
integer >= 1

The number of users to return per page.

Responses

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "pageNumber": 1,
  • "usersListedCount": 10,
  • "pageCount": 5
}

Create a new user

This endpoint creates a new user in the system. It requires an email, role, and optionally a name and systemId.

Request Body schema: application/json
required
email
string
role
string
Enum: "Teacher" "Coach" "Admin"
name
string
systemId
string
suppress_invite
boolean
groups
Array of strings

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "role": "Admin",
  • "name": "Jane Doe",
  • "systemId": "system123",
  • "suppress_invite": false,
  • "groups": [
    ]
}

Response samples

Content type
application/json
{
  • "userId": "newUserId123"
}

Create multiple users

This endpoint creates multiple users in the system. It requires an array of user invites with email (required) and name (optional), plus a role that applies to all users.

Request Body schema: application/json
required
required
Array of objects
role
required
string
Enum: "Teacher" "Coach" "Admin"
suppress_invite
boolean

Responses

Request samples

Content type
application/json
{
  • "invites": [
    ],
  • "role": "Teacher",
  • "suppress_invite": false
}

Response samples

Content type
application/json
{
  • "successes": [
    ],
  • "failures": [
    ]
}

Retrieve user details

This endpoint retrieves the details of a user based on their email.

path Parameters
email
required
string

The email of the user to retrieve.

Responses

Response samples

Content type
application/json
{
  • "email": "user@example.com",
  • "role": "Admin",
  • "name": "Jane Doe",
  • "status": "Active",
  • "lastSeen": "2023-10-01T12:00:00Z",
  • "groups": [
    ]
}

Update user details

Updates the details of a user based on their email.

path Parameters
email
required
string

The email of the user to update.

Request Body schema: application/json
required
name
string
role
string
Enum: "Teacher" "Coach" "Admin"
status
string
groups
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "Jane Doe",
  • "role": "Admin",
  • "status": "Active",
  • "groups": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "User details updated successfully."
}

Delete a user by email

Deletes a user from the system based on the provided email address.

path Parameters
email
required
string

The email of the user to delete.

Responses

Update multiple users' groups

Updates the groups associated with multiple users in the system.

Request Body schema: application/json
required
emails
Array of strings
groups
Array of strings

Responses

Request samples

Content type
application/json
{
  • "emails": [
    ],
  • "groups": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "User groups updated successfully for multiple users."
}

Retrieve user groups

This endpoint retrieves the groups associated with a user based on their email.

path Parameters
email
required
string

The email of the user whose groups are to be retrieved.

query Parameters
pageNumber
required
integer >= 1

The page number to retrieve.

limit
required
integer >= 1

The number of groups to return per page.

Responses

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "pageNumber": 1,
  • "pageCount": 5
}

Retrieve user notifications

This endpoint retrieves the notifications associated with a user based on their email.

path Parameters
email
required
string

The email of the user whose notifications are to be retrieved.

query Parameters
pageNumber
required
integer >= 1

The page number to retrieve.

limit
required
integer >= 1

The number of notifications to return per page.

Responses

Response samples

Content type
application/json
{
  • "notifications": [
    ],
  • "pageNumber": 1,
  • "pageCount": 5
}

Groups

Retrieve a list of groups

This endpoint retrieves a paginated list of groups based on optional filters such as name.

query Parameters
pageNumber
required
integer >= 1

The page number to retrieve.

limit
required
integer >= 1

The number of groups to return per page.

name
string

The name filter for group search.

Responses

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "pageNumber": 1,
  • "pageCount": 5
}

Create a new group

This endpoint creates a new group in the system. It requires a name and optionally a systemId.

Request Body schema: application/json
required
name
string

Responses

Request samples

Content type
application/json
{
  • "name": "New Group"
}

Response samples

Content type
application/json
{
  • "_id": "newGroupId123",
  • "name": "New Group"
}

Update an existing group

This endpoint updates the details of a group based on its name.

path Parameters
name
required
string

The name of the group to update.

Request Body schema: application/json
required
name
string

Responses

Request samples

Content type
application/json
{
  • "name": "Updated Group Name"
}

Response samples

Content type
application/json
{
  • "_id": "existingGroupId123",
  • "name": "Updated Group Name"
}

Delete a group by name

This endpoint deletes a group from the system based on the provided name.

path Parameters
name
required
string

The name of the group to delete.

Request Body schema: application/json
optional
systemId
string

Responses

Request samples

Content type
application/json
{
  • "systemId": "system123"
}

Tags

Retrieve a list of tags

This endpoint retrieves a paginated list of tags based on optional filters such as tag name and type.

query Parameters
pageNumber
required
integer >= 1

The page number to retrieve.

limit
required
integer >= 1

The number of tags to return per page.

tag
string

The tag name filter for tag search.

type
string
Enum: "content" "observation" "comment" "rubric" "focus"

The tag type filter.

Responses

Response samples

Content type
application/json
{
  • "tags": [
    ],
  • "pageNumber": 1,
  • "pageCount": 5
}

Create a new tag

This endpoint creates a new tag in the system. It requires a tag name and type.

Request Body schema: application/json
required
tag
string
type
string
Enum: "content" "observation" "comment" "rubric" "focus"

Responses

Request samples

Content type
application/json
{
  • "tag": "Math Concepts",
  • "type": "content"
}

Response samples

Content type
application/json
{
  • "_id": "newTagId123",
  • "tag": "Math Concepts",
  • "type": "content"
}

Update an existing tag

This endpoint updates the details of a tag based on its ID.

path Parameters
tagId
required
string

The ID of the tag to update.

Request Body schema: application/json
required
tag
string
type
string
Enum: "content" "observation" "comment" "rubric" "focus"

Responses

Request samples

Content type
application/json
{
  • "tag": "Updated Tag Name",
  • "type": "content"
}

Response samples

Content type
application/json
{
  • "_id": "existingTagId123",
  • "tag": "Updated Tag Name",
  • "type": "content"
}

Delete a tag by ID

This endpoint deletes a tag from the system based on the provided ID.

path Parameters
tagId
required
string

The ID of the tag to delete.

Responses

Systems

Retrieve a list of systems

This endpoint retrieves a paginated list of systems based on optional filters.

query Parameters
pageNumber
required
integer >= 1

The page number to retrieve.

limit
required
integer >= 1

The number of systems to return per page.

name
string

The name filter for system search.

Responses

Response samples

Content type
application/json
{
  • "systems": [
    ],
  • "pageNumber": 1,
  • "totalCount": 100
}

Retrieve a list of roles

This endpoint retrieves a paginated list of roles for a system. You can filter by role name.

query Parameters
pageNumber
required
integer >= 1

The page number to retrieve.

limit
required
integer >= 1

The number of roles to return per page.

name
string

Filter roles by name (case-insensitive, partial match).

systemId
string

The system ID to retrieve roles for. If not provided, uses the authenticated system.

Responses

Response samples

Content type
application/json
{
  • "roles": [
    ],
  • "pageNumber": 1,
  • "totalCount": 20
}

Retrieve profile attributes for a system

This endpoint retrieves the profile attributes for a specific system.

query Parameters
system
required
string

The system identifier to retrieve profile attributes for.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Reports

Retrieve report filter options

This endpoint retrieves the available filter options for reports.

query Parameters
systemId
string

The ID of the system to filter options.

Responses

Response samples

Content type
application/json
{
  • "filterOptions": {
    }
}

Run an insights report (CSV export)

This endpoint triggers the generation of an insights report as a CSV export based on the provided parameters.

Report Processing

All reports are processed asynchronously and generate CSV files. This endpoint immediately returns an insightsReportRequestId that you can use to check the report status and retrieve the CSV download URL via the /reports/{reportId} endpoint.

Note: This endpoint does not support pagination as it generates complete CSV exports.

ReportBuilder Reports

For reportBuilder reports, only saved reports are supported:

Saved Report CSV Export (Required)

  • Must provide reportId to reference an existing saved reportBuilder report
  • Cannot provide filterOptions - filter options are not accepted for reportBuilder reports
  • The reportId refers to a SavedReport from the user interface
  • The existing report's configuration will be used exactly as saved:
    • Column State: Which columns are visible, their order, grouping, etc.
    • Filter Model: All applied filters (date ranges, content filters, etc.)
    • Time Input: Date range settings
  • The entire dataset will be exported as a CSV file
  • The report will be run as the user who created the saved report

Other Report Types

For non-reportBuilder reports (systemPerformance, videoUsage, etc.), only filterOptions is supported. These reports require specific filter parameters as documented in the filter options endpoint.

For Live/Paginated Data

If you need real-time, paginated access to Report Builder data (not CSV export), use the /reports/reportBuilder/data endpoint instead.

Request Body schema: application/json
required
report
required
string
Enum: "systemPerformance" "domainsAndDimensions" "selfAssessments" "goals" "videoInteraction" "videoUsage" "fileUsage" "rubricUsage" "goalsActivity" "goalsCreation" "exemplarUsage" "forumUsage" "forumParticipation" "workflowParticipation" "observations" "coachingFrequency" "frequencySnapshot" "accountUsage" "activityStream" "learningPathsStatus" "reportBuilder"
object

Filter options for the report. Required for all report types EXCEPT reportBuilder reports.

For reportBuilder reports: filterOptions are NOT supported - you must use reportId instead.

Note: Pagination parameters are not supported since this endpoint generates complete CSV exports.

reportId
string

ID of an existing SavedReport (from the Report Builder UI) to run with its saved configuration.

Required for reportBuilder reports. For reportBuilder reports, this is the ONLY way to specify what data to export.

The SavedReport's configuration is used exactly as saved:

  • Column visibility, order, and grouping
  • All applied filters (date ranges, content types, etc.)
  • Date range settings

The report will be processed using the existing generateReportBuilderExport background job and run as the user who created the saved report.

Access Control: Users can only reference SavedReports they have access to based on their system membership or network permissions.

email
string <email>

Email of the user to run the report as.

Required for all report types EXCEPT reportBuilder reports. For reportBuilder reports, the report runs as the user who created the saved report.

Responses

Request samples

Content type
application/json
Example

Run an existing SavedReport configuration - the only way to use reportBuilder reports. No email needed.

{
  • "report": "reportBuilder",
  • "reportId": "savedReport123abc"
}

Response samples

Content type
application/json
Example

Creating a new reportBuilder report with custom filterOptions

{
  • "insightsReportRequestId": "export_abc123def456"
}

Retrieve report results or CSV download

This endpoint retrieves the status and results of a report based on the provided report ID.

Use this endpoint to:

  • Check if a report is still processing, completed, or failed
  • Retrieve CSV download URLs for Report Builder exports
  • Retrieve the actual report data for other report types when processing is complete

The reportId parameter should be the insightsReportRequestId returned from the POST /reports endpoint.

Report Processing States:

  • pending: Report is being processed (returns 202)
  • complete: Report is ready (returns 200)
  • failed: Report processing failed (returns 500)

Report Builder CSV Downloads: For reportBuilder reports, when complete, this endpoint returns a csvDownloadUrl instead of raw data. The CSV file contains the complete dataset and can be downloaded directly.

Other Report Types: For traditional insight reports (systemPerformance, videoUsage, etc.), this endpoint returns the processed data directly in JSON format.

This works for all report types, including:

  • New Report Builder CSV exports created with filterOptions
  • Report Builder CSV exports from existing SavedReports using reportId
  • Traditional insight reports (systemPerformance, videoUsage, etc.)
path Parameters
reportId
required
string
Example: export_abc123def456

The report export ID returned by POST /reports as insightsReportRequestId. This is NOT the same as a SavedReport ID - it's the ID of the export job.

Responses

Response samples

Content type
application/json
Example
{
  • "reportId": "export_abc123def456",
  • "filterOptions": {
    },
  • "status": "complete",
  • "reportData": [
    ]
}

Get Report Builder data (synchronous, paginated) from saved reports or direct filters

This endpoint provides real-time, paginated access to Report Builder data for interactive viewing and analysis using either saved reports or direct filter options.

Use this endpoint when you need:

  • Live data for dashboards or interactive interfaces
  • Paginated results for performance reasons
  • Immediate data without waiting for async processing

Use the /reports endpoint instead when you need:

  • Complete CSV exports for download
  • Async processing for large datasets
  • File-based reports

Key Features

  • Synchronous: Returns data immediately (no job processing)
  • Paginated: Supports pagination for performance
  • Dual Mode: Supports both saved reports (reportId) and direct filtering (filterOptions)
  • Real-time: Queries live data using either saved report configuration or provided filters

Usage Modes

Use reportId to query data using an existing saved report's configuration:

  • Leverages saved report's filter model, column state, and permissions
  • Uses the sophisticated ag-Grid server-side row model for optimal performance
  • Supports complex filtering, grouping, and aggregations

Mode 2: Direct Filters (Legacy)

Use filterOptions for simple direct database queries:

  • Basic filters
  • Supports timestamp ranges, system filters, and action type filters
  • Simpler but less feature-rich than saved reports

Note: You must provide either reportId OR filterOptions, but not both.

Authentication & Access Control

Same authentication rules as other endpoints:

  • Network Tokens: Access to all systems in their network

Performance Notes

  • Recommended page sizes: 10-100 items per page
  • Large page sizes may impact response time
  • Saved reports generally perform better due to optimized query handling
Request Body schema: application/json
required
One of
reportId
required
string

ID of an existing SavedReport (from the Report Builder UI) to query data from.

Mutually exclusive with filterOptions. Use this for querying data with saved report configuration. The saved report's filterModel will be used to determine what data to return.

Access Control: Users can only access saved reports they own or that belong to their system/network.

object

Direct filter options for querying Report Builder data.

Mutually exclusive with reportId. Use this for simple direct filtering without a saved report.

Supports basic filters like timestamp ranges, system restrictions, and action types.

pageSize
integer [ 10 .. 100 ]
Default: 50

Number of items per page (10-100)

pageNumber
integer >= 1
Default: 1

Page number to retrieve (1-based)

Responses

Request samples

Content type
application/json
Example

Get Report Builder data using a saved report with pagination

{
  • "reportId": "savedReport123abc",
  • "pageSize": 25,
  • "pageNumber": 1
}

Response samples

Content type
application/json
Example

Response when using reportId to query data

{
  • "reportData": [
    ],
  • "pagination": {
    },
  • "reportId": "savedReport123abc",
  • "savedReportTitle": "Monthly Activity Report"
}