Skip to content

System

Source code in src/cocalc_api/hub.py 
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
class System:

    def __init__(self, parent: "Hub"):
        self._parent = parent

    @api_method("system.ping")
    def ping(self) -> PingResponse:
        """
        Ping the server.

        Returns:
            PingResponse: JSON object containing the current server time.
        """
        raise NotImplementedError

    @api_method("system.test")
    def test(self) -> TestResponse:
        """
        Test the API key and get its scope information.

        Returns:
            TestResponse: JSON object containing:
                - account_id (if account-scoped key)
                - project_id (if project-scoped key)
                - server_time (current server time in milliseconds since epoch)
        """
        raise NotImplementedError

    def get_names(self, account_ids: list[str]) -> list[str]:
        """
        Get the displayed names of CoCalc accounts with given IDs.

        Args:
            account_ids (list[str]): List of account UUID strings.

        Returns:
            list[str]: Mapping from account_id to profile information.
        """
        return self._parent.call("system.getNames", [account_ids])

    @api_method("system.userSearch")
    def user_search(self, query: str) -> UserSearchResult:
        """
        Search for existing users by name or email address.

        Args:
            query (str): A query, e.g., partial name, email address, etc.

        Returns:
            UserSearchResult: Array of dicts with account_id, name,
                first_name, last_name, last_active (in ms since epoch),
                created (in ms since epoch) and email_address_verified.

        Examples:
            Search for myself:

            >>> import cocalc_api; hub = cocalc_api.Hub(api_key="sk...")
            >>> hub.system.user_search('w')
            [{'account_id': 'd0bdabfd-850e-4c8d-8510-f6f1ecb9a5eb',
              'first_name': 'W',
              'last_name': 'Stein',
              'name': None,
              'last_active': 1756503700052,
              'created': 1756056224470,
              'email_address_verified': None}]

            You can search by email address to ONLY get the user
            that has that email address:

            >>> hub.system.user_search('[email protected]')
            [{'account_id': 'd0bdabfd-850e-4c8d-8510-f6f1ecb9a5eb',
              'first_name': 'W',
              'last_name': 'Stein',
              'name': None,
              'email_address': '[email protected]',
              'last_active': 1756503700052,
              'created': 1756056224470,
              'email_address_verified': None}]
        """
        ...  # pragma: no cover

get_names(account_ids)

Get the displayed names of CoCalc accounts with given IDs.

Parameters:

Name Type Description Default
account_ids list[str]

List of account UUID strings.

 required

Returns:

Type Description
list[str]

list[str]: Mapping from account_id to profile information.
Source code in src/cocalc_api/hub.py 
 99
100
101
102
103
104
105
106
107
108
109
def get_names(self, account_ids: list[str]) -> list[str]:
    """
    Get the displayed names of CoCalc accounts with given IDs.

    Args:
        account_ids (list[str]): List of account UUID strings.

    Returns:
        list[str]: Mapping from account_id to profile information.
    """
    return self._parent.call("system.getNames", [account_ids])

ping()

Ping the server.

Returns:

Name Type Description
PingResponse PingResponse

JSON object containing the current server time.
Source code in src/cocalc_api/hub.py 
76
77
78
79
80
81
82
83
84
@api_method("system.ping")
def ping(self) -> PingResponse:
    """
    Ping the server.

    Returns:
        PingResponse: JSON object containing the current server time.
    """
    raise NotImplementedError

test()

Test the API key and get its scope information.

Returns:

Name Type Description
TestResponse TestResponse

JSON object containing: - account_id (if account-scoped key) - project_id (if project-scoped key) - server_time (current server time in milliseconds since epoch)
Source code in src/cocalc_api/hub.py 
86
87
88
89
90
91
92
93
94
95
96
97
@api_method("system.test")
def test(self) -> TestResponse:
    """
    Test the API key and get its scope information.

    Returns:
        TestResponse: JSON object containing:
            - account_id (if account-scoped key)
            - project_id (if project-scoped key)
            - server_time (current server time in milliseconds since epoch)
    """
    raise NotImplementedError

Search for existing users by name or email address.

Parameters:

Name Type Description Default
query str

A query, e.g., partial name, email address, etc.

 required

Returns:

Name Type Description
UserSearchResult UserSearchResult

Array of dicts with account_id, name, first_name, last_name, last_active (in ms since epoch), created (in ms since epoch) and email_address_verified.

Examples:

Search for myself:

>>> import cocalc_api; hub = cocalc_api.Hub(api_key="sk...")
>>> hub.system.user_search('w')
[{'account_id': 'd0bdabfd-850e-4c8d-8510-f6f1ecb9a5eb',
  'first_name': 'W',
  'last_name': 'Stein',
  'name': None,
  'last_active': 1756503700052,
  'created': 1756056224470,
  'email_address_verified': None}]

You can search by email address to ONLY get the user that has that email address:

>>> hub.system.user_search('[email protected]')
[{'account_id': 'd0bdabfd-850e-4c8d-8510-f6f1ecb9a5eb',
  'first_name': 'W',
  'last_name': 'Stein',
  'name': None,
  'email_address': '[email protected]',
  'last_active': 1756503700052,
  'created': 1756056224470,
  'email_address_verified': None}]
Source code in src/cocalc_api/hub.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
@api_method("system.userSearch")
def user_search(self, query: str) -> UserSearchResult:
    """
    Search for existing users by name or email address.

    Args:
        query (str): A query, e.g., partial name, email address, etc.

    Returns:
        UserSearchResult: Array of dicts with account_id, name,
            first_name, last_name, last_active (in ms since epoch),
            created (in ms since epoch) and email_address_verified.

    Examples:
        Search for myself:

        >>> import cocalc_api; hub = cocalc_api.Hub(api_key="sk...")
        >>> hub.system.user_search('w')
        [{'account_id': 'd0bdabfd-850e-4c8d-8510-f6f1ecb9a5eb',
          'first_name': 'W',
          'last_name': 'Stein',
          'name': None,
          'last_active': 1756503700052,
          'created': 1756056224470,
          'email_address_verified': None}]

        You can search by email address to ONLY get the user
        that has that email address:

        >>> hub.system.user_search('[email protected]')
        [{'account_id': 'd0bdabfd-850e-4c8d-8510-f6f1ecb9a5eb',
          'first_name': 'W',
          'last_name': 'Stein',
          'name': None,
          'email_address': '[email protected]',
          'last_active': 1756503700052,
          'created': 1756056224470,
          'email_address_verified': None}]
    """
    ...  # pragma: no cover