Users: Swarm users
Get a list of users
Summary
Get a list of users.
GET /api/v11/users
Description
Returns a list of users in Swarm.
Parameters
Parameter | Description | Type | Parameter Type | Required |
---|---|---|---|---|
ids |
An optional single string or an array of users to display. Omitting this parameter or passing an empty value shows all users. |
string |
query |
No |
ignoreExcludeList |
Determines if the list of users has the user_exclude_list filter applied or not. Add the parameter to ignore the user_exclude_list filter. |
boolean |
query |
No |
Example usage
Get a list of users
curl -u "username:ticket" "https://myswarm-url/api/v11/users"
Swarm responds with all users in Swarm:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"users": [
{
"id": "bruno",
"type": "standard",
"email": "bruno@perforce.com",
"update": "2013/10/11 21:05:15",
"access": "2021/01/21 16:55:38",
"fullName": "Bruno First",
"jobView": null,
"password": null,
"authMethod": "perforce",
"reviews": []
},
...
<other users formatted as above>
...
}
]
}
}
Fetch a specific user
To fetch details for bruno:
curl -u "username:ticket" "https://myswarm-url/api/v11/users?ids=bruno"
Swarm responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"users": [
{
"id": "bruno",
"type": "standard",
"email": "bruno@perforce.com",
"update": "2013/10/11 21:05:15",
"access": "2021/01/21 16:55:38",
"fullName": "Bruno First",
"jobView": null,
"password": null,
"authMethod": "perforce",
"reviews": []
}
]
}
}
Fetch a number of specific users
To fetch details for bruno and alice:
curl -u "username:ticket" "https://myswarm-url/api/v11/users?ids[]=bruno&ids[]=alice"
Swarm responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"users": [
{
"id": "bruno",
"type": "standard",
"email": "bruno@perforce.com",
"update": "2013/10/11 21:05:15",
"access": "2021/01/21 16:55:38",
"fullName": "Bruno First",
"jobView": null,
"password": null,
"authMethod": "perforce",
"reviews": []
},
{
"user": "alice",
"type": "standard",
"email": "asmith@perforce.com",
"update": "2018/09/11 18:17:14",
"access": "2020/12/24 16:55:38",
"fullName": "Alice Smith",
"jobView": null,
"password": null,
"authMethod": "perforce",
"reviews": []
}
]
}
}
If a request fails
<error code>:
401 Incorrect or missing credentials
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}
Get information for a specific user
Summary
Get information for a specific user.
GET /api/v11/users/{id}
Description
Returns information for a specific user in Swarm.
Parameters
Parameter | Description | Type | Parameter Type | Required |
---|---|---|---|---|
id |
User ID |
string |
path |
Yes |
Example usage
Get information for a specific user
To fetch information for bruno:
curl -u "username:ticket" "https://myswarm-url/api/v11/users/bruno"
Swarm responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"users": [
{
"id": "bruno",
"type": "standard",
"email": "bruno@perforce.com",
"update": "2013/10/11 21:05:15",
"access": "2021/01/21 16:55:38",
"fullName": "Bruno First",
"jobView": null,
"password": null,
"authMethod": "perforce",
"reviews": []
}
]
}
}
If a request fails
<error code>:
- 401 Incorrect or missing credentials
- 404 User does not exist
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}
Check for user deletion or add user for deletion in Swarm
Summary
Check if a user has been successfully deleted from the user profile, test definitions, workflows, projects, or groups.
POST /api/v11/users/{id}/cleanup
Description
When a user is deleted from the Helix Core Server, Swarm automatically removes the deleted user from the user configuration, test definitions, workflows, projects, or groups. An admin user can use this API endpoint to determine if a user is successfully deleted from Swarm or if a user is not deleted, Swarm adds the cleanup action for that user in the queue . For more information about how Swarm handles deleted users, see How Swarm handles deleted users .
Parameters
Parameter | Description | Type | Parameter Type | Required |
---|---|---|---|---|
id |
User ID |
string |
path |
Yes |
Example usage
Check if a user has been successfully deleted across all entities in Swarm
To check if user bruno is successfully deleted from Swarm:
curl -u "username:ticket" -X POST "https://myswarm-url/api/v11/users/bruno/cleanup"
Swarm responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": {
"code": 200,
"text": {
"testdefinition": "The requested user bruno does not exist in any testdefinition",
"workflow": "The requested user bruno does not exist in any workflow",
"project": "Your request to clean up project for the deleted user bruno has been queued",
"group": "Your request to clean up group for the deleted user bruno has been queued",
"followers": "Your request to clean up followers for the deleted user bruno has been queued"
}
},
"data": []
}
Check if a user has been successfully deleted from all test definitions in Swarm
To check if user bruno is successfully deleted from all test definitions in Swarm:
curl -u "username:ticket" -X POST "https://myswarm-url/api/v11/users/bruno/cleanup/testdefinition"
Swarm responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": {
"code": 200,
"text": "The requested user bruno does not exist in any test definition"
},
"data":[]
}
Check if a user has been successfully deleted from all workflows in Swarm
To check if user bruno is successfully deleted from all workflows in Swarm:
curl -u "username:ticket" -X POST "https://myswarm-url/api/v11/users/bruno/cleanup/workflow"
Swarm responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": {
"code": 200,
"text": "Your request to clean up workflow for the deleted user bruno has been queued"
},
"data":[]
}
Check if a user has been successfully deleted from all projects in Swarm
To check if user bruno is successfully deleted from all projects in Swarm:
curl -u "username:ticket" -X POST "https://myswarm-url/api/v11/users/bruno/cleanup/projects"
Swarm responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": {
"code": 200,
"text": "The requested user bruno does not exist in any project"
},
"data":[]
}
Check if a user has been successfully deleted from all groups in Swarm
To check if user bruno is successfully deleted from all groups in Swarm:
curl -u "username:ticket" -X POST "https://myswarm-url/api/v11/users/bruno/cleanup/groups"
Swarm responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": {
"code": 200,
"text": "Your request to clean up group for the deleted user bruno has been queued"
},
"data":[]
}
Check if a user has been successfully deleted from the user configuration in Swarm
To check if user bruno is successfully deleted from the user configuration in Swarm:
curl -u "username:ticket" -X POST "https://myswarm-url/api/v11/users/bruno/cleanup/config"
Swarm responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": {
"code": 200,
"text": "The requested user bruno does not exist in any config"
},
"data":[]
}
If a request fails
<error code>:
- 400 User is active and not yet deleted
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}