LRS HTTP server

Ralph implements the Learning Record Store (LRS) specification defined by ADL.

Ralph LRS, based on FastAPI, has the following key features:

• Supports of multiple databases through different backends
• Secured with multiple authentication methods
• Supports multitenancy
• Enables the Total Learning Architecture with statements forwarding
• Monitored thanks to the Sentry integration

API documentation

FastAPI 0.1.0

Endpoints

---

GET /xAPI/statements/

Get

Description

Read a single xAPI Statement or multiple xAPI Statements.

LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI-Communication.md#213-get-statements

Input parameters

Parameter	In	Type	Default	Nullable	Description
HTTPBasic	header	string	N/A	No	Basic authentication
HTTPBasic	header	string	N/A	No	Basic authentication
activity	query	string		No	Filter, only return Statements for which the Object of the Statement is an Activity with the specified id
agent	query	string		No	Filter, only return Statements for which the specified Agent or Group is the Actor or Object of the Statement
ascending	query	boolean	False	No	If "true", return results in ascending order of stored time
attachments	query	boolean	False	No	**Not implemented** If "true", the LRS uses the multipart response format and includes all attachments as described previously. If "false", the LRS sends the prescribed response with Content-Type application/json and does not send attachment data.
format	query	string	exact	No	**Not implemented** If "ids", only include minimum information necessary in Agent, Activity, Verb and Group Objects to identify them. For Anonymous Groups this means including the minimum information needed to identify each member. If "exact", return Agent, Activity, Verb and Group Objects populated exactly as they were when the Statement was received. An LRS requesting Statements for the purpose of importing them would use a format of "exact" in order to maintain Statement Immutability. If "canonical", return Activity Objects and Verbs populated with the canonical definition of the Activity Objects and Display of the Verbs as determined by the LRS, after applying the language filtering process defined below, and return the original Agent and Group Objects as in "exact" mode.
limit	query	integer	100	No	Maximum number of Statements to return. 0 indicates return the maximum the server will allow
mine	query	boolean	False	No	If "true", return only the results for which the authority matches the "agent" associated to the user that is making the query.
pit_id	query	string		No	Point-in-time ID to ensure consistency of search requests through multiple pages.NB: for internal use, not part of the LRS specification.
registration	query	string		No	**Not implemented** Filter, only return Statements matching the specified registration id
related_activities	query	boolean	False	No	**Not implemented** Apply the Activity filter broadly. Include Statements for which the Object, any of the context Activities, or any of those properties in a contained SubStatement match the Activity parameter, instead of that parameter's normal behaviour
related_agents	query	boolean	False	No	Apply the Agent filter broadly. Include Statements for which the Actor, Object, Authority, Instructor, Team, or any of these properties in a contained SubStatement match the Agent parameter, instead of that parameter's normal behaviour.
search_after	query	string		No	Sorting data to allow pagination through large number of search results. NB: for internal use, not part of the LRS specification.
since	query	string		No	Only Statements stored since the specified Timestamp (exclusive) are returned
statementId	query	string		No	Id of Statement to fetch
until	query	string		No	Only Statements stored at or before the specified Timestamp are returned
verb	query	string		No	Filter, only return Statements matching the specified Verb id
voidedStatementId	query	string		No	**Not implemented** Id of voided Statement to fetch

Responses

200 OK422 Unprocessable Entity

application/json

Schema of the response body

{
    "type": "object",
    "title": "Response Get Xapi Statements  Get"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

PUT /xAPI/statements/

Put

Description

Store a single statement as a single member of a set.

LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI-Communication.md#211-put-statements

Input parameters

Parameter	In	Type	Default	Nullable	Description
HTTPBasic	header	string	N/A	No	Basic authentication
HTTPBasic	header	string	N/A	No	Basic authentication
statementId	query	string		No

Request body

application/json

{
    "actor": null,
    "id": "8c83ad01-b519-4bce-b4b8-afd12f0229c1",
    "object": {
        "id": "string"
    },
    "verb": {
        "id": "string"
    }
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "actor": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/BaseXapiAgentWithMbox"
                },
                {
                    "$ref": "#/components/schemas/BaseXapiAgentWithMboxSha1Sum"
                },
                {
                    "$ref": "#/components/schemas/BaseXapiAgentWithOpenId"
                },
                {
                    "$ref": "#/components/schemas/BaseXapiAgentWithAccount"
                },
                {
                    "$ref": "#/components/schemas/BaseXapiAnonymousGroup"
                },
                {
                    "$ref": "#/components/schemas/BaseXapiIdentifiedGroupWithMbox"
                },
                {
                    "$ref": "#/components/schemas/BaseXapiIdentifiedGroupWithMboxSha1Sum"
                },
                {
                    "$ref": "#/components/schemas/BaseXapiIdentifiedGroupWithOpenId"
                },
                {
                    "$ref": "#/components/schemas/BaseXapiIdentifiedGroupWithAccount"
                }
            ],
            "title": "Actor"
        },
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "object": {
            "$ref": "#/components/schemas/LaxObjectField"
        },
        "verb": {
            "$ref": "#/components/schemas/LaxVerbField"
        }
    },
    "type": "object",
    "required": [
        "actor",
        "object",
        "verb"
    ],
    "title": "LaxStatement",
    "description": "Pydantic model for lax statement.\n\nIt accepts without validating all fields beyond the bare minimum required to\nqualify an object as an XAPI statement."
}

Responses

204 No Content400 Bad Request409 Conflict422 Unprocessable Entity

application/json

{
    "detail": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "type": "string",
            "title": "Detail"
        }
    },
    "type": "object",
    "required": [
        "detail"
    ],
    "title": "ErrorDetail",
    "description": "Pydantic model for errors raised detail.\n\nType for return value for errors raised in API endpoints.\nUseful for OpenAPI documentation generation."
}

application/json

{
    "detail": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "type": "string",
            "title": "Detail"
        }
    },
    "type": "object",
    "required": [
        "detail"
    ],
    "title": "ErrorDetail",
    "description": "Pydantic model for errors raised detail.\n\nType for return value for errors raised in API endpoints.\nUseful for OpenAPI documentation generation."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

POST /xAPI/statements/

Post

Description

Store a set of statements (or a single statement as a single member of a set).

NB: at this time, using POST to make a GET request, is not supported. LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI-Communication.md#212-post-statements

Input parameters

Parameter	In	Type	Default	Nullable	Description
HTTPBasic	header	string	N/A	No	Basic authentication
HTTPBasic	header	string	N/A	No	Basic authentication

Request body

application/json

Schema of the request body

{
    "anyOf": [
        {
            "$ref": "#/components/schemas/LaxStatement"
        },
        {
            "items": {
                "$ref": "#/components/schemas/LaxStatement"
            },
            "type": "array"
        }
    ],
    "title": "Statements"
}

Responses

200 OK400 Bad Request409 Conflict422 Unprocessable Entity

application/json

[
    null
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "items": {},
    "type": "array",
    "title": "Response Post Xapi Statements  Post"
}

application/json

{
    "detail": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "type": "string",
            "title": "Detail"
        }
    },
    "type": "object",
    "required": [
        "detail"
    ],
    "title": "ErrorDetail",
    "description": "Pydantic model for errors raised detail.\n\nType for return value for errors raised in API endpoints.\nUseful for OpenAPI documentation generation."
}

application/json

{
    "detail": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "type": "string",
            "title": "Detail"
        }
    },
    "type": "object",
    "required": [
        "detail"
    ],
    "title": "ErrorDetail",
    "description": "Pydantic model for errors raised detail.\n\nType for return value for errors raised in API endpoints.\nUseful for OpenAPI documentation generation."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /xAPI/statements

Get

Description

Read a single xAPI Statement or multiple xAPI Statements.

LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI-Communication.md#213-get-statements

Input parameters

Parameter	In	Type	Default	Nullable	Description
HTTPBasic	header	string	N/A	No	Basic authentication
HTTPBasic	header	string	N/A	No	Basic authentication
activity	query	string		No	Filter, only return Statements for which the Object of the Statement is an Activity with the specified id
agent	query	string		No	Filter, only return Statements for which the specified Agent or Group is the Actor or Object of the Statement
ascending	query	boolean	False	No	If "true", return results in ascending order of stored time
attachments	query	boolean	False	No	**Not implemented** If "true", the LRS uses the multipart response format and includes all attachments as described previously. If "false", the LRS sends the prescribed response with Content-Type application/json and does not send attachment data.
format	query	string	exact	No	**Not implemented** If "ids", only include minimum information necessary in Agent, Activity, Verb and Group Objects to identify them. For Anonymous Groups this means including the minimum information needed to identify each member. If "exact", return Agent, Activity, Verb and Group Objects populated exactly as they were when the Statement was received. An LRS requesting Statements for the purpose of importing them would use a format of "exact" in order to maintain Statement Immutability. If "canonical", return Activity Objects and Verbs populated with the canonical definition of the Activity Objects and Display of the Verbs as determined by the LRS, after applying the language filtering process defined below, and return the original Agent and Group Objects as in "exact" mode.
limit	query	integer	100	No	Maximum number of Statements to return. 0 indicates return the maximum the server will allow
mine	query	boolean	False	No	If "true", return only the results for which the authority matches the "agent" associated to the user that is making the query.
pit_id	query	string		No	Point-in-time ID to ensure consistency of search requests through multiple pages.NB: for internal use, not part of the LRS specification.
registration	query	string		No	**Not implemented** Filter, only return Statements matching the specified registration id
related_activities	query	boolean	False	No	**Not implemented** Apply the Activity filter broadly. Include Statements for which the Object, any of the context Activities, or any of those properties in a contained SubStatement match the Activity parameter, instead of that parameter's normal behaviour
related_agents	query	boolean	False	No	Apply the Agent filter broadly. Include Statements for which the Actor, Object, Authority, Instructor, Team, or any of these properties in a contained SubStatement match the Agent parameter, instead of that parameter's normal behaviour.
search_after	query	string		No	Sorting data to allow pagination through large number of search results. NB: for internal use, not part of the LRS specification.
since	query	string		No	Only Statements stored since the specified Timestamp (exclusive) are returned
statementId	query	string		No	Id of Statement to fetch
until	query	string		No	Only Statements stored at or before the specified Timestamp are returned
verb	query	string		No	Filter, only return Statements matching the specified Verb id
voidedStatementId	query	string		No	**Not implemented** Id of voided Statement to fetch

Responses

200 OK422 Unprocessable Entity

application/json

Schema of the response body

{
    "type": "object",
    "title": "Response Get Xapi Statements Get"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

PUT /xAPI/statements

Put

Description

Store a single statement as a single member of a set.

LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI-Communication.md#211-put-statements

Input parameters

Parameter	In	Type	Default	Nullable	Description
HTTPBasic	header	string	N/A	No	Basic authentication
HTTPBasic	header	string	N/A	No	Basic authentication
statementId	query	string		No

Request body

application/json

{
    "actor": null,
    "id": "00af4f39-0a42-47c7-b3a5-b667445204ac",
    "object": {
        "id": "string"
    },
    "verb": {
        "id": "string"
    }
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "actor": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/BaseXapiAgentWithMbox"
                },
                {
                    "$ref": "#/components/schemas/BaseXapiAgentWithMboxSha1Sum"
                },
                {
                    "$ref": "#/components/schemas/BaseXapiAgentWithOpenId"
                },
                {
                    "$ref": "#/components/schemas/BaseXapiAgentWithAccount"
                },
                {
                    "$ref": "#/components/schemas/BaseXapiAnonymousGroup"
                },
                {
                    "$ref": "#/components/schemas/BaseXapiIdentifiedGroupWithMbox"
                },
                {
                    "$ref": "#/components/schemas/BaseXapiIdentifiedGroupWithMboxSha1Sum"
                },
                {
                    "$ref": "#/components/schemas/BaseXapiIdentifiedGroupWithOpenId"
                },
                {
                    "$ref": "#/components/schemas/BaseXapiIdentifiedGroupWithAccount"
                }
            ],
            "title": "Actor"
        },
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "object": {
            "$ref": "#/components/schemas/LaxObjectField"
        },
        "verb": {
            "$ref": "#/components/schemas/LaxVerbField"
        }
    },
    "type": "object",
    "required": [
        "actor",
        "object",
        "verb"
    ],
    "title": "LaxStatement",
    "description": "Pydantic model for lax statement.\n\nIt accepts without validating all fields beyond the bare minimum required to\nqualify an object as an XAPI statement."
}

Responses

204 No Content400 Bad Request409 Conflict422 Unprocessable Entity

application/json

{
    "detail": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "type": "string",
            "title": "Detail"
        }
    },
    "type": "object",
    "required": [
        "detail"
    ],
    "title": "ErrorDetail",
    "description": "Pydantic model for errors raised detail.\n\nType for return value for errors raised in API endpoints.\nUseful for OpenAPI documentation generation."
}

application/json

{
    "detail": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "type": "string",
            "title": "Detail"
        }
    },
    "type": "object",
    "required": [
        "detail"
    ],
    "title": "ErrorDetail",
    "description": "Pydantic model for errors raised detail.\n\nType for return value for errors raised in API endpoints.\nUseful for OpenAPI documentation generation."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

POST /xAPI/statements

Post

Description

Store a set of statements (or a single statement as a single member of a set).

NB: at this time, using POST to make a GET request, is not supported. LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI-Communication.md#212-post-statements

Input parameters

Parameter	In	Type	Default	Nullable	Description
HTTPBasic	header	string	N/A	No	Basic authentication
HTTPBasic	header	string	N/A	No	Basic authentication

Request body

application/json

Schema of the request body

{
    "anyOf": [
        {
            "$ref": "#/components/schemas/LaxStatement"
        },
        {
            "items": {
                "$ref": "#/components/schemas/LaxStatement"
            },
            "type": "array"
        }
    ],
    "title": "Statements"
}

Responses

200 OK400 Bad Request409 Conflict422 Unprocessable Entity

application/json

[
    null
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "items": {},
    "type": "array",
    "title": "Response Post Xapi Statements Post"
}

application/json

{
    "detail": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "type": "string",
            "title": "Detail"
        }
    },
    "type": "object",
    "required": [
        "detail"
    ],
    "title": "ErrorDetail",
    "description": "Pydantic model for errors raised detail.\n\nType for return value for errors raised in API endpoints.\nUseful for OpenAPI documentation generation."
}

application/json

{
    "detail": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "type": "string",
            "title": "Detail"
        }
    },
    "type": "object",
    "required": [
        "detail"
    ],
    "title": "ErrorDetail",
    "description": "Pydantic model for errors raised detail.\n\nType for return value for errors raised in API endpoints.\nUseful for OpenAPI documentation generation."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /lbheartbeat

Lbheartbeat

Description

Load balancer heartbeat.

Return a 200 when the server is running.

Responses

200 OK

application/json

Schema of the response body

---

GET /heartbeat

Heartbeat

Description

Application heartbeat.

Return a 200 if all checks are successful.

Responses

200 OK

application/json

Schema of the response body

---

GET /whoami

Whoami

Description

Return the current user’s username along with their scopes.

Input parameters

Parameter	In	Type	Default	Nullable	Description
HTTPBasic	header	string	N/A	No	Basic authentication

Responses

200 OK

application/json

Schema of the response body

{
    "type": "object",
    "title": "Response Whoami Whoami Get"
}

---

Schemas

BaseXapiAccount

Name	Type	Description
homePage	string
name	string

BaseXapiAgentWithAccount

Name	Type	Description
account	BaseXapiAccount
name	string
objectType	string

BaseXapiAgentWithMbox

Name	Type	Description
mbox	string
name	string
objectType	string

BaseXapiAgentWithMboxSha1Sum

Name	Type	Description
mbox_sha1sum	string
name	string
objectType	string

BaseXapiAgentWithOpenId

Name	Type	Description
name	string
objectType	string
openid	string(uri)

BaseXapiAnonymousGroup

Name	Type	Description
member	Array<>
name	string
objectType	string

BaseXapiIdentifiedGroupWithAccount

Name	Type	Description
account	BaseXapiAccount
member	Array<>
name	string
objectType	string

BaseXapiIdentifiedGroupWithMbox

Name	Type	Description
mbox	string
member	Array<>
name	string
objectType	string

BaseXapiIdentifiedGroupWithMboxSha1Sum

Name	Type	Description
mbox_sha1sum	string
member	Array<>
name	string
objectType	string

BaseXapiIdentifiedGroupWithOpenId

Name	Type	Description
member	Array<>
name	string
objectType	string
openid	string(uri)

ErrorDetail

Name	Type	Description
detail	string

HTTPValidationError

Name	Type	Description
detail	Array<ValidationError>

LaxObjectField

Name	Type	Description
id	string(uri)

LaxStatement

Name	Type	Description
actor
id	string(uuid)
object	LaxObjectField
verb	LaxVerbField

LaxVerbField

Name	Type	Description
id	string(uri)

ValidationError

Name	Type	Description
loc	Array<>
msg	string
type	string

Security schemes

Name	Type	Scheme	Description
HTTPBasic	http	basic