Search
Search
Several system methods are provided to search and filter results by their metadata. For example, /system/findDataObjects can return a list of all data objects that you can access, filtered by name, tags, types, regions, properties, etc.
Regular Expressions and Globbing
In some of these routes, you can restrict your search to names matching a particular regular expression or a glob (wildcard pattern). For the glob pattern, we support the wildcard *
for matching a string of any length, and the wildcard ?
for matching a single character. (We do not at this moment support the bracket notation []
.) If you are searching for the actual characters "_", "?", or "\", you will need to escape them with a backslash, e.g. "\_a\?xfoo\" matches the exact string "*a?xfoo\".
Pagination of Results
The limit
and starting
input parameters, together with the next
output field, can be used to paginate the results. The limit
parameter determines the maximum number of returned results. If there are more results than limit
allowed for, then next
is non-null and may be used as the starting
argument for a subsequent call. If the call is repeated with the starting
input parameter set to the previous call's next
return value, then the next unique subset of results will be returned. Repeat this process until next
is null to retrieve all results.
Search API Method Specifications
API method: /system/findDataObjects
/system/findDataObjects
Specification
Searches for data objects satisfying particular constraints. By default this will return all entities and objects for which the user has at least "VIEW" permission (permission acquired by PUBLIC nature of a project is not counted in this criterion). This constraint cannot be removed. However, additional constraints can be specified that can further restrict the objects that will be returned.
Ordering of results
Data objects from the same project always appear together in the search results in descending order of their last modified timestamp, unless overwritten by the sortBy
input field. Ties are broken in ascending order of their IDs.
Inputs
class
string (optional) The entity type to restrict the search by. Must be one of "record", "file", "applet", "workflow".state
string (optional, default "any") One of the values: "open", "closing", "closed", or "any".visibility
string (optional, default "visible") One of the values: "hidden", "visible", or "either".name
string or mapping (optional) If a string, the exact case-sensitive name that the results must have. If a mapping, then it can have a subset of the following fields:regexp
string (mutually exclusive withglob
; required ifglob
is not present) A PCRE (external link) regular expression that the name of all results must matchflags
string (optional; can only be present ifregexp
is present) Currently this field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expressionglob
string (mutually exclusive withregexp
; required ifregexp
is not present) A wildcard pattern that the name of all results must match. The valid wildcard characters are '*' (0 or more characters) and '?' (1 character).
id
array of strings (optional) If provided, results must have object IDs among the provided list of IDs. If the ID is not accessible to the user or does not exist, that ID is not included in the results array. The array may have no more than 1000 elements. (Note that the number of results may exceed the number of IDs provided here because an object appears once in the results for each accessible project it is found in, unlessscope.project
is set.) .type
string or mapping (optional) Defined by grammar below, represents the type(s) that any results must havetype ::= < string >
type ::= {"$and": typeArray}
type ::= {"$or": typeArray}
typeArray ::= [ ]
typeArray ::= [type, ...]
tags
string or mapping (optional) Defined by grammar below, represents the tag(s) any results must havetags ::= < string >
tags ::= {"$and": tagsArray}
tags ::= {"$or": tagsArray}
tagsArray ::= [ ]
tagsArray ::= [tags, ...]
region
string or array of strings (optional) If a string, then the result set will contain only entities whose associatedregion
matches the string. If an array, then the result set will contain only entities whose associatedregion
is one of the specified strings.properties
mapping (optional) Defined by grammar below. If provided, each matching result must have the specified properties. Each "key" is a property name, and each "value" may either be a string (meaning that the key must have the specified value), a boolean (true meaning that the specified key must be present but may have any value, false meaning that the specified key must not be present), or the mapping {$ne: } meaning that the specified key must not equal the specified string value.constraint ::= { key: value, ... }
constraint ::= { "$and": constraintArray }
constraint ::= { "$or": constraintArray }
constraintArray ::= []
constraintArray ::= [constraint, ...]
link
string (optional) An object ID to which matching objects must link to in their detailsscope
mapping (optional) Restrict the search to a particular projectproject
string ID of the project in which all results must residefolder
string (optional, default "/") Folder path inproject
in which all results must residerecurse
boolean (optional, default true) Whether the search should be performed recursively on subfolders as well
sortBy
mapping (optional) Changes the ordering that the result set is returned in. Must be specified with thescope
field.field
string The field that determines the sort order of the result set. Acceptable values:created
ordering
string The arrangement of the result set based upon the field. One ofascending
ordescending
level
string (optional, default "VIEW") One of: "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER", representing the minimum permissions level by which to restrict the list of projects searchedmodified
mapping (optional) If at least one of the following keys is specified, the resulting data objects must have been last modified in the indicated time frame. If not specified, there will be no constraint on when the data object was last modified. If amodified
hash does not contain at least one of the following keys, an error will be thrown.after
timestamp (optional) If specified, only return results that were last modified at or after this timebefore
timestamp (optional) If specified, only return results that were last modified at or before this time
created
mapping (optional) If at least one of the following keys is specified, the resulting data objects must have been created in the indicated time frame. If not specified, there will be no constraint on data object creation time. If acreated
hash does not contain at least one of the following keys, an error will be thrown.after
timestamp (optional) If specified, only return results created at or after this timebefore
timestamp (optional) If specified, only return results created at or before this time
describe
boolean or mapping (optional, default false) Either false to indicate that no extra metadata should be retrieved with the results, or a mapping representing the input that would be used for calling "describe" on each of the returned results.starting
mapping (optional) Continue a previous query that had reached its limit; the non-null value that was returned asnext
in the query's output should be provided here.limit
int (optional, default 1000) Maximum number of results that may be returned; must be between 1 and 1000 (inclusive).archivalState
string (optional, default "any") One of the values: "archived", "live", "archival", “unarchiving”, or "any". Requires the additional input class having the value “file”.scope.project
andscope.folder
must also be set.
Outputs
results
array of mappings List of results, each with the following fields:project
string ID of the project in which the result was foundid
string ID of the resultdescribe
mapping The output of the result's corresponding describe method ifdescribed
was supplied as an input.
next
mapping or null If null, all results were reported inresults
. If a mapping, represents the next result that could not be returned becauselimit
results have already been returned. This value should be passed directly tostarting
in a subsequent query if more results are desired.
Errors
InvalidInput
The input is not a hash
class
(if supplied) is not one of: "record", "file", "applet", or "workflow"state
(if supplied) is not one of: "open", "closing", "closed", or "any"visibility
(if supplied) is not one of: "hidden", "visible", or "either"level
(if supplied) is not one of: "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER"name
(if supplied) is not a string or a mapping such that any of the following is satisfiedflags
is present, but keyregexp
is missing or the value supplied toflags
is not "i".Mutually exclusive keys
glob
andregexp
are provided togetherNeither
glob
norregexp
is present
id
(if supplied) is an array containing greater than 1000 elementstype
,properties
, ortags
(if supplied) do not take any of the specified grammarsregion
(if supplied) is not one of our supported regions. See Regions for more informationmodified
orcreated
(if supplied) does not contain either anafter
orbefore
timestamplimit
is not between 1 and 1000sortBy
was specified without also specifyingscope
archivalState
if supplied, is not one of "archived", "live", "archival", “unarchiving”, or "any". Will also return error if the value of class is not "file",scope.project
is not set, orscope.folder
is not set.
PermissionDenied
VIEW access to the project specified in
scope.project
is required ifscope.project
is supplied.
API method: /system/findDatabases
/system/findDatabases
Specification
Searches for database data objects satisfying particular constraints. By default this will return all database objects from projects for which the user has at least "VIEW" permission and which are accessible through the license. Permission acquired by PUBLIC nature of a project is counted in this criterion only when public
key of the input is set to true. Additional constraints can be specified that can further restrict the objects that will be returned.
Ordering of results
Database data objects from the same project always appear together in the search results in descending order of their last modified timestamp, with ties broken in ascending order of their IDs.
Inputs
databaseName
string or mapping (optional) If a string, the exact case-sensitive databaseName that the results must have. If a mapping, then it can have a subset of the following fields:regexp
string (mutually exclusive withglob
; required ifglob
is not present) A PCRE (external link) regular expression that the databaseName of all results must matchflags
string (optional; can only be present ifregexp
is present) Currently this field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expressionglob
string (mutually exclusive withregexp
; required ifregexp
is not present) A wildcard pattern that the databaseName of all results must match. The valid wildcard characters are '*' (0 or more characters) and '?' (1 character).
uniqueDatabaseName
string or mapping (optional) If a string, the exact case-sensitive uniqueDatabaseName that the results must have. If a mapping, then it can have a subset of the following fields:regexp
string (mutually exclusive withglob
; required ifglob
is not present) A PCRE (external link) regular expression that the uniqueDatabaseName of all results must matchflags
string (optional; can only be present ifregexp
is present) Currently this field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expressionglob
string (mutually exclusive withregexp
; required ifregexp
is not present) A wildcard pattern that the uniqueDatabaseName of all results must match. The valid wildcard characters are '*' (0 or more characters) and '?' (1 character).
visibility
string (optional, default "visible") One of the values: "hidden", "visible", or "either"region
string or array of strings (optional) If a string, then the result set will contain only entities whose associatedregion
matches the string. If an array, then the result set will contain only entities whose associatedregion
is one of the specified strings.scope
mapping (optional) Restrict the search to a particular projectproject
string ID of the project in which all results must residefolder
string (optional, default "/") Folder path inproject
in which all results must residerecurse
boolean (optional, default true) Whether the search should be performed recursively on subfolders as well
level
string (optional, default "VIEW") One of: "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER", representing the minimum permissions level by which to restrict the list of projects searchedpublic
boolean (optional, default false) Whether the search should be performed also on PUBLIC projectsmodified
mapping (optional) If at least one of the following keys is specified, the resulting data objects must have been last modified in the indicated time frame. If not specified, there will be no constraint on when the data object was last modified. If amodified
hash does not contain at least one of the following keys, an error will be thrown.after
timestamp (optional) If specified, only return results that were last modified at or after this timebefore
timestamp (optional) If specified, only return results that were last modified at or before this time
created
mapping (optional) If at least one of the following keys is specified, the resulting data objects must have been created in the indicated time frame. If not specified, there will be no constraint on data object creation time. If acreated
hash does not contain at least one of the following keys, an error will be thrown.after
timestamp (optional) If specified, only return results created at or after this timebefore
timestamp (optional) If specified, only return results created at or before this time
describe
boolean or mapping (optional, default false) Either false to indicate that no extra metadata should be retrieved with the results, or a mapping representing the input that would be used for calling "describe" on each of the returned results.starting
mapping (optional) Continue a previous query that had reached its limit; the non-null value that was returned asnext
in the query's output should be provided herelimit
int (optional, default 1000) Maximum number of results that may be returned; must be between 1 and 1000 (inclusive)
Outputs
results
array of mappings List of results, each with the following fields:project
string ID of the project in which the result was foundid
string ID of the resultlevel
string permission level of the project in which the result was founddescribe
mapping The output of the result's corresponding describe method ifdescribe
was supplied as an input
next
mapping or null If null, all results were reported inresults
. If a mapping, represents the next result that could not be returned becauselimit
results have already been returned. This value should be passed directly tostarting
in a subsequent query if more results are desired.
Errors
InvalidInput
databaseName
oruniqueDatabaseName
(if supplied) is not a string or a mapping such that any of the following is satisfied *flags
is present, but keyregexp
is missing or the value supplied toflags
is not "i".Mutually exclusive keys
glob
andregexp
are provided togetherNeither
glob
norregexp
is present
level
(if supplied) is not one of: "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER"region
(if supplied) is not one of our supported regions. See Regions for more informationmodified
orcreated
(if supplied) does not contain either anafter
orbefore
timestamplimit
is not between 1 and 1000
ResourceNotFound
Project specified in
scope.project
orstarting.project
needs to be under license to be accessible for this action
PermissionDenied
VIEW access to the project specified in
scope.project
is required ifscope.project
is suppliedVIEW access to the project specified in
starting.project
is required ifstarting
is supplied
API method: /system/findExecutions
/system/findExecutions
Specification
Searches for execution (job or analysis) objects.
Ordering of results
Jobs and analyses returned by /system/findExecutions
, /system/findJobs
, and /system/findAnalyses
are sorted by their created timestamp (in descending order, i.e., the latest execution appears first). Ties are broken in ascending order of their IDs. Job tries with the same created timestamp and same job ID are returned in an undefined order that is consistent across API calls.
Inputs
class
string (optional) Entity type to restrict the search by; must be either "job" or "analysis"includeSubjobs
boolean (optional, default true) If set to false, only non-subjob executions (i.e., master jobs, origin jobs, or analyses) will be returnedincludeRestarted
boolean (optional, default false) If set to true, returns information about initial job tries for restarted jobs and jobs within execution subtrees rooted in these initial tries (for jobs belonging to root executions launched after July 12, 2023 00:13 UTC) in addition to the final job tries and execution subtrees rooted in the final job tries which are returned for bothtrue
andfalse
values of this input argument. When settingincludeRestarted
flag to true, use thedescribe
input argument to output the values oftry
to distinguish between different tries of the same output job ID.launchedBy
string (optional) ID of the user who launched the jobname
string or mapping (optional) If a string, the exact case-sensitive name that the results must have. If a mapping, then it can have a subset of the following fields:regexp
string (mutually exclusive withglob
; required ifglob
is not present) A PCRE (external link) regular expression that the name of all results must matchflags
string (optional; can only be present ifregexp
is present) Currently this field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expressionglob
string (mutually exclusive withregexp
; required ifregexp
is not present) A wildcard pattern that the name of all results must match. The valid wildcard characters are '*' (0 or more characters) and '?' (1 character).
id
array of strings (optional) If provided, results must have execution IDs among the provided list of IDs. The array may have no more than 1000 elements. Job IDs (if provided) will output information for the latest tries./system/describeExecutions
can be used to fetch information about specific job tries.executable
string (optional) ID of the executable (app or applet) that the results were responsible for runningproject
string (optional) ID of the project context, or the project in which the job was launchedtags
string or mapping (optional) Defined by grammar below, represents the tag(s) any results must havetags ::= < string >
tags ::= {"$and": tagsArray}
tags ::= {"$or": tagsArray}
tagsArray ::= [ ]
tagsArray ::= [tags, ...]
properties
mapping (optional) Defined by grammar below. If provided, each matching result must have the specified properties. Each "key" is a property name, and each "value" may either be a string (meaning that the key must have the specified value) or the boolean true (meaning that the specified key must be present but may have any value).constraint ::= { key: value, ... }
constraint ::= { "$and": constraintArray }
constraint ::= { "$or": constraintArray }
constraintArray ::= []
constraintArray ::= [constraint, ...]
state
string or array of strings (optional) State(s) that the results must be in. Possible values by execution type:Queries to
/system/findExecutions
can use states from either list.rootExecution
string or array of strings (optional) One or more IDs of the top-level (user-initiated) execution(s); results will be constrained to executions in those execution trees. IfincludeRestarted
input is set to true, trees for all tries with the specified root executions (all tries of the root executions, and everything rooted in all the tries) will be returned for root executions launched after July 12, 2023 00:13 UTC.originJob
string or array of strings (optional) Restrict results to executions which have one of the provided string IDs as an origin job; an origin job is one launched via/app-xxxx/run
or/applet-xxxx/run
, or as a stage in an analysis. IfincludeRestarted
input is set to true, trees for all tries with the specified origin jobs will be returned for origin jobs that belong to root executions launched after July 12, 2023 00:13 UTC.parentJob
string or null (optional) If the value is a string, then all results must be executions directly launched byparentJob
. If the value is null, then only executions with no parent job are searched. Use null values for this field andparentAnalysis
in order to restrict the search to root executions only.parentJobTry
non-negative integer (optional) IfincludeRestarted
is true andparentJobTry
is specified, only the children ofparentJobTry
ofparentJob
are returned. IfparentJob
string is specified butparentJobTry
is not specified, only the children of the latestparentJob
try are returned.parentAnalysis
string or null (optional) If the value is a string, then all results must be executions launched as stages ofparentAnalysis
. If the value is null, then only executions which do not have a parent analysis are searched. Use null values for this field andparentJob
in order to restrict the search to root executions only.created
mapping (optional) If at least one of the following keys is specified, the resulting execution objects must have been created in the indicated time frame. If not specified, there will be no constraint on execution object creation time. If acreated
hash does not contain at least one of the following keys, an error will be thrown.after
timestamp (optional) If specified, only return results created at or after this timebefore
timestamp (optional) If specified, only return results created at or before this time
describe
boolean or mapping (optional, default false) False indicates that no extra metadata should be retrieved with the results. A mapping represents the input that would be used for calling the corresponding "describe" API method on each of the returned results; a value of true is equivalent to the empty hash input. The mapping should be of the format{"fields": {"field1": true, "field2": true, ...}}
.starting
string (optional) Continue a previous query that had reached its limit; the non-null value that was returned asnext
in the query's output should be provided herelimit
int (optional, default 1000) Maximum number of results that may be returned; must be between 1 and 1000 (inclusive)
Outputs
results
array of mappings List of results, each with the following fields:id
string ID of the resultdescribe
mapping The output of the result's corresponding describe method ifdescribe
was set as an input
next
string or null If null, all results were reported inresults
. If a string, represents the next result that could not be returned becauselimit
results have already been returned. This value should be passed directly tostarting
in a subsequent query if more results are desired.
Errors
InvalidInput
id
input cannot be specified withincludeRestarted
set totrue
parentJobTry
cannot be specified without specifyingparentJob
inputparentJobTry
cannot be specified withoutincludeRestarted
set totrue
See Errors (Protocols) for additional information.
API method: /system/findAnalyses
/system/findAnalyses
This method is identical to /system/findExecutions with the class
constraint set to "analysis".
API method: /system/findJobs
/system/findJobs
This method is identical to /system/findExecutions with the class
constraint set to "job".
API method: /system/findApps
/system/findApps
Specification
This route provides functionality to search for apps; the ordering of results is arbitrary. Only apps for which the requesting user has access to will be returned (for example, the user is on the authorized users list for the app).
Inputs
name
string or mapping (optional) If a string, the exact case-sensitive name that the results must have. If a mapping, then it can have a subset of the following fields:regexp
string (mutually exclusive withglob
; required ifglob
is not present) A PCRE (external link) regular expression that the name of all results must matchflags
string (optional; can only be present ifregexp
is present) Currently this field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expressionglob
string (mutually exclusive withregexp
; required ifregexp
is not present) A wildcard pattern that the name of all results must match. The valid wildcard characters are '*' (0 or more characters) and '?' (1 character).
category
string or mapping (optional) A category is defined by the grammar below:category ::= < string >
category ::= {"$and": categoryArray}
category ::= {"$or": categoryArray}
categoryArray ::= [category, ...]
allVersions
boolean (optional, default false) Whether to remove the restriction that only app versions tagged with "default" are returnedpublished
boolean (optional) If true, only published apps are returned; if false, only unpublished apps are returnedbillTo
string or array of strings (optional) If a string, then the result set will contain only apps whosebillTo
matches the string. If an array, then the result set will contain only apps whosebillTo
is one of the specified entities.createdBy
string (optional) ID of the user who created the appdeveloper
string (optional) ID of a developer the app must haveauthorizedUser
string (optional) userID, orgID or "PUBLIC" that must exist in each app'sauthorizedUsers
listmodified
mapping (optional) If at least one of the following keys is specified, the resulting apps must have been last modified in the indicated time frame. If not specified, there will be no constraint on when the app was last modified. If amodified
hash does not contain at least one of the following keys, an error will be thrown.after
timestamp (optional) If specified, only return results that were last modified at or after this timebefore
timestamp (optional) If specified, only return results that were last modified at or before this time
created
mapping (optional) If at least one of the following keys is specified, the resulting apps must have been created in the indicated time frame. If not specified, there will be no constraint on app creation time. If acreated
hash does not contain at least one of the following keys, an error will be thrown.after
timestamp (optional) If specified, only return results created at or after this timebefore
timestamp (optional) If specified, only return results created at or before this time
describe
boolean or mapping (optional, default false) False indicates that no extra metadata should be retrieved with the results. A mapping represents the input that would be used for calling /app-xxxx/describe on each of the returned results; a value of true is equivalent to the empty hash input.starting
string (optional) Continue a previous query that had reached its limit; the value that was returned asnext
in the query's output should be provided herelimit
int (optional, default 1000) Maximum number of results that may be returned; must be between 1 and 1000 (inclusive)
Outputs
results
array of mappings List of results, each with the following fields:id
string ID of the resultdescribe
mapping The output of the result's corresponding describe method if thedescribe
method was set as an input
next
string or null If null, all results were reported inresults
. If a string, represents the next result that could not be returned becauselimit
results have already been returned. This value should be passed directly tostarting
in a subsequent query if more results are desired.
Errors
API method: /system/findProjects
/system/findProjects
Specification
Find projects accessible to a user or job at a given permission level.
Ordering of results is:
Descending by last modified time stamp, then
Ascending by ID
Inputs
name
string or mapping (optional) If a string, the exact case-sensitive name that the results must have. If a mapping, then it can have a subset of the following fields:regexp
string (mutually exclusive withglob
; required ifglob
is not present) A PCRE (external link) regular expression that the name of all results must matchflags
string (optional; can only be present ifregexp
is present) Currently this field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expressionglob
string (mutually exclusive withregexp
; required ifregexp
is not present) A wildcard pattern that the name of all results must match. The valid wildcard characters are '*' (0 or more characters) and '?' (1 character).
id
array of strings (optional) If provided, results must have project IDs among the provided list of IDs. The array may have no more than 1000 elements.billTo
string or array of strings (optional) If a string, then the result set will contain only projects whosebillTo
matches the string. If an array, then the result set will contain only projects whosebillTo
is one of the specified strings.cloudAccount
string (optional) If specified, the result set will contain only projects that are associated with the provided cloud account ID.provider
string (optional) If specified, the result set will contain only projects that are associated with the provider ID.region
string or array of strings (optional) If a string, then the result set will contain only projects whoseregion
matches the string. If an array, then the result set will contain only projects whoseregion
is one of the specified strings.tags
string or mapping (optional) Defined by grammar below, represents the tag(s) any results must havetags ::= < string >
tags ::= {"$and": tagsArray}
tags ::= {"$or": tagsArray}
tagsArray ::= [ ]
tagsArray ::= [tags, ...]
properties
mapping (optional) Defined by grammar below. If provided, each matching result must have the specified properties. Each "key" is a property name, and each "value" may either be a string (meaning that the key must have the specified value) or the boolean true (meaning that the specified key must be present but may have any value).constraint ::= { key: value, ... }
constraint ::= { "$and": constraintArray }
constraint ::= { "$or": constraintArray }
constraintArray ::= [ ]
constraintArray ::= [constraint, ...]
level
string (optional, default "CONTRIBUTE") Must be one of "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER" to represent the minimum permissions level of the project results to be returnedexplicitPermission
boolean (optional) If a value of true is provided, then the results will be restricted to projects for which there is at least one explicit or implicit permission. If false, then the results will be restricted to public projects for which the user has neither explicit nor implicit permissionspublic
boolean (optional) If set to true, then only public projects will be included in result. If false, then no public project will be included in result.created
mapping (optional) If at least one of the following keys is specified, the resulting projects must have been created in the indicated time frame. If not specified, there will be no constraint on project creation time. If acreated
hash does not contain at least one of the following keys, an error will be thrown.after
timestamp (optional) If specified, only return results created at or after this timebefore
timestamp (optional) If specified, only return results created at or before this time
describe
boolean or mapping (optional, default false) False indicates that no extra metadata should be retrieved with the results. A mapping represents the input that would be used for calling /project-xxxx/describe on each of the returned results; a value of true is equivalent to the empty hash input.starting
string (optional) Continue a previous query that had reached its limit; the value that was returned asnext
in the query's output should be provided herecontainsPHI
boolean (optional) If set to true, only projects that contain PHI data will be retrieved. If set to false, only projects that do not contain PHI data will be retrieved.externalUploadRestricted
boolean (optional) If provided, only projects with the specifiedexternalUploadRestricted
setting will be retrieved.limit
int (optional, default 1000) Maximum number of results that may be returned; must be between 1 and 1000 (inclusive)sharedWith
string (optional) If specified, the results will be restricted to projects that are explicitly shared with the specified user ID, organization ID, or the string "PUBLIC" for public projects
Outputs
results
array of mappings List of results, each with the following fields:id
string ID of the resultlevel
string Maximal permission level (one of "VIEW", "UPLOAD", "CONTRIBUTE", "ADMINISTER") held by the requesting user/job (either directly or through an organization)permissionSources
array of strings (present only if an unrestricted login token is used to make this API call) IDs of the source(s) that were granted the maximal permission levellevel
through which the requesting user has access. Possible values are the user's ID, organization IDs, or the string "PUBLIC" for public projectspublic
boolean Whether the project is publicdescribe
mapping The output of the result's corresponding describe method ifdescribe
was set as an input
next
string or null If null, all results were reported inresults
. If a string, represents the next result that could not be returned becauselimit
results have already been returned. This value should be passed directly tostarting
in a subsequent query if more results are desired.
Errors
API method: /system/findProjectMembers
/system/findProjectMembers
Specification
Returns a list of all the members (user, team, or organization) of a project.
Note: "PUBLIC" is never included in the list of project members; instead, the output hash contains a boolean value public
to indicate whether the project is public
Ordering of results is:
Ascending by member ID.
Inputs
project
string ID of the projectlevel
string (optional, default "VIEW") Must be one of "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER", to represent the minimum permissions level that the members must have (granted directly to them)describe
boolean (optional, default false) Whether describe should be called for all resultsstarting
string (optional) Continue a previous query that had reached its limit; the value that was returned asnext
in the query's output should be provided herelimit
int (optional, default 1000) Maximum number of results that may be returned; must be between 1 and 1000 (inclusive)
Outputs
results
array of mappings List of results, each with the following fields:id
string ID of the project memberlevel
string Permission level for the given project granted directly to the memberdescribe
mapping Metadata about the project member if thedescribe
input was set containing the following fields:id
string ID of the memberclass
string Either "user" or "org"permittedRegions
array of strings The regions this member can operate in
The following keys are present if
class
is "user":first
string The user's first namelast
string The user's last namemiddle
string The user's middle namehandle
string The user's username or handle
The following key is present if
class
is "org":name
string Organization name
public
boolean Whether the project is publicnext
string or null If null, all results were reported inresults
. If a string, represents the next result that could not be returned becauselimit
results have already been returned. This value should be passed directly tostarting
in a subsequent query if more results are desired.
Errors
InvalidInput
The input is not a hash
level
, if provided, is not a recognized permissions level
PermissionDenied
VIEW access to the project is required
API method: /system/findOrgs
/system/findOrgs
Specification
Lists orgs in which the requesting user has at least the specified membership level, subject to additional query constraints.
Ordering of results
Orgs will be returned in ascending order by their IDs.
Inputs
id
array of strings (optional) If provided, results will be limited to the org IDs included in the array. The array may have no more than 1000 elements.level
string one of "ADMIN" or "MEMBER". The results will contain only orgs in which the requesting user has at least the specified membership level.allowBillableActivities
boolean (optional) if a boolean, then the results will contain only orgs in which the requesting user either has (true) or does not have (false) theallowBillableActivities
membership permission.describe
boolean or mapping (optional; default false) if a mapping, then it represents the input that will be used to describe each of the results; true indicates that the empty mapping will be used. A value of false indicates that no extra metadata be retrieved with the results.starting
mapping (optional) mapping used to continue a previous query that had reached its limit; the non-null value that was returned asnext
in the output of that query should be specified here.limit
int (optional; default 1000) maximum number of results that may be returned; must be between 1 and 1000 (inclusive)
Outputs
results
array of mappings list of results, each with the following fields:id
string org ID.describe
mapping the output of describing the corresponding org ifdescribe
is set as an input
next
mapping or null if null, then all results were returned inresults
; otherwise, represents the next result that could not be returned becauselimit
results have already been returned. If a mapping, then this value should be specified as thestarting
input in a subsequent query if more results are desired.
Errors
PermissionDenied
The requesting user does not have a full scope token
Last updated