> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opigno.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Badges
The Opigno Enterprise API provides queries retrieve the available achievements information,
along with the user’s current earning status.
Each badge represents a specific goal or condition that a user may fulfill
such as completing an action, reaching a defined threshold, or maintaining a certain level of engagement.
## Data Structure
### Badge
An achievement object that might be earned by user.
| Field | Type | Description |
| ------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `ID!` | The Badge entity ID. |
| `title` | `String!` | The title of the Badge. |
| `picture` | `MediaImage!` | `MediaImage` object representing the Badge picture. |
| `status` | `BadgeStatus!` | The status of the badge. |
| `earned(format: String)` | `String` | A string showing the badge earning time, formatted according to the optional `format` argument (default: `d/m/Y`). Empty if the badge status is not `EARNED`. |
| `earningCriteria` | `BadgeEarningCriteria!` | An earning criteria definition for the badge. |
### BadgeEarningCriteria
A union of available criteria types that describes a condition for badge earning
#### BadgeEarningCriteriaLpComplete
Represents criteria for badge earning by Learning Path accomplishment.
| Field | Type | Description |
| ---------------- | ----- | -------------------------------------------- |
| `learningPathId` | `ID!` | The Learning Path ID required to accomplish. |
#### BadgeEarningCriteriaLpPassed
Represents criteria for badge earning by successful Learning Path accomplishment.
| Field | Type | Description |
| ---------------- | ----- | --------------------------------------------------------- |
| `learningPathId` | `ID!` | The Learning Path ID required to successfully accomplish. |
#### BadgeEarningCriteriaLpEnroll
Represents criteria for badge earning by Learning Path enrollment.
| Field | Type | Description |
| ---------------- | ----- | --------------------------------------------- |
| `learningPathId` | `ID!` | The Learning Path ID required for enrollment. |
#### BadgeEarningCriteriaSocialConnection
Represents criteria for badge earning by reaching the required number of established social connections.
| Field | Type | Description |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `threshold` | `Int!` | The number of connections required to be established. |
| `currentThreshold` | `Int!` | The number of social connections already established. |
| `period` | `Int` | Optional period parameter. If specified, the badge can be earned only if the threshold has been reached within the number of seconds defined by this period. |
#### BadgeEarningCriteriaSocialEngagement
Represents criteria for badge earning based on the total number of social posts created.
| Field | Type | Description |
| ------------------ | ------ | -------------------------------------------------- |
| `threshold` | `Int!` | The number of social posts required to be created. |
| `currentThreshold` | `Int!` | The number of social posts already created. |
#### BadgeEarningCriteriaRegisteredFor
Represents criteria for badge earning based on the user’s registration duration, requiring the user account to exist for a specified period of time.
| Field | Type | Description |
| ------------------ | ------ | ----------------------------------------------------------- |
| `threshold` | `Int!` | The number of seconds the user account must exist. |
| `currentThreshold` | `Int!` | The number of seconds the user account has already existed. |
## Queries
### getBadge
This query is used to retrieve a single badge information.
* You must have `AUTHENTICATED` scope to access badges. Anonymous users cannot retrieve badges data.
* The API user context must be present and valid - otherwise, access is denied.
The following arguments can be used in the query:
| Argument | Type | Description |
| :---------------- | :--- | :------------------------------------------------------------------------------------- |
| `badgeId` | `ID` | The badge entity ID. |
| `userContextUuid` | `ID` | The user context UUID. If omitted, the user context from the API request will be used. |
```graphql GraphQL Query theme={null}
query getBadges {
getBadges(
badgeId: 2,
) {
id
title
picture {
url
}
status
earned(format: "d/m/y")
}
}
```
```json Response theme={null}
{
"data": {
"getBadge": {
"id": "2",
"title": "Training passed!",
"picture": {
"url": "http://backoffice-site.url/path-to-badge-icon/icon.png"
},
"status": "EARNED",
"earned": "22/10/25"
}
}
}
```
### getBadges
This query is used to retrieve the full badges list available
and supports cursor-based pagination (`after`, `before`) or limit-based (`first`, `last`).
* You must have `AUTHENTICATED` scope to access badges. Anonymous users cannot retrieve badges data.
* The API user context must be present and valid - otherwise, access is denied.
The following arguments can be used in the query:
| Argument | Type | Description |
| :---------------- | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
| `userContextUuid` | `ID` | The user context UUID. If omitted, the user context from the API request will be used. |
| `status` | `BadgeStatus` | The earning status of the badge. |
| `title` | `String` | Allows to search by the badge title; operator "CONTAINS". |
| `after` | `Cursor` | Returns the elements that come before the specified cursor. |
| `before` | `Cursor` | Returns results that come before the specified cursor. Should be used together with `last` parameter. Cannot be used if `after` is set. |
| `first` | `Integer` | Returns up to the first N elements from the list. Required if `after` parameter is set. Cannot be used together with `last`. |
| `last` | `Integer` | Returns up to the first N elements from the list. Required if `before` parameter is set. Cannot be used together with `first`. |
| `reverse` | `Boolean` | Allows to change the order of the sorting to `DESC`. |
| `sortKey` | `BadgeSortKey` | Sort the underlying list by the given key. By default badges will be sorted by the creation date. |
```graphql GraphQL Query theme={null}
query getBadges {
getBadges(
first: 3,
status: EARNED,
) {
edges {
node {
id
title
picture {
url
}
status
earned(format: "d/m/y")
}
}
pageInfo {
hasNextPage
endCursor
}
totalItems
}
}
```
```json Response theme={null}
{
"data": {
"getBadges": {
"edges": [
{
"node": {
"id": "1",
"title": "Training completed",
"picture": {
"url": "http://backoffice-site.url/path-to-badge-icon/icon.png"
},
"status": "EARNED",
"earned": "22/10/25"
}
},
{
"node": {
"id": "2",
"title": "Training passed!",
"picture": {
"url": "http://backoffice-site.url/path-to-badge-icon/icon.png"
},
"status": "EARNED",
"earned": "22/10/25"
}
},
{
"node": {
"id": "3",
"title": "Registered to training",
"picture": {
"url": "http://backoffice-site.url/path-to-badge-icon/icon.png"
},
"status": "EARNED",
"earned": "22/10/25"
}
}
],
"pageInfo": {
"hasNextPage": true,
"endCursor": "TzozMzoiRHJ1cGFsXG9waWdub19hcGlcV3JhcHBlcnNcQ3Vyc29yIjo0OntzOjE0OiIAKgBiYWNraW5nVHlwZSI7czoxMjoib3BpZ25vX2JhZGdlIjtzOjEyOiIAKgBiYWNraW5nSWQiO2k6MztzOjEwOiIAKgBzb3J0S2V5IjtzOjc6IkNSRUFURUQiO3M6MTI6IgAqAHNvcnRWYWx1ZSI7czoxMDoiMTc2MTEyMjA2OSI7fQ=="
},
"totalItems": 4
}
}
}
```
## Related Features
The `getBadges` query supports the same advanced features as other catalog queries:
Learn how to efficiently navigate through large sets of badges using cursor-based pagination.
Understand the authentication requirements and how to properly authenticate your requests.
Common error scenarios and solutions:
* **401 Unauthorized**: Ensure you're using a valid authentication token with `AUTHENTICATED` scope
* **403 Forbidden**: Verify your user account has the necessary permissions to access badges data
* **Missing cursor parameter**: When using `after`, you must also specify `first`
* **Invalid cursor**: Ensure cursor values are valid and not expired
* **Conflicting parameters**: Don't use both `first`/`after` and `last`/`before` together