list_user_agreements

ManagementApi.list_user_agreements(role_id, projection_expression=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

List user agreements

Returns metadata for every user agreement in the system. Requires system-settings.view. The response is not paginated; the full list is returned in one call. Optional projectionExpression limits which fields appear on each item (comma-separated names, not trimmed).

Parameters:

  • role_id (str) – Amorphic role ID the request is authorized against. Must be a role the user belongs to. Used for permission checks and audit logs. (required)

  • projection_expression (str) – Comma-separated item keys to keep on each userAgreements element (AgreementName, Description, Version, S3Path, CreatedBy, CreationTime). Split is not trimmed. When omitted, every stored attribute is returned. Envelope key userAgreements is always present.

  • _request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.

  • _request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.

  • _content_type (str, Optional) – force content-type for the request.

  • _headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.

  • _host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

ListUserAgreementsResponse

Returns:

Returns the result object.

Request and Response Examples

HTTP: GET /user-agreements

Success (HTTP 200)

Envelope userAgreements is a list of metadata items. Empty list when the table has no rows. Item properties are not required because projection can omit them.

Full metadata list

{
  "userAgreements": [
    {
      "AgreementName": "Default_User_Agreement",
      "Description": "Default Agreement",
      "Version": "1548975106",
      "S3Path": "s3://example-misc/user-agreements/1548975106.md",
      "CreatedBy": "system",
      "CreationTime": "2026-08-01 00:30:12"
    }
  ]
}

Errors

Documented error codes: AUTH-1001, AUTH-1030, RTE-1001, EMF-1001.

HTTP 400

AUTH-1001 when role_id is missing. AUTH-1030 when the role lacks system-settings.view.

Missing role_id

{
  "Message": "AUTH-1001 - Missing role information in event header"
}

Missing permission

{
  "Message": "AUTH-1030 - User is not authorized to list user agreements due to the following missing permission(s) - {'system-settings': ['view']}"
}

HTTP 500

Uncaught Exception formatted as RTE-1001 via EMF-1001.

Uncaught Exception

{
  "Message": "RTE-1001 - Failed to scan User Agreements table."
}