searchProjects
Get projects paginated
Details
- Method:
GET - Path:
/rest/api/3/project/search - Operation ID:
searchProjects
Parameters
{
"startAt": {
"description": "The index of the first item to return in a page of results (page offset).",
"required": false,
"location": "query",
"type": "integer",
"format": "int64"
},
"maxResults": {
"description": "The maximum number of items to return per page. Must be less than or equal to 100. If a value greater than 100 is provided, the `maxResults` parameter will default to 100.",
"required": false,
"location": "query",
"type": "integer",
"format": "int32"
},
"orderBy": {
"description": "[Order](#ordering) the results by a field.\n\n * `category` Sorts by project category. A complete list of category IDs is found using [Get all project categories](#api-rest-api-3-projectCategory-get).\n * `issueCount` Sorts by the total number of issues in each project.\n * `key` Sorts by project key.\n * `lastIssueUpdatedTime` Sorts by the last issue update time.\n * `name` Sorts by project name.\n * `owner` Sorts by project lead.\n * `archivedDate` EXPERIMENTAL. Sorts by project archived date.\n * `deletedDate` EXPERIMENTAL. Sorts by project deleted date.",
"required": false,
"location": "query",
"type": "string",
"enum": [
"category",
"-category",
"+category",
"key",
"-key",
"+key",
"name",
"-name",
"+name",
"owner",
"-owner",
"+owner",
"issueCount",
"-issueCount",
"+issueCount",
"lastIssueUpdatedDate",
"-lastIssueUpdatedDate",
"+lastIssueUpdatedDate",
"archivedDate",
"+archivedDate",
"-archivedDate",
"deletedDate",
"+deletedDate",
"-deletedDate"
]
},
"id": {
"description": "The project IDs to filter the results by. To include multiple IDs, provide an ampersand-separated list. For example, `id=10000&id=10001`. Up to 50 project IDs can be provided.",
"required": false,
"location": "query",
"type": "array"
},
"keys": {
"description": "The project keys to filter the results by. To include multiple keys, provide an ampersand-separated list. For example, `keys=PA&keys=PB`. Up to 50 project keys can be provided.",
"required": false,
"location": "query",
"type": "array"
},
"query": {
"description": "Filter the results using a literal string. Projects with a matching `key` or `name` are returned (case insensitive).",
"required": false,
"location": "query",
"type": "string"
},
"typeKey": {
"description": "Orders results by the [project type](https://confluence.atlassian.com/x/GwiiLQ#Jiraapplicationsoverview-Productfeaturesandprojecttypes). This parameter accepts a comma-separated list. Valid values are `business`, `service_desk`, and `software`.",
"required": false,
"location": "query",
"type": "string"
},
"categoryId": {
"description": "The ID of the project's category. A complete list of category IDs is found using the [Get all project categories](#api-rest-api-3-projectCategory-get) operation.",
"required": false,
"location": "query",
"type": "integer",
"format": "int64"
},
"action": {
"description": "Filter results by projects for which the user can:\n\n * `view` the project, meaning that they have one of the following permissions:\n \n * *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project.\n * *Administer projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project.\n * *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).\n * `browse` the project, meaning that they have the *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project.\n * `edit` the project, meaning that they have one of the following permissions:\n \n * *Administer projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project.\n * *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).\n * `create` the project, meaning that they have the *Create issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project in which the issue is created.",
"required": false,
"location": "query",
"type": "string",
"enum": [
"view",
"browse",
"edit",
"create"
]
},
"expand": {
"description": "Use [expand](#expansion) to include additional information in the response. This parameter accepts a comma-separated list. Expanded options include:\n\n * `description` Returns the project description.\n * `projectKeys` Returns all project keys associated with a project.\n * `lead` Returns information about the project lead.\n * `issueTypes` Returns all issue types associated with the project.\n * `url` Returns the URL associated with the project.\n * `insight` EXPERIMENTAL. Returns the insight details of total issue count and last issue update time for the project.",
"required": false,
"location": "query",
"type": "string"
},
"status": {
"description": "EXPERIMENTAL. Filter results by project status:\n\n * `live` Search live projects.\n * `archived` Search archived projects.\n * `deleted` Search deleted projects, those in the recycle bin.",
"required": false,
"location": "query",
"type": "array"
},
"properties": {
"description": "EXPERIMENTAL. A list of project properties to return for the project. This parameter accepts a comma-separated list.",
"required": false,
"location": "query",
"type": "array"
},
"propertyQuery": {
"description": "EXPERIMENTAL. A query string used to search properties. The query string cannot be specified using a JSON object. For example, to search for the value of `nested` from `{\"something\":{\"nested\":1,\"other\":2}}` use `[thepropertykey].something.nested=1`. Note that the propertyQuery key is enclosed in square brackets to enable searching where the propertyQuery key includes dot (.) or equals (=) characters. Note that `thepropertykey` is only returned when included in `properties`.",
"required": false,
"location": "query",
"type": "string"
}
}Response Schema
{
"additionalProperties": false,
"description": "A page of items.",
"properties": {
"isLast": {
"description": "Whether this is the last page.",
"readOnly": true,
"type": "boolean"
},
"maxResults": {
"description": "The maximum number of items that could be returned.",
"format": "int32",
"readOnly": true,
"type": "integer"
},
"nextPage": {
"description": "If there is another page of results, the URL of the next page.",
"format": "uri",
"readOnly": true,
"type": "string"
},
"self": {
"description": "The URL of the page.",
"format": "uri",
"readOnly": true,
"type": "string"
},
"startAt": {
"description": "The index of the first item returned.",
"format": "int64",
"readOnly": true,
"type": "integer"
},
"total": {
"description": "The number of items returned.",
"format": "int64",
"readOnly": true,
"type": "integer"
},
"values": {
"description": "The list of items.",
"items": {
"additionalProperties": false,
"description": "Details about a project.",
"properties": {
"archived": {
"description": "Whether the project is archived.",
"readOnly": true,
"type": "boolean"
},
"archivedBy": {
"allOf": [
{
"$ref": "#/components/schemas/User"
}
],
"description": "The user who archived the project.",
"readOnly": true
},
"archivedDate": {
"description": "The date when the project was archived.",
"format": "date-time",
"readOnly": true,
"type": "string"
},
"assigneeType": {
"description": "The default assignee when creating issues for this project.",
"enum": [
"PROJECT_LEAD",
"UNASSIGNED"
],
"readOnly": true,
"type": "string"
},
"avatarUrls": {
"allOf": [
{
"$ref": "#/components/schemas/AvatarUrlsBean"
}
],
"description": "The URLs of the project's avatars.",
"readOnly": true
},
"components": {
"description": "List of the components contained in the project.",
"items": {
"additionalProperties": false,
"description": "Details about a project component.",
"properties": {
"ari": {
"description": "Compass component's ID. Can't be updated. Not required for creating a Project Component.",
"readOnly": true,
"type": "string"
},
"assignee": {
"allOf": [
{
"$ref": "#/components/schemas/User"
}
],
"description": "The details of the user associated with `assigneeType`, if any. See `realAssignee` for details of the user assigned to issues created with this component.",
"readOnly": true
},
"assigneeType": {
"description": "The nominal user type used to determine the assignee for issues created with this component. See `realAssigneeType` for details on how the type of the user, and hence the user, assigned to issues is determined. Can take the following values:\n\n * `PROJECT_LEAD` the assignee to any issues created with this component is nominally the lead for the project the component is in.\n * `COMPONENT_LEAD` the assignee to any issues created with this component is nominally the lead for the component.\n * `UNASSIGNED` an assignee is not set for issues created with this component.\n * `PROJECT_DEFAULT` the assignee to any issues created with this component is nominally the default assignee for the project that the component is in.\n\nDefault value: `PROJECT_DEFAULT`. \nOptional when creating or updating a component.",
"enum": [
"PROJECT_DEFAULT",
"COMPONENT_LEAD",
"PROJECT_LEAD",
"UNASSIGNED"
],
"type": "string"
},
"description": {
"description": "The description for the component. Optional when creating or updating a component.",
"type": "string"
},
"id": {
"description": "The unique identifier for the component.",
"readOnly": true,
"type": "string"
},
"isAssigneeTypeValid": {
"description": "Whether a user is associated with `assigneeType`. For example, if the `assigneeType` is set to `COMPONENT_LEAD` but the component lead is not set, then `false` is returned.",
"readOnly": true,
"type": "boolean"
},
"lead": {
"allOf": [
{
"$ref": "#/components/schemas/User"
}
],
"description": "The user details for the component's lead user.",
"readOnly": true
},
"leadAccountId": {
"description": "The accountId of the component's lead user. The accountId uniquely identifies the user across all Atlassian products. For example, *5b10ac8d82e05b22cc7d4ef5*.",
"maxLength": 128,
"type": "string",
"writeOnly": true
},
"leadUserName": {
"description": "This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details.",
"type": "string"
},
"metadata": {
"additionalProperties": {
"readOnly": true,
"type": "string"
},
"description": "Compass component's metadata. Can't be updated. Not required for creating a Project Component.",
"readOnly": true,
"type": "object"
},
"name": {
"description": "The unique name for the component in the project. Required when creating a component. Optional when updating a component. The maximum length is 255 characters.",
"type": "string"
},
"project": {
"description": "The key of the project the component is assigned to. Required when creating a component. Can't be updated.",
"type": "string"
},
"projectId": {
"description": "The ID of the project the component is assigned to.",
"format": "int64",
"readOnly": true,
"type": "integer"
},
"realAssignee": {
"allOf": [
{
"$ref": "#/components/schemas/User"
}
],
"description": "The user assigned to issues created with this component, when `assigneeType` does not identify a valid assignee.",
"readOnly": true
},
"realAssigneeType": {
"description": "The type of the assignee that is assigned to issues created with this component, when an assignee cannot be set from the `assigneeType`. For example, `assigneeType` is set to `COMPONENT_LEAD` but no component lead is set. This property is set to one of the following values:\n\n * `PROJECT_LEAD` when `assigneeType` is `PROJECT_LEAD` and the project lead has permission to be assigned issues in the project that the component is in.\n * `COMPONENT_LEAD` when `assignee`Type is `COMPONENT_LEAD` and the component lead has permission to be assigned issues in the project that the component is in.\n * `UNASSIGNED` when `assigneeType` is `UNASSIGNED` and Jira is configured to allow unassigned issues.\n * `PROJECT_DEFAULT` when none of the preceding cases are true.",
"enum": [
"PROJECT_DEFAULT",
"COMPONENT_LEAD",
"PROJECT_LEAD",
"UNASSIGNED"
],
"readOnly": true,
"type": "string"
},
"self": {
"description": "The URL of the component.",
"format": "uri",
"readOnly": true,
"type": "string"
}
},
"type": "object",
"xml": {
"name": "component"
}
},
"readOnly": true,
"type": "array"
},
"deleted": {
"description": "Whether the project is marked as deleted.",
"readOnly": true,
"type": "boolean"
},
"deletedBy": {
"allOf": [
{
"$ref": "#/components/schemas/User"
}
],
"description": "The user who marked the project as deleted.",
"readOnly": true
},
"deletedDate": {
"description": "The date when the project was marked as deleted.",
"format": "date-time",
"readOnly": true,
"type": "string"
},
"description": {
"description": "A brief description of the project.",
"readOnly": true,
"type": "string"
},
"email": {
"description": "An email address associated with the project.",
"type": "string"
},
"expand": {
"description": "Expand options that include additional project details in the response.",
"readOnly": true,
"type": "string",
"xml": {
"attribute": true
}
},
"favourite": {
"description": "Whether the project is selected as a favorite.",
"type": "boolean"
},
"id": {
"description": "The ID of the project.",
"type": "string"
},
"insight": {
"allOf": [
{
"$ref": "#/components/schemas/ProjectInsight"
}
],
"description": "Insights about the project.",
"readOnly": true
},
"isPrivate": {
"description": "Whether the project is private from the user's perspective. This means the user can't see the project or any associated issues.",
"readOnly": true,
"type": "boolean"
},
"issueTypeHierarchy": {
"allOf": [
{
"$ref": "#/components/schemas/Hierarchy"
}
],
"description": "The issue type hierarchy for the project.",
"readOnly": true
},
"issueTypes": {
"description": "List of the issue types available in the project.",
"items": {
"additionalProperties": false,
"description": "Details about an issue type.",
"properties": {
"avatarId": {
"description": "The ID of the issue type's avatar.",
"format": "int64",
"readOnly": true,
"type": "integer"
},
"description": {
"description": "The description of the issue type.",
"readOnly": true,
"type": "string"
},
"entityId": {
"description": "Unique ID for next-gen projects.",
"format": "uuid",
"readOnly": true,
"type": "string"
},
"hierarchyLevel": {
"description": "Hierarchy level of the issue type.",
"format": "int32",
"readOnly": true,
"type": "integer"
},
"iconUrl": {
"description": "The URL of the issue type's avatar.",
"readOnly": true,
"type": "string"
},
"id": {
"description": "The ID of the issue type.",
"readOnly": true,
"type": "string"
},
"name": {
"description": "The name of the issue type.",
"readOnly": true,
"type": "string"
},
"scope": {
"allOf": [
{
"$ref": "#/components/schemas/Scope"
}
],
"description": "Details of the next-gen projects the issue type is available in.",
"readOnly": true
},
"self": {
"description": "The URL of these issue type details.",
"readOnly": true,
"type": "string"
},
"subtask": {
"description": "Whether this issue type is used to create subtasks.",
"readOnly": true,
"type": "boolean"
}
},
"type": "object"
},
"readOnly": true,
"type": "array"
},
"key": {
"description": "The key of the project.",
"readOnly": true,
"type": "string"
},
"landingPageInfo": {
"allOf": [
{
"$ref": "#/components/schemas/ProjectLandingPageInfo"
}
],
"description": "The project landing page info.",
"readOnly": true
},
"lead": {
"allOf": [
{
"$ref": "#/components/schemas/User"
}
],
"description": "The username of the project lead.",
"readOnly": true
},
"name": {
"description": "The name of the project.",
"readOnly": true,
"type": "string"
},
"permissions": {
"allOf": [
{
"$ref": "#/components/schemas/ProjectPermissions"
}
],
"description": "User permissions on the project",
"readOnly": true
},
"projectCategory": {
"allOf": [
{
"$ref": "#/components/schemas/ProjectCategory"
}
],
"description": "The category the project belongs to.",
"readOnly": true
},
"projectTypeKey": {
"description": "The [project type](https://confluence.atlassian.com/x/GwiiLQ#Jiraapplicationsoverview-Productfeaturesandprojecttypes) of the project.",
"enum": [
"software",
"service_desk",
"business"
],
"readOnly": true,
"type": "string"
},
"properties": {
"additionalProperties": {
"readOnly": true
},
"description": "Map of project properties",
"readOnly": true,
"type": "object"
},
"retentionTillDate": {
"description": "The date when the project is deleted permanently.",
"format": "date-time",
"readOnly": true,
"type": "string"
},
"roles": {
"additionalProperties": {
"format": "uri",
"readOnly": true,
"type": "string"
},
"description": "The name and self URL for each role defined in the project. For more information, see [Create project role](#api-rest-api-3-role-post).",
"readOnly": true,
"type": "object"
},
"self": {
"description": "The URL of the project details.",
"format": "uri",
"readOnly": true,
"type": "string"
},
"simplified": {
"description": "Whether the project is simplified.",
"readOnly": true,
"type": "boolean"
},
"style": {
"description": "The type of the project.",
"enum": [
"classic",
"next-gen"
],
"readOnly": true,
"type": "string"
},
"url": {
"description": "A link to information about this project, such as project documentation.",
"readOnly": true,
"type": "string"
},
"uuid": {
"description": "Unique ID for next-gen projects.",
"format": "uuid",
"readOnly": true,
"type": "string"
},
"versions": {
"description": "The versions defined in the project. For more information, see [Create version](#api-rest-api-3-version-post).",
"items": {
"additionalProperties": false,
"description": "Details about a project version.",
"properties": {
"approvers": {
"description": "If the expand option `approvers` is used, returns a list containing the approvers for this version.",
"items": {
"additionalProperties": true,
"description": "Contains details about a version approver.",
"properties": {
"accountId": {
"description": "The Atlassian account ID of the approver.",
"readOnly": true,
"type": "string"
},
"declineReason": {
"description": "A description of why the user is declining the approval.",
"readOnly": true,
"type": "string"
},
"description": {
"description": "A description of what the user is approving within the specified version.",
"readOnly": true,
"type": "string"
},
"status": {
"description": "The status of the approval, which can be *PENDING*, *APPROVED*, or *DECLINED*",
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"readOnly": true,
"type": "array"
},
"archived": {
"description": "Indicates that the version is archived. Optional when creating or updating a version.",
"type": "boolean"
},
"description": {
"description": "The description of the version. Optional when creating or updating a version. The maximum size is 16,384 bytes.",
"type": "string"
},
"driver": {
"description": "If the expand option `driver` is used, returns the Atlassian account ID of the driver.",
"readOnly": true,
"type": "string"
},
"expand": {
"description": "Use [expand](em>#expansion) to include additional information about version in the response. This parameter accepts a comma-separated list. Expand options include:\n\n * `operations` Returns the list of operations available for this version.\n * `issuesstatus` Returns the count of issues in this version for each of the status categories *to do*, *in progress*, *done*, and *unmapped*. The *unmapped* property contains a count of issues with a status other than *to do*, *in progress*, and *done*.\n * `driver` Returns the Atlassian account ID of the version driver.\n * `approvers` Returns a list containing approvers for this version.\n\nOptional for create and update.",
"type": "string",
"xml": {
"attribute": true
}
},
"id": {
"description": "The ID of the version.",
"readOnly": true,
"type": "string"
},
"issuesStatusForFixVersion": {
"allOf": [
{
"$ref": "#/components/schemas/VersionIssuesStatus"
}
],
"description": "If the expand option `issuesstatus` is used, returns the count of issues in this version for each of the status categories *to do*, *in progress*, *done*, and *unmapped*. The *unmapped* property contains a count of issues with a status other than *to do*, *in progress*, and *done*.",
"readOnly": true
},
"moveUnfixedIssuesTo": {
"description": "The URL of the self link to the version to which all unfixed issues are moved when a version is released. Not applicable when creating a version. Optional when updating a version.",
"format": "uri",
"type": "string"
},
"name": {
"description": "The unique name of the version. Required when creating a version. Optional when updating a version. The maximum length is 255 characters.",
"type": "string"
},
"operations": {
"description": "If the expand option `operations` is used, returns the list of operations available for this version.",
"items": {
"additionalProperties": false,
"description": "Details about the operations available in this version.",
"properties": {
"href": {
"type": "string"
},
"iconClass": {
"type": "string"
},
"id": {
"type": "string"
},
"label": {
"type": "string"
},
"styleClass": {
"type": "string"
},
"title": {
"type": "string"
},
"weight": {
"format": "int32",
"type": "integer"
}
},
"type": "object",
"xml": {
"name": "link"
}
},
"readOnly": true,
"type": "array"
},
"overdue": {
"description": "Indicates that the version is overdue.",
"readOnly": true,
"type": "boolean"
},
"project": {
"description": "Deprecated. Use `projectId`.",
"type": "string"
},
"projectId": {
"description": "The ID of the project to which this version is attached. Required when creating a version. Not applicable when updating a version.",
"format": "int64",
"type": "integer"
},
"releaseDate": {
"description": "The release date of the version. Expressed in ISO 8601 format (yyyy-mm-dd). Optional when creating or updating a version.",
"format": "date",
"type": "string"
},
"released": {
"description": "Indicates that the version is released. If the version is released a request to release again is ignored. Not applicable when creating a version. Optional when updating a version.",
"type": "boolean"
},
"self": {
"description": "The URL of the version.",
"format": "uri",
"readOnly": true,
"type": "string"
},
"startDate": {
"description": "The start date of the version. Expressed in ISO 8601 format (yyyy-mm-dd). Optional when creating or updating a version.",
"format": "date",
"type": "string"
},
"userReleaseDate": {
"description": "The date on which work on this version is expected to finish, expressed in the instance's *Day/Month/Year Format* date format.",
"readOnly": true,
"type": "string"
},
"userStartDate": {
"description": "The date on which work on this version is expected to start, expressed in the instance's *Day/Month/Year Format* date format.",
"readOnly": true,
"type": "string"
}
},
"type": "object",
"xml": {
"name": "version"
}
},
"readOnly": true,
"type": "array"
}
},
"type": "object",
"xml": {
"name": "project"
}
},
"readOnly": true,
"type": "array"
}
},
"type": "object"
}Usage
from ocp_agent import OCPAgent
agent = OCPAgent()
await agent.register_api('jira')
# Call this tool
result = await agent.call_tool('searchProjects', {
# Add required parameters here
})