<< Back to GForge REST API

Entity: User

GET

getActivityLog

Parameters (7)

Name Type Description
id string The database ID or unix name of the user whose activity log to retrieve.
startDate string Start date for the activity range (inclusive). Default: 1970-01-01.
endDate string End date for the activity range (inclusive). Default: now.
max int Maximum number of activity log entries to return. Default: 20.
page_num int Page number (1-based). Default: 1.
rel string Comma-separated list of related entity types to include. Pass project to include project data on each log entry.
project string The database ID or unix name of a project to scope results.
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Related Entities (1)

rel= Type Description
\gforge\core\models\api\ProjectBasic project

Return: \gforge\core\models\api\ActivityLogBasic[]

Name Type Description
id int Unique database field for the activity log
date \datetimetz Date and time of the log
section string Type of the associated object
refId int Id of object associated with this activity log
description string Description of the action that was logged
activityType string Type of activity
url string Url associated with the log
userApiUrl string Api url of user
projectApiUrl string Api url of project
userId int Unique identifier for the user
project \models\Project
projectId int
extendedData object Additional information about the target of this activity record (e.g., tracker item, document, wiki page, user, etc.). Fields and format depend on the target object.

Example 1

Get activity log for gforgeadmin user, with defaults set 
     GET http://next.centos6-restapi.example.com/api/user/gforgeadmin/activitylog

{
 "paging":{
    "page_size":20,
    "page_num":1,
    "sort_field":"id",
    "sort_dir":"asc"
 },
 "items":[
    {
       "id":915,
       "date":"2015-02-05 16:23:13 -0300",
       "section":"trackeritem",
       "refId":95,
       "description":null,
       "activityType":"create",
       "url":"\/gf\/project\/test_phash\/tracker\/?action=TrackerItemEdit&tracker_item_id=95",
       "userApiUrl":"\/api\/user\/101",
       "projectApiUrl":"\/api\/project\/",
       "userId":101,
       "projectId":null,
       "project":null,
       "extendedData":{
          "tracker_item_id":95,
          "tracker_id":204,
          "status_id":1,
          "priority":3,
          "submitted_by":101,
          "open_date":"2015-02-05 19:23:12",
          "close_date":null,
          "summary":"Testing 123",
          "details":"\nTesting 123\n",
          "last_modified_date":"2015-02-05 19:23:12",
          "last_modified_by":0,
          "sort_order":0,
          "parent_id":0,
          "has_subitems":false,
          "subitems_count":0,
          "waiting_for":0,
          "sprint_id":null,
          "tracker_name":"Bugs"
       }
    },
    {
       "id":916,
       "date":"2015-02-05 13:26:16 -0300",
       "section":"trackeritem",
       "refId":96,
       "description":null,
       "activityType":"create",
       "url":"\/gf\/project\/test_phash\/tracker\/?action=TrackerItemEdit&tracker_item_id=96",
       "userApiUrl":"\/api\/user\/101",
       "projectApiUrl":"\/api\/project\/",
       "userId":101,
       "projectId":null,
       "project":null,
       "extendedData":{
          "tracker_item_id":96,
          "tracker_id":204,
          "status_id":1,
          "priority":3,
          "submitted_by":101,
          "open_date":"2015-02-05 16:26:16",
          "close_date":null,
          "summary":"Testing tracker item",
          "details":"\nTesting tracker item\n",
          "last_modified_date":"2015-02-05 16:26:16",
          "last_modified_by":0,
          "sort_order":0,
          "parent_id":0,
          "has_subitems":false,
          "subitems_count":0,
          "waiting_for":0,
          "sprint_id":null,
          "tracker_name":"Bugs"
       }
    }
 ],
 "links":[

 ]
}

Example 2

Get activity log with projects, with all parameters set and associated related data 
     GET http://next.centos6-restapi.example.com/api/user/gforgeadmin/activitylog?rel=project&startDate=2015-01-01&endDate=2015-02-01&max=10


 {
 "paging":{
    "page_size":20,
    "page_num":1,
    "sort_field":"id",
    "sort_dir":"asc"
 },
 "items":[
    {
       "id":914,
       "date":"2015-01-27 13:07:04 -0300",
       "section":"wiki",
       "refId":47,
       "description":null,
       "activityType":"update",
       "url":"\/gf\/project\/testing3\/wiki\/?pagename=NewPage",
       "userApiUrl":"\/api\/user\/101",
       "projectApiUrl":"\/api\/project\/",
       "userId":101,
       "projectId":null,
       "project":{
          "id":47,
          "name":"test_export",
          "unixName":"testing3",
          "description":"test_export",
          "homepageUrl":"\/gf\/project\/testing3\/",
          "createDate":"2013-08-02 05:33:45 -0300",
          "isPublic":"Y",
          "status":1,
          "isTemplate":"N",
          "templateProjectId":0
       },
       "extendedData":{
          "wiki_page_id":213,
          "section":"project",
          "ref_id":47,
          "pagename":"NewPage",
          "flags":0,
          "latest_version":{
          },
          "page_views":0
       }
    },
    {
       "id":913,
       "date":"2015-01-27 13:06:53 -0300",
       "section":"wiki",
       "refId":47,
       "description":null,
       "activityType":"create",
       "url":"\/gf\/project\/testing3\/wiki\/?pagename=NewPage",
       "userApiUrl":"\/api\/user\/101",
       "projectApiUrl":"\/api\/project\/",
       "userId":101,
       "projectId":null,
       "project":{
          "id":47,
          "name":"test_export",
          "unixName":"testing3",
          "description":"test_export",
          "homepageUrl":"\/gf\/project\/testing3\/",
          "createDate":"2013-08-02 05:33:45 -0300",
          "isPublic":"Y",
          "status":1,
          "isTemplate":"N",
          "templateProjectId":0
       },
       "extendedData":{
          "wiki_page_id":213,
          "section":"project",
          "ref_id":47,
          "pagename":"NewPage",
          "flags":0,
          "latest_version":null,
          "page_views":null
       }
    },
    {
       "id":912,
       "date":"2015-01-27 13:06:48 -0300",
       "section":"wiki",
       "refId":47,
       "description":null,
       "activityType":"update",
       "url":"\/gf\/project\/testing3\/wiki\/?pagename=FrontPage",
       "userApiUrl":"\/api\/user\/101",
       "projectApiUrl":"\/api\/project\/",
       "userId":101,
       "projectId":null,
       "project":{
          "id":47,
          "name":"test_export",
          "unixName":"testing3",
          "description":"test_export",
          "homepageUrl":"\/gf\/project\/testing3\/",
          "createDate":"2013-08-02 05:33:45 -0300",
          "isPublic":"Y",
          "status":1,
          "isTemplate":"N",
          "templateProjectId":0
       },
       "extendedData":{
          "wiki_page_id":171,
          "section":"project",
          "ref_id":47,
          "pagename":"FrontPage",
          "flags":0,
          "latest_version":{
          },
          "page_views":2
       }
    },
    {
       "id":911,
       "date":"2015-01-22 17:45:54 -0300",
       "section":"trackeritem",
       "refId":94,
       "description":null,
       "activityType":"create",
       "url":"\/gf\/project\/svn_test1\/tracker\/?action=TrackerItemEdit&tracker_item_id=94",
       "userApiUrl":"\/api\/user\/101",
       "projectApiUrl":"\/api\/project\/",
       "userId":101,
       "projectId":null,
       "project":{
          "id":49,
          "name":"svn_test1",
          "unixName":"svn_test1",
          "description":"testing",
          "homepageUrl":"\/gf\/project\/svn_test1\/",
          "createDate":"2013-10-17 13:36:17 -0300",
          "isPublic":"N",
          "status":1,
          "isTemplate":"N",
          "templateProjectId":41
       },
       "extendedData":{
          "tracker_item_id":94,
          "tracker_id":181,
          "status_id":1,
          "priority":3,
          "submitted_by":101,
          "open_date":"1969-12-31 23:59:59",
          "close_date":null,
          "summary":"Testing 123",
          "details":"",
          "last_modified_date":"2015-01-22 20:45:54",
          "last_modified_by":0,
          "sort_order":0,
          "parent_id":0,
          "has_subitems":false,
          "subitems_count":0,
          "waiting_for":0,
          "sprint_id":null,
          "tracker_name":"To-Do"
       }
    }
 ],
 "links":[

 ]
}

getAuthorizedKeys

Returns the SSH authorized keys configured for the specified user.

Parameters (1)

Name Type Description
id string The database ID or unix name of the user (URL segment).

Return: array

Associative array with key authorized_keys containing the raw key data.

getAvatar

Get the image representing the user. Users may upload a custom avatar, and the system also provides a default one.

Parameters (1)

Name Type Description
id mixed The database ID or unix name of the user.

Return: mixed

The user's selected avatar image data, or the data for the general avatar if the user has none.

getDetails

Get the detailed profile data for a specific user. Callers may specify the unixName or the database id in the id parameter.

Parameters (4)

Name Type Description
id string The database ID or unix name of the user to retrieve.
rel string Comma-separated list of related entity types to include. Allowed values: projects, activitylog, queue, trackeritems, chat, groups, lock, trackers, memberprojects.
project string The database ID or unix name of a project to scope related data.
max int Maximum number of activity log entries to return when activitylog rel is requested. Default: 20.

Related Entities (4)

rel= Type Description
projects \gforge\core\models\api\ProjectBasic[] The list of projects for which the user is a member.
activitylog \gforge\core\models\api\ActivityLogBasic[] The most recent actions done by the user.
queue \gforge\plugins\tracker\models\api\TrackerItemBasic[] The set of TIs in the user's queue
trackerItems \gforge\plugins\tracker\models\api\TrackerItemBasic[] The set of TIs currently assigned to the user

Return: \gforge\core\models\api\UserDetail

A UserDetail structure if the user exists. Otherwise, a NotFoundException (404 response).

Name Type Description
address string First line of physical/mailing address
address2 string Second (optional) line of physical/mailing address
dateFormat string Unix-style format for presenting dates to this user (e.g., Y-m-d H:i:s)
phone string Free-form field for user's phone number
fax string Free-form field for user's fax number
title string User's job title
createDate string Date when the account was created
lastLogin string Date/time when the account was last used
theme string ID or name of the user's preferred UI theme
userText1 string Flex field for customer use
userText2 string Flex field for customer use
userText3 string Flex field for customer use
userText4 string Flex field for customer use
userText5 string Flex field for customer use
userText6 string Flex field for customer use
isRestricted string "Y" if the account is locked/restricted, "N" otherwise (default)
useCustomAvatar string "Y" for use custom avatar, "N" for use default avatar
id int Unique database identifier for the user
unixName string Short, unix-friendly identifier for the user. This is usually also the user's shell logon.
password string Shared secret for authenticating the user. This value is only set for requests, not for responses.
firstname string First name for the user
lastname string Last name for the user
email string Email address for the user
timezone string Name of the user's time zone (from PHP std list)
status int Account status, 0 = Pending, 1 = Active, 2 = Deleted
externalId string Custom external identifier for use in sync to other systems
isGroup string Y if the specified record is a group, N if it is a single user
ccode string
language string
img_url string Relative path to the user's icon, if any
html_url string Relative path to the user's details page (display)
details_url string Relative path to the user's detail data (API)
isSiteAdmin bool
authMethod string|null
api_url string Relative path to the user's basic data (API)

Example 1

Retrieve user details for user with unix name of 'mtutty': 
  GET http://api.mygforge.tld/user/mtutty/details


{
"address":"",
"address2":"",
"time_zone":"America\/Chicago",
"dateFormat":"Y-M-D",
"phone":"",
"fax":"",
"title":"",
"createDate":"2005-09-12 00:24:33 -0500",
"lastLogin":"2013-07-25 21:34:14 -0500",
"theme":"GForge 5 default theme",
"userText1":null,
"userText2":null,
"userText3":null,
"userText4":null,
"userText5":"gforgegroup",
"userText6":null,
"isRestricted":"N",
"id":5945,
"unixName":"mtutty",
"password":null,
"firstName":"Michael",
"lastName":"Tutty",
"email":"mtutty@gforgegroup.com",
"status":1,
"externalId":null,
"isGroup":"N",
"ccode":"US",
"language":"en",
"img_url":"\/images\/custom_avatars\/5945.jpg",
"html_url":"\/gf\/user\/mtutty\/",
"details_url":"\/api\/user\/mtutty\/details",
"api_url":"\/api\/user\/mtutty"
}

Example 2

Retrieve user details and associated entities, use startDate param, for a full list check getActivityLog 
     GET http://next.centos6-restapi.example.com/api/user/gforgeadmin/details?rel=projects,activity&startDate=2014-01-01


{
 "address":null,
 "address2":"",
 "dateFormat":"Y-M-D",
 "phone":"+543413224296",
 "fax":"",
 "title":"",
 "createDate":"2006-06-12 12:37:11 -0300",
 "lastLogin":"2015-02-05 13:53:17 -0300",
 "theme":null,
 "userText1":null,
 "userText2":null,
 "userText3":null,
 "userText4":null,
 "userText5":null,
 "userText6":null,
 "isRestricted":"N",
 "id":101,
 "unixName":"gforgeadmin",
 "password":null,
 "firstname":"GForge Admin",
 "lastname":"User",
 "email":"root@gforge-as-63.example.com",
 "timezone":"GMT",
 "status":1,
 "externalId":null,
 "isGroup":"N",
 "ccode":"US",
 "language":"en   ",
 "img_url":"\/api\/user\/gforgeadmin\/avatar",
 "html_url":"\/#\/user\/gforgeadmin\/",
 "details_url":"\/api\/user\/gforgeadmin\/details",
 "isSiteAdmin":true,
 "api_url":"\/api\/user\/gforgeadmin",
 "projects":[
    {
       "id":52,
       "name":"test_parent_hash",
       "unixName":"test_phash",
       "description":"testing",
       "homepageUrl":"\/gf\/project\/test_phash\/",
       "createDate":"2013-11-06 19:28:17 -0300",
       "isPublic":"N",
       "status":1,
       "isTemplate":"N",
       "templateProjectId":4
    },
    {
       "id":40,
       "name":"test message wall",
       "unixName":"test_wall2",
       "description":"test message wall",
       "homepageUrl":"\/gf\/project\/test_wall2\/",
       "createDate":"2013-05-27 16:25:04 -0300",
       "isPublic":"Y",
       "status":1,
       "isTemplate":"N",
       "templateProjectId":0
    },
    {
       "id":42,
       "name":"test message wall",
       "unixName":"test_wall3",
       "description":"test message wall",
       "homepageUrl":"\/gf\/project\/test_wall3\/",
       "createDate":"2013-05-27 16:25:04 -0300",
       "isPublic":"N",
       "status":1,
       "isTemplate":"N",
       "templateProjectId":0
    },
    {
       "id":43,
       "name":"test_git",
       "unixName":"test_git3",
       "description":"testing",
       "homepageUrl":"\/gf\/project\/test_git3\/",
       "createDate":"2013-06-26 19:33:13 -0300",
       "isPublic":"N",
       "status":1,
       "isTemplate":"N",
       "templateProjectId":0
    },
    {
       "id":47,
       "name":"test_export",
       "unixName":"testing3",
       "description":"test_export",
       "homepageUrl":"\/gf\/project\/testing3\/",
       "createDate":"2013-08-02 05:33:45 -0300",
       "isPublic":"Y",
       "status":1,
       "isTemplate":"N",
       "templateProjectId":0
    },
    {
       "id":49,
       "name":"svn_test1",
       "unixName":"svn_test1",
       "description":"testing",
       "homepageUrl":"\/gf\/project\/svn_test1\/",
       "createDate":"2013-10-17 13:36:17 -0300",
       "isPublic":"N",
       "status":1,
       "isTemplate":"N",
       "templateProjectId":41
    },
    {
       "id":45,
       "name":"test_export",
       "unixName":"testing",
       "description":"test_export",
       "homepageUrl":"\/gf\/project\/testing\/",
       "createDate":"2013-08-02 05:33:45 -0300",
       "isPublic":"N",
       "status":1,
       "isTemplate":"N",
       "templateProjectId":4
    },
    {
       "id":51,
       "name":"test_support",
       "unixName":"test_support",
       "description":"test_support",
       "homepageUrl":"\/gf\/project\/test_support\/",
       "createDate":"2013-10-28 14:35:37 -0300",
       "isPublic":"N",
       "status":1,
       "isTemplate":"N",
       "templateProjectId":4
    },
    {
       "id":24,
       "name":"test_svn",
       "unixName":"test_svn",
       "description":"test_svn",
       "homepageUrl":"\/gf\/project\/test_svn\/",
       "createDate":"2013-06-26 19:33:47 -0300",
       "isPublic":"N",
       "status":1,
       "isTemplate":"N",
       "templateProjectId":3
    },
    {
       "id":6,
       "name":"test message wall",
       "unixName":"test_wall",
       "description":"test message wall",
       "homepageUrl":"\/gf\/project\/test_wall\/",
       "createDate":"2013-05-27 16:25:04 -0300",
       "isPublic":"N",
       "status":1,
       "isTemplate":"N",
       "templateProjectId":4
    },
    {
       "id":48,
       "name":"2testing",
       "unixName":"testing2",
       "description":"testing",
       "homepageUrl":"\/gf\/project\/testing2\/",
       "createDate":"2013-10-15 22:26:11 -0300",
       "isPublic":"N",
       "status":1,
       "isTemplate":"N",
       "templateProjectId":4
    },
    {
       "id":23,
       "name":"test_git",
       "unixName":"test_git",
       "description":"testing",
       "homepageUrl":"\/gf\/project\/test_git\/",
       "createDate":"2013-06-26 19:33:13 -0300",
       "isPublic":"N",
       "status":1,
       "isTemplate":"N",
       "templateProjectId":4
    },
    {
       "id":25,
       "name":"test_cvs",
       "unixName":"test_cvs",
       "description":"testing",
       "homepageUrl":"\/gf\/project\/test_cvs\/",
       "createDate":"2013-06-26 19:34:03 -0300",
       "isPublic":"N",
       "status":1,
       "isTemplate":"N",
       "templateProjectId":2
    },
    {
       "id":26,
       "name":"Parent project",
       "unixName":"parent_prj",
       "description":"Parent project",
       "homepageUrl":"\/gf\/project\/parent_prj\/",
       "createDate":"2013-06-28 18:18:29 -0300",
       "isPublic":"N",
       "status":1,
       "isTemplate":"N",
       "templateProjectId":4
    }
 ],
 "activity":[
    {
       "id":915,
       "date":"2015-02-05 16:23:13 -0300",
       "section":"trackeritem",
       "refId":95,
       "description":null,
       "activityType":"create",
       "url":"\/gf\/project\/test_phash\/tracker\/?action=TrackerItemEdit&tracker_item_id=95",
       "userApiUrl":"\/api\/user\/101",
       "projectApiUrl":"\/api\/project\/",
       "userId":101,
       "projectId":null,
       "project":null,
       "extendedData":{
          "tracker_item_id":95,
          "tracker_id":204,
          "status_id":1,
          "priority":3,
          "submitted_by":101,
          "open_date":"2015-02-05 19:23:12",
          "close_date":null,
          "summary":"Testing 123",
          "details":"\nTesting 123\n",
          "last_modified_date":"2015-02-05 19:23:12",
          "last_modified_by":0,
          "sort_order":0,
          "parent_id":0,
          "has_subitems":false,
          "subitems_count":0,
          "waiting_for":0,
          "sprint_id":null,
          "tracker_name":"Bugs"
       }
    },
    {
       "id":916,
       "date":"2015-02-05 13:26:16 -0300",
       "section":"trackeritem",
       "refId":96,
       "description":null,
       "activityType":"create",
       "url":"\/gf\/project\/test_phash\/tracker\/?action=TrackerItemEdit&tracker_item_id=96",
       "userApiUrl":"\/api\/user\/101",
       "projectApiUrl":"\/api\/project\/",
       "userId":101,
       "projectId":null,
       "project":null,
       "extendedData":{
          "tracker_item_id":96,
          "tracker_id":204,
          "status_id":1,
          "priority":3,
          "submitted_by":101,
          "open_date":"2015-02-05 16:26:16",
          "close_date":null,
          "summary":"Testing tracker item",
          "details":"\nTesting tracker item\n",
          "last_modified_date":"2015-02-05 16:26:16",
          "last_modified_by":0,
          "sort_order":0,
          "parent_id":0,
          "has_subitems":false,
          "subitems_count":0,
          "waiting_for":0,
          "sprint_id":null,
          "tracker_name":"Bugs"
       }
    },
    {
       "id":914,
       "date":"2015-01-27 13:07:04 -0300",
       "section":"wiki",
       "refId":47,
       "description":null,
       "activityType":"update",
       "url":"\/gf\/project\/testing3\/wiki\/?pagename=NewPage",
       "userApiUrl":"\/api\/user\/101",
       "projectApiUrl":"\/api\/project\/",
       "userId":101,
       "projectId":null,
       "project":null,
       "extendedData":{
          "wiki_page_id":213,
          "section":"project",
          "ref_id":47,
          "pagename":"NewPage",
          "flags":0,
          "latest_version":{
          },
          "page_views":0
       }
    },
    {
       "id":913,
       "date":"2015-01-27 13:06:53 -0300",
       "section":"wiki",
       "refId":47,
       "description":null,
       "activityType":"create",
       "url":"\/gf\/project\/testing3\/wiki\/?pagename=NewPage",
       "userApiUrl":"\/api\/user\/101",
       "projectApiUrl":"\/api\/project\/",
       "userId":101,
       "projectId":null,
       "project":null,
       "extendedData":{
          "wiki_page_id":213,
          "section":"project",
          "ref_id":47,
          "pagename":"NewPage",
          "flags":0,
          "latest_version":null,
          "page_views":null
       }
    },
    {
       "id":912,
       "date":"2015-01-27 13:06:48 -0300",
       "section":"wiki",
       "refId":47,
       "description":null,
       "activityType":"update",
       "url":"\/gf\/project\/testing3\/wiki\/?pagename=FrontPage",
       "userApiUrl":"\/api\/user\/101",
       "projectApiUrl":"\/api\/project\/",
       "userId":101,
       "projectId":null,
       "project":null,
       "extendedData":{
          "wiki_page_id":171,
          "section":"project",
          "ref_id":47,
          "pagename":"FrontPage",
          "flags":0,
          "latest_version":{
          },
          "page_views":2
       }
    },
    {
       "id":911,
       "date":"2015-01-22 17:45:54 -0300",
       "section":"trackeritem",
       "refId":94,
       "description":null,
       "activityType":"create",
       "url":"\/gf\/project\/svn_test1\/tracker\/?action=TrackerItemEdit&tracker_item_id=94",
       "userApiUrl":"\/api\/user\/101",
       "projectApiUrl":"\/api\/project\/",
       "userId":101,
       "projectId":null,
       "project":null,
       "extendedData":{
          "tracker_item_id":94,
          "tracker_id":181,
          "status_id":1,
          "priority":3,
          "submitted_by":101,
          "open_date":"1969-12-31 23:59:59",
          "close_date":null,
          "summary":"Testing 123",
          "details":"",
          "last_modified_date":"2015-01-22 20:45:54",
          "last_modified_by":0,
          "sort_order":0,
          "parent_id":0,
          "has_subitems":false,
          "subitems_count":0,
          "waiting_for":0,
          "sprint_id":null,
          "tracker_name":"To-Do"
       }
    }
 ]
}

getGroupUsers

Returns a list of the users that are members of the group.

Parameters (1)

Name Type Description
id string The database ID or unix name of the group (URL segment).

Return: \gforge\core\models\api\UserBasic[]

Zero or more UserBasic records.

Name Type Description
id int Unique database identifier for the user
unixName string Short, unix-friendly identifier for the user. This is usually also the user's shell logon.
password string Shared secret for authenticating the user. This value is only set for requests, not for responses.
firstname string First name for the user
lastname string Last name for the user
email string Email address for the user
timezone string Name of the user's time zone (from PHP std list)
status int Account status, 0 = Pending, 1 = Active, 2 = Deleted
externalId string Custom external identifier for use in sync to other systems
isGroup string Y if the specified record is a group, N if it is a single user
ccode string
language string
theme mixed
img_url string Relative path to the user's icon, if any
html_url string Relative path to the user's details page (display)
details_url string Relative path to the user's detail data (API)
isSiteAdmin bool
authMethod string|null
api_url string Relative path to the user's basic data (API)

getPermissions

Get the user's permissions for all projects and sections, or the specific project and section(s) if specified.

Parameters (4)

Name Type Description
id string The database ID or unix name of the user (URL segment via Route['user']).
project string The database ID or unix name of the project to filter on. Omit to return all projects.
section string A comma-separated list of zero or more plugin sections to filter on (e.g. tracker,wiki).
refId int The database ID of the specific resource within the section to filter on. Default: 0.

Return: \gforge\core\models\api\ProjectPermissionBasic

Zero or more ProjectPermissionBasic structures for the user's permissions.

Name Type Description
projectId int Unique database field for the project
unixName string unix name of the project
value int the max permission level
refId int the id of the associated entity
section string section the permission belongs to

Example 1

Retrieve permissions for user with unix name of 'mtutty': 
  GET http://api.mygforge.tld/user/mtutty/permissions

Example 2

Retrieve permissions for user with unix name of 'mtutty' on a specific project: 
  GET http://api.mygforge.tld/user/mtutty/permissions?project=myproject

Example 3

Retrieve permissions for user with unix name of 'mtutty' across all projects for specific sections: 
  GET http://api.mygforge.tld/user/mtutty/permissions?section=tracker,wiki

getPreference

Get one or more preference values for the specified user (specified in the route).

Parameters (4)

Name Type Description
id string The database ID or unix name of the user (URL segment).
search string A search term for finding preference names. If three characters or fewer, treated as a prefix match (e.g., abc%); if longer, treated as a contains match (e.g., %abcd%).
preferenceName string The specific preference to retrieve. Can also be specified as a URL route segment (e.g., /api/user/:unixName/preference/:preferenceName). If provided, overrides the search parameter and requires an exact match.
default string The value to return if the specified preference is not set. Only used when preferenceName is also specified.
Sortable
Use the sort_field and sort_dir parameters to control the order in which records are returned.
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Return: \gforge\core\models\api\UserPreferenceBasic[]|\gforge\core\models\api\UserPreferenceBasic

Zero or more preference records matching any specified criteria.

Example 1

List all of the preferences for a specific user (NOTE: You must be this user or a site admin): 
GET /api/user/mtutty/preference


{"paging":{"page_size":20,"page_num":1,"sort_field":"id","sort_dir":"asc"},
"items":[
    {
     "preferenceName":"forumsvdt_8310",
     "setDate":"2013-09-27 12:01:43 -0500",
     "preferenceValue":"1380301303|1379696503",
     "user":{...user basic...}
    },
    ... additional items...
  ]
}

Example 2

Retrieve a any preference records for this user where the preferenceName contains the substring "chat-room-". 
GET /api/user/mtutty/preference?search=chat-room-


{"paging":{"page_size":20,"page_num":1,"sort_field":"id","sort_dir":"asc"},
"items":[
    {
     "preferenceName":"chat-room-5559",
     "setDate":"2013-09-18 08:44:16 -0500",
     "preferenceValue":"N",
     "user":{...user basic...}
    },
    ... additional items...
  ]
}

Example 3

Retrieve a single preference record that exactly matches "trkquery9878". If the record does not exist, return a fake record with the specified default value of "NOPE"
Note: This usage will not return paged data, only a single record with the existing value or the specified default, or a 404 if no default is specified. 
GET /api/user/mtutty/preference/trkquery9878?default=NOPE


{
 "preferenceName":"trkquery9878",
 "setDate":"2014-10-07 16:08:41 -0500",
 "preferenceValue":{
     "tracker_query_id":"9097",
     "show":25,
     "start":0
    },
 "user":{...user basic...}
}

getProjects

Get the projects for which the user is a member.

Parameters (7)

Name Type Description
id string The database ID or unix name of the user (URL segment).
sort_field string Field to sort results by. One of: id, unixName, projectName, activity. Default: activity.
sort_dir string Sort direction. asc or desc. Default: asc.
page_num int Page number (0-based). Default: 0.
page_size int Number of results per page. Default: 20.
q string Optional free-text search filter applied to project names.
isOrg string If set, filter to organisation projects (true) or non-organisation projects (false). Omit to return all.
Sortable
Use the sort_field and sort_dir parameters to control the order in which records are returned.
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Return: \gforge\core\models\api\ProjectBasic[]

Zero or more ProjectBasic structures for the user's member projects.

Name Type Description
id int Unique database identifier for the project
name string Name of the project
unixName string Short, unix-friendly identifier for the project. This is usually also the project's shell logon.
description string Public description for the project
homepageUrl string GFAS url for the project
createDate \DateTime Date of project creation
isPublic string Returns "Y" if the project is public, "N" otherwise
status string Returns the status code for the project
isTemplate string Returns "Y" if the project is a template
templateProjectId int Returns the project used as template for this project
parentProjectId string Returns the parent project id for this project --- used as output, not allowed for input
averageRating int Returns the average rate for the project

Example 1

Retrieve projects for user with unix name of 'mtutty': 
  GET http://api.mygforge.tld/user/mtutty/projects

getQueue

Get the Tracker Item Queue for the specified user.

Parameters (4)

Name Type Description
id string The database ID or unix name of the user (URL segment).
project string The database ID or unix name of a project to scope the queue results.
page_num int Page number (0-based). Default: 0.
page_size int Number of results per page. Default: 10.
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Return: \StdClass

Zero or more \gforge\plugins\tracker\models\api\TrackerItemBasic structures, one for each item in the queue. The items are presented in the sort order defined by the user.

getSSOUnixName

Returns the unix name derived from the current SSO session.

Parameters (0)

Name Type Description
No parameters

Return: string

The unix name for the SSO-authenticated user, prefixed with u if numeric.

getTrackerItems

Retrieves a list of the user's assigned tracker items.

Parameters (6)

Name Type Description
id string The database ID or unix name of the user (URL segment).
projects string The database ID or unix name of a project, or comma-separated list of project IDs, to filter results by. Ignored when trackers is also specified.
trackers string Comma-separated list of tracker IDs to filter by.
queue string If false, excludes queue items. Default: include queue items.
page_num int Page number (0-based). Default: 0.
page_size int Number of results per page. Default: no limit.
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Return: \StdClass

Zero or more Tracker Items that are assigned to the user.

getUser

Searches for users matching criteria, or retrieves a specific user by unixname or database ID.

Parameters (13)

Name Type Description
id string The database ID or unix name of the user to retrieve. Omit to search.
rel string Comma-separated list of related entity types to include (e.g. projects).
sort_field string Field to sort results by. One of: id, unixName, firstname, lastname, email, status, externalId, isGroup. Default: unixName.
sort_dir string Sort direction. asc or desc. Default: asc.
page_num int Page number (0-based). Default: 0.
page_size int Number of results per page. Default: 20.
ids string Comma-separated list of user IDs to filter by (site admin only).
since string Filter to users active since this date string (site admin only).
admin int Filter to site admin users when non-zero (site admin only).
text string Free-text search filter across user fields.
ip string IP address filter (site admin only).
group int If non-zero, filter to group accounts only.
member string Filter to members of the specified project (unix name or ID).
Sortable
Use the sort_field and sort_dir parameters to control the order in which records are returned.
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Return: array

Zero or more \gforge\core\models\api\UserBasic records for a search. Zero or one record for an id retrieval.

Example 1

Find a user by matching last name: 
  GET http://api.mygforge.tld/user?lastName=tutty


  {
     "id":5945,
     "unixName":"mtutty",
     "password":null,
     "firstName":"Michael",
     "lastName":"Tutty",
     "email":"mtutty@gforgegroup.com",
     "status":1,
     "externalId":null,
     "isGroup":"N",
     "ccode":"US",
     "language":"en   ",
     "img_url":"\/images\/custom_avatars\/5945.jpg",
     "html_url":"\/gf\/user\/mtutty\/",
     "details_url":"\/api\/user\/mtutty\/details",
     "api_url":"\/api\/user\/mtutty"
  }

Example 2

Find a user by database ID: 
  GET http://api.mygforge.tld/user/5945


  {
     "id":5945,
     "unixName":"mtutty",
     "password":null,
     "firstName":"Michael",
     "lastName":"Tutty",
     "email":"mtutty@gforgegroup.com",
     "status":1,
     "externalId":null,
     "isGroup":"N",
     "ccode":"US",
     "language":"en   ",
     "img_url":"\/images\/custom_avatars\/5945.jpg",
     "html_url":"\/gf\/user\/mtutty\/",
     "details_url":"\/api\/user\/mtutty\/details",
     "api_url":"\/api\/user\/mtutty"
  }

Example 3

List all users in active status: 
  GET http://api.mygforge.tld/user?status=1


[
 {
    "id":24507,
    "unixName":"00090007",
    "password":null,
    "firstName":"sadas",
    "lastName":"sadasdsa",
    "email":"sherwun@live.hk",
    "status":1,
    "externalId":null,
    "isGroup":"N",
    "ccode":"HK",
    "language":"tw   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/00090007\/",
    "details_url":"\/api\/user\/00090007\/details",
    "api_url":"\/api\/user\/00090007"
 },
 {
    "id":14468,
    "unixName":"00700",
    "password":null,
    "firstName":"\u5f20",
    "lastName":"\u4e09",
    "email":"50599216@qq.com",
    "status":1,
    "externalId":null,
    "isGroup":"N",
    "ccode":"CN",
    "language":"zh   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/00700\/",
    "details_url":"\/api\/user\/00700\/details",
    "api_url":"\/api\/user\/00700"
 },
 {
    "id":30294,
    "unixName":"008byebye",
    "password":null,
    "firstName":"peng",
    "lastName":"yuan",
    "email":"532549992@qq.com",
    "status":1,
    "externalId":null,
    "isGroup":"N",
    "ccode":"AF",
    "language":"zh   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/008byebye\/",
    "details_url":"\/api\/user\/008byebye\/details",
    "api_url":"\/api\/user\/008byebye"
 },
 {
    "id":12624,
    "unixName":"00veni",
    "password":null,
    "firstName":"Veni",
    "lastName":"Soni",
    "email":"00veerei@gmail.com",
    "status":1,
    "externalId":null,
    "isGroup":"N",
    "ccode":"IN",
    "language":"en   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/00veni\/",
    "details_url":"\/api\/user\/00veni\/details",
    "api_url":"\/api\/user\/00veni"
 },
 {
    "id":12578,
    "unixName":"0873",
    "password":null,
    "firstName":"tom",
    "lastName":"corn",
    "email":"cornererbody@aol.com",
    "status":1,
    "externalId":null,
    "isGroup":"N",
    "ccode":"US",
    "language":"en   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/0873\/",
    "details_url":"\/api\/user\/0873\/details",
    "api_url":"\/api\/user\/0873"
 },
 {
    "id":10770,
    "unixName":"08mobile",
    "password":null,
    "firstName":"Yolanda",
    "lastName":"Olwage",
    "email":"info@08mobile.com",
    "status":1,
    "externalId":"\n",
    "isGroup":"N",
    "ccode":"ZA",
    "language":"en   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/08mobile\/",
    "details_url":"\/api\/user\/08mobile\/details",
    "api_url":"\/api\/user\/08mobile"
 },
 {
    "id":9400,
    "unixName":"0dbfs",
    "password":null,
    "firstName":"Jonathan",
    "lastName":"Breurtner",
    "email":"j.breurtner@dbfullscale.com",
    "status":1,
    "externalId":"\n",
    "isGroup":"N",
    "ccode":"US",
    "language":"en   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/0dbfs\/",
    "details_url":"\/api\/user\/0dbfs\/details",
    "api_url":"\/api\/user\/0dbfs"
 },
 {
    "id":31295,
    "unixName":"1025zhangrui",
    "password":null,
    "firstName":"\u745e",
    "lastName":"\u5f20",
    "email":"1025zhangrui@163.com",
    "status":1,
    "externalId":null,
    "isGroup":"N",
    "ccode":"AF",
    "language":"en   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/1025zhangrui\/",
    "details_url":"\/api\/user\/1025zhangrui\/details",
    "api_url":"\/api\/user\/1025zhangrui"
 },
 {
    "id":29173,
    "unixName":"10822123",
    "password":null,
    "firstName":"sky",
    "lastName":"sky",
    "email":"10822123@qq.com",
    "status":1,
    "externalId":null,
    "isGroup":"N",
    "ccode":"AF",
    "language":"en   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/10822123\/",
    "details_url":"\/api\/user\/10822123\/details",
    "api_url":"\/api\/user\/10822123"
 },
 {
    "id":18564,
    "unixName":"111111",
    "password":null,
    "firstName":"111111",
    "lastName":"111111",
    "email":"marewrch_yuan@yahoo.com.cn",
    "status":1,
    "externalId":null,
    "isGroup":"N",
    "ccode":"CN",
    "language":"zh   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/111111\/",
    "details_url":"\/api\/user\/111111\/details",
    "api_url":"\/api\/user\/111111"
 },
 {
    "id":25551,
    "unixName":"11111111",
    "password":null,
    "firstName":"111",
    "lastName":"111",
    "email":"910111100@qq.com",
    "status":1,
    "externalId":null,
    "isGroup":"N",
    "ccode":"BA",
    "language":"zh   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/11111111\/",
    "details_url":"\/api\/user\/11111111\/details",
    "api_url":"\/api\/user\/11111111"
 },
 {
    "id":29225,
    "unixName":"112clcool",
    "password":null,
    "firstName":"liang",
    "lastName":"cai",
    "email":"112clrwerwecool@gmail.com",
    "status":1,
    "externalId":null,
    "isGroup":"N",
    "ccode":"CN",
    "language":"zh   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/112clcool\/",
    "details_url":"\/api\/user\/112clcool\/details",
    "api_url":"\/api\/user\/112clcool"
 },
 {
    "id":25938,
    "unixName":"1227266822",
    "password":null,
    "firstName":"12",
    "lastName":"213",
    "email":"1227266822@qq.com",
    "status":1,
    "externalId":null,
    "isGroup":"N",
    "ccode":"AF",
    "language":"zh   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/1227266822\/",
    "details_url":"\/api\/user\/1227266822\/details",
    "api_url":"\/api\/user\/1227266822"
 },
 {
    "id":18090,
    "unixName":"123",
    "password":null,
    "firstName":"123",
    "lastName":"123",
    "email":"bai-xewrwerve@foxmail.com",
    "status":1,
    "externalId":null,
    "isGroup":"N",
    "ccode":"AF",
    "language":"en   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/123\/",
    "details_url":"\/api\/user\/123\/details",
    "api_url":"\/api\/user\/123"
 },
 {
    "id":32499,
    "unixName":"1231111",
    "password":null,
    "firstName":"11",
    "lastName":"11",
    "email":"398340908@qq.com",
    "status":1,
    "externalId":null,
    "isGroup":"N",
    "ccode":"US",
    "language":"en   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/1231111\/",
    "details_url":"\/api\/user\/1231111\/details",
    "api_url":"\/api\/user\/1231111"
 },
 {
    "id":28866,
    "unixName":"123123",
    "password":null,
    "firstName":"123123",
    "lastName":"123123",
    "email":"cesrewhiq@gmail.com",
    "status":1,
    "externalId":null,
    "isGroup":"N",
    "ccode":"CN",
    "language":"zh   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/123123\/",
    "details_url":"\/api\/user\/123123\/details",
    "api_url":"\/api\/user\/123123"
 },
 {
    "id":31373,
    "unixName":"1234",
    "password":null,
    "firstName":"aa",
    "lastName":"aa",
    "email":"597730326@qq.com",
    "status":1,
    "externalId":null,
    "isGroup":"N",
    "ccode":"AF",
    "language":"en   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/1234\/",
    "details_url":"\/api\/user\/1234\/details",
    "api_url":"\/api\/user\/1234"
 },
 {
    "id":10145,
    "unixName":"1234554321",
    "password":null,
    "firstName":"Max",
    "lastName":"k",
    "email":"maximkwerwqashin@yandex.ru",
    "status":1,
    "externalId":"\n",
    "isGroup":"N",
    "ccode":"RU",
    "language":"en   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/1234554321\/",
    "details_url":"\/api\/user\/1234554321\/details",
    "api_url":"\/api\/user\/1234554321"
 },
 {
    "id":9377,
    "unixName":"123456",
    "password":null,
    "firstName":"aa",
    "lastName":"aa",
    "email":"orhjagg05@gmail.com",
    "status":1,
    "externalId":"\n",
    "isGroup":"N",
    "ccode":"ES",
    "language":"es   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/123456\/",
    "details_url":"\/api\/user\/123456\/details",
    "api_url":"\/api\/user\/123456"
 },
 {
    "id":18812,
    "unixName":"1234561",
    "password":null,
    "firstName":"123",
    "lastName":"456",
    "email":"thewerlego_mawerster@hotmail.com",
    "status":1,
    "externalId":null,
    "isGroup":"N",
    "ccode":"BB",
    "language":"en   ",
    "img_url":"\/images\/stock_avatars\/default.png",
    "html_url":"\/gf\/user\/1234561\/",
    "details_url":"\/api\/user\/1234561\/details",
    "api_url":"\/api\/user\/1234561"
 }
]

getUserTopProjects

Returns a list of most active projects for a given user

Parameters (2)

Name Type Description
id string The database ID or unix name of the user. Defaults to the authenticated user.
rt string If set to any truthy value, forces a cache refresh (debugging use).

Return: \gforge\core\models\api\ProjectBasic[]|null

getWall

Get the wall posts for a user.

Parameters (10)

Name Type Description
id string The database ID or unix name of the user (URL segment).
page_num int Page number (0-based). Default: 0.
page_size int Number of results per page. Default: 20.
sort_dir string Sort direction. asc or desc. Default: desc.
sort_field string Field to sort results by. One of: id, postDate, user, itemSection, itemRefId, project. Default: id.
user string Filter by posting user (unix name or ID).
comment string Filter by comment text.
itemSection string Filter by item section name.
itemRefId string Filter by item reference ID.
project string Filter by project (unix name or ID).
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Return: \gforge\core\models\api\WallPostBasic[]

Zero or more WallPostBasic structures for the user's wall posts.

Name Type Description
id int Unique database field for the wall post
date \datetimetz Date and time of the posting
section string Type of the associated target
refId int Id of target with this wall post
itemSection string Type of the associated object
itemRefId int Id of object associated with this wall post
comment string Message content
user \gforge\core\models\api\UserBasic Info about the person who posted the wall message
project \gforge\core\models\api\ProjectBasic Info about the project to which the post belongs to

Example 1

Retrieve recent wall posts for user with unix name of 'mtutty': 
  GET http://api.mygforge.tld/user/mtutty/wall

POST

postAdmin

Grant site admin status to a user.

Parameters (1)

Name Type Description
id string The database ID or unix name of the user to promote (URL segment).

Return: void

postAuthorizedKeys

Sets the SSH authorized keys for the specified user.

Parameters (2)

Name Type Description
id string The database ID or unix name of the user (URL segment).
authorized_keys string The full set of authorized SSH public keys, newline-delimited.

Return: array

Associative array with key authorized_keys containing the saved key data.

postChange

Completes a password reset flow using a confirmation hash sent via email.

Parameters (4)

Name Type Description
id string The database ID or unix name of the user requesting the password change (URL segment).
unixName string The unix name of the user. Must match the confirmation hash.
confirmationHash string The alphanumeric confirmation hash generated during the reset request.
password string The new password to set.

Return: void

postDetails

Update details for the specified user profile. Callers may specify the unixName or the database id in the id parameter.

Parameters (18)

Name Type Description
id string The database ID or unix name of the user to update (URL segment). If omitted, a site admin may create a new user record directly.
address string Line 1 of the user's address. Optional field, no validation.
address2 string Line 2 of the user's address. Optional field, no validation.
time_zone string GMT offset or region name for the user's time zone.
dateFormat string User's preferred date format, e.g., Y-M-D.
phone string User's voice phone number. Optional field, no validation.
fax string User's fax number. Optional field, no validation.
title string User's position description or job title. Optional field, no validation.
createDate string Read-only. Date and time when the user record was created.
lastLogin string Read-only. Date and time of the user's last successful login.
theme string Short name for the user's preferred theme. Can only be set if the GForge instance supports per-user theme selection.
userText1 string Optional custom field, no validation.
userText2 string Optional custom field, no validation.
userText3 string Optional custom field, no validation.
userText4 string Optional custom field, no validation.
userText5 string Optional custom field, no validation.
userText6 string Optional custom field, no validation.
isRestricted bool Read-only. Identifies restricted accounts; administrative use only.

Return: array

A \gforge\core\models\api\UserDetail structure with updated values, if the user exists and was updated. If invalid data was provided, then a 400 (Bad Request) with a JSON-encoded list of validation issues. If the user does not exist, a 404 (NotFoundException).

postEmail

First step of user registration. Receives an email address and sends back an email with a token in response

Parameters (3)

Name Type Description
email string The email address for which to initiate registration or an email change request.
id string The unix name of an existing user when requesting an email change. Pass 0 or omit when registering a new account.
validateonly bool If true, validate the email without sending a confirmation message. Default: false.

Return: void

Example 1

Request creating a user for email 'some@email.com' 
POST http://api.mygforge.com/user/0/email
{ "email": "some@email.com" }

postEmailConfirm

Receives a unix name, email and an email change request token. Validates and confirms (persists) the new email for the given user.

Parameters (3)

Name Type Description
email string The new email address to set for the user.
id string The unix name of the user whose email is being changed (URL segment).
token string The token to validate against the email change request. Must be active (non-expired).

Return: void

Example 1

POST http://api.mygforge.com/api/user/someUnixName/emailconfirm


"email": "some@email.com",
"token":"asljdalksjdioweurnf"

postGroup

Creates a new group

Parameters (2)

Name Type Description
unixName string The unique unix name for the new group.
user_ids string Comma-separated list of user IDs to add to the new group.

Return: \gforge\core\models\api\GroupApi|null

The newly created group record.

postJoinProject

Redeems a project invitation token for the authenticated user. The invitation in the database includes the user, project and role for validation.

Parameters (1)

Name Type Description
token string The invitation token received via email (URL segment).

Return: \StdClass

Result data for the joined project.

postMobile

Enable or disable device push notifications.

Parameters (3)

Name Type Description
id string The database ID or unix name of the user (URL segment).
mode string Action to perform. add to register the device, remove to unregister it.
clientId string The device-specific ID used to push notifications to the device.

Return: array|object|string

postPassword

Change the password for the current user.

Parameters (3)

Name Type Description
id string The database ID or unix name of the user (URL segment).
oldPassword string The user's current password. Required unless the caller is a site admin changing another user's password, or the session was authenticated via OIDC.
password string The new password to set.

Return: void

Example 1

POST http://api.mygforge.com/api/user/myuser/password
password=newpasswd


200 OK

postPreference

Deprecated!
Do not use this method for new development. It probably still works, but is no longer supported.

See putPreference.

Parameters (1)

Name Type Description
request \RequestParameters

Return: (none)

postQueue

Add a single Tracker Item to the specified user's queue. This is subject to some rules, which are checked before allowing the action:

  1. Anonymous POSTs are not allowed.
  2. The requesting user must also be the target user, or an admin for the TI's project, or a site admin
  3. The target user must be able to update the specified TI
  4. If the TI is already in the target user's queue, no action will be taken, and no error will be reported.

Parameters (2)

Name Type Description
id string The database ID or unix name of the user (URL segment).
tracker_item_id int The database ID of the Tracker Item to be added to the user's queue.

Return: array

Location URL of the user's queue resource.

postRegister

Creates a new user

Parameters (10)

Name Type Description
unixName string Desired username. Must be unique among all users.
password string Login secret for the new account.
email string User's email address. Must be unique among all users.
firstName string User's first (given) name.
lastName string User's last (family) name.
ccode string Two-character country code for I18N. Default: US.
language string Two-character language code for I18N. Default: en.
theme string Theme ID or theme dirname.
timezone string GMT offset or region name for the user's time zone. Default: UTC.
registrationToken string Token received via the postEmail step. Required for non-admin registrations when SSO is not in use.

Return: string

Location URL of the newly created user resource.

Example 1

Create user with unix_name 'usertest1': 
POST http://api.mygforge.com/user


"unixName":"usertest1",
"password":"some_password",
"confirmPassword":"some_password",
"email":"user@example.com"
"firstname":"My first name",
"lastname":"My last name",
"ccode":"US" ,
"language":"EN",
"theme":"1",
"timezone":"America/New_York"

postReset

Requests a password reset for a user. Accepts either a unix name or an email address.

Parameters (1)

Name Type Description
id string The unix name or email address of the user requesting the password reset (URL segment).

Return: void

postToken

Based on an email and a token, validates the token. Throws a proper exception if invalid.

Parameters (2)

Name Type Description
email string The email address to check the token against.
token string The registration token to validate against the email. Must be active (non-expired).

Return: void

Example 1

POST http://api.mygforge.com/api/user/0/token


"email": "some@email.com",
"token":"asljdalksjdioweurnf"

postUser

Updates an existing User. See individual field notes for applicability in submitting values.

Parameters (16)

Name Type Description
id string The database ID or unix name of the user to update (URL segment). If omitted or zero, the call is routed to postRegister() to create a new user.
unixName string Unique username identifier. May be set when creating a user; cannot be changed after creation. Must be unique among all users in the system.
password string Login secret for the user. Can be submitted for new or updated records.
firstName string User's first (given) name.
lastName string User's last (family) name.
email string User's email address. Must be unique among all users in the system.
status int User account status. 0 = awaiting approval, 1 = active, 2 = inactive/deleted.
externalId string An unparsed, unvalidated field for use in external integrations.
isGroup bool Ignored. Value is always N. Groups are not currently creatable via API.
ccode string Two-character country code for I18N.
language string Two-character language code for I18N.
theme string Theme ID or theme dirname.
img_url string Read-only. Relative URL for the user's selected avatar image.
html_url string Read-only. Relative URL for the HTML version of the user's data.
details_url string Read-only. Relative URL for the user's detailed data (see getDetails method).
api_url string Read-only. Relative URL for the user's basic data (see getUser method).

Return: array|\User

PUT

putGroup

Set the entire set of users in a single call.

Parameters (2)

Name Type Description
id string The database ID or unix name of the group (URL segment).
user_ids string Comma-separated list of user IDs that comprise the full membership of the group.

Return: void

putPreference

Saves a user preference.
Returns 200 (OK) on success, 404 (Not Found) if the user does not exist, 403 (Forbidden) if the user is not allowed, 400 (Bad Request) otherwise with validation failure(s)

Parameters (2)

Name Type Description
preferenceName string The specific preference to retrieve for this user. Should be specified in the route (e.g., api/user/:unixName/preference/:preferenceName).
preferenceValue mixed The value to be recorded. This can be a scalar value (such as 1 or "apple"), or a JSON array or object value. Any submitted value will be serialized to the database.

Return: (none)

putQueue

Set the entire queue for the user in a single call. This is subject to the same rules as postQueue.

Parameters (2)

Name Type Description
id string The database ID or unix name of the user (URL segment).
tracker_item_ids string Comma-separated list of tracker item IDs that comprise the queue, in the order they should be arranged.

Return: void

DELETE

deleteAdmin

Revoke site admin status from a user.

Parameters (1)

Name Type Description
id string The database ID or unix name of the user to demote (URL segment).

Return: void

deleteAuthorizedKeys

Clears all SSH authorized keys for the specified user.

Parameters (1)

Name Type Description
id string The database ID or unix name of the user (URL segment).

Return: void

deleteGroup

Remove a group.

Parameters (1)

Name Type Description
id string The database ID or unix name of the group to remove (URL segment).

Return: void

deletePreference

Deletes a user preference.
Returns 200 (OK) on success, 404 (Not Found) if the user does not exist, 403 (Forbidden) if the user is not allowed, 400 (Bad Request) otherwise with validation failure(s)

Parameters (2)

Name Type Description
preferenceName string The specific preference to retrieve for this user. Should be specified in the route (e.g., api/user/:unixName/preference/:preferenceName).
preferenceValue mixed The value to be recorded. This can be a scalar value (such as 1 or "apple"), or a JSON array or object value. Any submitted value will be serialized to the database.

Return: (none)

deleteQueue

Remove a single Tracker Item from the specified user's queue. This is subject to the same rules as postQueue, above.

Parameters (2)

Name Type Description
id string The database ID or unix name of the user (URL segment).
tracker_item_id int The database ID of the Tracker Item to be removed from the user's queue.

Return: void