This is a standard ApplicationSearch method which will let you list, query, or search for objects. For documentation on these endpoints, see Conduit API: Using Search Endpoints.
project.search
API Method: project.search
- Returns
- map<string, wild>
- Errors
- ERR-CONDUIT-CORE: See error message for details.
- OAuth Scope
- OAuth clients may never call this method.
Method Description
Prebuilt Queries
You can choose a builtin or saved query as a starting point for filtering results by selecting it with queryKey. If you don't specify a queryKey, the query will start with no constraints.
For example, many applications have builtin queries like "active" or "open" to find only active or enabled results. To use a queryKey, specify it like this:
{ ... "queryKey": "active", ... }
The table below shows the keys to use to select builtin queries and your saved queries, but you can also use any query you run via the web UI as a starting point. You can find the key for a query by examining the URI after running a normal search.
You can use these keys to select builtin queries and your configured saved queries:
Query Key | Name | Builtin |
---|---|---|
active | Active | Builtin |
all | All | Builtin |
Constraints
You can apply custom constraints by passing a dictionary in constraints. This will let you search for specific sets of results (for example, you may want show only results with a certain state, status, or owner).
If you specify both a queryKey and constraints, the builtin or saved query will be applied first as a starting point, then any additional values in constraints will be applied, overwriting the defaults from the original query.
Different endpoints support different constraints. The constraints this method supports are detailed below. As an example, you might specify constraints like this:
{ ... "constraints": { "authorPHIDs": ["PHID-USER-1111", "PHID-USER-2222"], "flavors": ["cherry", "orange"], ... }, ... }
This API endpoint supports these constraints:
Key | Label | Type | Description |
---|---|---|---|
ids | IDs | list<int> | Search for objects with specific IDs. |
phids | PHIDs | list<phid> | Search for objects with specific PHIDs. |
name | Name | string | (Deprecated.) Search for projects with a given name or hashtag using tokenizer/datasource query matching rules. This is deprecated in favor of the more powerful "query" constraint. |
slugs | Slugs | list<string> | Search for projects with particular slugs. (Slugs are the same as project hashtags.) |
members | Members | list<user> | |
watchers | Watchers | list<user> | |
status | Status | Not supported. | |
isMilestone | Milestones | bool | Pass true to find only milestones, or false to omit milestones. |
isRoot | Root Projects | bool | Pass true to find only root projects, or false to omit root projects. |
minDepth | Minimum Depth | int | Find projects with a given minimum depth. Root projects have depth 0, their immediate children have depth 1, and so on. |
maxDepth | Maximum Depth | int | Find projects with a given maximum depth. Root projects have depth 0, their immediate children have depth 1, and so on. |
subtypes | Subtypes | list<string> | Search for projects with given subtypes. |
icons | Icons | list<string> | (See table below.) |
colors | Colors | list<string> | (See table below.) |
parents | Parent Projects | list<phid> | Find direct subprojects of specified parents. |
ancestors | Ancestor Projects | list<phid> | Find all subprojects beneath specified ancestors. |
query | Query | string | Find objects matching a fulltext search query. See "Search User Guide" in the documentation for details. |
spaces | Spaces | list<phid> | Search for objects in certain spaces. |
Constants supported by the icons constraint:
Key | Value |
---|---|
project | Project |
tag | Tag |
policy | Policy |
group | Group |
folder | Folder |
timeline | Timeline |
goal | Goal |
release | Release |
bugs | Bugs |
cleanup | Cleanup |
umbrella | Umbrella |
communication | Communication |
organization | Organization |
infrastructure | Infrastructure |
account | Account |
experimental | Experimental |
Constants supported by the colors constraint:
Key | Value |
---|---|
red | Red |
orange | Orange |
yellow | Yellow |
green | Green |
blue | Blue |
indigo | Indigo |
violet | Violet |
pink | Pink |
grey | Grey |
checkered | Checkered |
Result Ordering
Use order to choose an ordering for the results.
Either specify a single key from the builtin orders (these are a set of meaningful, high-level, human-readable orders) or specify a custom list of low-level columns.
To use a high-level order, choose a builtin order from the table below and specify it like this:
{ ... "order": "newest", ... }
These builtin orders are available:
Key | Description | Columns |
---|---|---|
name | Name | name |
newest | Creation (Newest First) | id |
oldest | Creation (Oldest First) | -id |
relevance | Relevance | rank, fulltext-modified, id |
You can choose a low-level column order instead. To do this, provide a list of columns instead of a single key. This is an advanced feature.
In a custom column order:
- each column may only be specified once;
- each column may be prefixed with - to invert the order;
- the last column must be a unique column, usually id; and
- no column other than the last may be unique.
To use a low-level order, choose a sequence of columns and specify them like this:
{ ... "order": ["color", "-name", "id"], ... }
These low-level columns are available:
Key | Unique |
---|---|
id | Yes |
rank | No |
fulltext-created | No |
fulltext-modified | No |
name | Yes |
milestoneNumber | No |
status | No |
Object Fields
Objects matching your query are returned as a list of dictionaries in the data property of the results. Each dictionary has some metadata and a fields key, which contains the information about the object that most callers will be interested in.
For example, the results may look something like this:
{ ... "data": [ { "id": 123, "phid": "PHID-WXYZ-1111", "fields": { "name": "First Example Object", "authorPHID": "PHID-USER-2222" } }, { "id": 124, "phid": "PHID-WXYZ-3333", "fields": { "name": "Second Example Object", "authorPHID": "PHID-USER-4444" } }, ... ] ... }
This result structure is standardized across all search methods, but the available fields differ from application to application.
These are the fields available on this object type:
Key | Type | Description |
---|---|---|
name | string | The name of the project. |
slug | string | Primary slug/hashtag. |
subtype | string | Subtype of the project. |
milestone | int? | For milestones, milestone sequence number. |
parent | map<string, wild>? | For subprojects and milestones, a brief description of the parent project. |
depth | int | For subprojects and milestones, depth of this project in the tree. Root projects have depth 0. |
icon | map<string, wild> | Information about the project icon. |
color | map<string, wild> | Information about the project color. |
spacePHID | phid? | PHID of the policy space this object is part of. |
dateCreated | int | Epoch timestamp when the object was created. |
dateModified | int | Epoch timestamp when the object was last updated. |
policy | map<string, wild> | Map of capabilities to current policies. |
description | wild | Short project description. |
custom.stwalkerster:external-sprint | wild |
Attachments
By default, only basic information about objects is returned. If you want more extensive information, you can use available attachments to get more information in the results (like subscribers and projects).
Generally, requesting more information means the query executes more slowly and returns more data (in some cases, much more data). You should normally request only the data you need.
To request extra data, specify which attachments you want in the attachments parameter:
{ ... "attachments": { "subscribers": true }, ... }
This example specifies that results should include information about subscribers. In the return value, each object will now have this information filled out in the corresponding attachments value:
{ ... "data": [ { ... "attachments": { "subscribers": { "subscriberPHIDs": [ "PHID-WXYZ-2222", ], "subscriberCount": 1, "viewerIsSubscribed": false } }, ... }, ... ], ... }
These attachments are available:
Key | Name | Description |
---|---|---|
members | Project Members | Get the member list for the project. |
watchers | Project Watchers | Get the watcher list for the project. |
ancestors | Project Ancestors | Get the full ancestor list for each project. |
Paging and Limits
Queries are limited to returning 100 results at a time. If you want fewer results than this, you can use limit to specify a smaller limit.
If you want more results, you'll need to make additional queries to retrieve more pages of results.
The result structure contains a cursor key with information you'll need in order to fetch the next page of results. After an initial query, it will usually look something like this:
{ ... "cursor": { "limit": 100, "after": "1234", "before": null, "order": null } ... }
The limit and order fields are describing the effective limit and order the query was executed with, and are usually not of much interest. The after and before fields give you cursors which you can pass when making another API call in order to get the next (or previous) page of results.
To get the next page of results, repeat your API call with all the same parameters as the original call, but pass the after cursor you received from the first call in the after parameter when making the second call.
If you do things correctly, you should get the second page of results, and a cursor structure like this:
{ ... "cursor": { "limit": 5, "after": "4567", "before": "7890", "order": null } ... }
You can now continue to the third page of results by passing the new after cursor to the after parameter in your third call, or return to the previous page of results by passing the before cursor to the before parameter. This might be useful if you are rendering a web UI for a user and want to provide "Next Page" and "Previous Page" links.
If after is null, there is no next page of results available. Likewise, if before is null, there are no previous results available.
Call Method
Examples
- Use the Conduit API Tokens panel in Settings to generate or manage API tokens.
- If you submit parameters, these examples will update to show exactly how to encode the parameters you submit.
-d api.token=api-token \
-d param=value \
...