Workflows endpoint
Manage your Item Review Workflows.
Endpoints:
Usage
The format of requests to the Data API use the following syntax:
https://data.learnosity.com/{LTS_VERSION}/{endpoint}
For example, to use the v2025.1.LTS version and the itembank/items endpoint, you would create a request like so:
https://data.learnosity.com/v2025.1.LTS/itembank/items
Important Data API is not a REST API. All requests must use the POST method with the action request body parameter specifying the operation to use. The Learnosity SDK must be used to make requests to Data API.
Note Data API usage is subject to rate limits.
Related articles:
- Getting Started with the Data API
- See Release Cadence and Version Lifecycle for more information on available LTS versions.
Get Workflows
Retrieve all of the Item review workflows available for the specified Item bank.
You would want to use this to inspect the all of the rules applied to a specific workflow.
| Endpoint | /{LTS_VERSION}/itembank/workflows |
|---|---|
| HTTP method | POST |
| Action type | "get" |
Request body parameters
Body content type: application/json
-
organisation_id integer
Specifies the Item bank to retrieve Item pools from.
The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.
Default: the primary Item bank associated with the API consumer.
-
limit integer
Restricts the number of records returned.
Maximum:
50 -
next string
A token used to request the next page of results.
After making an initial request, if it would produce a result set larger than the specified
limit, the return packet will include a token inmeta.next. Pass the token provided bymeta.nextalong with the original request parameters to retrieve the next page of results. -
references array[string]
Includes specific workflow references.
Maximum entries:
1000
Request body example
{
"request": {
"references": [
"Default workflow"
]
}
}
Responses
Response example
{
"meta": {
"status": true,
"timestamp": 1583988357,
"records": 1
},
"data": [
{
"reference": "Default workflow",
"initial_state_reference": "DRAFT",
"final_state_reference": "APPROVED",
"description": "Default workflow description",
"workflow_states": [
{
"reference": "APPROVED",
"description": "APPROVED STATE",
"label": "APPROVED",
"workflow_transitions": [
{
"label": "APPROVED TO REVIEW",
"to_state_label": "REVIEW",
"to_state_reference": "REVIEW",
"display_order": 1
}
]
},
{
"reference": "BLOCKED",
"description": "BLOCKED STATE",
"label": "BLOCKED",
"workflow_transitions": [
{
"label": "BLOCKED TO REVIEW",
"to_state_label": "REVIEW",
"to_state_reference": "REVIEW",
"display_order": 1
},
{
"label": "BLOCKED TO REWORK",
"to_state_label": "REWORK",
"to_state_reference": "REWORK",
"display_order": 2
},
{
"label": "BLOCKED TO DRAFT",
"to_state_label": "DRAFT",
"to_state_reference": "DRAFT",
"display_order": 3
}
]
},
{
"reference": "DRAFT",
"description": "DRAFT STATE",
"label": "Draft",
"workflow_transitions": [
{
"label": "DRAFT TO REVIEW",
"to_state_label": "REVIEW",
"to_state_reference": "REVIEW",
"display_order": 1
},
{
"label": "DRAFT TO BLOCKED",
"to_state_label": "BLOCKED",
"to_state_reference": "BLOCKED",
"display_order": 2
}
]
},
{
"reference": "REVIEW",
"description": "REVIEW STATE",
"label": "REVIEW",
"workflow_transitions": [
{
"label": "REVIEW TO APPROVED",
"to_state_label": "APPROVED",
"to_state_reference": "APPROVED",
"display_order": 1
},
{
"label": "REVIEW TO REWORK",
"to_state_label": "REWORK",
"to_state_reference": "REWORK",
"display_order": 2
}
]
},
{
"reference": "REWORK",
"description": "REWORK STATE",
"label": "REWORK",
"workflow_transitions": [
{
"label": "REWORK TO REVIEW",
"to_state_label": "REVIEW",
"to_state_reference": "REVIEW",
"display_order": 1
},
{
"label": "REWORK TO BLOCKED",
"to_state_label": "BLOCKED",
"to_state_reference": "BLOCKED",
"display_order": 2
}
]
}
]
}
]
}
Set Workflows
Create a new Item review workflow for the specified Item bank.
You would want to use this to set up a new Item review workflow so that your content creators can collaborate as desired.
| Endpoint | /{LTS_VERSION}/itembank/workflows |
|---|---|
| HTTP method | POST |
| Action type | "set" |
Request body parameters
Body content type: application/json
-
organisation_id integer
(optional) Specifies the Item bank to update.
The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.
Default: the primary Item bank associated with the API consumer.
-
workflows array[object]
A list of the workflows to create.
Maximum entries:
50-
reference string
The unique reference for the workflow.
Once created, this workflow reference can be used in the Author API initialization options to enable the workflow states.
Maximum: 150 ASCII characters.
Note Double quotes, single quotes, and accent characters are not allowed.
Maximum length:
150 -
description string
A description of the workflow. This description only appears when retrieving workflows using the GET
/itembank/workflowsendpoint.Maximum length:
1000 -
initial_state_reference string
The starting state of the workflow.
This reference must match one of the state references provided in
workflows[].workflow_states[].Note The reference is case sensitive.
Maximum length:
150 -
final_state_reference string
The ending state of the workflow.
This reference must match one of the state references provided in
workflows[].workflow_states[].Note The reference is case sensitive.
Maximum length:
150 -
workflow_states array[object]
A list of each separate state for the workflow.
-
reference string
The unique reference for the state.
Note The reference is case sensitive.
Maximum length:
150 -
description string
The description of the state.
Maximum length:
1000 -
label string
A human-readable label for the state shown in the user interface.
Maximum length:
150 -
workflow_transitions array[object]
Define all the states for the workflow.
-
to_state_reference string
The next state reference that the current state can progress to.
This reference must match one of the state references provided in
workflows[].workflow_states[].Note The reference is case sensitive.
Maximum length:
150 -
display_order integer
Set the display order for this state.
The state transitions are numerically sorted in the user interface, from smallest to largest, where the smallest appears on top. For example, when you have five states numbered from one to five, one will appear first in the list of states.
-
-
-
Request body example
{
"request": {
"workflows": [
{
"reference": "Default workflow",
"initial_state_reference": "DRAFT",
"final_state_reference": "APPROVED",
"description": "Default workflow description TEST1",
"workflow_states": [
{
"reference": "DRAFT",
"description": "DRAFT STATE",
"label": "DRAFT",
"workflow_transitions": [
{
"to_state_reference": "REVIEW",
"display_order": 1
},
{
"to_state_reference": "BLOCKED",
"display_order": 2
}
]
},
{
"reference": "BLOCKED",
"description": "BLOCKED STATE",
"label": "BLOCKED",
"workflow_transitions": [
{
"to_state_reference": "REVIEW",
"display_order": 1
},
{
"to_state_reference": "REWORK",
"display_order": 2
},
{
"to_state_reference": "DRAFT",
"display_order": 3
}
]
},
{
"reference": "REWORK",
"description": "REWORK STATE",
"label": "REWORK",
"workflow_transitions": [
{
"to_state_reference": "REVIEW",
"display_order": 1
},
{
"to_state_reference": "BLOCKED",
"display_order": 2
}
]
},
{
"reference": "REVIEW",
"description": "REVIEW STATE",
"label": "REVIEW",
"workflow_transitions": [
{
"to_state_reference": "APPROVED",
"display_order": 1
},
{
"to_state_reference": "REWORK",
"display_order": 2
}
]
},
{
"reference": "APPROVED",
"description": "APPROVED STATE",
"label": "APPROVED",
"workflow_transitions": [
{
"to_state_reference": "REVIEW",
"display_order": 1
}
]
}
]
}
]
}
}
Responses
Response example
{
"meta": {
"status": true,
"timestamp": 1583990495
},
"data": []
}